/** @file dox_cmd.h * @brief General documentation for assimp_cmd */ //---------------------------------------------------------------------------------------------- // ASSIMP CMD MAINPAGE /** @mainpage ASSIMP Command-line tools @section intro Introduction This document describes the usage of assimp's command line tools. This is *not* the SDK reference and programming-related stuff is not covered here.

NOTE: For simplicity, the following sections are written with Windows in mind. However it's not different for Linux/Mac at all, except there's probably no assimp.exe ... @section basic_use Basic use Open a command prompt and navigate to the directory where assimp.exe resides. The basic command line is: @code assimp [command] [parameters] @endcode The following commands are available:
@link version version @endlink Retrieve the current version of assimp
@link help help @endlink Get a list of all commands (yes, it's this list ...)
@link dump dump @endlink Generate a human-readable text dump of a model
@link extract extract @endlink Extract an embedded texture image
@link iinfo info @endlink Load a model and print basic statistics
@link cmpdump cmpdump @endlink Regression checking tool
If you use assimp's command line frequently, consider adding assimp to your PATH environment. */ /** @page version 'version'-Command Display the version/revision of Assimp used. */ /** @page help 'help'-Command Display a really helpful text. */ //---------------------------------------------------------------------------------------------- // ASSIMP INFO /** @page iinfo 'info'-Command Load a model file and print basic statistics. Full postprocessing is applied unless the -r switch is specified. Sample output (assimp info ./test/models/3DS/mar_rifle.3ds): @verbatim Launching model import ... OK Validating postprocessing flags ... OK Importing file ... OK import took approx. 0.02400 seconds Memory consumption: 69444 B Nodes: 2 Maximum depth 2 Meshes: 1 Animations: 0 Textures (embed.): 0 Materials: 1 Cameras: 0 Lights: 0 Vertices: 843 Faces: 572 Bones: 0 Animation Channels: 0 Primitive Types: triangles Average faces/mesh 572 Average verts/mesh 843 Minimum point (-3.522588 -11.573204 -40.340359) Maximum point (3.522622 30.196556 75.941292) Center point (0.000017 9.311676 17.800467) Named Materials: 'mat1' Texture Refs: 'm_rifl.bmp' Node hierarchy: '<3DSRoot>', meshes: 0 -- 'm_rifle', meshes: 1 <-- @endverbatim

Syntax:

@code assimp info file [-r] @endcode

Parameters:

file

Required. Input file.

-r
Optional. Don't perform any postprocessing. The long form of this parameter is --raw.

*/ //---------------------------------------------------------------------------------------------- // ASSIMP CMPDUMP /** @page cmpdump 'cmpdump'-Command Used for Assimp's internal regression testing. Compare two mini dumps (produced using assimp dump .. -b -s) and report any differences. In the regression test suite, this facility is used to build a database of 'known-to-be-fine' mini dumps, which are regularly compared against current results to detect regressions.

Syntax:

@code assimp cmpdmp actual expected @endcode

Parameters:

actual

Required. Mini dump now.

expected

Required. Archived dump from some point in the past.

*/ //---------------------------------------------------------------------------------------------- // ASSIMP DUMP /** @page dump 'dump'-Command Generate a text or binary dump of a model. This is the core component of Assimp's internal regression test suite but it could also be useful for other developers to quickly examine the contents of a model. Note that text dumps are not intended to be used as intermediate format, Assimp is not able to read them again, nor is the file format stable or well-defined. It may change with every revision without notice. Binary dumps (*.assbin) are backwards- and forwards-compatible.

Syntax:

@code assimp dump [] [-b] [-s] [common parameters] @endcode

Parameters:

model

Required. Relative or absolute path to the input model.

out

Optional. Relative or absolute path to write the output dump to. If it is omitted, the dump is written to <model>-dump.txt

-b

Optional. If this switch is specified, the dumb is written in binary format. The long form of this parameter is --binary.

-s<n>

Optional. If this switch is specified, the dumb is shortened to include only min/max values for all vertex components and animation channels. The resulting file is much smaller, but the original model can't be reconstructed from it. This is used by Assimp's regression test suite, comparing those minidumps provides a fast way to verify whether a loader works correctly or not. The long form of this parameter is --short.

common parameters

Optional. Import configuration & postprocessing. See the @link common common parameters page @endlink for more information.


Sample:

@code assimp dump test.3ds test.txt -l -cfull assimp dump test.3ds test.txt -include-log -config=full @endcode Dumps 'test.3ds' to 'test.txt' after executing full post-processing on tehe imported data. The log output is included with the dump. @code assimp dump files\*.* assimp dump files\*.* @endcode Dumps all loadable model files in the 'files' subdir. The output dumps are named -dump.txt. The log is not included. */ //---------------------------------------------------------------------------------------------- // ASSIMP EXTRACT /** @page extract 'extract'-Command Extracts one or more embedded texture images from models.

Syntax:

@code assimp extract [] [-t] [-f] [-ba] [-s] [common parameters] @endcode

Parameters:

model

Required. Relative or absolute path to the input model.

out

Optional. Relative or absolute path to write the output images to. If the file name is omitted the output images are named
The suffix _img<n> is appended to the file name if the -s switch is not specified (where <n> is the zero-based index of the texture in the model file).
The output file format is determined from the given file extension. Supported formats are BMP and TGA. If the file format can't be determined, the value specified with the -f switch is taken.
Format settings are ignored for compressed embedded textures. They're always written in their native file format (e.g. jpg).

-t<n>

Optional. Specifies the (zero-based) index of the embedded texture to be extracted from the model. If this option is *not* specified all textures found are exported. The long form of this parameter is --texture=<n>.

-ba<n>

Optional. Specifies whether output BMPs contain an alpha channel or not. The long form of this parameter is --bmp-with-alpha=<n>.

-f<n>

Optional. Specifies the output file format. Supported formats are BMP and TGA. The default value is BMP (if a full output filename is specified, the output file format is taken from its extension, not from here). The long form of this parameter is --format=<n>.

-s<n>

Optional. Prevents the tool from adding the _img<n> suffix to all filenames. This option must be specified together with -t to ensure that just one image is written. The long form of this parameter is --nosuffix.

common parameters

Optional. Import configuration & postprocessing. Most postprocessing-steps don't affect embedded texture images, configuring too much is probably senseless here. See the @link common common parameters page @endlink for more information.


Sample:

@code assimp extract test.mdl test.bmp --texture=0 --validate-data-structure assimp extract test.mdl test.bmp -t=0 -vds @endcode Extracts the first embedded texture (if any) from test.mdl after validating the imported data structure and writes it to test_img0.bmp. @code assimp extract files\*.mdl *.bmp assimp extract files\*.mdl *.bmp @endcode Extracts all embedded textures from all loadable .mdl files in the 'files' subdirectory and writes them to bitmaps which are named _img.bmp */ //---------------------------------------------------------------------------------------------- // ASSIMP COMMON PARAMETERS /** @page common Common parameters The parameters described on this page are commonly used by almost every assimp command. They specify how the library will postprocess the imported data. This is done by several configurable pipeline stages, called 'post processing steps'. Below you can find a list of all supported steps along with short descriptions of what they're doing.
Programmers: more information can be found in the aiPostProcess.h header.
Parameter Long parameter Description
-ptv --pretransform-vertices Move all vertices into worldspace and collapse the scene graph. Animation data is lost. This is intended for applications which don't support scenegraph-oriented rendering.
-gsn --gen-smooth-normals Computes 'smooth' per-vertex normal vectors if necessary. Mutually exclusive with -gn
-gn --gen-normals Computes 'hard' per-face normal vectors if necessary. Mutually exclusive with -gsn
-cts --calc-tangent-space If one UV channel and normal vectors are given, compute tangents and bitangents
-jiv --join-identical-vertices Optimize the index buffer. If this flag is not specified all vertices are referenced once.
-rrm --remove-redundant-materials Remove redundant materials from the imported data.
-fd --find-degenerates Find and process degenerates primitives.
-slm --split-large-meshes Split large meshes over a specific threshold in smaller sub meshes. The default vertex & face limit is 1000000
-lbw --limit-bone-weights Limit the number of bones influencing a single vertex. The default limit is 4.
-vds --validate-data-structure Performs a full validation of the imported data structure. Recommended to avoid crashes if an import plugin produces rubbish
-icl --improve-cache-locality Improve the cache locality of the vertex buffer by reordering the index buffer to achieve a lower ACMR (average post-transform vertex cache miss ratio)
-sbpt --sort-by-ptype Splits meshes which consist of more than one kind of primitives (e.g. lines and triangles mixed up) in 'clean' submeshes.
-lh --convert-to-lh Converts the imported data to left-handed coordinate space
-fuv --flip-uv Flip UV coordinates from upper-left origin to lower-left origin
-fwo --flip-winding-order Flip face winding order from CCW to CW
-ett --evaluate-texture-transform Evaluate per-texture UV transformations (e.g scaling, offset) and build pretransformed UV channels
-guv --gen-uvcoords Replace abstract mapping descriptions, such as 'spherical' or 'cylindrical' with proper UV channels
-fixn --fix-normals Run a heuristic algorithm to detect meshes with wrong face winding order/normals.
-tri --triangulate Triangulate poylgons with 4 and more points. Lines, points and triangles are not affected.
-fi --find-instances Search the data structure for instanced meshes and replace them by references. This can reduce vertex/face counts but the postprocessing-step takes some time.
-og --optimize-graph Simplify and optimize the scenegraph. Use it with care, all hierarchy information could be lost. Animations remain untouched.
-om --optimize-mesh Optimize mesh usage. Meshes are merged, if possible. Very effective in combination with --optimize-graph
For convenience some default postprocessing configurations are provided. The corresponding command line parameter is -c<name> (or --config=<name>).
Name Description List of steps executed
fast Fast post processing config, performs some essential optimizations and computes tangents -cts, -gn, -jiv, -tri, -guv, -sbpt
default Balanced post processing config; performs most optimizations -cts, -gsn, -jiv, -icl, -lbw, -rrm, -slm, -tri, -guv, -sbpt, -fd, -fiv
full Full post processing. May take a while but results in best output quality for most purposes -cts, -gsn, -jiv, -icl, -lbw, -rrm, -slm, -tri, -guv, -sbpt, -fd, -fiv, -fi, -vds -om
The -tuv, -ptv, -og flags always need to be enabled manually. There are also some common flags to customize Assimp's logging behaviour:
Name Description
-l or --show-log Show log file on console window (stderr)
-lo<file> or --log-out=<file> Streams the log to <file>
-v or --verbose Enables verbose logging. Debug messages will be produced too. This might decrease loading performance and result in *very* long logs ... use with caution if you experience strange issues.
*/