Decimate Meshes#

Key: decimateMeshes

Reduce the polygon count of UsdGeom.Mesh prims while preserving shape as much as possible. Decimation uses QEM (Quadric Error Metrics) edge-collapse simplification: edges are collapsed in order of least geometric error and the mesh is locally re-triangulated after each collapse. CPU (parallel and sequential) and GPU paths are selected automatically based on vertex count thresholds.

Choosing a stop condition#

reductionFactor and maxMeanError are the two stop conditions; either can be used alone or together (whichever is reached first stops decimation of a given mesh). Set one to 0.0 to disable it.

  • Prefer ``maxMeanError`` for silhouette-preserving decimation. It bounds the geometric error, so the decimator stops before visible features are lost. This is the recommended default: set a non-zero maxMeanError and reductionFactor to 0.0.

  • Use ``reductionFactor`` only to hit a target reduction rate (e.g. a memory budget or a fixed LOD level). It is a percentage in the range 0-100, not a fraction: 50 keeps 50% of the vertices, while 0.5 keeps 0.5% and destroys the mesh. Values below 10 typically ruin the silhouette.

Use float literals for these float arguments; some bindings reject an integer 0.

Scale and units#

maxMeanError is the maximum mean geometric distance (in stage units) the decimated surface may drift from the original. To target a physical tolerance, convert from millimetres using the stage’s metersPerUnit:

maxMeanError = (tolerance_mm / 1000) / metersPerUnit

UsdGeom.GetStageMetersPerUnit returns USD’s default of 0.01 (centimetres) when the metadata is unset, so a tolerance-sensitive config depends on the stage being authored at a known scale.

Important defaults and footguns#

  • pinBoundaries defaults to false. Set it to true explicitly whenever mesh outlines matter (architectural walls, tiles that must align along edges); otherwise boundary edges can collapse.

  • guideDecimation lets a vertex-colour or corner-normal attribute steer which regions are simplified more aggressively. allowCutAndGlue permits topology changes for better quality at aggressive reduction.

  • The GPU path requires CUDA and engages above gpuVertexCountThreshold (default 500K vertices); a CPU parallel path engages above cpuVertexCountThreshold (default 100K).

Decimation rewrites the vertex data of the targeted meshes. On stages with references, payloads, or scenegraph instances this writes overrides on the composed stage while the source asset stays high-poly; source-level optimization or proxy variants are often the better publishing path. Skinned (UsdSkel) meshes bind joint weights to vertex order, so decimation invalidates those bindings unless skin weights are regenerated.

Starting configurations#

Silhouette-preserving (recommended default), error-budget driven:

[{"operation": "decimateMeshes", "reductionFactor": 0.0, "maxMeanError": 0.01, "pinBoundaries": true}]

Conservative (tighter error budget):

[{"operation": "decimateMeshes", "reductionFactor": 0.0, "maxMeanError": 0.001, "pinBoundaries": true}]

Target reduction rate (keep 50% of vertices); disable the error cap:

[{"operation": "decimateMeshes", "reductionFactor": 50.0, "maxMeanError": 0.0, "pinBoundaries": true}]

Aggressive LOD (expect visible silhouette change; use only for small-screen LODs):

[{"operation": "decimateMeshes", "reductionFactor": 10.0, "maxMeanError": 0.0, "pinBoundaries": true, "allowCutAndGlue": true}]

Arguments#

Meshes to Decimate#

Optional list of prim paths/expressions to decimate

  • Name: paths

  • Type: [string]

  • Default Value: []

Reduce to Percentage#

Reduce to end result percentage from original vertex count, 0.0-100.0 values accepted. Set to 0 if using Maximum Mean Error.

  • Name: reductionFactor

  • Type: float

  • Default Value: 50

  • Min Value: 0.0

  • Max Value: 100.0

Maximum Mean Error#

Maximum mean error for the decimation, 0.0-100.0 values accepted. Set 0 to disable this option.

  • Name: maxMeanError

  • Type: float

  • Default Value: 0

  • Min Value: 0.0

  • Max Value: 10.0

Guide Decimation#

Guide Decimation by using Normals or Colors (if available)

  • Name: guideDecimation

  • Type: int

  • Default Value: 0

  • Enum Values:

    • 0: By normals

    • 1: By colors

    • 2: Off

Pin mesh boundaries#

Preserve the mesh boundaries

  • Name: pinBoundaries

  • Type: bool

  • Default Value: False

Topology Simplification#

Allow changes to mesh topology when decimating. Note that this will take more time

  • Name: allowCutAndGlue

  • Type: bool

  • Default Value: False

CPU Vertex Threshold#

Use CPU Parallel algorithm if vertex count is greater than this value

  • Name: cpuVertexCountThreshold

  • Type: int

  • Default Value: 100000

  • Min Value: 0.0

GPU Vertex Threshold#

Use GPU algorithm if vertex count is greater than this value

  • Name: gpuVertexCountThreshold

  • Type: int

  • Default Value: 500000

  • Min Value: 0.0