Scene conversion utility new in 2020.06
Converts scenes of different formats.
This utility is built if MAGNUM_WITH_SCENECONVERTER is enabled when building Magnum. To use this utility with CMake, you need to request the sceneconverter component of the Magnum package and use the Magnum::sceneconverter target for example in a custom command:
find_package(Magnum REQUIRED imageconverter) add_custom_command(OUTPUT ... COMMAND Magnum::sceneconverter ...)
See Downloading and building and Usage with CMake and the Trade namespace for more information. There's also a corresponding image conversion utility.
Example usage
Listing contents of a glTF file, implicitly using AnySceneImporter that delegates to GltfImporter, AssimpImporter or any other plugin capable of glTF import depending on what's available:
magnum-sceneconverter --info Box.gltf
Scene 0: Bound: 2 objects @ UnsignedInt (0.1 kB) Fields: Parent @ Int, 2 entries ImporterState @ Pointer, 2 entries Transformation @ Matrix4x4, 1 entries Mesh @ UnsignedInt, 1 entries MeshMaterial @ Int, 1 entries Total scene data size: 0.1 kB Object 0 (referenced by 1 scenes): Fields: Parent, ImporterState, Transformation Object 1 (referenced by 1 scenes): Fields: Parent, ImporterState, Mesh, MeshMaterial Material 0 (referenced by 1 objects): Red Type: PbrMetallicRoughness Base layer: BaseColor @ Vector4: ▓▓ {0.8, 0, 0, 1} Metalness @ Float: 0 Mesh 0 (referenced by 1 objects): Mesh Level 0: 24 vertices @ Triangles (0.6 kB) Normal @ Vector3, offset 0, stride 12 Position @ Vector3, offset 288, stride 12 36 indices @ UnsignedShort, offset 0, stride 2 (0.1 kB) Total mesh data size: 0.6 kB
Converting an OBJ file to a glTF, implicitly using AnySceneConverter that delegates to GltfSceneConverter or any other plugin capable of glTF export depending on what's available:
magnum-sceneconverter chair.obj chair.gltf
Extracting a single mesh from a glTF to a PLY file, implicitly delegated to StanfordSceneConverter, for closer inspection:
magnum-sceneconverter scene.gltf --mesh 17 mesh17.ply
Repacking a glTF and encoding all its images as Basis UASTC with BasisImageConverter using the imageConverter option of GltfSceneConverter:
magnum-sceneconverter scene.gltf scene.basis.gltf \ -c imageConverter=BasisKtxImageConverter,imageConverter/uastc
Printing features and documented options of a particular scene converter plugin. For debugging convenience the printed configuration file will reflect also all options specified via -c:
magnum-sceneconverter --info-converter -C GltfSceneConverter -c copyright="Me & Myself"
Plugin name: GltfSceneConverter Features: ConvertMultipleToData AddScenes AddMeshes AddMaterials AddTextures AddImages2D AddCompressedImages2D Configuration: # Copyright and generator name, written into the asset object. If empty, no # value is written. copyright=Me & Myself generator=Magnum GltfSceneConverter # Add one or more extensionUsed and/or extensionRequired values to populate # the extension usage and requirement arrays. # Whether to write a *.gltf or a *.glb file. If empty, detected automatically # based on filename extension, conversion to data defaults to a binary file. # If a text file is selected for conversion to data, converting anything that # involves binary buffers will currently fail. binary= …
Performing operations on all images and meshes in the file
Processing a glTF file and removing duplicates in all its meshes:
magnum-sceneconverter scene.gltf --remove-duplicate-vertices scene.deduplicated.gltf
Processing a glTF file, resizing all its images to 512x512 with StbResizeImageConverter, block-compressing their data to a BC3 using StbDxtImageConverter with high-quality output and saving them in a KTX2 container with KtxImageConverter and an experimental KHR_
magnum-sceneconverter scene.gltf scene.dxt.gltf \ -P StbResizeImageConverter -p size="512 512" \ -P StbDxtImageConverter -p highQuality \ -c imageConverter=KtxImageConverter,experimentalKhrTextureKtx
Processing a glTF file and decimating all its meshes to a half size with MeshOptimizerSceneConverter, with verbose output showing the processing stats. The -M / -m options can be chained the same way as -P / -p above, if needed:
magnum-sceneconverter scene.gltf scene.decimated.gltf \ -M MeshOptimizerSceneConverter \ -m simplify,simplifyTargetIndexCountThreshold=0.5 -v
Full usage documentation
magnum-sceneconverter [-h|--help] [-I|--importer PLUGIN] [-C|--converter PLUGIN]... [-P|--image-converter PLUGIN]... [-M|--mesh-converter PLUGIN]... [--plugin-dir DIR] [--prefer alias:plugin1,plugin2,…]... [--set plugin:key=val,key2=val2,…]... [--map] [--only-mesh-attributes N1,N2-N3…] [--remove-duplicate-vertices] [--remove-duplicate-vertices-fuzzy EPSILON] [--phong-to-pbr] [--remove-duplicate-materials] [-i|--importer-options key=val,key2=val2,…] [-c|--converter-options key=val,key2=val2,…]... [-p|--image-converter-options key=val,key2=val2,…]... [-m|--mesh-converter-options key=val,key2=val2,…]... [--passthrough-on-image-converter-failure] [--passthrough-on-mesh-converter-failure] [--mesh ID] [--mesh-level INDEX] [--concatenate-meshes] [--info-importer] [--info-converter] [--info-image-converter] [--info-animations] [--info-images] [--info-lights] [--info-cameras] [--info-materials] [--info-meshes] [--info-objects] [--info-scenes] [--info-skins] [--info-textures] [--info] [--color on|4bit|off|auto] [--bounds] [--object-hierarchy] [-v|--verbose] [--profile] [--] input output
Arguments:
input— input fileoutput— output file; ignored if--infois present-h,--help— display this help message and exit-I,--importer PLUGIN— scene importer plugin (default: AnySceneImporter)-C,--converter PLUGIN— scene converter plugin(s)-P,--image-converter PLUGIN— converter plugin(s) to apply to each image in the scene-M,--mesh-converter PLUGIN— converter plugin(s) to apply to each mesh in the scene--plugin-dir DIR— override base plugin dir--prefer alias:plugin1,plugin2,…— prefer particular plugins for given alias(es)--set plugin:key=val,key2=val2,…— set global plugin(s) option--map— memory-map the input for zero-copy import (works only for standalone files)--only-mesh-attributes N1,N2-N3…— include only mesh attributes of given IDs in the output. See Utility::String:: parseNumberSequence() for syntax description. --remove-duplicate-vertices— remove duplicate vertices using MeshTools::removeDuplicates(const Trade:: MeshData&) in all meshes after import --remove-duplicate-vertices-fuzzy EPSILON— remove duplicate vertices using MeshTools::removeDuplicatesFuzzy(const Trade:: MeshData&, Float, Double) in all meshes after import --phong-to-pbr— convert Phong materials to PBR metallic/roughness using MaterialTools::phongToPbrMetallicRoughness() --remove-duplicate-materials— remove duplicate materials using MaterialTools::removeDuplicatesInPlace() -i,--importer-options key=val,key2=val2,…— configuration options to pass to the importer-c,--converter-options key=val,key2=val2,…— configuration options to pass to scene converter(s)-p,--image-converter-options key=val,key2=val2,…— configuration options to pass to image converter(s)-m,--mesh-converter-options key=val,key2=val2,…— configuration options to pass to mesh converter(s)--passthrough-on-image-converter-failure— pass original data through if--image-converterfails--passthrough-on-mesh-converter-failure— pass original data through if--mesh-converterfails--mesh ID— convert just a single mesh instead of the whole scene--mesh-level LEVEL— level to select for single-mesh conversion--concatenate-meshes— flatten mesh hierarchy and concatenate them all together experimental--info-importer— print info about the importer plugin and exit--info-converter— print info about the scene or mesh converter plugin and exit--info-image-converter— print info about the image converter plugin and exit--info-animations— print into about animations in the input file and exit--info-images— print into about images in the input file and exit--info-lights— print into about lights in the input file and exit--info-cameras— print into about cameras in the input file and exit--info-materials— print into about materials in the input file and exit--info-meshes— print into about meshes in the input file and exit--info-objects— print into about objects in the input file and exit--info-scenes— print into about scenes in the input file and exit--info-skins— print into about skins in the input file and exit--info-textures— print into about textures in the input file and exit--info— print info about everything in the input file and exit, same as specifying all other data-related--info-*options together--color— colored output for--info(default:auto)--bounds— show bounds of known attributes in--infooutput--object-hierarchy— visualize object hierarchy in--infooutput-v,--verbose— verbose output from importer and converter plugins--profile— measure import and conversion time
If any of the --info-importer, --info-converter or --info-image-converter options are given, the utility will print information about given plugin specified via the -I, -C or -P option, including its configuration options potentially overriden with -i, -c or -p. In this case no file is read and no conversion is done and neither the input nor the output file needs to be specified.
If any of the other --info-* options are given, the utility will print information about given data. In this case the input file is read but no conversion is done and the output file doesn't need to be specified. In case one data references another and both --info-* options are specified, the output will also list reference count (for example, --info-scenes together with --info-meshes will print how many objects reference given mesh).
The -i, -c and -m arguments accept a comma-separated list of key/value pairs to set in the importer / converter plugin configuration. If the = character is omitted, it's equivalent to saying key=true; configuration subgroups are delimited with /. Prefix the key with + to add new options or multiple options of the same name.
It's possible to specify the -C option (and correspondingly also -c) multiple times in order to chain more converters together. All converters in the chain have to support the Trade::-C is specified, AnySceneConverter is used.
Similarly, the -P / -M options (and correspondingly also -p / -m) can be specified multiple times in order to chain more image / mesh converters together. All image converters in the chain have to support the ConvertImage*D feature for given image dimensions, all mesh converters in the chain have to support the ConvertMesh feature. If no -P / -M is specified, the imported images / meshes are passed directly to the scene converter.
The --remove-duplicate-vertices, --phong-to-pbr and --remove-duplicate-materials operations are performed on meshes and materials before passing them to any converter.
If --concatenate-meshes is given, all meshes of the input file are first concatenated into a single mesh using MeshTools::--only-mesh-attributes is specified as well, the IDs reference attributes of the first mesh.