TimeCodes and TimeSamples

This lesson, TimeCode and TimeSample, shows us how to set up animation in a stage using OpenUSD.

In this lesson, we will:

• Set start and end timeCodes for a stage. Learn how to set start and end timeCode metadata for a USD stage, establishing a timeline that forms the foundation for animated scenes.

• Set timeSamples on attributes. Gain the skills to set timeSamples on individual attributes, allowing us to animate specific properties of prims over time.

What are TimeCodes and TimeSamples?

In OpenUSD, timeCode and timeSample are two important concepts that enable us to work with animations and simulation in USD scenes.

TimeCode is a point in time with no unit assigned to it. You can think of these as frames whose units are derived from the stage.

TimeSample refers to the individual time-varying values associated with an attribute in USD. Each attribute can have a collection of timeSamples that map timeCode to the attribute’s data type values, allowing for animation over time. For a reminder of the purpose of attributes, please review the introductory lesson on attributes.

How Does It Work?

In a USD scene, the timeCode ordinates of all timeSamples are scaled to seconds based on the timeCodesPerSecond metadata value defined in the root layer.

This allows flexibility in encoding timeSamples within a range and scale suitable for the application, while maintaining a robust mapping to real-world time for playback and decoding.

For example, if the root layer has timeCodesPerSecond=24, a timeCode value of 48.0 would correspond to 2 seconds (48/24) of real time after the timeCode 0.

TimeSamples are used to store time-varying data for attributes, such as positions, rotations, or material properties. When an attribute is evaluated at a specific timeCode, the value is linearly interpolated from the surrounding timeSamples, allowing for smooth animation playback.

Working With Python

Below is an example of how we can get or set timeSamples in Python. First, we’re getting the timeSamples of the displayColor on a cube prim. This method returns a vector of timeCode ordinates at which time samples are authored for the given attribute.

Lastly, we’re setting a translation value of a sphere at a specified timeCode. This method sets the timeSample value of the attribute at the specified timeCode.

# Returns authored TimeSamples
cube.GetDisplayColorAttr().GetTimeSamples()

# Sets TimeSample Value (Gf.Vec3d(0,-4.5,0)) at a specified TimeCode (30)
sphere_xform_api.SetTranslate(Gf.Vec3d(0,-4.5,0), time=Usd.TimeCode(30))

Examples

Let’s create a USD stage to serve as the starting point for the example in this lesson. We will create a simple stage with a sphere and a blue cube as a backdrop.

# Import the necessary modules from the `pxr` library:
from pxr import Usd, UsdGeom, Gf

# Create a new USD stage file named "timecode_sample.usda":
stage: Usd.Stage = create_new_stage("_assets/timecode_sample.usda")

# Define a transform ("Xform") primitive at the "/World" path:
world: UsdGeom.Xform = UsdGeom.Xform.Define(stage, "/World")

# Define a Sphere primitive as a child of the transform at "/World/Sphere" path:
sphere: UsdGeom.Sphere = UsdGeom.Sphere.Define(stage, world.GetPath().AppendPath("Sphere"))

# Define a blue Cube as a background prim:
box: UsdGeom.Cube = UsdGeom.Cube.Define(stage, world.GetPath().AppendPath("Backdrop"))
box.GetDisplayColorAttr().Set([(0.0, 0.0, 1.0)])
cube_xform_api = UsdGeom.XformCommonAPI(box)
cube_xform_api.SetScale(Gf.Vec3f(5, 5, 0.1))
cube_xform_api.SetTranslate(Gf.Vec3d(0, 0, -2))

# Save the stage to the file:
stage.Save()

Loading your model...

_assets/timecode_sample.usda

        #usda 1.0

def Xform "World"
{
    def Sphere "Sphere"
    {
    }

    def Cube "Backdrop"
    {
        color3f[] primvars:displayColor = [(0, 0, 1)]
        float3 xformOp:scale = (5, 5, 0.1)
        double3 xformOp:translate = (0, 0, -2)
        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
    }
}


    

Example 1: Setting Start and End TimeCodes

TimeCode specifies an exact frame or moment in the animation timeline. It allows for precise control over the timing of changes to properties, enabling smooth and accurate animation of 3D objects.

A Usd.TimeCode is therefore a unitless, generic time measurement that serves as the ordinate for time-sampled data in USD files. Usd.Stage defines the mapping of TimeCodes to units like seconds and frames.

To set the stage’s start TimeCode and end TimeCode metadata, use the SetStartTimeCode() and SetEndTimeCode() methods.

from pxr import Usd, UsdGeom, Gf

