Skip to content

Curve Weight Curve Weight

A tube of influence around a curve's control polygon.

Node type RigExecCurveWeight
Example curve_weight.usda

On this page:

Overview

Curve Weight effect

A placed volume that generates its field from distance to a curve instead of storing one: everything within inputs:falloffMin of the curve is fully weighted, everything past inputs:falloffMax is not, and the band between them ramps. The curve is ordinary scene geometry named through rigExec:curve — a weight object never grows its own points — so a spline an artist already has becomes the shape of an influence. Distance is measured to the polyline through the control points, not to the evaluated basis, so the field never reaches anywhere the drawn guide does not.

Tubular falloff about a curve: d is the distance to the nearest point on the polyline through the target curve's points, measured in rigid volume-local space after inputs:scaleX/Y/Z.

The polyline through the control points is deliberate rather than a basis evaluation: a weight field wants a stable, cheap, monotone distance, and the control polygon bounds the curve it hulls, so the field never reaches somewhere the drawn guide does not.

How it works

Compile registers the volume's placement tap (computePointFrame, not computeMatrix, so an unanimated volume still lands where it is placed) and bakes the falloff into a lookup table; the structural digest hashes rigExec:curve together with the type its target resolves to, so repairing or retyping the points source re-enters Compile while merely moving the curve does not. Then, each frame, computeWeightPacket reads the curve's points and the weighted domain's points in the same space, carries both into rigid volume-local space, divides by inputs:scaleX/Y/Z, and remaps the nearest-segment distance through the baked profile plus inputs:invert and inputs:strength. The result is a dense float per target element, published as the envelope of whichever mover binds it through rigExec:weightObject — a matrix mover then applies p' = q + w (T q - q).

Wiring

Relationship Points to Required
rigExec:curve Exactly one native points source — a BasisCurves prim or an exact point3f[] property — whose control polygon the distance is measured to. yes
rigExec:weightTarget Exact points property this field covers. yes
rigExec:sampleSource Optional unposed points to measure instead of the target, at the same element count; the weighted domain stays the target. no
(bound by) A mover's rigExec:weightObject applies this field. -

Parameters

Falloff band, sampling and guide

purpose

Type: uniform token. Default: "guide".

Render purpose, overriding UsdGeomImageable's default fallback for the same reason RigExecJoint does: an influence volume is a DIAGNOSTIC, drawn when a viewer asks for guides, and the stock attribute keeps the drawing and the bounds from disagreeing.

rigExec:weightTarget

Relationship.

Canonical prim or exact property carrying the weighted domain.

Its rigExecReadPhase metadata chooses which points the distance function measures. base, the default, samples the AUTHORED points (or rigExec:sampleSource) rather than any mover's output, so one field per evaluation is shared by every mover that binds the weight and a point keeps the weight its bind pose earned -- the behaviour of a painted map, and what a matrix mover wants so that its own output cannot feed back into its own weights.

preceding samples the points AS THEY STAND at the consuming operation's position in the mover stack, so the volume grabs whatever is inside it right now. That is the dynamic behaviour, and it is order dependent by construction: the same volume placed at two points in the stack legitimately yields two different fields. final and checkpoint paths follow the ordinary read-phase rules; final on the consuming mover's own target includes that mover's output and is reported as an operation cycle.

rigExec:representation

Type: uniform token. Default: "dense".

Valid values: dense.

A generated field has a value at every element, so dense is the only representation it can honestly publish. Declared anyway, and rejected rather than coerced when authored otherwise, because the packet contract carries it and a combine has to match representations across its inputs.

rigExec:rangePolicy

Type: uniform token. Default: "clamp".

Valid values: strict, clamp.

Defaults to clamp rather than the strict used by the authored weight objects: inputs:strength and inputs:invert are animatable, and an artist scrubbing strength past one should see the field saturate, not have the packet invalidated and its mover pass through mid-drag.

inputs:falloffMin

Type: float. Default: 0.

Distance at which the field is fully ON. In the volume's local units after inputs:scaleX/Y/Z, so for a sphere it is simply the inner radius.

inputs:falloffMax

Type: float. Default: 1.

Distance at which the field is fully OFF; the outer radius for a sphere.

falloffMax < falloffMin is legal and flips the ramp -- the signed denominator does it with no special case. falloffMax exactly equal to falloffMin is the one degenerate case, and means a hard step at that distance.

inputs:invert

Type: float. Default: 0.

Exchanges the two ends of the band. A float rather than a bool so it can be animated or driven like any other avar: it LERPS between the two ramps, so an animated invert sweeps through a flat field at 0.5 instead of popping.

inputs:strength

Type: float. Default: 1.

Final multiplier on the remapped weight. Deliberately not clamped by the kernel -- rigExec:rangePolicy is the authority on out-of-range weights, and silently clamping here would hide a strict-policy violation.

