Skip to content

Pose Interpolator Pose Interpolator

Turns a driver's rotation into one float per authored pose.

Node type RigExecPoseInterpolator
Example pose_interpolator.usda

On this page:

Overview

Pose Interpolator effect

A pose interpolator is pose-space deformation's measuring device: one driver joint in, one weight per authored RigExecPose child out. Each pose records where the driver stands — a quaternion measured in the driver's own parent frame, relative to the driver's rest — plus how wide its influence reaches, and the interpolator publishes each pose's share of wherever the driver is now. It writes no transform and no points, so it is not a mover and carries no rigExec:moves; what makes it useful is that a RigExecBlendInput connects its inputs:weight to a pose's outputs:weight, so a corrective shape can be retargeted or layered without touching the interpolator that fires it.

A pose interpolator: one driver joint in, one weight per authored RigExecPose child out.

WHY A DRIVER JOINT AND NOT THE CONTROL THE ANIMATOR MOVES. A corrective wants to fire on one piece of a limb's motion and not another -- a wrist that twists should not trigger the shape for a wrist that bends. The rig builds that split out of the HIERARCHY rather than out of maths: it parks a hidden joint under the bone that already carries the twist and orient-constrains it to the bone that carries everything, so the parent subtracts the twist back out and the driver's LOCAL rotation is the swing alone. Point it the other way and the same subtraction yields the twist. This port keeps those joints -- shoulder_?driver, wristSwing?_driver and the rest -- so the weights come out of the rig's own arithmetic rather than something that resembles it.

The maths is a radial basis function and lives in libs/rigExecMath/rbf.h, held to 1e-6 by the parity fixture (tests/fixtures/psd_parity.json), whose 13,400 biped evaluations agree to 3.41e-11. The solve is a per-interpolator CONSTANT -- invert the matrix of every pose's kernel value at every other pose -- so it happens once and only the kernel row is per-frame. Nothing on this prim is that inverted matrix, because the matrix is a function of the poses, the per-pose radii, the kernel and the regularization, all of which ARE here: re-deriving it at compile time is exact, and storing it would be a second copy to keep in step.

The falloff width the fit solved with is not carried in the data, so the radii on the poses were FITTED by RigExecRbfFitWidth rather than read -- see rigExec:rotationRadius on RigExecPose for what that means for anyone editing one.

The prim is not a mover: it writes no transform and no points. It publishes a float per pose and a RigExecBlendInput's inputs:weight connects to it, which is what makes a corrective independently composable -- a layer can retarget one shape's channel without touching the interpolator that drives it.

How it works

The maths is a radial basis function (libs/rigExecMath/rbf.h). Compile reads the driver, the kernel, the channel switches and every enabled pose's rotation, type and radius, and inverts the kernel matrix once — it is a pure function of the authored poses, so nothing on the prim stores it. Evaluation is one operation of the shared graph that reads the last version of its driver's frame and of its nearest joint or control ancestor's, so dependencies place it after every operation that writes them and before the blend channels that read its weights (libs/rigExec/bakedPose.cpp:2627-2635): it takes the driver's final and rest frames, forms delta = restLocal⁻¹ · (parent⁻¹ · world) (libs/rigExecMath/poseArithmeticKernel.h:305-307), runs one kernel row through the inverted matrix, and publishes a float on each pose's outputs:weight into both the resolved-input table a consumer reads through and the rig pose's moved-property map (bakedPose.cpp:5914-5917). A driver with no usable final frame is diagnosed and the interpolator publishes zeros rather than quietly measuring a rest (bakedPose.cpp:5656-5661).

Wiring

Relationship Points to Required
rigExec:driver One RigExecJoint or RigExecControl whose local rotation every pose is measured against; a RigLogic solve takes several. Omit it when rigExec:driverAttributes names numeric drivers instead. unless numeric drivers
RigExecPose children One prim per pose, directly under the interpolator; any other child type is a compile error. yes
<pose>.outputs:weight Read by a consumer — a RigExecBlendInput's inputs:weight connects to it. The pose's own outputs:weight must carry no authored connection. -
rigExec:poseControls Authoring provenance on each pose: the control properties that put the rig into it. Never read at evaluation. no