stage: Usd.Stage = Usd.Stage.Open("_assets/timecode_sample.usda")
world: UsdGeom.Xform = UsdGeom.Xform.Define(stage, "/World")
sphere: UsdGeom.Sphere = UsdGeom.Sphere.Define(stage, world.GetPath().AppendPath("Sphere"))
box: UsdGeom.Cube = UsdGeom.Cube.Define(stage, world.GetPath().AppendPath("Backdrop"))
box.GetDisplayColorAttr().Set([(0.0, 0.0, 1.0)])
cube_xform_api = UsdGeom.XformCommonAPI(box)
cube_xform_api.SetScale(Gf.Vec3f(5, 5, 0.1))
cube_xform_api.SetTranslate(Gf.Vec3d(0, 0, -2))

# Set the `start` and `end` timecodes for the stage:
stage.SetStartTimeCode(1)
stage.SetEndTimeCode(60)

# Export to a new flattened layer for this example.
stage.Export("_assets/timecode_ex1.usda", addSourceFileComment=False)

Note the stage metadata at the top of the layer.

Loading your model...

_assets/timecode_ex1.usda

        #usda 1.0
(
    endTimeCode = 60
    startTimeCode = 1
)

def Xform "World"
{
    def Sphere "Sphere"
    {
    }

    def Cube "Backdrop"
    {
        color3f[] primvars:displayColor = [(0, 0, 1)]
        float3 xformOp:scale = (5, 5, 0.1)
        double3 xformOp:translate = (0, 0, -2)
        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
    }
}


    

Example 2: Setting TimeSamples for Attributes

TimeSamples represent a collection of attribute values at various points in time, allowing OpenUSD to interpolate between these values for animation purposes.

When animating an attribute, you define a timeCode at which the value should be applied. These values are then interpolated between the timeSamples to get the value that should be applied at the current timeCode.

To assign a value at a particular timeCode, use the Set() method.

Set() takes two arguments: the timeCode and the value to assign.

For example, if you want to set the size of a cube to 1 at timeCode 1 and 10 at timeCode 60:

# Get the size attribute of the cube
cube_size_attr: Usd.Attribute = cube_prim.GetSizeAttr()
# Set the size of the cube at time=1 to 1
cube_size_attr.Set(time=1, value=1)
# Set the size of the cube at time=60 to 10
cube_size_attr.Set(time=60, value=10)

USD will interpolate the values for the cube’s size attribute between set timeSamples.

Let’s create a sphere that moves up and down using the XformCommonAPI.

from pxr import Usd, UsdGeom

stage: Usd.Stage = Usd.Stage.Open("_assets/timecode_sample.usda")
world: UsdGeom.Xform = UsdGeom.Xform.Define(stage, "/World")
sphere: UsdGeom.Sphere = UsdGeom.Sphere.Define(stage, world.GetPath().AppendPath("Sphere"))
box: UsdGeom.Cube = UsdGeom.Cube.Define(stage, world.GetPath().AppendPath("Backdrop"))
box.GetDisplayColorAttr().Set([(0.0, 0.0, 1.0)])
cube_xform_api = UsdGeom.XformCommonAPI(box)
cube_xform_api.SetScale(Gf.Vec3f(5, 5, 0.1))
cube_xform_api.SetTranslate(Gf.Vec3d(0, 0, -2))

stage.SetStartTimeCode(1)
stage.SetEndTimeCode(60)

# Grab the translate 
if translate_attr := sphere.GetTranslateOp().GetAttr():
    translate_attr.Clear()

# Create XformCommonAPI object for the sphere
sphere_xform_api = UsdGeom.XformCommonAPI(sphere)

# Set translation of the sphere at time 1
sphere_xform_api.SetTranslate(Gf.Vec3d(0,  5.50, 0), time=1)  
# Set translation of the sphere at time 30
sphere_xform_api.SetTranslate(Gf.Vec3d(0, -4.50, 0), time=30)  
# Set translation of the sphere at time 45
sphere_xform_api.SetTranslate(Gf.Vec3d(0, -5.00, 0), time=45)  
# Set translation of the sphere at time 50
sphere_xform_api.SetTranslate(Gf.Vec3d(0, -3.25, 0), time=50)  
# Set translation of the sphere at time 60
sphere_xform_api.SetTranslate(Gf.Vec3d(0,  5.50, 0), time=60)  

# Export to a new flattened layer for this example.
stage.Export("_assets/timecode_ex2a.usda", addSourceFileComment=False)

Loading your model...

_assets/timecode_ex2a.usda

        #usda 1.0
(
    endTimeCode = 60
    startTimeCode = 1
)