rigExec:falloffProfile

Type: uniform token. Default: "smooth".

Valid values: linear, smooth, easeIn, easeOut, constant, curve.

Named analytic remap of the normalized band parameter, or curve to use the spline authored on rigExec:falloffCurve. Every profile pins f(0) = 0 and f(1) = 1, so switching profiles never moves the band's endpoints -- only its shape between them.

The presets are baked to the same lookup table the curve is resampled into, so there is exactly one remap path in the hot loop whether the author picked a preset or drew a curve.

inputs:falloffSamples

Type: float[]. Default: [].

Optional uniformly spaced samples of the normalized falloff profile, from the outer boundary (0) to the inner boundary (1). A nonempty array replaces falloffProfile and falloffCurve; an empty array uses that authored profile. Editors may preview this input without authoring it, then commit the custom spline on release.

rigExec:falloffCurve

Type: float. Default: 0.

Falloff shape as an authored Ts spline over x in [0, 1], read when rigExec:falloffProfile is curve. x is the ramp parameter -- 1 at falloffMin, 0 at falloffMax -- and the value is the weight.

This is a STRUCTURAL read, resampled to a lookup table once per compiled rig, NOT a per-frame input: a per-frame input is a value at one time, and a curve is the whole function. The animatable knobs are falloffMin/Max, invert, and strength; the curve is a rig-authoring parameter, which is also what keeps the field fixed-shape.

Held extrapolation outside [0, 1] is the Ts default and is exactly right here, so a curve authored over a shorter span still yields a total field.

rigExec:sampleSource

Relationship.

Optional explicit points source to measure against, overriding rigExec:weightTarget for SAMPLING only. The weighted domain stays the weightTarget, so this is how a volume weights one mesh by another mesh's shape -- typically an unposed reference copy -- and its point count must match the weightTarget's. Without rigExecReadPhase metadata it reads the authored points; a declared phase selects that version. Ignored when rigExec:weightTarget declares a phase other than base.

guide:weightDisplay

Type: uniform token. Default: "tint".

Valid values: tint, heatmap, bands.

Selected influence overlay: tint blends gray to red; heatmap interpolates dark blue, blue, teal, yellow and red at weights 0, .25, .5, .75 and 1. bands assigns five colors in .2-wide bins. Colors use resolved vertex weights, clamped to [0,1] for display; faces interpolate them, so bands are approximate on coarse meshes. Does not change weights, materials or opacity on the source stage.

guide:drawMode

Type: uniform token. Default: "falloff".

Valid values: falloff, cage, brackets, shell, wire, geometry, none.

falloff draws a soft inner shell at falloffMin with continuous inner rings and a dashed exterior cage at falloffMax. A zero inner radius draws only the exterior cage. cage draws a continuous inner boundary and dashed outer boundary without fill. brackets draws short cardinal sections of both boundaries. shell adds a faint outer surface to continuous rings. These styles use 30% of guide:wireWidth and at most five cross-section rings along a curve. wire draws the falloffMin and falloffMax iso-surfaces as curves, widthed by guide:wireWidth. A sphere weight in wire mode draws the falloffMin surface, the max-weight interior, as geometry at 50% opacity with dotted great-circle rings on it, and the falloffMax surface as a dotted wire. geometry draws every iso-surface solid; none suppresses the guide without disturbing the field.

guide:wireWidth

Type: double. Default: 0.05.

Width of the drawn wire guide curves; see RigExecControl.

guide:displayColor

Type: color3f. Default: (1.0, 0.2, 0.2).

Red by convention, matching the influence overlay the results scene index paints onto the weighted geometry so the volume and the region it grabs read as one object.

guide:displayOpacity

Type: float. Default: 0.35.

Placement

rest:tx

Type: double. Default: 0.

rest:ty

Type: double. Default: 0.

rest:tz

Type: double. Default: 0.

rest:rx

Type: double. Default: 0.

rest:ry

Type: double. Default: 0.

rest:rz

Type: double. Default: 0.

rest:space

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

Bind transform relative to the namespace frame provider's rest frame, applied after the rest:tx/ty/tz/rx/ry/rz offsets; always orthonormalized. A plain Xformable between the provider and that frame provider is composed in after it. A provider with no RigExec ancestor and no such Xformable resolves against identity, so its rest:space is its local-to-world bind transform.

default:tx

Type: double. Default: 0.

default:ty

Type: double. Default: 0.

default:tz

Type: double. Default: 0.

default:rx

Type: double. Default: 0.

default:ry

Type: double. Default: 0.

default:rz

Type: double. Default: 0.

default:space

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

