Houdini 21.0 Nodes APEX nodes

TransformObject

Represents and builds a hierarchy of transformations in a rig.

On this page
Since 20.0

The TransformObject node manages the transform behavior of elements, including defining transform hierarchies between elements. It also handles animation-friendly transform component inputs like translation, rotation, and scale, with a defined rotation order. When a TransformObject node is put in a graph, and its parameters are promoted (connected to the graph’s input node), the TransformObject element is picked up by the animate state and turned into a control - it is displayed as something the user can interact with. See controls for more information.

Transformation construction

The transformation represented by the TransformObject can be constructed in a number of different ways:

  1. Translate, rotate, and scale values can be wired into the t, r, and s ports, respectively.

    This option allows the TransformObject to be manipulated as a control in the animate state. When a t, r, or s port is promoted (connected to the graph’s input node), the TransformObject is picked up by the animate state and turned into a control. The animate state provides handles on the control, and when the handles are manipulated, the appropriate t, r, and s values are updated.

    The transformation order (the order to apply the translation, rotation, and scale operations) can be set with the xord port.

    xord

    Transformation Order

    0

    Scale → Rotate → Translate

    1

    Scale → Translate → Rotate

    2

    Rotate → Scale → Translate

    3

    Rotate → Translate → Scale

    4

    Translate → Scale → Rotate

    5

    Translate → Rotate → Scale

    The rotation order (the order that the rotations are applied about the X, Y, and Z axes) can be set with the rord port.

    rord

    Rotation Order

    0

    X → Y → Z

    1

    X → Z → Y

    2

    Y → X → Z

    3

    Y → Z → X

    4

    Z → X → Y

    5

    Z → Y → X

  2. The local port accepts a transformation matrix. It serves the same purpose as the t, r, and s ports.

    This option is convenient when the transformation data is already represented in matrix format. Oftentimes, this is used when the TransformObject is driven by rig logic, rather than being directly manipulated or animated. It also frees up the t, r, and s ports for animation to be layered on top of a driven motion.

  3. The restlocal port accepts a transformation matrix and uses it to set the initial position and orientation of the TransformObject. The t, r, s, and local transformations are applied relative to this coordinate frame. In effect, the restlocal port sets an initial transformation on the TransformObject while allowing the other transformation ports (t, r, s, and local) to be used for animation.

    An example use case for restlocal is in a joint hierarchy, where a joint’s position and orientation (relative to its parent) is stored in restlocal. This sets the joint’s rest transformation. See the note to Update Rest Transforms From Skeleton for more information.

  4. The xform port accepts a world space transformation matrix that overrides the local transformations set by the t, r, s, local, and restlocal ports. The TransformObject is constrained to the transformations of the xform input. See constraints for more information.

    By default, xform overrides all the components of the transformation. You could also constrain a combination of the translate, rotate, and scale components by providing an appropriate bit mask on the xformmask port. See constrain one transform component for more information.

    xformmask

    Overrides Applied

    0

    No Overrides

    1

    Translate

    2

    Rotate

    3

    Rotate, Translate

    4

    Scale

    5

    Scale, Translate

    6

    Scale, Rotate

    7

    Scale, Rotate, Translate

Local transformation

All transformation construction options can be used simultaneously in the process of creating the TransformObject’s local space transformation. The TransformObject uses the following logic to combine the t, r, and s ports with the local and restlocal transformation matrices:

localxform = (scale * local.scale * restlocal.scale) * 
             (local.shear + restlocal.shear) *
             (rotate * translate) *
             (rotate.local * translate.local) *
             (rotate.restlocal * translate.restlocal)

Effectively, the restlocal transformation acts as the parent of the local transformation, and the local transformation acts as the parent of the transform described by the t, r, and s ports. However, the scales and shears of the local and restlocal transformations are combined locally with the scaling of the s port.

Combining the transformations with this logic exhibits useful properties when considering the “rest local transformation” of an object. For example, if the TransformObject represents a prop, the prop’s restlocal transformation could be scaled without affecting its previously animated position. Simultaneously, this behavior avoids unintentional shearing when the prop rotates while non-uniformly scaled.

If the xform port is connected, the local transformation is updated to include the effects of the constraint.

Transformation hierarchies

TransformObjects can be connected in a parent-child fashion to create transformation hierarchies. Parent-child relationships are established by creating two connections between the parent and child TransformObject nodes:

  • parent.xform → child.parent

  • parent.localxform → child.parentlocal

The xform output port produces the TransformObject’s world space transformation matrix. The connection between the parent’s xform output and the child’s parent input gives the child access to the parent’s world space matrix.

The localxform output port produces a local transformation matrix that represents a combination of all the input transformation ports described in Transformation Construction. The connection between the parent’s localxform output and the child’s parentlocal input supports scale inheritance, giving the child access to the parent’s local scaling contributions.

Scale inheritance

When a parent TransformObject is scaled, its descendants inherit the effects of the scaling. There may be times when it would be beneficial to adjust the effects of the parent’s scaling to simplify various rig behaviors. For these cases, the following scale inheritance behaviors are available by setting the appropriate option on the scaleinheritance port:

0 - Default Scaling

Scaling is inherited normally from the parent.

