Spline Animation#

What Is Spline Animation?#

Time samples are a straightforward way to animate attributes: you author values at chosen time codes, and USD interpolates between them (for example, linearly). That model is a good fit when motion is simple or nearly piecewise linear.

An animation spline stores a curve defined by knots (time-value keys), tangent data, and interpolation modes between knots. Splines can represent smoother or sparser animation than dense time-sample sequences, and they support inner loops (repeating a prototype segment with a value offset) and extrapolation past the authored knot range (for example, repeating the whole curve). Pipeline tools and DCC exports can author splines directly on attributes that support them.

How Does It Work?#

This lesson shows how to build splines with the Python pxr.Ts helpers, attach them to a transform operation with UsdAttribute.SetSpline, and see how layer offsets apply to spline-evaluated motion the same way they do for time samples. For the full rules engine that merges defaults, time samples, splines, and more, see value resolution.

Note

Stage timing metadata (timeCodesPerSecond, startTimeCode, endTimeCode) still defines how time codes map to seconds for playback. When layers disagree on frame rate, USD reconciles timing during value resolution; see Units in OpenUSD for timeCodesPerSecond behavior.

Tip

The embedded 3D previews in this site use GLB conversion that keys off time samples, not raw spline payloads. Each example calls DisplayUSD(..., bake_splines_for_display=True), which writes a temporary flattened USD and evaluates splines into dense samples for the viewer only. Your saved _assets/*.usda files stay spline-authored; open them in usdview to inspect splines directly.

Working With Python#

The Ts package provides Ts.Spline, Ts.Knot, Ts.LoopParams, and Ts.Extrapolation. You construct a spline for an attribute’s value type (for example "float"), add knots, optionally configure loop or extrapolation settings, then call UsdAttribute.SetSpline.

Attention

Splines are only supported on floating-point scalar attributes: half, float, and double. Ts.Spline raises an error for any other type name, so the multi-axis transform ops cannot be splined directly: AddTranslateOp, AddRotateXYZOp, and AddScaleOp all produce a 3-component type (float3, double3, or half3, depending on the precision you request).

Use the single-axis ops instead, or author one spline per component. Single-axis ops are always scalar—AddRotateZOp yields a float by default and AddTranslateXOp a double, and passing UsdGeom.XformOp.PrecisionHalf or PrecisionDouble still gives you half or double. That is why the examples below can pass attr.GetTypeName() straight to Ts.Spline: every precision those ops can produce is one splines support.

Reading attr.Get(timeCode) evaluates the composed spline at that time, subject to layer time mapping—provided no time samples are authored for that attribute at a stronger or equal location. Time samples win over splines during value resolution, so an attribute carrying both returns the sampled value and attr.HasSpline() reports False.

The snippet below is a complete, self-contained example:

from pxr import Usd, UsdGeom, Ts

stage = Usd.Stage.CreateInMemory()
xform = UsdGeom.Xform.Define(stage, "/World/Spinner")

# xformOp:rotateZ is a float attribute, which splines support
spin = xform.AddRotateZOp(opSuffix="yaw")
attr = spin.GetAttr()
type_name = str(attr.GetTypeName())
spline = Ts.Spline(type_name)
spline.SetKnot(
    Ts.Knot(
        typeName=type_name,
        time=0,
        value=0,
        nextInterp=Ts.InterpLinear,
    )
)
spline.SetKnot(
    Ts.Knot(
        typeName=type_name,
        time=48,
        value=180,
        nextInterp=Ts.InterpLinear,
    )
)
attr.SetSpline(spline)

For extrapolation modes, knot tangents, and multi-dimensional types, see the OpenUSD C++ documentation for TsSpline.

Examples#

Tip

You can run these examples locally as Jupyter notebooks. See How to Run Notebooks Locally for setup instructions.

Note

Examples on this page use create_new_stage(), a notebook helper imported in a hidden setup cell. In your own scripts, use Usd.Stage.CreateNew() in its place. If you’re running the lessons from a clone of this repository, you can import the helper instead: from lousd.utils.helperfunctions import create_new_stage. See How to Run Notebooks Locally for why.

Example 1: Inner loop on a rotation#

Here a single linear segment from 0° to 90° over 24 frames is repeated four times (one prototype plus three post-loops) with a value offset of 90° each time, so the cube completes a full 360° turn without authoring every quarter-turn as separate samples.

from pxr import Usd, UsdGeom, Ts

spline_loop_path = "_assets/spline_inner_loop.usda"
stage = create_new_stage(spline_loop_path)
UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.y)
stage.SetTimeCodesPerSecond(24)
stage.SetStartTimeCode(0)
stage.SetEndTimeCode(96)

world = UsdGeom.Xform.Define(stage, "/World")
stage.SetDefaultPrim(world.GetPrim())

xform = UsdGeom.Xform.Define(stage, "/World/RotatingCube")
cube = UsdGeom.Cube.Define(stage, "/World/RotatingCube/Geometry")
cube.GetSizeAttr().Set(1.2)
cube.GetDisplayColorAttr().Set([(0.35, 0.65, 0.95)])

yaw = xform.AddRotateZOp(opSuffix="yaw")
yaw_attr = yaw.GetAttr()
type_name = str(yaw_attr.GetTypeName())

spline = Ts.Spline(type_name)
spline.SetKnot(
    Ts.Knot(
        typeName=type_name,
        time=0,
        value=0,
        nextInterp=Ts.InterpLinear,
    )
)
loop_params = Ts.LoopParams()
loop_params.protoStart = 0
loop_params.protoEnd = 24
loop_params.numPostLoops = 3
loop_params.valueOffset = 90
spline.SetInnerLoopParams(loop_params)
yaw_attr.SetSpline(spline)

stage.Save()

mid_proto = 12
print(f"Rotation at t=0: {yaw_attr.Get(0)}")
print(f"Rotation at t={mid_proto} (mid prototype): {yaw_attr.Get(mid_proto)}")
print(f"Rotation at t=24 (end of first loop): {yaw_attr.Get(24)}")
print(f"Rotation at t=48: {yaw_attr.Get(48)}")
print(f"Attribute stores a spline: {yaw_attr.HasSpline()}")

Rotation at t=0: 0.0
Rotation at t=12 (mid prototype): 45.0
Rotation at t=24 (end of first loop): 90.0
Rotation at t=48: 180.0
Attribute stores a spline: True

Loading your model...

_assets/spline_inner_loop.usda

        #usda 1.0
(
    defaultPrim = "World"
    endTimeCode = 96
    startTimeCode = 0
    timeCodesPerSecond = 24
    upAxis = "Y"
)

def Xform "World"
{
    def Xform "RotatingCube"
    {
        float xformOp:rotateZ:yaw.spline = {
            loop: (0, 24, 0, 3, 90),
            0: 0; pre (0, 0); post linear,
        }
        uniform token[] xformOpOrder = ["xformOp:rotateZ:yaw"]

        def Cube "Geometry"
        {
            color3f[] primvars:displayColor = [(0.35, 0.65, 0.95)]
            double size = 1.2
        }
    }
}

The .spline payload in USD text lists the loop parameters and knot data. At evaluation time, value resolution samples that curve at the requested time code.

Example 2: Post extrapolation#

Without extrapolation, querying times past the last knot holds the last value. Setting post extrapolation lets motion continue for the rest of the stage range (or until another rule applies).

This example rocks a cube on the Y axis from -12° to 12° over 60 frames, then keeps swinging by mirroring that segment with Ts.ExtrapLoopOscillate.

from pxr import Usd, UsdGeom, Ts

spline_extrap_path = "_assets/spline_extrapolation.usda"
stage = create_new_stage(spline_extrap_path)
UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.y)
stage.SetTimeCodesPerSecond(30)
stage.SetStartTimeCode(0)
stage.SetEndTimeCode(150)

world = UsdGeom.Xform.Define(stage, "/World")
stage.SetDefaultPrim(world.GetPrim())

xform = UsdGeom.Xform.Define(stage, "/World/RockingCube")
cube = UsdGeom.Cube.Define(stage, "/World/RockingCube/Geometry")
cube.GetSizeAttr().Set(1.0)
cube.GetDisplayColorAttr().Set([(0.9, 0.55, 0.25)])

rock = xform.AddRotateYOp(opSuffix="rock")
rock_attr = rock.GetAttr()
type_name = str(rock_attr.GetTypeName())

spline = Ts.Spline(type_name)
spline.SetKnot(
    Ts.Knot(
        typeName=type_name,
        time=0,
        value=-12,
        nextInterp=Ts.InterpCurve,
    )
)
spline.SetKnot(
    Ts.Knot(
        typeName=type_name,
        time=60,
        value=12,
        nextInterp=Ts.InterpCurve,
    )
)
spline.SetPostExtrapolation(Ts.Extrapolation(Ts.ExtrapLoopOscillate))
rock_attr.SetSpline(spline)

stage.Save()

print(f"t=45 (within authored span): {rock_attr.Get(45):.2f}")
print(f"t=75 (past the last knot, swinging back): {rock_attr.Get(75):.2f}")
print(f"t=120 (one full oscillation later): {rock_attr.Get(120):.2f}")

t=45 (within authored span): 6.00
t=75 (past the last knot, swinging back): 6.00
t=120 (one full oscillation later): -12.00

Loading your model...

_assets/spline_extrapolation.usda

        #usda 1.0
(
    defaultPrim = "World"
    endTimeCode = 150
    startTimeCode = 0
    timeCodesPerSecond = 30
    upAxis = "Y"
)

def Xform "World"
{
    def Xform "RockingCube"
    {
        float xformOp:rotateY:rock.spline = {
            bezier,
            post: loop oscillate,
            0: -12; pre (0, 0); post curve (0, 0),
            60: 12; pre (0, 0); post curve (0, 0),
        }
        uniform token[] xformOpOrder = ["xformOp:rotateY:rock"]

        def Cube "Geometry"
        {
            color3f[] primvars:displayColor = [(0.9, 0.55, 0.25)]
            double size = 1
        }
    }
}

Ts.ExtrapLoopOscillate continues the spline by mirroring the authored segment, so the cube swings back to -12° and repeats. Choose the mode that matches the motion: Ts.ExtrapLoopRepeat repeats the segment’s shape and offsets each cycle by the difference between the first and last knot values, which would keep turning this cube in one direction instead of rocking it.

Example 3: Layer offsets and spline time#

References can carry an Sdf.LayerOffset (scale and offset on the source layer’s time line). The same rules apply when the referenced animation is driven by splines: evaluation uses the mapped time when resolving values on the composed stage.

from pxr import Usd, UsdGeom, Ts, Sdf

slide_asset_path = "_assets/spline_slide_rig.usda"
rig_stage = create_new_stage(slide_asset_path)
UsdGeom.SetStageUpAxis(rig_stage, UsdGeom.Tokens.y)
rig_stage.SetTimeCodesPerSecond(24)
rig_stage.SetStartTimeCode(0)
rig_stage.SetEndTimeCode(48)

rig = UsdGeom.Xform.Define(rig_stage, "/SlideRig")
rig_stage.SetDefaultPrim(rig.GetPrim())
UsdGeom.Cube.Define(rig_stage, "/SlideRig/Geometry").GetSizeAttr().Set(0.6)

slide = rig.AddTranslateXOp(opSuffix="slide")
slide_attr = slide.GetAttr()
type_name = str(slide_attr.GetTypeName())

spline = Ts.Spline(type_name)
spline.SetKnot(
    Ts.Knot(typeName=type_name, time=0, value=0, nextInterp=Ts.InterpLinear)
)
spline.SetKnot(
    Ts.Knot(typeName=type_name, time=48, value=4, nextInterp=Ts.InterpLinear)
)
slide_attr.SetSpline(spline)
rig_stage.Save()

offset_scene_path = "_assets/spline_layer_offset_scene.usda"
scene = create_new_stage(offset_scene_path)
UsdGeom.SetStageUpAxis(scene, UsdGeom.Tokens.y)
scene.SetTimeCodesPerSecond(24)
scene.SetStartTimeCode(0)
scene.SetEndTimeCode(48)

UsdGeom.Xform.Define(scene, "/World")
scene.SetDefaultPrim(scene.GetPrimAtPath("/World"))

left_rig = UsdGeom.Xform.Define(scene, "/World/LeftRig")
left_rig.GetPrim().GetReferences().AddReference(slide_asset_path, primPath="/SlideRig")

right_rig = UsdGeom.Xform.Define(scene, "/World/RightRig")
right_rig.GetPrim().GetReferences().AddReference(
    slide_asset_path,
    primPath="/SlideRig",
    layerOffset=Sdf.LayerOffset(offset=24),
)

scene.Save()

composed = Usd.Stage.Open(offset_scene_path)
early = composed.GetPrimAtPath("/World/LeftRig").GetAttribute("xformOp:translateX:slide")
late = composed.GetPrimAtPath("/World/RightRig").GetAttribute("xformOp:translateX:slide")
t_query = 24
print(f"At global t={t_query}, left rig X (no offset): {early.Get(t_query)}")
print(f"At global t={t_query}, right rig X (offset +24): {late.Get(t_query)}")

At global t=24, left rig X (no offset): 2.0
At global t=24, right rig X (offset +24): 0.0

Loading your model...

_assets/spline_layer_offset_scene.usda

        #usda 1.0
(
    defaultPrim = "World"
    endTimeCode = 48
    startTimeCode = 0
    timeCodesPerSecond = 24
    upAxis = "Y"
)

def Xform "World"
{
    def Xform "LeftRig" (
        prepend references = @_assets/spline_slide_rig.usda@</SlideRig>
    )
    {
    }

    def Xform "RightRig" (
        prepend references = @_assets/spline_slide_rig.usda@</SlideRig> (offset = 24)
    )
    {
    }
}

The right instance sees source time t - 24 at global time t, so at global frame 24 it is only at the start of its slide. For deeper retiming, value clips remain the heavier-weight option.

Key Takeaways#

Splines complement time samples on the same attributes: you can author smooth, looping, or extrapolated motion without dense sample lists, where tooling supports spline authoring.
pxr.Ts + SetSpline is the usual Python path for constructing curves, inner loops, and extrapolation before saving USD.
Splines are for half, float, and double attributes only—animate single-axis transform ops, or one spline per component, rather than vector types like double3.
Resolution is per time code: Get(t) evaluates the composed spline (after strength ordering and time mapping), consistent with how samples and timeCodesPerSecond interact across layers. Time samples at a stronger or equal location take precedence over a spline.
Layer offsets retime splines just like samples—plan for held behavior outside knot coverage if you rely on offsets or short authored ranges.

For how defaults, samples, splines, and clips combine in the attribute stack, see Value resolution.