@ -48,6 +48,7 @@ namespace Magnum {
/** @page magnum-imageconverter Image conversion utility
@ brief Converts images of different formats
@ tableofcontents
@ m_footernavigation
@ m_keywords { magnum - imageconverter imageconverter }
@ -63,94 +64,53 @@ add_custom_command(OUTPUT ... COMMAND Magnum::imageconverter ...)
@ endcode
See @ ref building , @ ref cmake and the @ ref Trade namespace for more
information .
information . There ' s also a corresponding @ ref magnum - sceneconverter " scene conversion utility " .
@ section magnum - imageconverter - usage U sage
@ section magnum - imageconverter - example Example u sage
@ code { . sh }
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 ] [ - - color on | off | auto ] [ - v | - - verbose ] [ - - profile ] [ - - ] input output
@ endcode
Listing contents of a cubemap DDS file with mipmaps , implicitly using
@ relativeref { Trade , AnyImageImporter } that delegates to
@ relativeref { Trade , DdsImporter } or
@ ref file - formats " any other plugin capable of DDS import " depending on what ' s
available :
Arguments :
@ m_class { m - code - figure }
- ` 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 :
@ ref Trade : : AnyImageImporter " AnyImageImporter " )
- ` - C ` , ` - - converter PLUGIN ` - - - image converter plugin ( default :
@ ref Trade : : AnyImageConverter " 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 ` - - - 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
@ parblock
Specifying ` - - importer raw : & lt ; format & gt ; ` will treat the input as a raw
tightly - packed square of pixels in given @ ref PixelFormat . Specifying ` - C ` /
` - - converter raw ` will save raw imported data instead of using a converter
plugin .
@ code { . sh }
magnum - imageconverter - - info cubemap . dds
@ endcode
If ` - - info ` is given , the utility will print information about all images
present in the file , independently of the ` - D ` / ` - - dimensions ` option . In this
case no conversion is done and output file doesn ' t need to be specified .
< b > < / b >
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
` / ` .
@ m_class { m - nopad }
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 , @ relativeref { Trade , AnyImageConverter } is used to
save its output ; if no ` - C ` / ` - - converter ` is specified ,
@ relativeref { Trade , AnyImageConverter } is used .
@ include imageconverter - info . ansi
@ section magnum - imageconverter - example Usage examples
@ endparblock
Converting a JPEG file to a PNG :
Converting a JPEG file to a PNG , implicitly using
@ relativeref { Trade , AnyImageConverter } that delegates to
@ relativeref { Trade , PngImageConverter } , @ relativeref { Trade , StbImageConverter } or
@ ref file - formats " any other plugin capable of PNG export " depending on what ' s
available :
@ code { . sh }
magnum - imageconverter image . jpg image . png
@ endcode
Creating a JPEG file with 95 % quality from a PNG , by setting a plugin - specific
configuration option . The @ relativeref { Trade , AnyImageConverter } plugin is
implicitly used and it proxies the option to either
@ relativeref { Trade , JpegImageConverter } or
@ relativeref { Trade , StbImageConverter } , depending on which one is available :
configuration option that ' s recognized by both
@ ref Trade - JpegImageConverter - configuration " JpegImageConverter " and
@ ref Trade - StbImageConverter - configuration " StbImageConverter " :
@ code { . sh }
magnum - imageconverter image . png image . jpg - c jpegQuality = 0.95
@ endcode
Extracting raw ( uncompressed , compressed ) data from a DDS file for manual
inspection :
Extracting raw ( uncompressed or block - compressed ) data from a DDS file for
manual inspection :
@ code { . sh }
magnum - imageconverter image . dds - - converter raw data . dat
@ -159,17 +119,31 @@ 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 @ relativeref { Trade , AnySceneImporter } or for example directly
the @ relativeref { Trade , TinyGltfImporter } :
@ code { . shell - session }
$ # print a list of all images in the file
$ magnum - imageconverter - I AnySceneImporter - - info file . gltf
2 D image 0 : PixelFormat : : RGBA8Unorm Vector ( 2048 , 2048 )
2 D image 1 : PixelFormat : : RGBA8Unorm Vector ( 2048 , 2048 )
2 D image 2 : PixelFormat : : RGBA8Unorm Vector ( 2048 , 2048 )
…
$ # extract the third image to a PNG file for inspection
$ magnum - imageconverter - I AnySceneImporter - - image 2 file . gltf image . png
the @ relativeref { Trade , GltfImporter } . First printing a list of images to choose
from :
@ m_class { m - code - figure }
@ parblock
@ code { . sh }
magnum - imageconverter - I AnySceneImporter - - info file . gltf
@ endcode
< b > < / b >
@ m_class { m - nopad }
@ include imageconverter - info - gltf . ansi
@ endparblock
@ m_class { m - noindent }
and then extracting the third image to a PNG file for inspection :
@ code { . sh }
magnum - imageconverter - I AnySceneImporter - - image 2 file . gltf image . png
@ endcode
Converting a PNG file to a KTX2 , block - compressing the data to BC3 using
@ -209,7 +183,71 @@ file again:
magnum - imageconverter cube - mips . exr - - layer 2 - - level 1 + x - 128. exr
@ endcode
@ see @ ref magnum - sceneconverter
@ section magnum - imageconverter - usage Full usage documentation
@ code { . sh }
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 ] [ - - color on | off | auto ] [ - v | - - verbose ] [ - - profile ] [ - - ] input output
@ endcode
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 :
@ ref Trade : : AnyImageImporter " AnyImageImporter " )
- ` - C ` , ` - - converter PLUGIN ` - - - image converter plugin ( default :
@ ref Trade : : AnyImageConverter " 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 ` - - - 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 : & lt ; format & gt ; ` will treat the input as a raw
tightly - packed square of pixels in given @ ref PixelFormat . Specifying ` - C ` /
` - - 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 , independently of the ` - D ` / ` - - dimensions ` option . 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
` / ` .
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 , @ relativeref { Trade , AnyImageConverter } is used to
save its output ; if no ` - C ` / ` - - converter ` is specified ,
@ relativeref { Trade , AnyImageConverter } is used .
*/
}
Vladimír Vondruš
4 years ago