Houdini 20.5 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.

    Note

    The t, r, and s ports take priority over the local port. If any one of the t, r, or s ports has an incoming connection, the local port is ignored.

  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 (premultiplied). 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, and local ports. When the xform port is connected, 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

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

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 sets the TransformObject’s position, scale, and orientation 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. This matrix gives the TransformObject and its manipulation handles an initial transformation while keeping the transformation inputs (t, r, s, and local) clear, allowing them to be used for animation.

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 encoded by 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 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

Returns a copy of the TransformObject’s input restlocal matrix, which is used to set the initial position and orientation of the TransformObject.

t: Vector3

The translation applied to the TransformObject in its local space by either the t input port, or the translation component of the local input port matrix. This serves as a pass-through of the input translations.

r: Vector3

The Euler angles, in degrees, applied to the TransformObject in its local space by either the r input port, or the rotation component of the local input port matrix. The rotation order respects the input rord port. This serves as a pass-through of the input rotations.

s: Vector3

The scale applied to the TransformObject in its local space by either the s input port, or the scale component of the local input port matrix. This serves as a pass-through of the input scales.

See also

APEX nodes