Skip to content

Aim Constraint Aim Constraint

Rotates targets so a local axis points at blended sources.

Node type RigExecAimConstraint
Example aim_constraint.usda

On this page:

Overview

Aim Constraint effect

FBX-style aim: the transform named by rigExec:moves rotates so its aim vector points at the weighted source position, stabilized by the world-up policy. The everyday use is eyes tracking a look-at control, but the same node aims turrets, spotlights, and driven props.

FBX-style aim constraint. It rotates each transform named by RigExecMoverAPI rigExec:moves so inputs:aimVector points toward the weighted source position, with the selected world-up policy, axis masks, offset, and inherited normalized weight.

rigExec:aimTarget, rigExec:aimAxis, rigExec:upPolicy, and rigExec:preserve are retained as the legacy RigExec authoring contract so existing assets keep their authored fields. New assets use the inherited ordered rigExec:sources relationship and the FBX-style inputs below.

How it works

In the pose phase the constraint blends the ordered rigExec:sources into one goal position, builds the aim rotation from inputs:aimVector, inputs:upVector, and the world-up mode, then mixes the result over the incoming pose through the common mover envelope. Axis masks and the rotation offset shape the result per channel, and only rotation is written. New assets use sources; aimTarget/aimAxis/upPolicy/ preserve are the legacy contract kept for existing stages.

Wiring

Relationship Points to Required
rigExec:sources Ordered transform sources to track. yes
rigExec:moves Exactly one joint or provider to re-aim (pose phase). yes
rigExec:worldUpObject Provider for object world-up modes. no

Parameters

Common mover envelope

rigExec:moves

Relationship.

Reserved write-set relationship: exact prim/property targets.

inputs:enabled

Type: bool. Default: true.

Shape-preserving enable. Disabled movers pass their preceding revision through unchanged (value-only edit).

inputs:defaultWeight

Type: float. Default: 1.

Normalized common mover envelope in [0, 1]. With no bound rigExec:weightObject it broadcasts over every logical element: zero passes the incoming value through bit-for-bit and one applies the mover's full-strength result. A non-finite value or one outside [0, 1] passes the incoming value through with a diagnostic.

rigExec:weightObject

Relationship.

Optional compatible total weight field, at most one target. When bound, the weight object's values (including its own sparse or constant fallback) supply the common envelope instead of inputs:defaultWeight. Target, domain, and cardinality must match each mover application; an incompatible binding is a compile error. A multi-target mover may bind only a constant operation envelope whose weightTarget is the mover prim itself; that one value broadcasts to every application of the atomic mover.

Constraint base

rigExec:locked

Type: uniform bool. Default: false.

Authoring lock metadata for application interchange. Evaluation remains active while locked; use RigExecMoverAPI inputs:enabled or inputs:defaultWeight to disable or blend the operation.

inputs:affectTranslationX

Type: bool. Default: true.

Per-axis translation mask. Ignored groups are a compile error.

inputs:affectTranslationY

Type: bool. Default: true.

inputs:affectTranslationZ

Type: bool. Default: true.

inputs:affectRotationX

Type: bool. Default: true.

Per-axis rotation mask. Ignored groups are a compile error.

inputs:affectRotationY

Type: bool. Default: true.

inputs:affectRotationZ

Type: bool. Default: true.

inputs:affectScaleX

Type: bool. Default: true.

Per-axis scale mask. Ignored groups are a compile error. RigExecParentConstraint overrides the default to false to match the FBX runtime, which leaves scale off unless it is asked for.

inputs:affectScaleY

Type: bool. Default: true.

inputs:affectScaleZ

Type: bool. Default: true.

inputs:translationOffset

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

Additive translation offset applied after the source blend.

inputs:rotationOffset

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

Additive Euler rotation offset in degrees, applied after the blend.

inputs:scaleOffset

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