def Xform "World"
{
    def Sphere "Sphere"
    {
        double3 xformOp:translate.timeSamples = {
            1: (0, 5.5, 0),
            30: (0, -4.5, 0),
            45: (0, -5, 0),
            50: (0, -3.25, 0),
            60: (0, 5.5, 0),
        }
        uniform token[] xformOpOrder = ["xformOp:translate"]
    }

    def Cube "Backdrop"
    {
        color3f[] primvars:displayColor = [(0, 0, 1)]
        float3 xformOp:scale = (5, 5, 0.1)
        double3 xformOp:translate = (0, 0, -2)
        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
    }
}


    

TimeSamples can be used for baked, per-frame animation and it is good for interchange that is reproducible. However, timeSamples are not a replacement for animation curves.

For more complex animation it is not recommended to define the animation using scripting but rather in other Digital Content Creation (DCC) Applications.

---

It is possible to set timeSamples for different attributes. We can demonstrate this with the scale of the sphere.

from pxr import Usd, UsdGeom

stage: Usd.Stage = Usd.Stage.Open("_assets/timecode_sample.usda")
world: UsdGeom.Xform = UsdGeom.Xform.Define(stage, "/World")
sphere: UsdGeom.Sphere = UsdGeom.Sphere.Define(stage, world.GetPath().AppendPath("Sphere"))
box: UsdGeom.Cube = UsdGeom.Cube.Define(stage, world.GetPath().AppendPath("Backdrop"))
box.GetDisplayColorAttr().Set([(0.0, 0.0, 1.0)])
cube_xform_api = UsdGeom.XformCommonAPI(box)
cube_xform_api.SetScale(Gf.Vec3f(5, 5, 0.1))
cube_xform_api.SetTranslate(Gf.Vec3d(0, 0, -2))

stage.SetStartTimeCode(1)
stage.SetEndTimeCode(60)

if translate_attr := sphere.GetTranslateOp().GetAttr():
    translate_attr.Clear()
if scale_attr := sphere.GetScaleOp().GetAttr():
    scale_attr.Clear()

sphere_xform_api = UsdGeom.XformCommonAPI(sphere)

sphere_xform_api.SetTranslate(Gf.Vec3d(0,  5.50, 0), time=1)  
sphere_xform_api.SetTranslate(Gf.Vec3d(0, -4.50, 0), time=30)  
sphere_xform_api.SetTranslate(Gf.Vec3d(0, -5.00, 0), time=45)  
sphere_xform_api.SetTranslate(Gf.Vec3d(0, -3.25, 0), time=50)  
sphere_xform_api.SetTranslate(Gf.Vec3d(0,  5.50, 0), time=60)  

# Set scale of the sphere at time 1
sphere_xform_api.SetScale(Gf.Vec3f(1.00, 1.00, 1.00), time=1)  
# Set scale of the sphere at time 30
sphere_xform_api.SetScale(Gf.Vec3f(1.00, 1.00, 1.00), time=30)   
# Set scale of the sphere at time 45
sphere_xform_api.SetScale(Gf.Vec3f(1.00, 0.20, 1.25), time=45)   
# Set scale of the sphere at time 50
sphere_xform_api.SetScale(Gf.Vec3f(0.75, 2.00, 0.75), time=50)  
# Set scale of the sphere at time 60
sphere_xform_api.SetScale(Gf.Vec3f(1.00, 1.00, 1.00), time=60)  

# Export to a new flattened layer for this example.
stage.Export("_assets/timecode_ex2b.usda", addSourceFileComment=False)

Loading your model...

_assets/timecode_ex2b.usda

        #usda 1.0
(
    endTimeCode = 60
    startTimeCode = 1
)

def Xform "World"
{
    def Sphere "Sphere"
    {
        float3 xformOp:scale.timeSamples = {
            1: (1, 1, 1),
            30: (1, 1, 1),
            45: (1, 0.2, 1.25),
            50: (0.75, 2, 0.75),
            60: (1, 1, 1),
        }
        double3 xformOp:translate.timeSamples = {
            1: (0, 5.5, 0),
            30: (0, -4.5, 0),
            45: (0, -5, 0),
            50: (0, -3.25, 0),
            60: (0, 5.5, 0),
        }
        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
    }

    def Cube "Backdrop"
    {
        color3f[] primvars:displayColor = [(0, 0, 1)]
        float3 xformOp:scale = (5, 5, 0.1)
        double3 xformOp:translate = (0, 0, -2)
        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
    }
}


    

Key Takeaways

To sum it up, timeCode provides a unitless time ordinate scaled to real-world time, while timeSample stores the actual attribute values at specific timeCode ordinates. Understanding these concepts unlocks a way for creating, manipulating, and rendering dynamic scenes and simulations in OpenUSD-based workflows across various industries.