Ribbon¶
Samples a driver curve into transported frames for wrap deformers.
| Node type | RigExecRibbon |
| Example | ribbon.usda |
On this page:
Overview¶

Turns a native B-spline driver into a run of evenly spaced,
rotation-minimizing frames. A curve mover then rides geometry along those
frames, so a strip keeps its length and cross-section while the driver
bends — the classic spine/tentacle rig. The mover reads the frame array
off this prim directly; naming a joint per sample on rigExec:joints is
optional, and buys a posed chain that constraints and matrix movers can
read like any other joint.
Samples a native UsdGeomBasisCurves.points driver, read as one nonperiodic cubic uniform B-spline (linear below four points), at rigExec:sampleCount equal arc-length steps and transports a rotation-minimizing frame along it. The rest frames come from the driver's default-time points. Publishes computePointFrameArray; an empty driver or fewer than two samples publishes no frames.
Sampling is always by arc length with rotation-minimizing transport, whatever rigExec:parameterization and rigExec:frameTransport say. rigExec:startFrame, rigExec:endFrame and rigExec:twistFrames order the solve after any solver they name but supply no value to it.
How it works¶
All of it is pose phase: the solve is one solver operation
(libs/rigExecScene/solverProgram.cpp:91), and RigExecRibbon is one of
the six compiled solver types (libs/rigExec/bakedProgram.cpp:160). The
compiler resolves rigExec:driverCurve to the target's native points
attribute and the solve reads two values of it — the live one, at the read
phase declared on rigExec:driverCurve
(libs/rigExec/crossDomainInputs.cpp:244), and the bind-time (default)
one — then samples both at equal arc length and transports a
rotation-minimizing frame along each
(libs/rigExecMath/geometryKernels.cpp:805), publishing the posed frames
paired with their rests as one computePointFrameArray. Each
rigExec:joints entry takes one element of that array as its whole posed
frame through the compiled solver-to-joint binding. What a wrap measures
against is the bind-time curve.
Wiring¶
| Relationship | Points to | Required |
|---|---|---|
rigExec:driverCurve |
Native BasisCurves supplying the spine path; without it the solver publishes no frames rather than erroring. | yes |
rigExec:startFrame |
Joint provider naming the run's base; declared for authoring intent, read by no computation. | no |
rigExec:endFrame |
Joint provider naming the run's tip; the same. | no |
rigExec:twistFrames |
Twist solver named as the run's unwind; the same. | no |
rigExec:joints |
Ordered joints posed along the run, one per sample. | no |
Parameters¶
Node parameters¶
purpose¶
Type: uniform token. Default: "guide".
Render purpose, overriding UsdGeomImageable's default
fallback: joint and solver guides are DIAGNOSTICS, drawn when a
viewer asks for guides.
This is the stock attribute rather than a RigExec-specific token so
that the bounds and the drawing cannot disagree: UsdGeomBBoxCache
classifies a prim's extent by this exact attribute, and the results
scene index stamps the same resolved value onto the guide it
synthesizes. A control keeps the inherited default -- it is the
rig's interaction surface, not a diagnostic -- and authoring
guide on one moves both its drawing and its bounds together.
rigExec:driverCurve¶
Relationship.
rigExec:startFrame¶
Relationship.
rigExec:endFrame¶
Relationship.
rigExec:twistFrames¶
Relationship.
rigExec:sampleCount¶
Type: uniform int. Default: 5.
rigExec:parameterization¶
Type: uniform token. Default: "arcLength".
Valid values: arcLength, parametric.
rigExec:frameTransport¶
Type: uniform token. Default: "rotationMinimizing".
Valid values: rotationMinimizing.
rigExec:joints¶
Relationship.
Ordered output joints posed along the ribbon. The compiler binds each joint to one aggregate element.
rigExec:jointElements¶
Type: uniform int[]. Default: [].
Optional aggregate element index per rigExec:joints entry (parallel array). When absent/empty, element = list position.
guide:radius¶
Type: double. Default: 1.0.
Radius of the sphere and cone drawn at each aggregate element: the exact counterpart of RigExecJoint's guide:radius, including the rule that zero or negative draws no guides at all, which is how a solver's diagnostics are turned off.
Without it the elements draw at Hydra's fallback radius of 1.0, which is proportionate on an asset authored at tens of units and several times the size of the whole character on one authored at one unit.
guide:displayColor¶
Type: color3f. Default: (0.3, 0.6, 1.0).
guide:displayOpacity¶
Type: float. Default: 0.5.
Example¶
A 24-quad strip stands seven units tall beside an invisible
four-CV B-spline driver — offset a half-width along the bind binormal, so
the driver run and the nine joint guides on it sit clear of the mesh
instead of inside it — and the driver's control points swing on a
staggered cycle. The strip curls up one side until its tip has travelled
2.2 units across, dropped 2.2 and swung 1.0 toward camera around frame
1006; it sweeps back through upright near frame 1012, at its deepest
point toward camera (2.8 units, frame 1013); then it whips 4.0 units out
the other way by frame 1018 and recovers, closing the loop exactly at
frame 1024. The out-of-plane half of that swing is the part worth
watching: it is authored a quarter cycle out of phase with the sideways
sweep, so the driver is never planar and the rotation-minimizing frames
visibly roll as the strip travels — a planar driver would bend without
ever twisting. Only the two upper control points carry that Z, and the
upper one carries nearly all of it: the first tangent is set by CV0 and
CV2, and the seed normal is the world axis least parallel to it, so a Z
component there large enough to beat the X component would pick a
different axis and roll the whole wrap 90 degrees.
rigExec:sampleCount is nine, a curve mover in ribbon mode rides the
strip along the run through its primvars:st bind coordinates, and a
nine-joint chain named on rigExec:joints takes the same nine samples so
the run reads as a dense spine running up the edge of the bending
ribbon.
Open it live with:
Re-render the GIF above with:
Tips¶
- Never bind the driver perfectly straight. The seed normal is the world axis least parallel to the first tangent, picked once per curve, and a tie is broken by declaration order X, Y, Z (
libs/rigExecMath/geometryKernels.cpp:893-900), so a straight bind against bent poses picks a different axis for the rest than for the pose and rolls the whole wrap 90 degrees. Rest it at a lean and keep the leaning component of the first tangent larger than the other one all the way through the animation. rigExec:startFrame,rigExec:endFrameandrigExec:twistFramesare declared but never read: the solve's only inputs are the driver points,rigExec:sampleCountand the rests of the joints onrigExec:joints(libs/rigExec/moverKernels.cpp:877-885,libs/rigExec/bakedPose.cpp:574). A solver one of them names is still scheduled before the ribbon. What actually pins the run is the bind-time driver curve.rigExec:sampleCountis the run's cardinality. Below two the solver publishes no frames at all (libs/rigExec/solverKernels.cpp:66) and no joint element can bind, and time-sampling it is rejected at compile (libs/rigExec/rigEvaluatorCompile.cpp:824).