From dcfa07a0561d3fe7a0ebd27b2adebecca2c03a6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Fri, 10 Jun 2022 19:07:43 +0200 Subject: [PATCH] doc: overhaul documentation of console utilities. The boring dry usage info grew significantly, and listing it as the first thing on the page would scare people off. Put the examples first instead, and for the imageconverter and sceneconverter add --info listing examples, as that's what is eye-catchy. --- doc/snippets/imageconverter-info-gltf.ansi | 11 + doc/snippets/imageconverter-info.ansi | 8 + doc/snippets/sceneconverter-info.ansi | 24 +++ src/Magnum/SceneTools/sceneconverter.cpp | 77 ++++--- src/Magnum/ShaderTools/shaderconverter.cpp | 47 +++-- src/Magnum/Text/fontconverter.cpp | 42 ++-- .../TextureTools/distancefieldconverter.cpp | 32 +-- src/Magnum/Trade/imageconverter.cpp | 196 +++++++++++------- 8 files changed, 272 insertions(+), 165 deletions(-) create mode 100644 doc/snippets/imageconverter-info-gltf.ansi create mode 100644 doc/snippets/imageconverter-info.ansi create mode 100644 doc/snippets/sceneconverter-info.ansi diff --git a/doc/snippets/imageconverter-info-gltf.ansi b/doc/snippets/imageconverter-info-gltf.ansi new file mode 100644 index 000000000..f62721739 --- /dev/null +++ b/doc/snippets/imageconverter-info-gltf.ansi @@ -0,0 +1,11 @@ +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) +… diff --git a/doc/snippets/imageconverter-info.ansi b/doc/snippets/imageconverter-info.ansi new file mode 100644 index 000000000..ac53ebc69 --- /dev/null +++ b/doc/snippets/imageconverter-info.ansi @@ -0,0 +1,8 @@ +3D image 0: + Level 0: {512, 512, 6} @ Bc3RGBAUnorm (1536.0 kB) + Level 1: {256, 256, 6} @ Bc3RGBAUnorm (384.0 kB) + Level 2: {128, 128, 6} @ Bc3RGBAUnorm (96.0 kB) + Level 3: {64, 64, 6} @ Bc3RGBAUnorm (24.0 kB) + Level 4: {32, 32, 6} @ Bc3RGBAUnorm (6.0 kB) + Level 5: {16, 16, 6} @ Bc3RGBAUnorm (1.5 kB) +Total image data size: 2047.5 kB diff --git a/doc/snippets/sceneconverter-info.ansi b/doc/snippets/sceneconverter-info.ansi new file mode 100644 index 000000000..f23a5baf7 --- /dev/null +++ b/doc/snippets/sceneconverter-info.ansi @@ -0,0 +1,24 @@ +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 diff --git a/src/Magnum/SceneTools/sceneconverter.cpp b/src/Magnum/SceneTools/sceneconverter.cpp index 30d61a00c..1219d75ba 100644 --- a/src/Magnum/SceneTools/sceneconverter.cpp +++ b/src/Magnum/SceneTools/sceneconverter.cpp @@ -61,6 +61,7 @@ namespace Magnum { @brief Converts scenes of different formats @m_since{2020,06} +@tableofcontents @m_footernavigation @m_keywords{magnum-sceneconverter sceneconverter} @@ -76,9 +77,53 @@ add_custom_command(OUTPUT ... COMMAND Magnum::sceneconverter ...) @endcode See @ref building and @ref cmake and the @ref Trade namespace for more -information. +information. There's also a corresponding @ref magnum-imageconverter "image conversion utility". -@section magnum-sceneconverter-usage Usage +@section magnum-sceneconverter-example Example usage + +Listing contents of a glTF file, implicitly using +@relativeref{Trade,AnySceneImporter} that delegates to +@relativeref{Trade,GltfImporter}, @relativeref{Trade,AssimpImporter} or +@ref file-formats "any other plugin capable of glTF import" depending on what's +available: + +@m_class{m-code-figure} + +@parblock + +@code{.sh} +magnum-sceneconverter --info Box.gltf +@endcode + + + +@m_class{m-nopad} + +@include sceneconverter-info.ansi + +@endparblock + +Converting an OBJ file to a PLY, implicitly using +@relativeref{Trade,AnySceneConverter} that delegates to +@relativeref{Trade,StanfordSceneConverter} or +@ref file-formats "any other plugin capable of PLY export" depending on what's +available: + +@code{.sh} +magnum-sceneconverter chair.obj chair.ply +@endcode + +Processing an OBJ file with @relativeref{Trade,MeshOptimizerSceneConverter}, +setting @ref Trade-MeshOptimizerSceneConverter-configuration "plugin-specific configuration options" +to reduce the index count to half, saving as a PLY, with verbose output showing +the processing stats: + +@code{.sh} +magnum-sceneconverter chair.obj -C MeshOptimizerSceneConverter \ + -c simplify=true,simplifyTargetIndexCountThreshold=0.5 chair.ply -v +@endcode + +@section magnum-sceneconverter-usage Full usage documentation @code{.sh} magnum-sceneconverter [-h|--help] [-I|--importer PLUGIN] @@ -171,34 +216,6 @@ scene hierarchy transformation baked in using @ref SceneTools::flattenMeshHierarchy3D(). Only attributes that are present in the first mesh are taken, if `--only-attributes` is specified as well, the IDs reference attributes of the first mesh. - -@section magnum-sceneconverter-example Example usage - -Printing info about all meshes in a glTF file: - -@code{.sh} -magnum-sceneconverter --info scene.gltf -@endcode - -Converting an OBJ file to a PLY, using @ref Trade::StanfordSceneConverter "StanfordSceneConverter" -picked by @ref Trade::AnySceneConverter "AnySceneConverter": - -@code{.sh} -magnum-sceneconverter chair.obj chair.ply -@endcode - -Processing an OBJ file with @ref Trade::MeshOptimizerSceneConverter "MeshOptimizerSceneConverter", -setting @ref Trade-MeshOptimizerSceneConverter-configuration "plugin-specific configuration options" -to reduce the index count to half, saving as a PLY, with verbose output showing -the processing stats: - -@m_class{m-console-wrap} - -@code{.sh} -magnum-sceneconverter chair.obj --converter MeshOptimizerSceneConverter -c simplify=true,simplifyTargetIndexCountThreshold=0.5 chair.ply -v -@endcode - -@see @ref magnum-imageconverter */ } diff --git a/src/Magnum/ShaderTools/shaderconverter.cpp b/src/Magnum/ShaderTools/shaderconverter.cpp index dd2d69f1d..2abf0eca1 100644 --- a/src/Magnum/ShaderTools/shaderconverter.cpp +++ b/src/Magnum/ShaderTools/shaderconverter.cpp @@ -42,6 +42,7 @@ namespace Magnum { @brief Converts, compiles, optimizes and links shaders of different formats @m_since_latest +@tableofcontents @m_footernavigation @m_keywords{magnum-shaderconverter shaderconverter} @@ -59,7 +60,31 @@ add_custom_command(OUTPUT ... COMMAND Magnum::shaderconverter ...) See @ref building, @ref cmake and the @ref ShaderTools namespace for more information. -@section magnum-shaderconverter-usage Usage +@section magnum-shaderconverter-example Example usage + +Validate a SPIR-V file for a Vulkan 1.1 target, implicitly using +@ref ShaderTools::AnyConverter "AnyShaderConverter" that delegates to +@ref ShaderTools::SpirvToolsConverter "SpirvToolsShaderConverter" or +@ref file-formats "any other plugin capable of SPIR-V validation" depending on +what's available: + +@code{.sh} +magnum-shaderconverter --validate --output-version vulkan1.1 shader.spv +@endcode + +Converting a GLSL 4.10 file to a SPIR-V, supplying various preprocessor +definitions, treating warnings as errors and targeting OpenGL instead of the +(default) Vulkan, this time delegated to @ref ShaderTools::GlslangConverter "GlslangShaderConverter" +or @ref file-formats "any other plugin capable of GLSL->SPIR-V conversion" +depending on what's available: + +@code{.sh} +magnum-shaderconverter phong.frag phong.frag.spv \ + -DDIFFUSE_TEXTURE -DNORMAL_TEXTURE --warning-as-error \ + --input-version "410 core" --output-version opengl4.5 +@endcode + +@section magnum-shaderconverter-usage Full usage documentation @code{.sh} magnum-shaderconverter [-h|--help] [--validate] [--link] @@ -146,26 +171,6 @@ Values accepted by `-O` / `--optimize`, `-g` / `--debug-info`, `--input-format`, converter-specific, see documentation of a particular converter for more information. -@section magnum-shaderconverter-example Example usage - -Validate a SPIR-V file for a Vulkan 1.1 target, using -@ref ShaderTools::SpirvToolsConverter "SpirvToolsShaderConverter" picked by -@ref ShaderTools::AnyConverter "AnyShaderConverter": - -@code{.sh} -magnum-shaderconverter --validate --output-version vulkan1.1 shader.spv -@endcode - -Converting a GLSL 4.10 file to a SPIR-V, supplying various preprocessor -definitions, treating warnings as errors and targeting OpenGL instead of the -(default) Vulkan, using @ref ShaderTools::GlslangConverter "GlslangShaderConverter" -picked again by @ref ShaderTools::AnyConverter "AnyShaderConverter": - -@m_class{m-console-wrap} - -@code{.sh} -magnum-shaderconverter phong.frag -DDIFFUSE_TEXTURE -DNORMAL_TEXTURE --input-version "410 core" --output-version opengl4.5 --warning-as-error phong.frag.spv -@endcode */ } diff --git a/src/Magnum/Text/fontconverter.cpp b/src/Magnum/Text/fontconverter.cpp index 0c81d7cd0..ba007a1c6 100644 --- a/src/Magnum/Text/fontconverter.cpp +++ b/src/Magnum/Text/fontconverter.cpp @@ -62,6 +62,7 @@ namespace Magnum { @page magnum-fontconverter Font conversion utility @brief Converts font to raster one of given atlas size +@tableofcontents @m_footernavigation @m_keywords{magnum-fontconverter fontconverter} @@ -78,7 +79,27 @@ add_custom_command(OUTPUT ... COMMAND Magnum::fontconverter ...) See @ref building, @ref cmake and the @ref Text namespace for more information. -@section magnum-fontconverter-usage Usage +@note This executable is available only if Magnum is compiled with + @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features + for more information. + +@section magnum-fontconverter-example Example usage + +Making raster font from TTF file with default set of characters using +@ref Text::FreeTypeFont "FreeTypeFont" font plugin and +@ref Text::MagnumFontConverter "MagnumFontConverter" converter plugin: + +@code{.sh} +magnum-fontconverter DejaVuSans.ttf myfont \ + --font FreeTypeFont --converter MagnumFontConverter +@endcode + +According to @ref Text::MagnumFontConverter "MagnumFontConverter" plugin +documentation, this will generate files `myfont.conf` and `myfont.tga` in +current directory. You can then load and use them via the +@ref Text::MagnumFont "MagnumFont" plugin. + +@section magnum-fontconverter-usage Full usage documentation @code{.sh} magnum-fontconverter [--magnum-...] [-h|--help] --font FONT @@ -107,25 +128,6 @@ Arguments: The resulting font files can be then used as specified in the documentation of `converter` plugin. - -@section magnum-fontconverter-example Example usage - -Making raster font from TTF file with default set of characters using -@ref Text::FreeTypeFont "FreeTypeFont" font plugin and -@ref Text::MagnumFontConverter "MagnumFontConverter" converter plugin: - -@code{.sh} -magnum-fontconverter --font FreeTypeFont --converter MagnumFontConverter DejaVuSans.ttf myfont -@endcode - -According to @ref Text::MagnumFontConverter "MagnumFontConverter" plugin -documentation, this will generate files `myfont.conf` and `myfont.tga` in -current directory. You can then load and use them via the -@ref Text::MagnumFont "MagnumFont" plugin. - -@note This executable is available only if Magnum is compiled with - @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features - for more information. */ namespace Text { diff --git a/src/Magnum/TextureTools/distancefieldconverter.cpp b/src/Magnum/TextureTools/distancefieldconverter.cpp index 5aad73f6a..81b846f3b 100644 --- a/src/Magnum/TextureTools/distancefieldconverter.cpp +++ b/src/Magnum/TextureTools/distancefieldconverter.cpp @@ -69,6 +69,7 @@ namespace Magnum { /** @page magnum-distancefieldconverter Distance Field conversion utility @brief Converts red channel of an image to distance field representation +@tableofcontents @m_footernavigation @m_keywords{magnum-distancefieldconverter distancefieldconverter} @@ -86,7 +87,22 @@ add_custom_command(OUTPUT ... COMMAND Magnum::distancefieldconverter ...) See @ref building, @ref cmake and the @ref TextureTools namespace for more information. -@section magnum-distancefieldconverter-usage Usage +@note This executable is available only if Magnum is compiled with + @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features + for more information. + +@section magnum-distancefield-example Example usage + +@code{.sh} +magnum-distancefieldconverter logo-src.png logo.png \ + --output-size "256 256" --radius 24 +@endcode + +This will open monochrome `logo-src.png` image using any plugin that can open +PNG files and converts it to 256x256 distance field `logo.png` using any plugin +that can write PNG files. + +@section magnum-distancefieldconverter-usage Full usage documentation @code{.sh} magnum-distancefieldconverter [--magnum-...] [-h|--help] [--importer IMPORTER] @@ -115,20 +131,6 @@ Images with @ref PixelFormat::R8Unorm, @ref PixelFormat::RGB8Unorm or The resulting image can be then used with @ref Shaders::DistanceFieldVectorGL shader. See also @ref TextureTools::DistanceField for more information about the algorithm and parameters. - -@section magnum-distancefield-example Example usage - -@code{.sh} -magnum-distancefieldconverter --output-size "256 256" --radius 24 logo-src.png logo.png -@endcode - -This will open monochrome `logo-src.png` image using any plugin that can open -PNG files and converts it to 256x256 distance field `logo.png` using any plugin -that can write PNG files. - -@note This executable is available only if Magnum is compiled with - @ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features - for more information. */ namespace TextureTools { diff --git a/src/Magnum/Trade/imageconverter.cpp b/src/Magnum/Trade/imageconverter.cpp index 810bd4869..f17e00151 100644 --- a/src/Magnum/Trade/imageconverter.cpp +++ b/src/Magnum/Trade/imageconverter.cpp @@ -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 Usage +@section magnum-imageconverter-example Example usage -@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:<format>` 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. + -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 -2D image 0: PixelFormat::RGBA8Unorm Vector(2048, 2048) -2D image 1: PixelFormat::RGBA8Unorm Vector(2048, 2048) -2D 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 + + + +@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:<format>` 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. */ }