Utilities » 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_texture_ktx glTF extension:

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 file
  • output — output file; ignored if --info is 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-converter fails
  • --passthrough-on-mesh-converter-failure — pass original data through if --mesh-converter fails
  • --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 --info output
  • --object-hierarchy — visualize object hierarchy in --info output
  • -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::SceneConverterFeature::ConvertMultiple or ConvertMesh feature, the last converter either Trade::SceneConverterFeature::ConvertMultiple, ConvertMesh, ConvertMultipleToFile or ConvertMeshToFile. If the last converter doesn't support conversion to a file, AnySceneConverter is used to save its output. If no -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::concatenate(), with the scene hierarchy transformation baked in using SceneTools::absoluteFieldTransformations3D(), and then passed through the remaining operations. Only attributes that are present in the first mesh are taken, if --only-mesh-attributes is specified as well, the IDs reference attributes of the first mesh.