UVAtlasTool

This UVAtlas sample is an implementation of the uvatlas command-line sample from the legacy DirectX SDK using UVAtlas, DirectXTex, and DirectXMesh rather than the deprecated D3DX library. This tool imports geometry and generates an isochart mesh.

The original tool imported from legacy X files. This version imports from WaveFront Object (OBJ) or VBO files.

Syntax

UVAtlasTool.exe uses the following command syntax:

uvatlastool [options] [--file-list <filename>] <file-name(s)>

The command-line parsing uses Windows-style - or / for options. It also has some POSIX-like behavior: it supports --version and --help command-line options, and the use of -- disables further options parsing to support filenames that begin with - or / characters. There are 'GNU long options' style command-line parameters that use -- as well.

Optional Switches Description

File options

-r: Input file names can contain wildcard characters (? or *). If this switch is used, subdirectories are also searched.

The legacy DirectX SDK sample used -s. We use -r to be more consistent with other command-line tools.

-flist filename, --file-type filename: Uses the provided filename as a text file containing a list of input files (one per line). Ignores lines that begin with # (used for comments). Does not support providing additional command-line arguments or the use of filename wildcards.

-o filename: specifies output filename which is otherwise generated from the input file name. Use of this switch supports only one input file.

-l, --to-lowercase: Forces the output path & filename to all lower-case. Windows file system is case-insensitive by default, but some programs like git are case-sensitive.

-y, --overwrite: overwrite existing output file if any. By default, the tool will abort if the output file already exists.

ISOChart options

-q level, --quality level: sets quality level to DEFAULT, FAST or QUALITY. With DEFAULT, the tool uses QUALITY for meshes below a threshold, and FAST otherwise.

-n number, --max-charts number: sets the maximum number of charts to generate. The default of 0 uses max-stretch as the limit. Note this is a soft limit.

-st float, --max-stretch float: sets the maximum amount of stretch 0.0..1.0, defaulting to 0.16667

-g float, --gutter-width float: this is the gutter width between charts in texels, which defaults to 2.0

-lms / --limit-merge-stretch, -lfs / --limit-face-stretch: Limits on merge stretching and/or face stretching. These are artist control toggles that are generally useful when long triangles are grouped with uniformly sized triangles.

-w / --width, -h / --height: number texture width/height for the atlas, defaults to 512x512.

-ta, --topological-adjacency: when generating adjacency use topological adjacency (the default)
-ga, --geometric-adjacency: when generating adjacency use geometric adjacency (uses epsilon of 1e-5f)

-it filename, --imt-tex-file filename: calculates IMT for the mesh using this texture file using dds, tga, hdr, or a WIC-supported format (bmp, jpg, png, jxr, etc.).

-iv channel, --imt-vertex channel: calculates IMT using per-vertex data where channel is NORMAL, COLOR, or TEXCOORD

Additional output options

-c, --color-mesh: generate mesh with colors showing charts (replaces the materials set and attributes in the output).

-t, --uv-mesh: generates a separate mesh with uvs as position information to allow visualization of the isochart. Output name has _texture appended. If you also specify -vn the output mesh will have per-vertex colors for visualization of the normals as well.

-m, --output-remap: generates a text file which provides the vertex remapping in the form of newIndex,oldIndex for each vertex in the output mesh. Output name has _map.txt appended.

Normal/Tangent options

-n, --normal-by-angle: generate normals weighted by angle
-na, --normal-by-area: generate normals weighted by area
-ne, --normal-by-equal: generate normals weighted equally

-tt, --tangents: generate tangents.
-tb, --tangent-frame: generate tangents and bi-tangents (aka bi-normals).

-fn format, --normal-format format: Sets the format for writing vertex normals/tangents/bi-normals for SDKMESH output: float3 (the default), float16_4, or r11g11b10 (x2 biased). This switch is not supported by CMO or VBO.

-cw, --clockwise: faces are clockwise (defaults to counter-clockwise) for generating normal

Face-winding options

-flip, --flip-face-winding: reverses the winding of faces

Texture coordinate options

--flip-u: inverts the u texture coordinate
--flip-v: inverts the v texture coordinate (Direct3D vs. OpenGL image orientation)

-uv2: If the model already has a texture coordinate channel, then the isochart uvs are placed into a second channel. This is only supported for SDKMESH.

Vertex/index options

--flip-z: negates the z component (RH vs. LH view systems)

-ib32, --index-buffer-32-bit: Forces the use of 32-bit indices for SDKMESH output. By default it will attempt to write 16-bit indices if possible. This switch is not supported by CMO or VBO.

-fuv format, --uv-format format: Sets the format for writing vertex texture coordinates for SDKMESH output: float2 (the default) or float16_2. This switch is not supported by CMO or VBO.

-fc format, --color-format format: Sets the format for writing vertex color for SDKMESH output: bgra (the default), rgba, float4, float16_4, rgba_10 or r11g11b10. This switch is not supported by CMO or VBO.

Output format options

-ft file-type, --file-type file-type: A file type for the output texture. Use one of the following. The default value is dds.

• sdkmesh: output an SDKMESH file (the default)
• sdkmesh2: output an SDKMESH file with PBR materials
• cmo: output a Visual Studio CMO file (requires normals, tangents and texture coordinates)
• vbo: output a VBO file (requires normals and texture coordinates)
• obj: output a WaveFront Object OBJ file

-nodds: prevents extension renaming in exported materials. By default, texture filenames are converted from an existing image extension to .dds assuming they are going to be processed by 'texconv'. This flag prevents the renaming and leaves the original extension.

Miscellaneous options

-nologo: suppress copyright message.

Example

uvatlastool cup.obj -t -c

This loads the geometry in a Wavefront OBJ file 'cup.obj', generates normals (using weight by angle), generates an isochart, and then writes the result to cup.sdkmesh as well as a visualization to cup_texture.sdkmesh both using a material set that colors each face by which chart it belongs to in the atlas.

Remarks

Support for OpenEXR (EXR) can be added to the uvatlas utility for the -it switch. Uncomment #define USE_OPENEXR in the source, and add the DirectXTex auxiliary module to the project. See Adding OpenEXR for more details including building the OpenEXR library.