MeshOptimizer v2.1.9

Owned by Jure Ratkovic
Nov 03, 2023
19 min read

Released on 11/06/2023

Release Notes

  • Features

    • Added the --preserve_draco flag which adds Draco on glTF output if it was present on input

    • Added --remove_morph_animations flag which removes morph animations only

    • Added --textureless_small_features flag

      • Bakes small features as textureless double sided quads with single color vertices

      • --no_vtx_color_small_features bakes colors in material factors instead of vertex colors

    • Added --dont_export_flat_normals flag which doesn’t export flat glTF normals

  • Improvements

    • Image processing performance improvements, including cropping, resizing, alpha cleanup and sRGB conversion

    • Improved OBJ loading performance by a factor of ~4x

  • Bug fixes

    • Fixed --scale_size, --scale_dimension and --rotation flags

    • Fixed ray casts sometimes missing AABBs

    • Fixed decimation being able to produce degenerate triangles

    • Fixed a bug with invalid tangents being being produced

    • Fixed imprecisions in small feature baking

System Requirements

CLI Documentation

Basic Usage

Use --version to print the version and your license information.

Basic usage:

> MeshOptimizer [OPTIONS] -f <path_to_input_file> -o <path_to_output_file>

Use --help to get a list of all available command line flags. Currently the --help output is as follows:

