Sphere Weight¶
A ball of influence: radial falloff generated from a placed volume.
| Node type | RigExecSphereWeight |
| Example | sphere_weight.usda |
On this page:
Overview¶

The weight nobody paints. A sphere weight is a placed volume that
generates a scalar field instead of storing one: every point of the
target gets the weight its distance from the volume's origin earns,
ramped between inputs:falloffMin (fully on) and inputs:falloffMax
(fully off). Because it is a RigExecXformable, it is one selectable,
framable prim positioned by the same avars as a control or joint — so a
sphere authored inside a joint rides that joint with nothing wired, and
the region a mover grabs can be animated by moving the ball. Per-axis
inputs:scaleX/Y/Z turn the iso-surfaces into ellipsoids.
inputs:scaleXPos/YPos/ZPos and inputs:scaleXNeg/YNeg/ZNeg multiply
the matching shared axis scale independently on each local half-axis.
All six default to 1, preserving existing shapes; values must be finite
and positive. The center stays fixed as either side grows or shrinks.
Radial falloff about the volume's placed origin: d = |(px/sx, py/sy, pz/sz)| in rigid volume-local space, so inputs:falloffMin/falloffMax are the inner and outer radii and inputs:scaleX/Y/Z make the iso-surfaces ellipsoidal. The scaleXPos/YPos/ZPos and scaleXNeg/YNeg/ZNeg inputs multiply the shared scale on each local half-axis independently, keeping the origin fixed.
How it works¶
The prim publishes a weight packet that the bound mover consumes as
its envelope during the geometry (point-chain) phase. Each evaluation it
takes its own posed frame from computePointFrame, strips scale and
shear so the field matches the rigid guide that is drawn, divides local
coordinates by inputs:scaleX/Y/Z and the matching positive or negative
local-axis multiplier, then measures d = |(px/sx, py/sy, pz/sz)|
using those effective divisors for every element of
rigExec:weightTarget — or of rigExec:sampleSource, when authored,
which changes what is measured without changing what is weighted.
d is normalized across the falloff band, exchanged end-for-end by
inputs:invert, remapped through the falloff lookup table, multiplied by
inputs:strength, and bounded by rigExec:rangePolicy (clamp by
default, so scrubbing strength saturates instead of invalidating the
rig). The rigExecReadPhase metadata on rigExec:weightTarget chooses
the points measured: base (the default) uses the STATIC authored base
points, so a point keeps the weight its bind pose earned and a mover's
own output cannot feed back into its own weights; preceding re-measures
the points as they stand at that position in the mover stack. The band, invert and strength
are live per-frame inputs; rigExec:falloffProfile and rigExec:falloffCurve are
structural and are baked to one lookup table per compiled rig.
Wiring¶
| Relationship | Points to | Required |
|---|---|---|
rigExec:weightTarget |
Exact points property this generated field covers; must be the same target the bound mover moves. | yes |
rigExec:sampleSource |
Static points to measure against instead of the target — typically an unposed reference copy. The weighted domain stays the target. | no |
| (placement) | No wiring: the volume is posed by its own rest:space and avars, or follows its namespace-parent xformable when unwired. |
- |
| (bound by) | A mover's rigExec:weightObject applies this field. |
- |
Parameters¶
Volume weight¶
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.
Transform provider¶
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¶
inputs:scaleX¶
Type: float. Default: 1.
Per-axis divisor applied to the local coordinate before the radial distance, so the iso-surfaces are ellipsoids. Three separate floats rather than a vec3, per the Ir alignment. A non-positive or non-finite value on any axis is rejected and the packet is invalid, rather than silently collapsing the volume.
inputs:scaleY¶
Type: float. Default: 1.
inputs:scaleZ¶
Type: float. Default: 1.
inputs:scaleXPos¶
Type: float. Default: 1.
Positive, finite multiplier of the shared axis scale on the positive local X half-axis.
inputs:scaleYPos¶
Type: float. Default: 1.
Positive, finite multiplier of the shared axis scale on the positive local Y half-axis.
inputs:scaleZPos¶
Type: float. Default: 1.
Positive, finite multiplier of the shared axis scale on the positive local Z half-axis.
inputs:scaleXNeg¶
Type: float. Default: 1.
Positive, finite multiplier of the shared axis scale on the negative local X half-axis.
inputs:scaleYNeg¶
Type: float. Default: 1.
Positive, finite multiplier of the shared axis scale on the negative local Y half-axis.
inputs:scaleZNeg¶
Type: float. Default: 1.
Positive, finite multiplier of the shared axis scale on the negative local Z half-axis.
Example¶
A 24 x 14 quad plank is lifted by one matrix mover whose joint holds a
static one-unit rise — no animation on the deformation at all. The only
spline in the file slides the Probe control along the plank, and the
sphere authored inside the probe joint rides it, so the region the mover
grabs travels and a bump walks back and forth. The plank is wider than
the ball and the travel stops short of both ends, so the field never
runs off an edge: it stays a complete red disc ringed by grey. In the
legacy wire draw, the max-weight interior is geometry at 50% opacity
with dotted great-circle rings on it, and the exterior falloff is the
same dotted wire — the translucent ball is inputs:falloffMin 0.6,
where the field is fully on and the plank is lifted the whole unit,
and the outer dotted sphere is inputs:falloffMax 1.6, where it is
fully off; linear between them so the ramp reads as an even slope
rather than a plateau with an edge.
Open it live with:
Re-render the GIF above with:
Tips¶
- Author the volume inside the joint or control it should follow: an unwired xformable takes its namespace parent's posed space, so a ball of influence needs no constraint and no wiring.
- Size the ball with
inputs:falloffMin/inputs:falloffMaxandinputs:scaleX/Y/Z, never with a scale in the transform — the placement has its scale and shear removed before the field is built, so a scale inherited from the volume's parent changes neither the field nor the drawn guide and simply does nothing. A non-positive or non-finite axis scale invalidates the packet outright. falloffMaxbelowfalloffMinflips the ramp with no special case — that is the hole-instead-of-ball idiom. The two exactly equal is the one degenerate case and means a hard step at that radius.