Parameters

Pose

rigExec:poseType

Type: uniform token. Default: "swing".

Valid values: swing, twist, whole.

poseType (1 swing, 2 twist, 0 whole): WHICH PART of the driver's rotation this pose is measured against.

The metric belongs to the pose and not to the interpolator because one driver usually carries both at once and they mean different things: a neck that has twisted has not bent, and its bend shapes should stay at zero. Measuring the whole rotation instead leaks about 0.05 of every swing pose into a pure twist on the shipped biped.

rigExec:rotation

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

Where the driver stands in this pose: its LOCAL rotation relative to its own rest, in the driver's parent frame.

REBASED. The authored poseRotation is measured from whatever configuration the rig happened to be in when the poses were captured, which on this character is 3 to 10 degrees off the bind pose -- a wrist FK control reading 10 degrees, an elbow 4.7. This port's drivers DO read identity at bind, so the neutral quaternion is taken out of every pose (neutral^-1 * pose) before it is authored here. It is a rigid rotation applied to all of them, so every pairwise distance and therefore the whole solve is unchanged; only the point the poses are measured FROM moves, which is the thing that was wrong. Skipping it moved the skin about two millimetres.

Measured against this port's own drivers it lands at 0.00 degrees on the elbow, the knee and the toe and 1.64 on the shoulder.

rigExec:translation

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

The driver's translation in this pose, in the driver's own rest frame and its frame's units (CENTIMETRES on the shipped biped). Read only when the interpolator has rigExec:enableTranslation on or numeric drivers, whose values it then holds in their own units (rigExec:driverAttributes); an interpolator with no authored translations has nothing to say about translation, and saying every pose is equally close would peg its weights at 1/n.

rigExec:rotationRadius

Type: float. Default: 0.

How far in RADIANS the driver may stray before this pose's kernel has fallen away -- one falloff width, this pose's own.

FITTED, NOT EXPORTED. The width a set of poses was tuned with is not in the data; rigExec:falloff, a share relative to the closest other pose, is. So the shape of the rule is preserved and the size is not recoverable, and one scale for the whole rig does not work because the pose layouts are not alike: the thigh has poses 25 to 150 degrees apart, the shoulder eight with pairs 45 apart, the index three in a line. Narrow enough for the shoulder leaves the thigh with a hole in the middle of every swing; wide enough for the thigh sends the shoulder's weights to 9.

RigExecRbfFitWidth therefore fits it per interpolator to two requirements, in order: no dead zone (the kernels sum to at least 0.5 everywhere between the poses), then the least overshoot among the widths that manage it. A painted rigExec:falloff other than the default 0.3 is applied on top as falloff/0.3.

Compile uses the authored width as it stands and fits nothing. Zero is a zero width: the pose reads as infinitely far from every rotation but its own, so its kernel contributes nothing between the poses. To get the fit, run rigexec.rbf_fit_width (RigExecRbfFitWidth) and author the widths it returns.

rigExec:translationRadius

Type: float. Default: 0.

The same width for the translation channel, in rigExec:translation's units.

It is NOT the rotation radius and must not be borrowed from it: a brow's poses sit millimetres apart and a rotation width would swallow every one of them. rigexec.rbf_fit_width fits it by the same swept scale, because the metric already divides each channel by its own width -- the shape of the pose space is fixed by the RATIO of the two and only its overall size is free. As with rigExec:rotationRadius, compile reads it as authored and zero is a zero width.

rigExec:rotations

Type: quatf[]. Default: [].

A RigLogic solve with several frame drivers: where each driver stands in this pose, one rotation per rigExec:driver target in order, measured as rigExec:rotation is. Empty with one driver reads rigExec:rotation; any other count than one per driver is a compile error.

rigExec:scale

Type: uniform float. Default: 1.

A RigLogic solve multiplies this pose's normalized weight by this before the threshold: RigLogic's pose scale.

rigExec:falloff

Type: float. Default: 0.3.