ADDITIVE scale offset applied after the blend, which is why its identity is (0, 0, 0) and not (1, 1, 1): the kernel computes blendedScale + offset. A multiplicative offset would be a different operator, not a different default.

rigExec:rotationOrder

Type: uniform token. Default: "XYZ".

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

Euler order for the operators that compose a rotation. Authoring it on one that does not is a compile error.

Ordered sources

rigExec:sources

Relationship.

Ordered transform sources. Order is preserved through composition because it identifies entries in every parallel source array.

inputs:sourceWeights

Type: float[]. Default: [].

Per-source weights parallel to rigExec:sources. An empty array gives every source equal, full weight. A non-empty array must have exactly one entry per source. Weights are relative: the sources mix by weight over their total, and each must be finite and not negative.

Node parameters

rigExec:worldUpRotationOnly

Type: uniform bool. Default: false.

objectRotationUp: take the world-up direction from the up object's ROTATION alone, orthonormalizing its frame first. A rotation extracted from a scaled or sheared frame is not that frame's rotation, so under a scaled rig root the derived up can swing far enough to turn an aim-constrained foot. Off (the default) extracts the rotation from the up object's frame as authored.

inputs:aimVector

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

Local-space vector that points toward the constrained aim direction.

inputs:upVector

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

Local-space vector used to stabilize roll around the aim direction.

inputs:worldUpVector

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

World-space up direction for the vector world-up mode. For objectRotationUp it is expressed in the up object's axes and turned by that object's rotation, or used as is when no up object is named.

rigExec:worldUpObject

Relationship.

Optional single transform provider used by object world-up modes. With none named, objectUp points the up at the scene origin.

rigExec:worldUpType

Type: uniform token. Default: "none".

Valid values: sceneUp, objectUp, objectRotationUp, vector, none.

rigExec:aimTarget

Relationship.

Legacy single aim source, read only when rigExec:sources is empty; retained for backward compatibility. With it and no world-up direction, the solve keeps the input frame's up rather than taking the minimum swing.

rigExec:aimAxis

Type: uniform token. Default: "x".

Valid values: x, y, z.

Legacy positive-axis selector retained for existing assets: it selects the aim axis only when inputs:aimVector is unauthored.

rigExec:upPolicy

Type: uniform token. Default: "preserveInputUp".

Valid values: preserveInputUp.

Legacy up policy retained for existing assets.

rigExec:preserve

Type: uniform token[]. Default: ["origin", "scale"].

Legacy component-preservation declaration retained for existing assets. Only the default is accepted; any other value is a compile error, and the inputs:affect* masks choose the channels instead.

Example

Two eye joints track a look-at control that sweeps across the front of the face. The control carries its own solid sphere guide, so the thing being aimed at is a visible orange ball rather than an implied point: it slides side to side and rises and falls, and each eye swings through about 70 degrees horizontally and another 20 vertically following it. Each eye is a small sphere with a bright iris cone on its front, both skinned rigidly to the aimed joint, so the iris points wherever the eye is aimed at every angle. Both eyes converge on the same target, so the closer the ball comes the more their lines of sight cross.

Open it live with:

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

Re-render the GIF above with:

python docs/render_media.py --page aim_constraint

Tips

  • Put pose-phase constraints in a scope ordered below Geometry (bottom executes first) so skinning reads their final output.
  • rigExec:worldUpType = "vector" with inputs:worldUpVector +Y keeps eyes level while they swing; none applies no roll correction at all (FBX minimum swing) -- but only once rigExec:sources is authored, because the legacy rigExec:aimTarget spelling still preserves the input up.
  • Make the look-at handle visible: it is an ordinary control, so on the RigExecControl prim guide:shape = "sphere" with guide:drawMode = "geometry" draws a solid ball at its posed origin instead of the default wire circle, sized by guide:scaleX/Y/Z times the evaluated frame scale. Seeing the target is what makes an aim rig readable -- an eye pointing at nothing is just a rotating eye.

See also


UsdRig