Options: -h,--help Print this help message and exit --config,--ini Read an ini file --version Display program version information and exit -o,--output_file TEXT Output filename. If it is not provided, it is auto-generated. [Option Group: Required] Required options [At least 1 of the following options are required] Options: --dump_config{} Dumps the config file set from current settings (without the input file and output file if given) and immediately exits. Config is either written to console or to file if filepath is provided. E.g. --dump_config config.TOML will write the current settings to config.TOML file. -f,--input_file TEXT Filename to process. [Option Group: debug_level] Debug Level Options: --debug_after_each_task Output .glb after each task in sequence. --dbg_fbx_ascii Convert loaded fbx to ascii without any optimizer processing. [Option Group: optimization_level] Optimization Level [At most 1 of the following options are allowed] Options: -i,--info Output only the .json file with model details and quit. -c,--convert -c0: Convert only (no optimization). Same as -c. -c1: Convert only, one level up from '-c' (import/export to/from the internal Scene). -c2: Everything except decimation. --tris INT:POSITIVE [50000] Target triangle count, enables decimation. [Option Group: opt_params] Optimization Params Options: --skip_mesh_merger Skip mesh merging. --skip_decimation Needs: --tris Skip geometry decimation. --ignore_parallel_geometry Skip extra steps that ensure that nearby parallel layers are transformed with the same decimation operations. Appropriate for apparel and footwear CAD assets. --ignore_crossing_check Skip extra steps that prevent decimation to create new intersections. --remove_obstructed_geometry Remove geometry that is obstructed. --bake_small_features Detect and bake small features into textured quads. --textureless_small_features Needs: --bake_small_features Bake small features as textureless quads with flat normals. --no_vtx_color_small_features Needs: --textureless_small_features Bake colors in material factors instead of vertex colors for textureless small features. --detect_instances Excludes: --freeze_transforms Detect identical mesh instances. --freeze_transforms Excludes: --detect_instances Bake node transforms into vertex attributes and set all node transforms to identity. Will clone meshes if instances exist. Implicitly turns on --reset_scaling. --allow_zero_accessors Allow glTF accessors that do not reference buffer views in output. --force_float_vert_attribs Forces 4 byte floating point data for all vertex attributes. --embedded_gltf If the requested output is a .gltf and this flag is set, image and geometry data will be embedded in the .gltf file. --dont_export_tangents Tangent vertex attribute won't be exported even if the primitive's material has a normal map. This may cause normals from textures to be oriented incorrectly. --dont_export_flat_normals Excludes: --scanned_model Normal vertex attribute won't be exported if it didn't exist on input (vertex normals are flat). --preserve_empty_nodes Don't remove leaf nodes which don't reference any scene object. --ignore_polygon_intersections Do not split the geometry on intersections. --force_poly_count Don't stop decimation until poly count is hit. This ignores shininess and doesn't bound the error norm. --scanned_model Excludes: --dont_export_flat_normals Perform operations specific to scans like crease smoothing. --file_size_limit FLOAT:POSITIVE Excludes: --skip_tex_opt Enforce output file size limit in MB. --force_file_size_limit Needs: --file_size_limit Don't stop decreasing texture quality until the file size limit is hit. Using this option may severly degrade texture quality. [Option Group: runtime] Runtime Options: -j UINT [32] Number of threads to run. Use -j0 for the single-threaded algorithm. Allocating fewer threads than CPU cores is useful if you want to run other tasks on the machine. -v,--verbose Enable verbose (debug) output. --skip_scene_validation Skip scene data validation that happens after each task. [Option Group: misc] Miscellanious Options: --remove_animations Remove all animations present in the model. --remove_morph_animations Remove morph animations present in the model. --preserve_morph_targets Don't bake non-animated morph targets into meshes. --reset_center{center} :value in { none, center, bottom } The center of the scene is set to the origin of the coordinate system, or the bottom of the scene aabb. Specifying 'none' is the same as not setting the flag. Can use it with -c1, -c2 or with optimization. --reset_scaling Remove reflection transforms from the scene. --remove_cameras Remove any existing cameras from the file. --remove_lights Remove any existing lights from the file. --one_primitive_per_mesh Allow a maximum of one primitive per one mesh in the glTF output. --scale_size FLOAT Size in meters to which model extents will be scaled to. --scale_dimension ENUM:value in { x, y, z, max } Needs: --scale_size Dimension (x, y, z or max) to scale model in. --rotation FLOAT x 3 Rotation [yaw pitch roll] in degrees to apply to model [Option Group: matTex] Texture and Material Settings Options: --convert_spec_gloss Convert glTF's KHR_materials_pbrSpecularGlossiness to standard pbr workflow. --max_tex_size INT [2048] Excludes: --skip_tex_resize Maximum texture size. Textures larger than this size will be scaled down to it. --skip_material_visibility Skip material visibility computation. --pot_textures Force all textures to power of two dimensions. --square_textures Needs: --pot_textures Force all textures to square dimensions. --skip_tex_fill Skip unused texture area filling. --skip_alpha_boost Skip alpha mask boosting designed to prevent alpha tested textures from vanishing at a distance. --aggressive_alpha_removal Relaxes the conditions to remove alpha channels based on alpha value threshold and total opaque area covered by a material. --skip_material_data_cleanup Skip duplicate, unused and redundant material data cleanup. Requires -c1 and --skip_tex_opt. --skip_alpha_mode_cleanup Skip alpha mode cleanup based on uv coverage. --skip_normal_map_sanitization Skip sanitization of normal maps. Most importantly clamping them so that they do not point away from the vertex normals. --skip_normal_baking Excludes: --minimize_materials --force_uv_unwrap Skip normal baking. --max_baking_resolution INT Maximum resolution of textures to be baked. --atlas_padding INT:INT bounded to [0 - 10] Number of pixels to be used in atlas padding. --skip_extra_uv_layer_removal Excludes: --force_one_uv_layer Skip removal of unused and duplicate uv layers. --skip_stray_uv_fixing Skip stray uv polys relocation in order to compactify uv space. --skip_uv_unoverlapping Skip unoverlapping uv polys. This may result in bad texture baking results. --minimize_materials Excludes: --skip_normal_baking Undertake processes which aim to minimize the number of materials present in the output file, potentially at the expense texture space and rendering performance. --atlas_single_color_tex If set, single color textures will be atlassed if possible, instead of being replaced with a material factor. --force_uv_unwrap Excludes: --skip_normal_baking Force unwrapping of tiled UVs --remove_occlusion_maps Remove all ambient occlusion maps from all materials in the input file. --force_alpha_mode ENUM:value in { none, opaque, mask, blend } Force all materials in the scene to the specified alpha mode. none is the default and doesn't change any alpha modes. --force_one_uv_layer Excludes: --skip_extra_uv_layer_removal Remove occlusion maps which use UV layer > 0. Crash if there is more than one UV layer legitimately used in any material. Don't create new UV layers in AO baking. Don't remove existing unused UV0 layers. --skip_duplicate_material_cleanup Needs: --skip_normal_baking Materials which are duplicate (identical) won't be merged into one. [Option Group: texOpt] Texture Optimization Options: --skip_tex_resize Excludes: --max_tex_size Skip texture resizing. --skip_early_tex_resize Skip resizing textures during loading. This may improve texture quality but will drastically increase memory consumption --skip_tex_opt Excludes: --file_size_limit Skip texture optimization. --skip_tex_crop Skip texture cropping. --skip_texel_density Skip texel density based texture resizing. --target_tex_density :POSITIVE Target texel density to be used in texture optimization in pixels/maximum_scene_dimension. If undefined median is used. --tex_opt_compression INT:INT bounded to [0 - 100] [80] Excludes: --lossless_tex_opt Texture compression level, 100 being max quality. --norm_opt_compression INT:INT bounded to [0 - 100] [80] Excludes: --lossless_norm_opt Normal map compression level, 100 being max quality. --mr_opt_compression INT:INT bounded to [0 - 100] Metallic-roughness map compression level, 100 being max quality. If not specified tex_opt_compression will be used. --lossless_tex_opt Excludes: --tex_opt_compression Use lossless texture compression. --lossless_norm_opt Excludes: --norm_opt_compression Use lossless texture compression for normal maps. --skip_atlassing Skip arranging textures into atlases. --use_ktx Needs: --pot_textures Use KTX2 as output texture format, instead of JPEG/PNG. --allow_ktx Needs: --pot_textures Allow KTX2 as output texture format. --alpha_mask_tex_density Enables texel density based resize for alpha mask materials. [Option Group: ao] Ambient Occlusion Baking Options: --skip_ao_baking Excludes: --ao_strength --ao_max_resolution --ao_radius Skip ambient occlusion baking. --ao_strength FLOAT:FLOAT bounded to [0.1 - 3] Excludes: --skip_ao_baking Ambient occlusion strength, higher values mean darker AO. --ao_radius INT:INT bounded to [1 - 20] Excludes: --skip_ao_baking AO baking radius as a percentage of the scene size. --ao_max_resolution INT:INT bounded to [512 - 2048] Excludes: --skip_ao_baking Maximum AO baking resolution. [Option Group: draco] Draco Options: --draco_encode Excludes: --preserve_draco Apply draco compression to output glTF. --allow_draco_decode Excludes: --preserve_draco Decode draco encoded files on input. --preserve_draco Excludes: --allow_draco_decode --draco_encode Apply draco compression to output glTF if input file was draco encoded. --draco_method ENUM:value in { edgebreaker, sequential } Draco compression method. --draco_speed INT:INT bounded to [1 - 10] Encoding speed, lower means higher compression quality. --draco_pos_bits INT:INT bounded to [1 - 16] Position quantization bits. --draco_nor_bits INT:INT bounded to [1 - 16] Normal quantization bits. --draco_uv_bits INT:INT bounded to [1 - 16] UV quantization bits. --draco_col_bits INT:INT bounded to [1 - 16] Color quantization bits. --draco_gen_bits INT:INT bounded to [1 - 16] Generic quantization bits. [Option Group: jewelry] Jewelry prep options Options: --apply_jewelry Compute raytracing caches for jewelry assets. --gem_cubemap_size INT:INT bounded to [8 - 128] Size of the plane cache cubemap used for gem raytracing. [Option Group: fbx] FBX Options: --output_fbx Output FBX file. --fbx_ascii Needs: --output_fbx Output ASCII Fbx. --roughness_as_shininess Needs: --output_fbx Output roughness in shininess exponent map/factor.