Local-to-world zero position for posing. Its computed fallback is compose(default translation/XYZ rotation) * rest * inverse(parent rest) * parent:defaultSpace. The rest is unaffected by default edits. A connection is authoritative, including identity. Otherwise a non-identity authored matrix overrides the computed fallback; an identity value selects that fallback.

posed:space

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

Final local-to-world transform. For a joint a solver writes, this is supplied by the compiler's solver binding; it may also be authored or connected directly. Unwired xformables follow the parent chain with rest offsets and avars.

posed:defaultSpace

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

Controller-adjusted zero pose; falls back to avars:defaultSpace. Used by the local-avars pose path before parent motion. A connection overrides the fallback, as does a non-identity authored matrix.

avars:tx

Type: double. Default: 0.

avars:ty

Type: double. Default: 0.

avars:tz

Type: double. Default: 0.

avars:rx

Type: double. Default: 0.

avars:ry

Type: double. Default: 0.

avars:rz

Type: double. Default: 0.

avars:rspin

Type: double. Default: 0.

avars:rotationOrder

Type: token. Default: "XYZ".

Valid values: XYZ, XZY, YXZ, YZX, ZXY, ZYX.

avars:defaultSpace

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

Zero pose supplied to avar evaluation; falls back to the computed default:space. A connection or non-identity authored matrix selects another zero pose.

avars:unitScaleFactor

Type: double. Default: 1.

Multiplier converting translation avars into local distance units before the selected default and parent transforms. Rotations and scales are unaffected.

avars:rotationSign

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

Per-axis sign applied to rx, ry and rz -- and to rspin, which is an X rotation -- before they are composed. Each component carries a sign and nothing else: a magnitude is discarded, and anything that is not negative, including zero, selects +1. Zero would otherwise erase an axis, so it resolves to the unmirrored answer rather than a collapsed one.

This is how a MIRRORED limb is declared: the same rotation value moves both sides symmetrically. A mirror expressed as a negative scale cannot survive into a rest frame here -- it would make the frame left-handed and every joint, driver and bind below it would have to be rebuilt to match -- so the mirror is declared on the avars instead, where it belongs: it says which of this control's axes already point the mirrored way and which answer backwards.

Identity at rest, and that is the point. A sign changes nothing when the avars are zero, so declaring it cannot move the rest pose, the skin, or anything constrained to this control. Only what the animator types changes meaning.

Applied to the avar, not to the frame, so the control's own posed frame mirrors too and a manipulator turns with the limb rather than against it.

parent:space

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

Selected parent's posed local-to-world space. Falls back to the nearest namespace provider's computePointFrame; identity when there is none. Connections (including identity) or a non-identity authored matrix select a different parent space.

parent:defaultSpace

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

Selected parent's default local-to-world space. Falls back to the nearest namespace provider's computeDefaultFrame. Connections (including identity) or a non-identity authored matrix override it. The avar pose is avars * posed:defaultSpace * inverse(parent:defaultSpace) * parent:space, in row-vector convention.

Node parameters

rigExec:curve

Relationship.

Exactly one native points source for the curve -- a UsdGeomBasisCurves prim or an exact point3f[] property. Its points are read in the same space as the weighted domain's, so both are carried into volume-local space together.

inputs:scaleX

Type: float. Default: 1.

Per-axis divisor making the tube elliptical; see RigExecSphereWeight.

inputs:scaleY

Type: float. Default: 1.

inputs:scaleZ

Type: float. Default: 1.

Example

A flat 13x13 sheet is weighted by a tube around a shallow V-shaped curve, and a matrix mover lifts the weighted points 0.8 units. Nothing in the rig animates — the Lift control holds avars:ty for the whole shot — but the curve's own points sweep across the sheet and back, so a curved ridge travels with it. What moves is not the transform but which points the field grabs. Two different things are drawn: the amber wire tube is the pair of iso-surfaces at inputs:falloffMin and inputs:falloffMax, and the red band painted on the sheet is the field those two distances produce — the tube is the rule, the band is the result. The curve itself rides at y = 0.3, just clear of the sheet, so the control polygon the distance is measured to stays visible above the geometry it weights.

Open it live with:

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

Re-render the GIF above with:

python docs/render_media.py --page curve_weight

Tips

  • The field uses the control polygon, not the evaluated basis, so a cubic curve influences the region around its hull rather than around the smooth curve you see; add control points where you need the tube to bend.
  • inputs:scaleX/Y/Z divide the local coordinate before the distance, turning the tube elliptical — but any axis that is non-positive or non-finite invalidates the whole packet rather than collapsing the volume.
  • Leave rigExec:weightTarget at its default base read phase and the tube measures the static bind points, so a point keeps the weight its rest position earned; rigExecReadPhase = "preceding" measures the points as they stand at this mover's place in the stack, which makes the field order dependent by design.

See also


UsdRig