poseFalloff, kept as provenance and as the editable dial: the share the artist painted on top of the fitted width, where 0.3 is the default and means just reach the closest other pose. 0.3 on every pose of the shipped biped except the clavicles and the mouth corners, which are 0.5.

The radii above already carry it (falloff/0.3, floored at 0.05), so it is not applied a second time at runtime. It is here so that an editor changing it can re-derive them, and so that a rig whose radii were hand-tuned still says what it started from.

rigExec:poseControls

Relationship.

The exact control PROPERTIES that put the rig into this pose -- an L_LoArm control's avars:rz on the shipped biped, and the like -- parallel to rigExec:poseControlValues. Properties rather than prims because a control carries nine channels and a pose usually sets one.

It is authoring data for a tool that jumps the rig to a pose to sculpt against it: nothing in evaluation or in the bundled Shape Editor reads it, and a pose with none is still a valid pose.

rigExec:poseControlValues

Type: double[]. Default: [].

The value for each target of rigExec:poseControls, in OUR units and from OUR zero: degrees for a rotation avar, centimetres for a translation one, measured from the rig's rest rather than from the authored data's.

The authored numbers are absolute and in radians, and their zero is the configuration the poses were captured in rather than the bind pose. Measured: driving this rig with those absolute values reaches the authored quaternion to 45.4 degrees on the shoulder and 10.0 on the wrist; driving it with (pose - neutral) reaches 1.64 and 0.00. So the subtraction happens once, at build time, and what is stored is what an editor can set directly.

inputs:enabled

Type: bool. Default: true.

Shape-preserving enable. A disabled pose publishes zero and is left out of the solve entirely rather than solved and then silenced: leaving it in would keep it in every other pose's matrix row, so switching one pose off would quietly change all the others.

outputs:weight

Type: float. Default: 0.

How much this pose counts, for wherever the driver is now. The output a RigExecBlendInput's inputs:weight connects to.

1 with the driver standing on this pose, and elsewhere a share of the interpolator's normalized total -- which may be negative when rigExec:allowNegativeWeights is on, and should be: that is the instruction to lean away from a pose, and clamping it is what makes a blend muddy.

Node parameters

rigExec:driver

Relationship.

The driver: a RigExecJoint or RigExecControl whose LOCAL rotation -- its pose relative to its own rest, in the frame of its nearest joint or control ancestor -- is what every pose is measured against. At most one target for the pose solver; a RigLogic solver (rigExec:solver additive or interpolative) takes several, each one quaternion of the input row in target order.

LOCAL, not world, and relative to rest rather than absolute: the rest orientation is the joint orient the authored data removes from poseRotation, so a driver sitting at its rest measures as identity and the neutral pose reads 1.000 with the rig standing still.

rigExec:driverAttributes

Relationship.

A NUMERIC driver: one to three float or double PROPERTIES -- avars, usually -- read in order as the driver's position, in place of a transform's translation.

This is what lets a corrective be driven by a dial rather than by something the rig moves: a breath, a squash amount, a shot-specific knob. Each pose carries the values it stands at in rigExec:translation and their width in rigExec:translationRadius, so the solve, the fit and the baked program are the ones the translation channel already had -- the only difference is where the position comes from.

Authoring this makes rigExec:driver optional (a RigLogic solve refuses both) and measures no rotation: there is no frame to take one from. Up to three because that is what one position is; a corrective wanting more channels is two interpolators whose weights multiply.

rigExec:solver

Type: uniform token. Default: "pose".

Valid values: pose, additive, interpolative.

Which solve turns distances into weights.

pose is this interpolator's own solve: per-pose widths, swing, twist and whole pose types, an optional translation channel, and the inverse of the pose matrix.

additive and interpolative are RigLogic's solvers (Epic Games OpenRigLogic, see docs/references.md). additive sums each pose's kernel value; interpolative weights them through the inverse of the pose-to-pose kernel matrix and clamps each to [0, 1]. Both then apply rigExec:normalizeMethod, each pose's rigExec:scale and rigExec:weightThreshold. They read rigExec:distanceMethod, rigExec:radius, rigExec:automaticRadius and rigExec:twistAxis, and ignore the pose solver's radii, pose types, translation channel, regularization, normalize and allowNegativeWeights.

