Skip to content

Control Control

The animator's handle: animation is authored on its avars.

Node type RigExecControl
Example control.usda

On this page:

Overview

Control effect

A control is the rig's interaction surface. An animator keys its translation, rotation, scale, and spin avars, and solvers and movers read the resulting posed frame. Controls draw a viewport guide at the posed origin — sphere, circle, box, cube, diamond or pyramid, drawn as curves (wire) or as solids (geometry), or custom wire polylines from guide:points — so the handle can be picked directly; unlike joints and solvers, a control is not a diagnostic, so it keeps the default render purpose.

An animator-facing RigExecXformable: animation is authored on the avars (or an authored/connected posed:space). Channel semantics live on the applied RigExecControlAPI. Publishes computePointFrame/computeRestFrame/ computeMatrix. A synthesized viewport guide can be drawn at the posed frame origin (see guide:shape) in the same synthesis-only style as the RigExecJoint guides; it carries the control's resolved purpose, which stays default unless authored.

How it works

A control is an input: no solver writes it, and its base frame comes from rest:space plus the avars each frame: translations and Euler rotations compose over the rest offset inside the selected parent and default spaces (avars * posed:defaultSpace * inverse(parent:defaultSpace) * parent:space), and scale avars apply before rotation and translation. A pose constraint that names the control on rigExec:moves, such as a harmonics jiggle, revises it in the pose phase, and a consumer that reads final sees the revision. Anything downstream — an FK chain listing the control, a constraint naming it as a source, a matrix mover reading its frame — follows the animated result with no further wiring.

Wiring

Relationship Points to Required
(none) Controls are read by solvers, constraints, and movers; they take no input relationships. -

Parameters

Control channel

rigExec:channelRole

Type: uniform token. Default: "pose".

Valid values: pose, switch, tweak.

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

rigExec:channelSpaces

Relationship.

Optional ordered pair of control providers publishing the rotation and translation channel bases in asset space. This is an explicit editing contract for a connected posed:space computation that consumes this control's unconnected TRS avars: rotation is S * R * rotationSpace, and position is translationSpace.Transform(T). A channel-independent scale multiplier before R is allowed. Hosts must read all three frames from the same evaluated publication and refuse editing if the providers are missing or singular. The pair does not replace evaluation or authorize editing an arbitrary solver output. Pivot edits are unavailable for this contract.

rigExec:translationEnabled

Type: uniform bool. Default: true.

Whether a channelSpaces control accepts translation edits. Rotation and scale remain editable when false.

guide:source

Relationship.

Optional single rig control or joint whose evaluated frame places the guide. Picking still selects the owning control.

avars:sx

Type: double. Default: 1.

Local X scale applied before rotation and translation; finite magnitudes below 1e-4 resolve to signed 1e-4, strict authoring rejects non-finite values, and raw non-finite USD resolves to identity on this axis.

avars:sy

Type: double. Default: 1.

Local Y scale applied before rotation and translation; finite magnitudes below 1e-4 resolve to signed 1e-4, strict authoring rejects non-finite values, and raw non-finite USD resolves to identity on this axis.

avars:sz

Type: double. Default: 1.

Local Z scale applied before rotation and translation; finite magnitudes below 1e-4 resolve to signed 1e-4, strict authoring rejects non-finite values, and raw non-finite USD resolves to identity on this axis.

guide:shape

Type: uniform token. Default: "circle".

Valid values: sphere, circle, box, cube, diamond, pyramid, custom.

Guide primitive synthesized at the control's posed frame origin (docs/specs/control-guides.md), exactly parallel to the RigExecJoint sphere/cone guides. The built-in shapes are unit-sized and centered at the origin: sphere and circle have radius 1, box and cube span +-1, diamond (octahedron) has vertices at +-1 on each axis, and pyramid has base corners (+-1, -1, +-1) with apex (0, 1, 0). circle and box are the planar shapes -- normal +Y, drawn in the local XZ plane -- while cube is the 3D box; this is the conventional rigging distinction between the two box-ish tokens. custom uses arbitrary local polylines from guide:points and guide:curveVertexCounts, preserving the evaluated affine frame.

guide:points

Type: point3f[]. Default: [].

Local vertices of a custom wire guide, placed by the evaluated control frame.

guide:curveVertexCounts

Type: int[]. Default: [].

Consecutive polyline sizes for guide:shape=custom. Each is at least two and their sum must equal guide:points size; otherwise no guide is drawn.

guide:planeNormal

Type: uniform token. Default: "Y".

Valid values: X, Y, Z.

Which LOCAL axis the planar guides' normal points along, for circle and box. Ignored by the volumetric shapes.

A rig's control curves lie in whichever plane the rigger drew them in. A planar guide drawn in a different plane from its curve shows edge-on, as a sliver of the right size.

Y is the default.

guide:drawMode

Type: uniform token. Default: "wire".

Valid values: wire, geometry.

wire draws the guide as curves, widthed by guide:wireWidth. geometry draws solid shapes instead; custom draws only as wire, so custom with geometry draws no guide.

guide:wireWidth

Type: double. Default: 0.05.

