Skip to content

Lattice Mover Lattice Mover

Deforms points through a legacy cage or a regular interpolation grid.

Node type RigExecLatticeMover
Example lattice_mover.usda

On this page:

Overview

Lattice Mover effect

Free-form deformation: a native Points or mesh cage surrounds the geometry, and posing the cage (default time is the bind, timeSamples are the posed cage) carries the moved points through tensor-product basis evaluation. Fewer cage points than mesh vertices drive broad, smooth shaping — bulges, bends, squash and stretch.

Reads cage points from a native mesh/points prim and writes exactly one exact native UsdGeomPointBased points property through tensor-product basis evaluation. rigExec:cage honors rigExecReadPhase metadata. rigExec:evaluation selects the basis; rigExec:basis is not read.

How it works

The default rigExec:evaluation = legacy is the tensor-product Bernstein cage evaluator. regularGrid interpolates cage displacement from canonical origin and spacing, with separate linear, cardinal, B-spline or Catmull-Rom interpolation on each axis. divisions uses x-fastest ordering; single-point axes are supported. Outside coordinates retain their extrapolated basis weights while individual cage indices clamp at the boundary.

strength and per-point mask scale the displacement before the common mover envelope. cageMatrix and targetMatrix, optionally followed by the two frames providers, define the coordinate spaces. pointSpace = common is for points already in a shared asset space; local is for object-local points. These settings and frames belong to regularGrid; authoring them with legacy fails the mover's compile check. The cage points are read at the rigExecReadPhase declared on rigExec:cage; frames providers take base or final.

.rigexec exports carry these settings from format revision 21. A revision 20 file has none of them and plays the legacy cage evaluator.

Wiring

Relationship Points to Required
rigExec:cage Native Points/mesh prim supplying cage points. yes
rigExec:moves Exact points property to deform. yes

Parameters

Common mover envelope

rigExec:moves

Relationship.

Reserved write-set relationship: exact prim/property targets.

inputs:enabled

Type: bool. Default: true.

Shape-preserving enable. Disabled movers pass their preceding revision through unchanged (value-only edit).

inputs:defaultWeight

Type: float. Default: 1.

Normalized common mover envelope in [0, 1]. With no bound rigExec:weightObject it broadcasts over every logical element: zero passes the incoming value through bit-for-bit and one applies the mover's full-strength result. A non-finite value or one outside [0, 1] passes the incoming value through with a diagnostic.

rigExec:weightObject

Relationship.

Optional compatible total weight field, at most one target. When bound, the weight object's values (including its own sparse or constant fallback) supply the common envelope instead of inputs:defaultWeight. Target, domain, and cardinality must match each mover application; an incompatible binding is a compile error. A multi-target mover may bind only a constant operation envelope whose weightTarget is the mover prim itself; that one value broadcasts to every application of the atomic mover.

Node parameters

rigExec:cage

Relationship.

Native mesh/points prim supplying cage control points.

rigExec:basis

Type: uniform token. Default: "bspline".

Valid values: bspline, bernstein.

rigExec:divisions

Type: int3. Default: (2, 2, 2).

rigExec:evaluation

Type: uniform token. Default: "legacy".

Valid values: legacy, regularGrid.

Legacy binds each base point into the bound of the cage's default-time points and moves the incoming point by the Bernstein blend of the cage's motion from them; it needs at least two divisions per axis, and an authored regular-grid setting (interpolation, origin, spacing, strength, mask, pointSpace, cageMatrix, targetMatrix or frames) is a compile error. Regular grid interpolates current cage displacement against canonical origin/spacing at each incoming point and needs at least one division per axis.

rigExec:interpolationU

Type: uniform token. Default: "bspline".

Valid values: bspline, linear, cardinal, catmullRom.

rigExec:interpolationV

Type: uniform token. Default: "bspline".

Valid values: bspline, linear, cardinal, catmullRom.

rigExec:interpolationW

Type: uniform token. Default: "bspline".

Valid values: bspline, linear, cardinal, catmullRom.

rigExec:origin

Type: float3. Default: (-0.5, -0.5, -0.5).

rigExec:spacing

Type: float3. Default: (1, 1, 1).

rigExec:strength

Type: float. Default: 1.

rigExec:mask

Type: float[]. Default: [].

rigExec:pointSpace

Type: uniform token. Default: "local".

Valid values: local, common.

rigExec:cageMatrix

Type: matrix4d. Default: ((1,0,0,0),(0,1,0,0),(0,0,1,0),(0,0,0,1)).

rigExec:targetMatrix

Type: matrix4d. Default: ((1,0,0,0),(0,1,0,0),(0,0,1,0),(0,0,0,1)).

rigExec:frames

Relationship.

Optional cage and target rest-to-pose providers: none, or exactly these two in that order, applied after their local-to-common matrices. Regular grid only; a checkpoint read phase is a compile error.

Example

A 2×3×2 Bernstein cage bulges its middle layer outward and back, widening the middle of a vertical strip. Bind and posed cage share the same point ordering.

Open it live with:

bin\launch_usdview.bat docs\examples\lattice_mover.usda

Re-render the GIF above with:

python docs/render_media.py --page lattice_mover

Tips

  • Hide the cage (visibility = invisible): it is scaffolding, not geometry.
  • Follow a bulge with a Smooth mover to settle the lattice falloff or a Volume Correct mover to hold girth.

See also


UsdRig