Xformable

The Xformable schema is the base class for all prims that can be positioned, rotated, and scaled in 3D space. It allows encoding sequences of transformations (translate, rotate, scale, etc.) as
operations that are applied in a specific order.

Primary Features

3D Positioning: Placing objects at specific locations in 3D space
Animation: Creating animated transformations over time
Hierarchical Transforms: Building complex transform hierarchies
Asset Assembly: Positioning and orienting referenced assets
Coordinate System Management: Handling different coordinate systems and up axes

Transforming Geometry

The Xformable schema provides translation, rotation, scale, and support for complex transform sequences. A transform is expressed as an ordered list of xformOps: individual attributes (xformOp:translate, xformOp:rotateXYZ, xformOp:scale, etc.) whose evaluation order is recorded in xformOpOrder. The ordering is in the opposite order in which the xformOps are applied.

Transforms can be animated using TimeSamples or Splines with op attributes.

For common Scale-Rotate-Translate (SRT) workflows, XformCommonAPI provides a higher-level interface with built-in pivot support, compatible with most DCC SRT conventions.

Examples

Basic Transformation

This example shows a Cube with translation, rotation, and scaling operations, and a Sphere with translation and rotation. Notice how the xformOps are specified and how the evaluation order is defined in xformOpOrder.

#usda 1.0

def Cube "TransformedCube"
{
    float3 xformOp:scale = (2, 2, 2)
    float3 xformOp:translate = (10, 5, 0)
    float3 xformOp:rotateXYZ = (0, 45, 0)
    uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ", 
        "xformOp:scale"]
}

def Sphere "TransformedSphere"
{
    double radius = 2.0
    float3[] extent = [(-2, -2, -2), (2, 2, 2)]
    float3 xformOp:translate = (2, 3, 4)
    float3 xformOp:rotateXYZ = (45, 30, 0)
    uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ"]
}

Animated Transformations

See Transforming Geometry for an example that uses a Cylinder with translation and rotation operations animated using TimeSamples.

Hierarchical Transformation

This example uses multiple hierarchical transformations.

#usda 1.0

def Xform "Car"
{
    # Car body transform
    float3 xformOp:translate = (0, 0, 0)
    float3 xformOp:rotateXYZ = (0, 0, 0)
    float3 xformOp:scale = (1, 1, 1)
    uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ", 
        "xformOp:scale"]
    
    # Wheel 1
    def Xform "Wheel1"
    {
        float3 xformOp:translate = (1.5, -0.5, 1.0)
        float3 xformOp:rotateXYZ = (0, 0, 0)
        float3 xformOp:scale = (0.5, 0.5, 0.5)
        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ", 
            "xformOp:scale"]
        
        def Cylinder "WheelGeometry"
        {
            double radius = 1.0
            double height = 0.3
        }
    }
}

Pivot Example

In the following example we rotate a cube around a pivot point, using an additional xformOp namespace component, and a special “invert” xformOp. An xformOp can have additional namespace components beyond the “xformOp:” namespace. In this case we use a custom “pivot” namespace to create a pivot point translation. We also need to use a special operation token, “!invert!” to automatically negate the “xformOp:translate:pivot” translation after the rotation operation is applied.

def Xform "World"                                                                   
{                                                                                   
    def Cube "Box"                                                                  
    {                                                                               
        double size = 2.0
                                                                                    
        # Translate the prim in the scene                                           
        float3 xformOp:translate = (3, 0, 0)                                       
                                                                                    
        # Translate to the pivot point (e.g. one corner of the cube)                
        float3 xformOp:translate:pivot = (1, 1, 0)                                 
                                                                                    
        # Rotation applied around the pivot                                         
        float3 xformOp:rotateXYZ = (0, 45, 0)                                       
                                                                                    
        # The !invert! prefix applies the inverse of xformOp:translate:pivot,       
        # translating back from pivot space to object space                         
        uniform token[] xformOpOrder = [                                            
            "xformOp:translate",                                                    
            "xformOp:translate:pivot",                                              
            "xformOp:rotateXYZ",                                                    
            "!invert!xformOp:translate:pivot"                                       
        ]       
    }                                                                               
}

Properties

xformOpOrder

USD type: token[]

The xformOpOrder attribute contains the names of transform operation attributes in the precise sequence they should be applied. This ensures transforms are evaluated in the correct order.

Special tokens:

“!resetXformStack!”: Indicates this prim should not inherit parent transforms. Can introduce uncertainty for some scene processing algorithms.
“!invert!”: Indicates an inverted operation (e.g., for pivot points). Automatically resolves to the negated value of its “paired op” (indicated in opName). See Xformable for an example using the invert op.

Inherited Properties (Imageable)

proxyPrim

USD type: rel (relationship)

The proxyPrim relationship allows linking a prim whose purpose is “render” to its (single target) purpose="proxy" prim. This is useful for providing a less complex proxy geometry representation of a prim optimized for interactive renders.

Typically you would author proxyPrim for prims whose purpose is “render”, although this is not required for render and proxy prims to draw properly in the appropriate circumstances. Rather, it is for users and DCC’s to reason more easily about the different representations.

purpose

USD type: token

Fallback value: default

Purpose classifies geometry into categories that can each be independently included or excluded from different operations, such as rendering or bounding-box computation.

Allowed values:

“default”: No special purpose, included in all traversals. This is the fallback value if a purpose has not been authored.
“render”: For final quality renders.
“proxy”: For lightweight interactive renders. For example, the prim might be a lower-complexity representation of a mesh for rendering in a DCC tool.
“guide”: For helper/visualization geometry. For example, the prim might be a spline used as a visual aid in a rigging tool.

Purpose is inherited down the scene namespace. If a prim is not imageable or does not have an authored opinion about its own purpose, then it will inherit the purpose of the closest imageable ancestor with an authored purpose opinion (or use the fallback purpose if no ancestor has an authored purpose).

visibility

USD type: token

Fallback value: inherited

Visibility is the simplest way to control whether geometry is shown or hidden. It can be animated, allowing a sub-tree of geometry to appear and disappear over time. Unlike deactivating geometry, invisible geometry is still available for inspection, positioning, and computing against. Note that visibility is strongly inherited down the namespace, so child prims of a prim set as invisible cannot be switched to visible.

Allowed values:

“inherited” (the fallback value): Inherits visibility from parent prims
“invisible”: Hides the prim and all its children from rendering