Width of the drawn wire guide curves, in the LOCAL pre-scale units of the unit shape -- so the drawn width tracks the evaluated control-frame scale multiplied by guide:scaleX/Y/Z along with the rest of the shape. A non-uniform effective scale thickens the curve anisotropically exactly as it stretches the points.

Zero, negative, or non-finite publishes no widths and falls back to hairline rendering; geometry draw mode ignores this entirely.

It has a default rather than being left unauthored because usdview picks with a single-pixel window: an unwidthed hairline is a one-pixel target that a real click virtually never lands on, and an empty pick deselects to the pseudo-root. The default width is what makes a wire control selectable at all.

guide:scaleX

Type: double. Default: 1.0.

Positive per-axis draw multiplier of the guide shape whose final size is abs(evaluated frame axis) * guide:scaleAxis, authored as three separate double properties rather than a vec3. The control's posed frame is orthonormalized for placement while its evaluated axis magnitudes are retained for sizing. A non-positive or non-finite guide multiplier on any axis draws no guide at all, independently of the signed 1e-4 floor on avars:sx/sy/sz.

guide:scaleY

Type: double. Default: 1.0.

Per-axis draw scale along the local Y axis; see guide:scaleX.

guide:scaleZ

Type: double. Default: 1.0.

Per-axis draw scale along the local Z axis; see guide:scaleX.

guide:offset

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

Where the guide shape is drawn, in the control's LOCAL frame, relative to the control's origin. The control still pivots, rotates and scales about its origin; only the drawn shape moves. It is what lets a control whose pivot is buried inside a character (the upper face turns about the base of the skull) be drawn somewhere it can be seen and picked. Scaled by the evaluated control-frame scale, so a scaled control carries its shape with it.

guide:orient

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

Rotation of the drawn shape in the control's LOCAL frame, applied after guide:scaleX/Y/Z and guide:planeNormal and before guide:offset. Lets a shape keep its placement when the control's own axes are re-oriented: the shape stays where it was drawn while the axes the animator rotates about change. Identity by default.

guide:displayColor

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

Constant colour of the synthesized guide. May be CONNECTED to another color3f attribute, in which case the first connection source's value at the evaluated time is drawn instead of the local one -- the imaging bridge follows the connection because UsdAttribute::Get never does. A source that math movers revise is read at this attribute's rigExecReadPhase: its authored base unless final or a checkpoint is declared.

guide:displayOpacity

Type: float. Default: 1.0.

Constant opacity of the synthesized guide. May be CONNECTED to a float or double attribute -- a limb's IK/FK dial, say -- and then the first connection source's value at the evaluated time is what is drawn, optionally complemented by guide:displayOpacityInvert and never below guide:displayOpacityMin. A dial that math movers revise is read at this attribute's rigExecReadPhase: its authored base unless final or a checkpoint is declared. An unconnected attribute draws exactly the value it holds, floor and invert ignored.

guide:displayOpacityInvert

Type: uniform bool. Default: false.

When guide:displayOpacity is connected, draw 1 - source instead of source. This is what lets one dial fade two control sets in opposite directions: the IK controls connect to the switch as-is, the FK controls connect to the SAME switch with this set, and there is no second source of truth to drift. Ignored when the opacity is not connected.

guide:displayOpacityMin

Type: uniform float. Default: 0.15.

Floor applied to a CONNECTED guide:displayOpacity after the optional inversion. A dial parked at its end stop would otherwise drive the inactive control set to exactly zero, and a fully transparent control is a trap: an animator who switches a limb to IK can no longer see the FK controls they need to switch back. Hydra still picks at any opacity above 0.0001, so the floor is for the eye, not the picker: 0.15 is enough to find a ghosted control against the character. Zero restores a true fade-out. Ignored when the opacity is not connected.

Example

Twelve controls in a 6x2 grid draw every built-in guide:shape in every guide:drawMode. Left to right in both rows: sphere, circle, box, cube, diamond, pyramid — box is the planar square lying flat in XZ, cube the solid six-sided one. The top row is wire (the guide is drawn as curves), the bottom row geometry (the same shape drawn as a solid). All twelve carry the same animation — avars:ry 0 → 90°, avars:rz 0 → 22° and avars:ty 0 → 0.25 by 1012, back to 0 by 1024 — and all twelve do real work: each feeds an FK chain that poses a joint resting at the control, and a matrix mover carries the grey card a unit below it. Watch either row against the blue rest outline the cards leave behind: ry spins the card about the handle's own origin, rz tips it out of the ground plane, and ty lifts it clear of the outline. The rotation is what the round shapes could not show on their own — a sphere or a circle turned about its symmetry axis looks identical — so the card is where the frame's motion becomes visible.

Open it live with:

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

Re-render the GIF above with:

python docs/render_media.py --page control

Tips

  • Keep rest:space at the handle's bind pose and animate only the avars; rest edits re-proportion every downstream solve.
  • guide:shape and guide:drawMode change the pickable viewport guide without touching evaluation; a pair the build does not draw synthesizes no guide at all rather than falling back to one.
  • guide:wireWidth is in the unit shape's local units — the drawn width is scaled by guide:scaleX/Y/Z along with the shape — and geometry draw mode ignores it entirely.

See also


UsdRig