Configuration Files

Instead of specifying lengthy command lines, configuration files may be used. To use a config file add a path to it via the --config flag:

> MeshOptimizer --config=<path_to_config_file> -f <path_to_input_file> -o <path_to_output_file>

To convert a command line to a config file, --dump_config option can be used:

> MeshOptimizer [OPTIONS] --dump_config=<path_to_config_file>

Below are a number of config files corresponding to pipelines on the VNTANA Platform. They all feature reasonable defaults for optimizing assets based on what their source is. Some specifics of these configurations include:

  • CLO - Sets a high target texel density because CLO files often feature very tiled UV spaces

  • BW - Converts specularGlossiness materials to metallicRoughness

  • 3D_SCAN - passes the --scanned_asset flag to the optimizer, which tells it to perform some techniques specifically useful to 3D scans (see examples below)

  • STITCH_BAKING_ONLY - only bakes the small features present in the asset into textured quads (see examples below)

  • OTHER - use this if no other config file fits

  • NO_BAKING - disables texture and normal baking

  • KEYSHOT - suitable for Keyshot CAD assets

  • FORCE_BAKING - forcefully bakes textures, even if UV spaces are very tiled

Config files are easily editable in any text editor.

Examples

Obstructed Geometry Removal (--remove_obstructed_geometry)

Removes all polygons that are not visible from outside of the asset. E.g. for this asset:

The results with (left) and without (right) OGR are:

 

Small Feature Baking (--bake_small_features)

Bakes small features in the asset (such as stitches) into alpha masked quads.

Before:

After:

Instance Detection (--detect_instances)

Detects mesh copies which are then stored as a single mesh with multiple instances with different node transforms.

Before:

After:

Forcing polygon limit (--force_poly_count)

By default, MeshOptimizer will not honor the target polygon count (--tris) if its internal error norm becomes too large. This is done to prevent optimized assets having poor visuals or decimation errors. With the --force_poly_count flag this default behavior will be overridden and more effort will be put into achieving the desired poly limit.

Without poly limit forcing:

With:

Scanned Model Decimation (--scanned_model)

This flag will enable crease smoothing via edge flipping, as creases are often present on scanned models:

Ambient Occlusion Baking (--skip_ao_baking)

On by default, can be skipped with the --skip_ao_baking flag. Will not overwrite occlusion maps already present in the asset, unless --remove_occlusion_maps is passed as well.