Utilities » Image conversion utility

Converts images of different formats.

This utility is built if both WITH_TRADE and 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.


magnum-imageconverter [-h|--help] [--importer IMPORTER] [--converter CONVERTER]
    [--plugin-dir DIR] [-i|--importer-options key=val,key2=val2,…]
    [-c|--converter-options key=val,key2=val2,…] [--info] [-v|--verbose] [--]
    input output


  • input — input image
  • output — output image
  • -h, --help — display this help message and exit
  • --importer IMPORTER — image importer plugin (default: AnyImageImporter)
  • --converter CONVERTER — image converter plugin (default: AnyImageConverter)
  • --plugin-dir DIR — override base plugin dir
  • -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
  • --info — print info about the input file and exit
  • -v, --verbose — verbose output from importer and converter plugins

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

If --info is given, the utility will print information about all images present in the file. In this case 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 /.

Example usage

Converting a JPEG file to a PNG:

magnum-imageconverter image.jpg image.png

Creating a JPEG file with 95% quality from a PNG, by setting a plugin-specific configuration option. Note that currently the proxy AnyImageImporter and AnyImageConverter plugins don't know how to correctly propagate options to the target plugin, so you need to specify --importer / --converter explicitly when using the -i / -c options.

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

Extracting raw (uncompressed, compressed) data from a DDS file for manual inspection:

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