Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

If you have HOOPS CAD conversion licensed, unzip the HOOPS binaries next to the optimizer or provide the path to them via the --hoops_bin_flag when running the MeshOptimizer.

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:

...

breakoutModefull-width

Setup

  1. Install the system requirements for your platform (listed above)

  2. Download the CLI from here and unzip it.

  3. (optional, if processing CAD assets) Download the HOOPS binaries from here, unzip them and place them in the directory where the MeshOptimizer is so that the hoops/ directory is next to the MeshOptimizer executable.

  4. Activate the license by running passing the activation flags to the MeshOptimizer: ./MeshOptimizer --activate_license --license_key=XXXX-XXXX-XXXX

    1. For offline license activation:

      1. Generate the request file with --license_activation_request_path

      2. Upload it here to get the license activation file

      3. Run the MeshOptimizer with --license_activation_fileto activate your license

    2. Alternatively run the optimizer with --activate_license and follow the activation steps thet best suite you

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:

Code Block
breakoutModefull-width
Options:
  -h,--help                   Print this help message and exit
  --config,--ini              Read an ini file
  -o,--output_file TEXT       Output filename. If it is not provided, it is auto-generated. Default output format is GLB
  --version                   Display program version information and exit
[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.
    --activate_license
[Option Group: optimization_level]
  Optimization Level
  [At most 1 of the following options are allowed]
  Options:
    -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.
    --skip_geometry_ops_material_regex TEXT
                                Skip geometry operations like decimation and welding on materials with names matching the given regex.
    --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.
    --allow_anti_aligned_polygons
                                Leaves collocated polygons with different winding in place, instead of removing one of them and marking the other as doublesided.
    --skip_doublesided_from_visibility
                                Skip setting materials as doublesided based on material visibility.
    --skip_degen_fixing         Skip fixing degenerate triangles by trying to flip/collapse them.
    --skip_degen_poly_normal_fixing
                                Skip fixing vertex normals on degenerate triangles.
    --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.
    --flatten                   Flatten the node hierarchy.
    --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.
    --calc_shading_normals      Replace vertex normals in the file with smooth normals computed from geometry.
    --skip_boundary_edge_welding
                                Skip welding along boundary edges.
    --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 TEXT         Scene aabb will be aligned on each axis by the given rule. For example, --reset_center=center top bottom will make x=0 center of the aabb, y=0 as top of the aabb and z=0 as bottom. If --reset_center is specified, the default  for axis will be set to center, so if less than 3 arguments are provided, the default will be 'center' for each  axis that is missing. 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.
    --remove_lines              Remove any existing lines from the file.
    --remove_names              Remove names from all objects.
    --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
    --skip_aux_output           Don't output aux files to disk (e.g. log file, json summary)
[Option Group: matTex]
  Texture and Material Settings
  Options:
    --max_tex_size INT          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_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_max_resolution --ao_strength --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: --draco_encode --allow_draco_decode
                                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 [0 - 10]
                                Encoding speed, lower means higher compression quality.
    --draco_pos_bits INT:INT bounded to [0 - 16]
                                Position quantization bits.
    --draco_nor_bits INT:INT bounded to [0 - 16]
                                Normal quantization bits.
    --draco_uv_bits INT:INT bounded to [0 - 16]
                                UV quantization bits.
    --draco_col_bits INT:INT bounded to [0 - 16]
                                Color quantization bits.
    --draco_gen_bits INT:INT bounded to [0 - 16]
                                Generic quantization bits.
[Option Group: gltf]
  glTF
  Options:
    --one_primitive_per_mesh    Allow a maximum of one primitive per one mesh in the glTF output.
    --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.
    --force_float_vert_attribs  Forces 4 byte floating point data for all vertex attributes.
    --allow_zero_accessors      Allow glTF accessors that do not reference buffer views in output.
    --use_gpu_instancing        Use EXT_mesh_gpu_instancing extension for all instances.
    --output_glb                Output .glb file.
    --output_gltf               Output .gltf file.
[Option Group: fbx]
  FBX
  Options:
    --output_fbx                Output FBX file.
    --fbx_ascii Needs: --output_fbx
                                Output ASCII Fbx.
    --roughness_as_shininess Needs: --output_fbx Excludes: --fbx_pbr
                                Output roughness in shininess exponent map/factor.
    --fbx_pbr Needs: --output_fbx Excludes: --roughness_as_shininess
                                Output PBR textures in FBX non-PBR texture slots.
    --fbx_pbr_input             Assume non-PBR FBX texture slots contain PBR textures.
    --fbx_anm_sample_rate{sample_rate} :value in { 120, 24, 30, 60 } [24]
                                Animation sampling rate when importing FBX files.
[Option Group: usd]
  USD
  Options:
    --output_usdz               Output USDZ file.
    --usd_float16_uv Needs: --output_usdz
                                Store UVs as 16bit floats.
    --usd_remove_ao Needs: --output_usdz
                                Remove AO textures for usdz.
    --usd_emulate_doublesided Needs: --output_usdz
                                Emulate doublesided materials by duplicating geometry.
    --usd_enable_instancing Needs: --output_usdz
                                Enable geometry instancing. Otherwise, instanced geometry is duplicated.
    --usd_max_texture_memory UINT
                                Max available texture memory.
    --usd_fit_texture_memory    Resize textures to fit in the memory limt.
    --usd_bake_tex_transforms   Bake base color texture transform into UV layer.
[Option Group: obj]
  OBJ
  Options:
    --output_obj                Output OBJ/MTL files.
    --obj_neg_idx               Use negative indices in OBJ files.
[Option Group: cad]
  CAD
  Options:
    --hoops_bin_path TEXT       Path to Hoops Exchange binaries
    --hoops_export TEXT         HOOPS export path.
    --hoops_translate           Translate the cad file to glb with hoops first and then process the glb with the optimizer instead of loading the cad file directly to optimization scene.
    --tessellate_pmi            Tessellate pmi data.
    --read_hidden_objects       Read and export hidden objects.
  [Option Group: tessellation quality]
    These options affect tessellation quality when tessellating boundary representation.
    Here are some quality presets:
      Extra Low:
        --chord_height_ratio=50
        --angle_tolerance_deg=40
      Low:
        --chord_height_ratio=600
        --angle_tolerance_deg=40
      Medium:
        --chord_height_ratio=2000
        --angle_tolerance_deg=40
      High:
        --chord_height_ratio=5000
        --angle_tolerance_deg=30
      Extra High:
        --chord_height_ratio=10000
        --angle_tolerance_deg=20

    Options:
      --chord_height_ratio FLOAT:FLOAT bounded to [50 - 10000] [2000]
                                  Controls chord height - the distance between vertex of an arc and a tessellation segment connecting two points on the arc.Specified as the ratio of the diagonal length of the bounding box (defined by the tessellation segment and chord height) to the chord height. A value of 50 means that the diagonal of the bounding box is 50 times greater than the chord height. Higher values will generate more accurate tessellation.
      --angle_tolerance_deg FLOAT:FLOAT bounded to [10 - 40] [40]
                                  Specifies the maximum angle between two contiguous tessellation segments describing the curve of a topological edge for every face.Lower values will result in greater accuracy.
      --max_triangle_edge_length FLOAT [0]
                                  Maximal length of the edges of triangles. Disabled if value is 0. Too small values can generate a huge tessellation
[Option Group: licensing]
  Licensing Options
  Options:
    --license_key TEXT          License Key.
    --license_file TEXT         Path to the license file.
    --license_activation_file TEXT
                                Path to the offline license activation file.
    --license_activation_request_path TEXT
                                Path to the offline license activation file.

...

> 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.

View file
nameINDUSTRIAL_REMOVA_ALPHA.toml
View file
nameINDUSTRIAL.toml
View file
nameFORCE_BAKING.toml
View file
nameCLO.toml
View file
nameBW.toml
View file
nameAPPAREL_TILED_TEXTURES.toml
View file
name3D_SCAN.toml

...

_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/BW - Suited for assets coming out of Clo 3D and Browzwear

  • 3D_SCAN - Suitable for 3D scans/photogrammetry assets

  • INDUSTRIAL - Suitable for CAD assets

  • OTHER - Reasonable defaults config if your asset doesn’t fit any other

Config files are easily editable in any text editor.

View file
namePRESERVE_NODES_AND_MATERIALS3D_SCAN.toml
View file
namePRESERVE_MESHES_AND_UVSOTHER.toml
View file
nameOTHERINDUSTRIAL.toml
View file
nameNO_BAKINGCLO.toml
View file
nameKEYSHOTBW.toml

Examples

Obstructed Geometry Removal (--remove_obstructed_geometry)

...