Utilities » Image conversion utility

Converts images of different formats.

This utility is built if MAGNUM_WITH_IMAGECONVERTER is enabled when building Magnum. To use this utility with CMake, you need to request the imageconverter component of the Magnum package and use the Magnum::imageconverter target for example in a custom command:

find_package(Magnum REQUIRED imageconverter)

add_custom_command(OUTPUT ... COMMAND Magnum::imageconverter ...)

See Downloading and building, Usage with CMake and the Trade namespace for more information. There's also a corresponding scene conversion utility.

Example usage

Listing contents of a cubemap DDS file with mipmaps, implicitly using AnyImageImporter that delegates to DdsImporter or any other plugin capable of DDS import depending on what's available:

magnum-imageconverter --info cubemap.dds
3D image 0:
  Level 0: CubeMap {512, 512, 6} @ Bc3RGBAUnorm (1536.0 kB)
  Level 1: CubeMap {256, 256, 6} @ Bc3RGBAUnorm (384.0 kB)
  Level 2: CubeMap {128, 128, 6} @ Bc3RGBAUnorm (96.0 kB)
  Level 3: CubeMap {64, 64, 6} @ Bc3RGBAUnorm (24.0 kB)
  Level 4: CubeMap {32, 32, 6} @ Bc3RGBAUnorm (6.0 kB)
  Level 5: CubeMap {16, 16, 6} @ Bc3RGBAUnorm (1.5 kB)
Total image data size: 2047.5 kB

Converting a JPEG file to a PNG, implicitly using AnyImageConverter that delegates to PngImageConverter, StbImageConverter or any other plugin capable of PNG export depending on what's available:

magnum-imageconverter image.jpg image.png

Creating a JPEG file with 95% quality from a PNG, by setting a plugin-specific configuration option that's recognized by both JpegImageConverter and StbImageConverter:

magnum-imageconverter image.png image.jpg -c jpegQuality=0.95

Extracting raw (uncompressed or block-compressed) data from a DDS file for manual inspection:

magnum-imageconverter image.dds --converter raw data.dat

Extracting an arbitrary image from a glTF file. Note that only image formats are considered by default so you have to explicitly supply a scene importer, either the generic AnySceneImporter or for example directly the GltfImporter. First printing a list of images to choose from:

magnum-imageconverter -I GltfImporter --info file.gltf
2D image 0: alpha baseColor
  Level 0: {1024, 1024} @ RGBA8Unorm (4096.0 kB)
2D image 1: alpha metallicRoughness
  Level 0: {1024, 1024} @ RGB8Unorm (3072.0 kB)
2D image 2: interiors baseColor
  Level 0: {512, 512} @ RGB8Unorm (768.0 kB)
2D image 3: interiors emissive
  Level 0: {512, 512} @ RGB8Unorm (768.0 kB)
2D image 4: plastic soft baseColor
  Level 0: {4096, 4096} @ RGB8Unorm (49152.0 kB)
…

... and then extracting the third image to a PNG file for inspection:

magnum-imageconverter -I GltfImporter --image 2 file.gltf image.png

Converting a PNG file to a KTX2, resizing it to 512x512 with StbResizeImageConverter, block-compressing its data to BC3 using StbDxtImageConverter with high-quality output. Because the plugin implements image-to-image conversion, the AnyImageConverter plugin is implicitly used after it, proxying to KtxImageConverter as the *.ktx2 extension was chosen:

magnum-imageconverter image.png image.ktx2 \
    -C StbResizeImageConverter -c size="512 512" \
    -C StbDxtImageConverter -c highQuality

Printing features and documented options of a particular image converter plugin. For debugging convenience the printed configuration file will reflect also all options specified via -c:

magnum-imageconverter --info-converter -C StbResizeImageConverter -c size="512 512"
Plugin name: StbResizeImageConverter
Features:
  Convert2D
  Convert3D