A RigLogic solve's input row is each frame driver's local rotation from rest as (x, y, z, w) on the w >= 0 hemisphere, in rigExec:driver order, or the numeric drivers' values as read. A pose's row is its rigExec:rotations (or rigExec:rotation for one driver), or the first values of its rigExec:translation.

rigExec:distanceMethod

Type: uniform token. Default: "quaternion".

Valid values: euclidean, quaternion, swingAngle, twistAngle.

A RigLogic solve's metric. euclidean is the n-dimensional distance over the raw row and is the only one numeric drivers may use. quaternion sums, over the drivers, the squared arc length between rotations, and takes the square root. swingAngle does the same on the swing about rigExec:twistAxis, and twistAngle on the difference of unwound twist angles, which keeps +120 and -120 degrees 240 apart.

rigExec:normalizeMethod

Type: uniform token. Default: "onlyAboveOne".

Valid values: onlyAboveOne, always.

A RigLogic solve's normalization: divide the weights by their sum only when it exceeds one, or always.

rigExec:automaticRadius

Type: uniform bool. Default: false.

A RigLogic solve's radius is the mean distance between every pair of poses, in place of rigExec:radius.

rigExec:radius

Type: uniform float. Default: 0.

A RigLogic solve's kernel width, in the metric's units: radians for quaternion, swing and twist, the drivers' own units for euclidean. Zero leaves only an exact match with any weight.

rigExec:weightThreshold

Type: uniform float. Default: 0.

A RigLogic solve publishes zero for any pose whose normalized, scaled weight is at or below this.

rigExec:kernel

Type: uniform token. Default: "gaussian".

Valid values: gaussian, linear, exponential, cubic, quintic.

How a pose's weight falls away with distance. Of the parity fixture's 67 biped interpolators, 16 are gaussian and 51 linear.

exponential, cubic and quintic are RigLogic's weight functions: exp(-2 d/r), max(0, 1 - (d/r)^3) and max(0, 1 - (d/r)^5). In the pose solver gaussian is exp(-(d/r)^2); in a RigLogic solve it is RigLogic's exp(-d / r^2), which depends on the radius's units.

Gaussian never quite reaches zero, so a little of every pose survives everywhere -- a soft blend. Linear reaches zero AT the radius and has compact support, so past the radius a pose is not nearly off, it is off, which is what makes the coverage floor in rbf.h worth measuring.

rigExec:enableRotation

Type: bool. Default: true.

enableRotation: measure the driver's rotation.

Honoured rather than assumed. On the biped the two channels are mutually exclusive -- 39 of the parity fixture's interpolators rotation, 28 translation -- and reading a translation interpolator as a rotation makes every one of its poses identity, so it solves degenerate and drives nothing.

rigExec:enableTranslation

Type: bool. Default: false.

enableTranslation: measure the driver's translation as well, in the driver's own frame. Radians and centimetres cannot be added, so each channel is divided by its own radius first and the two are combined as a right-angled triangle (rbf.h RigExecRbfCombine).

rigExec:allowNegativeWeights

Type: bool. Default: true.

allowNegativeWeights. A negative weight is not an error: it falls out of the matrix inverse and means lean AWAY from this pose. Clamping them is what produces the soft, muddy blend that makes a pose fail to reach its own shape, so the default keeps them. The clamp this selects is max(0, w) applied AFTER normalization, never before and never inside the solve.

rigExec:normalize

Type: bool. Default: true.

Divide the weights by their SUM, so they stay a partition of unity. By their sum and not by the sum of magnitudes, because a negative weight is a real instruction. Where the sum is smaller than 1e-6 there is nothing to divide by and the weights are left alone, which is what falling away to nothing outside the poses should look like.

rigExec:regularization

Type: float. Default: 0.

regularization, added to the matrix diagonal before inverting. Trades exactness at the poses for a calmer result between them, and rescues a solve whose poses sit so close together that the matrix is singular. Zero on every interpolator of the shipped biped.

rigExec:twistAxis