xform = localxform * parent

1 - Offset Only

Only the child’s position is affected by scaling.

xform = localxform.scale * localxform.rotate * 
        inverse(parentlocal.scale) * localxform.translate * parent

Tip

This is similar to Maya’s segment scale compensation.

2 - Offset and Scale

The child’s position is scaled as in the Offset Only option, and the parent’s local scale is applied in the child’s local space. For example, if the parent is scaled by a factor of 2 in its x-direction, the child will also apply a scaling of 2 in its own x-direction.

xform = parentlocal.scale * localxform.scale * localxform.rotate * 
        inverse(parentlocal.scale) * localxform.translate * parent

localxform = parentlocal.scale * localxform

Tip

This is similar to Softimage’s hierarchical scaling.

3 - Scale Only

The same local scaling is applied as in the Offset and Scale option, but the child’s translation remains unaffected.

xform = parentlocal.scale * localxform * 
        inverse(parentlocal.scale) * parent

localxform = parentlocal.scale * localxform

4 - Ignore Parent Scaling

No scaling is inherited from the parent.

xform = localxform * inverse(parentlocal.scale) * parent

TransformObject output ports

Generally speaking, the xform output port, which represents the world space transformation matrix produced by the TransformObject, should be used for most rigging purposes. One exception is that the output localxform should be connected to descendant TransformObjects to support transformation hierarchies.

The remainder of the TransformObject output ports exist to support rig inversion workflows (for example, motion retargeting). Many output ports have common names that could be interpreted in a number of ways, so pay extra attention to the descriptions in the documentation when using these ports.

Inputs

parent: Matrix4

The parent’s world matrix. When establishing a parent-child relationship with the current TransformObject as the child, connect this port to the parent TransformObject’s xform port.

parentlocal: Matrix4

The parent’s local matrix. When establishing a parent-child relationship with the current TransformObject as the child, connect this port to the parent TransformObject’s localxform port.

scaleinheritance: Int

Controls the effect of the parent’s local scaling on the child. See scale inheritance.

xform: Matrix4

A transformation matrix that overrides the TransformObject’s position, scale, and orientation in world space. It can be used in combination with xformmask to selectively set the scale, rotation, and translation components of the TransformObject.

t: Vector3

Translation values that set the TransformObject’s position in local space.

r: Vector3

Euler angles, in degrees, that set the TransformObject’s orientation in local space. The rotation order is set with the rord port.

s: Vector3

Scale values that set the TransformObject’s scale in local space.

local: Matrix4

A transformation matrix that serves the same purpose as the t, r, and s ports. The local port allows the TransformObject to be driven by rig logic while simultaneously freeing up the input t, r, and s ports for further animation. local can also be understood as an additional offset for the TransformObject’s restlocal matrix in local space.

restlocal: Matrix4

A transformation matrix that applies an initial position, scale, and orientation to the TransformObject in its local space. Transformations from the t, r, s, and local inputs are applied relative to this coordinate frame.

xord: Int

Sets the transformation order of both the input and output t, r, and s ports. The default order is scale → rotate → translate. See transformation order.

rord: Int

Sets the rotation order of the Euler angles on the input and output r ports. The default value is X → Y → Z. See rotation order.

xformmask: Int

A bit mask that is used in combination with the input matrix xform to override specific components of the transformation. The first bit overrides the translation, the second bit overrides the rotation, and the third bit overrides the scale. All three bits are set by default. See the xformmask table.

Outputs

xform: Matrix4

The world space matrix of the TransformObject.

localxform: Matrix4

The local transformation matrix of the TransformObject such that xform = localxform * parent.

Warning

When non-default scale inheritance is used, localxform is modified to include the additional parent local scaling so that it can be properly reapplied in descendant hierarchies. In this scenario, localxform represents the effective local transformation, and the previous relationship, xform = localxform * parent, is no longer accurate. In order to calculate a localxform that maintains the previous xform = localxform * parent relationship, you can use the formula: localxform = xform * inverse(parent).

restlocal: Matrix4

The combination of the input local and input restlocal transformations (see local transformation). This matrix represents the initial position and orientation of the TransformObject relative to its parent in a transformation hierarchy. Animation on the input t, r, and s ports is applied in this local coordinate frame.

t: Vector3

The translation applied to the TransformObject in its local space by the t input port. When the TransformObject is constrained, t represents the translation that produces animation that is equivalent to the motion of the constraint. This t value can be applied to the input t port of an equivalent TransformObject without the constraint, and produce motion as if the original constraint is baked into the animation.

r: Vector3

The Euler angles, in degrees, applied to the TransformObject in its local space by the r input port. The rotation order respects the input rord value. When the TransformObject is constrained, r represents the rotation that produces animation that is equivalent to the motion of the constraint. This r value can be applied to the input r port of an equivalent TransformObject without the constraint, and produce motion as if the original constraint is baked into the animation.

s: Vector3

The scale applied to the TransformObject in its local space by the s input port. When the TransformObject is constrained, s represents the scaling that produces animation that is equivalent to the motion of the constraint. This s value can be applied to the input s port of an equivalent TransformObject without the constraint, and produce motion as if the original constraint is baked into the animation.

See also

APEX nodes