Configuration:
  # Target width and height, separated by a space. Required.
  size=512 512

  # How neighboring pixel values are retrieved on image edges. Valid values
  # are:
  #  - clamp -- as if the edge pixels were extended
  #  - wrap -- as if the image was repeated
  #  - reflect -- as if the image was repeated and reflected
  #  - zero -- uses zero values for out-of-bounds pixels
  edge=clamp
…

Dealing with image levels and layers

Converting six 2D images to a 3D cube map file using OpenExrImageConverter. Note the -c envmap-cube which the plugin needs to produce an actual cube map file, the -- is then used to avoid -x.exr and others to be treated as options instead of files. On Unix shells you could also use ./-x.exr etc. to circumvent that ambiguity.

magnum-imageconverter --layers -c envmap=cube -- \
    +x.exr -x.exr +y.exr -y.exr +z.exr -z.exr cube.exr

Creating a multi-level OpenEXR cube map file from a set of input files. Note the use of -D3 which switches to dealing with 3D images instead of 2D:

magnum-imageconverter --levels -c envmap=cube -D3 \
    cube-256.exr cube-128.exr cube-64.exr cube-mips.exr

Extracting the second level of a +Y face (third layer) of the above cube map file again:

magnum-imageconverter cube-mips.exr --layer 2 --level 1 +x-128.exr

Full usage documentation

magnum-imageconverter [-h|--help] [-I|--importer PLUGIN]
    [-C|--converter PLUGIN]... [--plugin-dir DIR] [--map]
    [-i|--importer-options key=val,key2=val2,…]
    [-c|--converter-options key=val,key2=val2,…]... [-D|--dimensions N]
    [--image N] [--level N] [--layer N] [--layers] [--levels] [--in-place]
    [--info-importer] [--info-converter] [--info] [--color on|off|auto]
    [-v|--verbose] [--profile] [--] input output

Arguments:

  • input — input image
  • output — output image; ignored if --info is present, disallowed for --in-place
  • -h, --help — display this help message and exit
  • -I, --importer PLUGIN — image importer plugin (default: AnyImageImporter)
  • -C, --converter PLUGIN — image converter plugin (default: AnyImageConverter)
  • --plugin-dir DIR — override base plugin dir
  • --map — memory-map the input for zero-copy import (works only for standalone files)
  • -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 the converter(s)
  • -D, --dimensions N — import and convert image of given dimensions (default: 2)
  • --image N — image to import (default: 0)
  • --level N — import given image level instead of all
  • --layer N — extract a layer into an image with one dimension less
  • --layers — combine multiple layers into an image with one dimension more
  • --levels — combine multiple image levels into a single file
  • --in-place — overwrite the input image with the output
  • --info-importer — print info about the importer plugin and exit
  • --info-converter — print info about the image converter plugin and exit
  • --info — print info about the input file and exit
  • --color — colored output for --info (default: auto)
  • -v, --verbose — verbose output from importer and converter plugins
  • --profile — measure import and conversion time

Specifying --importer raw:<format> will treat the input as a raw tightly-packed square of pixels in given PixelFormat. Specifying -C / --converter raw will save raw imported data instead of using a converter plugin.

If the --info-importer or --info-converter option is given, the utility will print information about given plugin specified via the -I or -C option, including its configuration options potentially overriden with -i or -c. 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 --info is given, the utility will print information about given data, independently of the -D / --dimensions option. In this case the input file is read but no no conversion is done and output file doesn't need to be specified.

The -i / --importer-options and -c / --converter-options 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 / --converter option (and correspondingly also -c / --converter-options) multiple times in order to chain more converters together. All converters in the chain have to support image-to-image conversion, the last converter has to be either raw or support either image-to-image or image-to-file conversion. If the last converter doesn't support conversion to a file, AnyImageConverter is used to save its output; if no -C / --converter is specified, AnyImageConverter is used.

« Font conversion utility | Utilities | Scene conversion utility »