Volumetric weight objects¶
A weight object publishes a total scalar field over the logical elements
of one exact prim or property target. Two weight objects carry no
position: an authored table (RigExecStaticWeight) and a scalar-driven
modulation of one (RigExecDynamicWeight). With them a painted map is the
only way a point gets a weight, and painting is the one thing a
composition-native, code-authored rig cannot do.
Four more types fill that gap; three of them generate a field from a placed volume:
| Type | Base | Distance function |
|---|---|---|
RigExecVolumeWeight |
abstract, RigExecXformable |
— |
RigExecSphereWeight |
RigExecVolumeWeight |
\|(px/sx, py/sy, pz/sz)\| |
RigExecPlaneWeight |
RigExecVolumeWeight |
signed p[axis], optionally clipped to a rectangle |
RigExecCurveWeight |
RigExecVolumeWeight |
distance to the curve's polyline |
RigExecCombineWeight |
RigExecWeightObject |
folds other weight objects |
Sphere axis divisors are the shared inputs:scaleX/Y/Z multiplied by
inputs:scaleXPos/YPos/ZPos for nonnegative local coordinates and
inputs:scaleXNeg/YNeg/ZNeg for negative ones. All six directional
multipliers default to 1 and must be finite and positive. The origin stays
fixed; placement rotation determines the axes. These inputs are animatable
and affect evaluation, guides, and framing bounds.
Binary exports from inner format version 20 on carry all six directional inputs. Re-export
older .rigexec files and rebuild runtime consumers; USD source stages
retain their previous shape when directional inputs are absent.
The remap¶
Every volume shares one distance-to-weight remap:
u = clamp01((d - falloffMin) / (falloffMax - falloffMin))
u = lerp(u, 1 - u, invert)
w = strength * Curve(1 - u)
so the field is fully ON at inputs:falloffMin and fully OFF at
inputs:falloffMax — for a sphere they read directly as inner and outer
radii.
falloffMax < falloffMinis legal and flips the ramp. The signed denominator does it; there is no special case.falloffMax == falloffMinis the one degenerate case, and means a hard step at that distance.inputs:invertis a float, not 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 rather than popping.inputs:strengthis deliberately not clamped by the kernel.rigExec:rangePolicyis the authority on out-of-range weights, and clamping in the kernel would hide a strict-policy violation. Volume weights default toclamprather than the authored types'strict, because strength and invert are animatable and an artist scrubbing strength past one should see the field saturate, not invalidate the rig mid-drag.
Curve is a lookup table baked once per compiled rig, from either a
named rigExec:falloffProfile (linear, smooth, easeIn, easeOut,
constant) or — when the profile is curve — the Ts spline authored on
rigExec:falloffCurve. Both land in the same table, so the hot loop has
exactly one remap path and switching between a preset and a hand-drawn
curve changes only numbers. Every profile pins f(0) = 0 and f(1) = 1,
so switching never moves the band's endpoints, only its shape between
them.
A nonempty inputs:falloffSamples array replaces that table: uniformly
spaced samples of Curve from the outer boundary (0) to the inner
boundary (1), read as an ordinary per-frame input. The weight editor
previews a curve edit through it without authoring, then commits the
spline on release. Binary format 27 and later carry it; an older
.rigexec plays its compiled table.
Three decisions worth knowing¶
1. A volume weight is an RigExecXformable, not a RigExecWeightObject¶
usdGenSchema permits a typed schema exactly one base — "Schemas can only
inherit from one other schema at most" (usdGenSchema:512-522, verified
empirically). The three RigExecWeightObject contract properties are
therefore redeclared on RigExecVolumeWeight, so the composed prim
definition is identical; what is lost is only IsA-testability, and
RigExec already dispatches weight objects by type name everywhere.
_IsWeightObjectType in libs/rigExec/rigEvaluatorInputs.cpp names the
set for the evaluator; bakedProgram.cpp repeats it as
_IsBakedWeightType.
Spending the one base on the xformable side is what buys the behaviour a
rigger needs: the volume is one selectable, framable, UsdGeomBoundable
prim, positioned by the same Ir-aligned avars as every control and joint
— and because an unwired xformable follows its namespace-parent
xformable's posed space, a volume authored inside a joint rides that
joint with nothing wired. See ShoulderVolume in
examples/11_VolumeWeights.usda.
2. Shape comes from floats, never from the transform¶
The posed frame is orthonormalized before a guide is drawn (guides are
rigid). A scale baked into the transform would therefore deform the field
without deforming the drawn guide, and the artist would be painting with
a shape they cannot see. So the rigid placement positions the volume and
inputs:scaleX/Y/Z plus inputs:falloffMin/falloffMax are the sole
authority on its size. Guide and field agree by construction.
Both the weight-packet kernel (libs/rigExec/weightPackets.cpp) and the CPU
reference (libs/rigExecOracle/weightReference.cpp) call RemoveScaleShear() on
the placement before inverting it, for exactly this reason.
3. The falloff curve is structural¶
An input sampled per frame is a value at one time; a falloff curve is the
whole function. So the curve is structural: resampled to a
RigExecFalloffLut at Compile and held as a compiled input of the weight
packet until the next compiled rig. The consequence is that the curve's shape is
a rig-authoring parameter rather than an animation channel — which is also
what keeps the field fixed-shape. The animatable knobs are
falloffMin/falloffMax, invert, and strength, all of which are
ordinary per-frame inputs; a shape that has to change per frame goes
through inputs:falloffSamples rather than the curve.
OpenExec 26.08 has no accessor for an attribute's spline (// XXX:TODO
Accessors for AnimSpline in exec/computationBuilders.h:584), so the
OpenExec registration's computeFalloffLut is a stub, and the
reference check
supplies the compiled table as a RigExecValueOverride.
Editing the curve changes the structure digest and begins a new compiled rig.
The digest hashes the baked table, which also covers
rigExec:falloffProfile, rather than the knots; the animatable floats and
inputs:falloffSamples deliberately are not hashed.
The plane's two axes: the band along it, the extents across it¶
A plane weight carries two independent sizes and conflating them is the one mistake this shape invites.
inputs:falloffMin/falloffMaxare distances alongrigExec:planeAxis. They are the band, and they decide where the gradient starts and stops — the same meaning they have on every other volume.inputs:extentU/extentVare half-extents across it, in the two in-plane axesU = (axis + 1) % 3andV = (axis + 2) % 3(for the defaultythat is Z and X). They decide how far the sheet reaches.
They are different directions and different quantities, and neither can
be derived from the other. The guide used to try: with no authored
extent it sized its drawn square max(1, |falloffMin|, |falloffMax|), so
a rigger dragging the band watched the plane grow and shrink instead of
watching its two surfaces separate. Adding the extents fixes that from
both ends — the square now has a real size, and the band now only slides
it.
rigExec:planeBounds then turns that size into a boundary:
| field | |
|---|---|
unbounded (default) |
signed axis distance everywhere; the plane is infinite |
bounded |
the same distance inside the rectangle, exactly zero outside it |
Containment is hard — a point one epsilon outside gets zero, not a ramped-down weight — which is what was asked for and the only rule that makes the affected region exactly the drawn rectangle. Softening the border is composition's job: multiply the bounded plane by a sphere and the edge inherits that volume's falloff. That is the same answer this extension gives to every other "but softer" question.
unbounded is the default because it is what a half-space falloff wants
and what every plane weight authored before these properties existed
had. It is also structural — it selects which field function runs, so
it is hashed into the compiled rig signature next to rigExec:planeAxis, while the
extents are ordinary per-frame floats and deliberately are not.
The extents size the drawn guide either way, so an unbounded plane still
gets a square an artist can aim; only planeBounds decides whether that
square is a boundary or a label. The two read differently on purpose:
bounded draws the closed rectangle alone (what you see is what the
field covers), unbounded adds four short outward ticks at the edge
midpoints saying "this continues". The ticks are a separate curve element
rather than extra segments on the rectangle because in geometry draw
mode the rectangle is a mesh and cannot carry them, and they are a
fraction of the extent rather than a fixed length so they survive being
drawn at any scale.
Two independent implementations apply the bound — the weight-packet kernel
in libs/rigExec/weightPackets.cpp and the CPU reference in
libs/rigExecOracle/weightReference.cpp — and the CPU reference check holds them
together. A bound applied by only one of them still moves points, just not
the same ones, and the reference mismatch that produces is exactly the
failure TestPlaneBounded exists to catch.
Sample phase¶
The rigExecReadPhase metadata on rel rigExec:weightTarget decides which
points the distance is measured against. Any phase other than these two is
a compile error.
base(default) samples the static authored base points, so a point keeps the weight its bind pose earned — the behaviour of a painted map, and what a matrix mover wants so its own output cannot feed back into its own weights.rel rigExec:sampleSourceoptionally overrides what is sampled without changing what is weighted, which is how one mesh is weighted by another mesh's shape.precedingsamples the points as they stand at that operation's position in the mover stack, so the volume grabs whatever is inside it right now. Order dependent by construction: the same volume at two points in the stack legitimately yields two different fields.
A preceding weight is a per-revision read. Each revision whose weight
object samples preceding gets its own field, measured against the point
version entering that revision, and uses it in place of the shared packet
(currentPhasePacket in libs/rigExec/bakedGeometry.cpp).
Know the cost before reaching for it. A base field is one packet per
generation, shared by every mover that binds the weight object. A
preceding field cannot be shared, so every revision that samples it pays
for its own field evaluation. Reach for preceding where the behaviour is
actually wanted (a volume that should grab whatever has been deformed into
it), not as a general-purpose "more correct" setting.
Composition¶
RigExecCombineWeight folds an ordered list of weight objects. Every
input is resolved to a dense field over the same element count before
folding, so a painted RigExecStaticWeight, a driven
RigExecDynamicWeight, and a generated volume compose without any of
them knowing about the others.
multiply, add, max, min, and average are order independent.
subtract and overlay are not: they seed from the first input and
fold the rest in authored target order. That is the one place this
extension departs from the spec §7.2 rule that target-list permutation
cannot change a result, and it is stated rather than hidden — authors who
need a permutation-proof composition use a commutative mode.
Combines nest, and nesting is how mixed modes are expressed: one combine carries one mode, so a relationship never has to carry per-target metadata. (falloff list attaches a mode to each entry; a USD relationship cannot, and nesting is the composition-native answer.)
A length mismatch between inputs is a structural error, not a truncated fold — a short input would silently read as identity over its missing tail.
Where the code lives¶
| Concern | File |
|---|---|
| Schema | libs/rigExecSchema/schema.usda (volumetric section) |
| Pure kernels | libs/rigExecMath/weightFields.{h,cpp} |
| Weight packets | libs/rigExec/weightPackets.cpp, libs/rigExecScene/weightProgram.cpp |
| OpenExec registrations, used only by the reference check | libs/rigExec/moverKernels.cpp (_Build*WeightPacket), libs/rigExec/computations.cpp (RIGEXEC_REGISTER_XFORMABLE(RigExecVolumeWeight)) |
| LUT packet type | libs/rigExec/types.h (RigExecFalloffLut) |
| CPU reference | libs/rigExecOracle/weightReference.cpp |
| Compiled rig and falloff tables | libs/rigExec/rigEvaluatorCompile.cpp, libs/rigExec/rigEvaluatorGeometry.cpp (_BakeFalloffLut) |
| Resolved field for tools | RigExecRigPose::weightFields |
| Authoring UI | plugin/rigExecUsdview/volumeWeightUI.py, plugin/rigExecUsdview/weightViewport.py |
| Influence overlay + guides | libs/rigExecImaging/ (RigExecImaging_SetWeightOverlayForStage) |
| Example | examples/11_VolumeWeights.usda |
| Tests | tests/testRigExecWeightFields.cpp, tests/testRigExecWeightProgram.cpp, tests/testRigExecVolumeWeights.cpp, tests/testRigExecWeightOverlay.cpp, bin/test/run_testusdview_overlay.bat |
Registering computations on an abstract base¶
This section concerns the OpenExec registrations, which only the
reference check
and tests request. RIGEXEC_REGISTER_XFORMABLE is invoked on the
abstract RigExecVolumeWeight, unlike RigExecJoint/RigExecControl
which are concrete. Exec composes a prim's computation set by walking its full
ancestor type vector strongest-to-weakest
(exec/definitionRegistry.cpp::_GetFullyExpandedSchemaTypeVector), so
the three concrete volume weights inherit the three xformable
computations from the base.
It has to be the base here, because the concrete types already carry an
EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA block in moverKernels.cpp for
computeWeightPacket, and one schema may only be opened once: the macro
emits a whole registration function plus its TF_REGISTRY_FUNCTION per
invocation, and a second block for the same schema is a second,
independent registration pass over a type the first pass has already
marked complete. Splitting by type rather than by file keeps each
schema opened exactly once.
The influence overlay, and the trap under it¶
RigExecImaging_SetWeightOverlayForStage(stageCacheId, primPath) paints
a weight object's resolved field onto its target geometry as a vertex
displayColor, grey at 0 to red at 1 — the Rhythm & Hues Voodoo idiom —
under the default
guide:weightDisplay = "tint"; heatmap and bands use a five-color
ramp instead. Pass "" to turn it off. The volume's own falloffMin and
falloffMax iso-surfaces draw as guides through the same synthesis
protocol the control and joint guides use. The default guide:drawMode
is falloff: a soft inner shell at falloffMin and a dashed exterior cage
at falloffMax, with cage, brackets, and shell as lighter variants
and none hiding the guide. A sphere weight in wire mode draws the
max-weight interior (falloffMin) as geometry at 50% opacity with dotted
great-circle rings on that fill, and the exterior falloff (falloffMax)
as a dotted wire. Plane and curve weights in wire mode draw both
iso-surfaces as continuous wires. geometry draws every iso-surface
solid.
A primvar appearing is a resync, not a dirty.
HdSceneIndexAdapterSceneDelegate caches each rprim's primvar
descriptors and rebuilds them from PrimsAdded. A dirty — even
HdDataSourceLocatorSet::UniversalSet() — re-pulls values for the
descriptors it already has. So turning the overlay on while the mesh was
already synced left a perfectly correct red displayColor sitting in the
scene index one hop upstream, with Storm never asking for it and the mesh
rendering grey forever.
Every scene-index-level assertion passed throughout. The bug was only visible in the framebuffer, and the measurements are worth keeping because they are what distinguishes the two hypotheses:
| red-ish pixels | |
|---|---|
| overlay off | 1009 |
| overlay on, dirty-notice path | 997 |
| overlay on, cold renderer rebuild | 3456 |
A cold rebuild rendering red is what proved the data path was already
correct and the fault was purely invalidation. The fix re-announces the
prim with its upstream type on the on/off transition
(sceneIndices.cpp, the structural arm of NotifyGenerationPublished).
bin/test/run_testusdview_overlay.bat (and bin/test/run_testusdview_overlay.sh) now
asserts on pixels, not just on the scene index, and that assertion is
mutation-verified: disabling the resync makes it fail while every other test in
the suite still passes.
It asserts on the difference between the overlay-off and overlay-on frames, not on how much red is in either one. RigExec draws its own guide geometry, the volume rings and bars are red, and they cover far more of the viewport than the strip does — so an absolute red-pixel count is mostly guides, and it shifts whenever guide drawing changes. Differencing cancels them, since they are identical in both frames. The measurement is a fraction of the frame rather than a pixel count so that window size and HiDPI do not enter into it: the overlay moves 2.8% of the frame, a disabled resync moves 0.0%, and the threshold sits at 0.5%.
The second invalidation trap: who hears an edit first¶
The overlay repainted correctly on the toggle and then appeared frozen
while a rigger dragged inputs:falloffMax. It was not frozen — it was
one edit late, and so was the geometry. A drag hides that almost
perfectly: every mouse-move step draws the previous step's answer, so the
picture moves and only the final value is wrong.
RigExecImagingRegistry::_OnObjectsChanged re-evaluates from inside
UsdNotice::ObjectsChanged dispatch. Tf_NoticeRegistry::_Register
prepends its deliverer, so listeners run most-recently-registered
first. A listener that re-evaluates must therefore run after every
listener that drops cached values for the same edit, or it publishes a
pre-edit answer. The registry registers its listener before Compile()
(libs/rigExecImaging/registryLifecycle.cpp:233), which puts it at the back of the
delivery list.
Production evaluation holds no OpenExec ExecUsdSystem, whose
_NoticeListener drops cached computed values when an attribute is
authored. Only the RigExecTapSet requests of the
reference check
and of tests create one. _OnObjectsChanged first calls
RigExecTapSet::PrepareStageChange (registryInvalidation.cpp:499), which retires
those requests when a prim is removed.
Two things are worth carrying forward. First, a direct SetTime() call
cannot see this class of bug, because the dispatch has ended by then.
TestAuthoredEditRepublishesFreshField in testRigExecWeightOverlay.cpp
therefore authors to the stage and lets the notice do the republishing.
Second, a plain default Set and the spline knot the authoring panel
writes are not equivalent through USD's change classification, so the
test covers both.
The third cause of the same symptom: the wrong frame¶
Two edit-freshness bugs above, and a third that presents identically and lives somewhere else entirely: the usdview plugin published the frame the artist had just left.
RootDataModel.currentFrame's setter emits currentFrameChanged(value)
and only then assigns self._currentFrame
(Usdviewq/rootDataModel.py:158-160), so
RigExecUsdviewContainer._OnFrameChanged re-reading
dataModel.currentFrame was handed the previous frame. Every
publication still happened, on time and in order, with the wrong pose in
it.
That is worse than it sounds, because it compounds with the authoring
panel. volumeWeightUI.SetAtTime writes a spline knot at the frame
the artist is looking at; an engine sitting one frame back resolves the
knot they did not touch, so scrubbing inputs:falloffMax changes the
picture not at all. Measured on 11_VolumeWeights at frame 1024, with
the overlay on and the band scrubbed through the panel's own call:
| red-ish pixels | published field | |
|---|---|---|
before, falloffMax 2 |
12228 | frozen at the frame-1001 field |
before, falloffMax 8 |
12250 | the same frozen field |
after, falloffMax 2 |
2182 | 0.87, 0.48, 0.05, 0, … |
after, falloffMax 8 |
5635 | 0.99, 0.95, 0.88, 0.79, … |
The fix is to use the frame the signal carries
(rigExecUsdview.py::_OnFrameChanged), and the reason it survived so
long is that testUsdviewRigExec.py counted generations rather than
checking which frame was in them. It now drives one frame both ways --
through currentFrame and through RigExecImaging_SetTimeForStage, which is
unambiguous by construction -- and compares the published points.
Mutation-verified: restoring the property read fails that comparison
((0.0, 9.5, 0.0) vs (0.06, 10.13, 0.48)) while
bin/test/run_testusdview_overlay.bat and all nine ctest binaries still pass,
which is exactly the blindness that let it ship.
What the compiled rig signature is and is not tested for¶
TestPlaneBounded asserts the bounded field, and it passes with
rigExec:planeBounds removed from the structure digest entirely -- each
Resolve() builds a fresh evaluator, so there is no stale compiled rig for an
unhashed token to strand. The digest therefore needs its own case, and
TestPlaneBoundsCompiledRigSplit is it: one evaluator, edited twice.
inputs:extentU/Vmust change the field and not the digest. A digest that hashes an animatable float rebuilds the whole rig on every mouse-move of the scrub row that drives it.rigExec:planeBoundsmust change both, and raise thecompiled rig rebuiltdiagnostic.
Mutation-verified in both directions: dropping the planeBounds hash
fails the second half, and adding an extentU hash fails the first,
each with nothing else in the suite noticing.
TestPlaneBoundedInvalidExtents covers the remaining arm, where the two
implementations could disagree quietly: bounded with a non-positive
extent is rejected by the weight-packet kernel (an invalid packet) and by the
CPU reference (an error), and both have to mean pass-through downstream. A
kernel that read a negative extent as "unbounded" would move points the
reference leaves alone and only the reference check would see it.