Type: uniform token. Default: "X".

Valid values: X, Y, Z.

The axis a twist pose spins about, in the DRIVER's own frame. driverTwistAxis (0 X, 1 Y, 2 Z), and X on every body interpolator of the shipped biped but the torso's (Y), because the bind skeleton aims +X down the bone.

Read only by poses whose rigExec:poseType is swing or twist; a whole pose measures the entire rotation and never splits it. A RigLogic solve reads it only for the swingAngle and twistAngle metrics.

inputs:enabled

Type: bool. Default: true.

Shape-preserving enable. A disabled interpolator publishes zero on every pose rather than holding its last value: a corrective that is off has to be off, not frozen.

Example

An Elbow control closes a skinned 30-quad strip to 40 degrees, holds there, closes to 80, holds again and opens; two matrix movers skin the strip to the Upper and Fore joints. The interpolator watches the Fore joint — not the Elbow control the animator keys — and carries three poses, neutral at identity, half at 40 degrees and bent at 80, each 0.7 radians wide, which is the spacing between them. Watch the three floats trade: at rest neutral reads 1.000 and half and bent 0.000; at frame 1004, halfway to the first hold, they split 0.529 / 0.601 / 0.000; on the first hold half reads 1.000 alone; on the second bent reads 1.000 and the others 0.000. Only bent.outputs:weight is connected to the blend channel, so the corrective swells on the outside of the elbow exactly when that one float does — nothing at the half hold, full at the bent hold.

RigLogic's solvers have a stage of their own, pose_interpolator_riglogic.usda. A shoulder swings a skinned arm up, forward and down while the elbow folds, and three interpolators read the same motion: ShoulderSwing (additive, swing distance, cubic kernel), ArmFold (interpolative, quaternion distance over two drivers, with a half-scale pose and a weight threshold) and ControlKeys (additive and euclidean over the controls' own avars, with an automatic radius). Each pose weight lifts one bar of a meter, so the three solves can be compared at a glance; open it with bin\launch_usdview.bat docs\examples\pose_interpolator_riglogic.usda.

Open it live with:

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

Re-render the GIF above with:

python docs/render_media.py --page pose_interpolator

Tips

  • Author a non-zero rigExec:rotationRadius on every pose, roughly the angle between neighbouring poses. A per-pose zero is used literally rather than fitted (rbf.cpp:974-983, rbf.cpp:401-407), and an interpolator whose radii are all zero reads 1 only when the driver stands exactly on a pose and 0 everywhere else.
  • Drive from a joint whose parent already carries the motion you do not want measured: the interpolator measures the driver's rotation relative to its rest in its nearest joint or control ancestor's frame, so the parent subtracts its own share back out. Measuring against anything other than the immediate namespace parent is reported as a warning.
  • rigExec:enableTranslation also measures the driver's translation from rest, in its own rest frame, against each pose's rigExec:translation and rigExec:translationRadius (poseArithmeticKernel.h:337-343). Disabling a whole interpolator publishes zeros, while disabling one pose drops it out of the solve entirely so the other poses' weights change.
  • A radius wider than the pose spacing makes the Gaussian rows overlap enough that the inverse pushes a far pose negative between two near ones. rigExec:allowNegativeWeights = 0 clamps that lobe; leave it on only when a consumer wants the extrapolation.
  • rigExec:solver additive or interpolative switches to Epic Games RigLogic's radial-basis solvers: several frame drivers (one quaternion each, with rigExec:rotations on each pose), the euclidean, quaternion, swing and twist distances, RigLogic's five weight functions, its normalize methods, an automatic radius, a weight threshold and a per-pose rigExec:scale. The default pose solver is unchanged. In a RigLogic solve gaussian is RigLogic's exp(-d/r^2), whose shape depends on the radius's units. RigLogic behaviours covers the solvers, their example and their provenance (OpenRigLogic, MIT; see algorithm references).
  • An interpolative RigLogic solve inverts the pose-to-pose kernel matrix, so two poses at the same place under the distance method (a pure twist about the twist axis has the neutral's swing) make it singular; compile warns.

See also


UsdRig