NCP-OUSD: USD Foundations &
Data Modeling

The USD Stage

The Stage is the entry point for all USD operations. It represents the fully composed scene by resolving the layer stack according to USD's composition rules (LIVERPS). You never interact with raw layers during typical authoring — the Stage provides the composed view.

• Open / Create: Usd.Stage.Open(filePath) — open an existing .usda/.usdc file; Usd.Stage.CreateNew(filePath) — create a new stage backed by a file on disk; Usd.Stage.CreateInMemory() — create an anonymous in-memory stage.
• Traversal: stage.GetPseudoRoot() returns the invisible root prim; stage.Traverse() iterates all prims; stage.GetPrimAtPath("/World/Cube") fetches a specific prim.
• Stage metadata: defaultPrim — the prim consumers use as the root reference; upAxis ("Y" or "Z"); metersPerUnit; timeCodesPerSecond; startTimeCode; endTimeCode.
• Saving: stage.Save() writes the root layer; stage.Export(filePath) flattens and exports the entire composed scene.

from pxr import Usd

# Open existing stage
stage = Usd.Stage.Open("/path/to/scene.usda")

# Create new stage backed by file
stage = Usd.Stage.CreateNew("/path/to/new_scene.usda")

# In-memory stage
stage = Usd.Stage.CreateInMemory()

# Traverse all active prims
for prim in stage.Traverse():
    print(prim.GetPath())

# Get prim at specific path
prim = stage.GetPrimAtPath("/World/Cube")

# Stage metadata
stage.SetMetadata("upAxis", "Y")
start = stage.GetStartTimeCode()
end = stage.GetEndTimeCode()

Prim Hierarchy & Paths

The prim hierarchy forms a tree rooted at the pseudo-root (/). Every prim has an SdfPath — a string-based address that uniquely identifies it. Paths are the backbone of all USD cross-referencing.

• SdfPath types: Absolute (/World/Cube), relative (./Child), property path (/Cube.points), relationship target path.
• Prim queries: prim.GetPath(), prim.GetName(), prim.GetTypeName().
• Hierarchy navigation: prim.GetParent(), prim.GetChildren(), prim.GetAllChildren() (includes inactive).
• Active vs inactive: prim.SetActive(False) — inactive prims are excluded from stage.Traverse() by default and not rendered.
• Prim specifiers: def — concrete, creates a renderable prim; over — override, adds opinions to an existing prim without creating it; class — abstract template, never rendered directly, used as an inheritance source via inherits arc.

from pxr import Usd, Sdf

stage = Usd.Stage.CreateInMemory()

# Define a concrete prim (specifier: def)
prim = stage.DefinePrim("/World/Cube", "Cube")

# Check prim properties
print(prim.GetPath())      # Sdf.Path('/World/Cube')
print(prim.GetName())      # 'Cube'
print(prim.GetTypeName())  # 'Cube'

# Navigate hierarchy
parent = prim.GetParent()   # /World prim
children = parent.GetChildren()

# Deactivate a prim (excludes from traversal)
prim.SetActive(False)
print(prim.IsActive())  # False

Properties: Attributes & Relationships

Properties are the data attached to prims. All properties live in a namespace on the prim and can be queried by name. Two kinds exist: Attributes carry typed scalar or array values, while Relationships point to other prim paths.

• Create attribute: prim.CreateAttribute("myFloat", Sdf.ValueTypeNames.Float)
• Set/Get value: attr.Set(1.5, time=Usd.TimeCode.Default()) for a default value; attr.Set(2.0, 10) for timeCode 10; attr.Get(time) to read.
• TimeSamples: attr.GetTimeSamples() returns a sorted list of time codes that have values; attr.GetTimeSamplesInInterval(interval) for a range.
• Relationship: prim.CreateRelationship("material:binding"); rel.AddTarget(Sdf.Path("/Materials/Red")); rel.GetTargets().
• Primvars: Special attributes with an interpolation mode. Accessed via UsdGeom.PrimvarsAPI(prim); created with api.CreatePrimvar("st", Sdf.ValueTypeNames.Float2Array, UsdGeom.Tokens.faceVarying).

from pxr import Usd, Sdf, UsdGeom

stage = Usd.Stage.CreateInMemory()
prim = stage.DefinePrim("/World/Sphere", "Sphere")

# Create and set an attribute
attr = prim.CreateAttribute("myRadius", Sdf.ValueTypeNames.Float)
attr.Set(2.5)  # default value
attr.Set(3.0, 10)  # time sample at frame 10
attr.Set(5.0, 24)  # time sample at frame 24

# Read back
print(attr.Get())        # 2.5 (default)
print(attr.Get(10))      # 3.0
print(attr.GetTimeSamples())  # [10.0, 24.0]

# Create a relationship
rel = prim.CreateRelationship("material:binding")
rel.AddTarget(Sdf.Path("/Materials/Red"))
print(rel.GetTargets())  # [Sdf.Path('/Materials/Red')]

# Primvar
mesh = stage.DefinePrim("/World/Mesh", "Mesh")
api = UsdGeom.PrimvarsAPI(mesh)
pv = api.CreatePrimvar("st", Sdf.ValueTypeNames.Float2Array, UsdGeom.Tokens.faceVarying)
pv.Set([(0,0),(1,0),(1,1),(0,1)])

Value Types & TimeSamples

USD has a rich type system covering scalar, vector, matrix, and array types. The Sdf.ValueTypeNames namespace contains all built-in types. Array types correspond to VtArray<T> in C++ and Python lists/tuples.

TimeSamples: A dict-like structure of {timeCode: value} pairs stored on an attribute. When both a default value and time samples exist, time-sampled values take precedence at any time code within range. Between samples USD performs linear interpolation by default; held interpolation freezes the previous value.

• Blocked value: attr.Set(Sdf.ValueBlock()) masks any composed value, making the attribute appear unset — useful to suppress inherited or referenced values.
• Held interpolation: attr.SetMetadata("interpolation", "held") — value jumps discretely at each sample rather than interpolating.

from pxr import Sdf, Usd

stage = Usd.Stage.CreateInMemory()
prim = stage.DefinePrim("/Anim/Ball")

# Float attribute with time samples
attr = prim.CreateAttribute("xpos", Sdf.ValueTypeNames.Float)
attr.Set(0.0)        # default value
attr.Set(0.0, 1)     # frame 1
attr.Set(10.0, 24)   # frame 24

# Time-sampled value wins over default
print(attr.Get(1))   # 0.0
print(attr.Get(12))  # ~5.0 (linear interpolation)
print(attr.Get(24))  # 10.0

# Block a value (suppresses inheritance)
attr.Set(Sdf.ValueBlock())

# Matrix4d for transforms
xform_attr = prim.CreateAttribute("xformOp:transform",
                                   Sdf.ValueTypeNames.Matrix4d)

USD File Formats

The generic extension .usd can refer to either .usda or .usdc — USD auto-detects the format. The command-line tools usdcat (dump scene as ASCII) and usdview (interactive viewer) are essential debugging aids. Use usdzip to create .usdz packages.

Built-in Schema Domains (Overview)

• UsdGeom — Geometry primitives: Mesh, Xform, Camera, Scope, Points, BasisCurves. Defines xformOp ordering, visibility, purpose, and extent.
• UsdShade — Shading networks: Material, Shader, NodeGraph. Handles material binding and shader connections.
• UsdLux — Lighting: SphereLight, DomeLight, RectLight, DistantLight, CylinderLight. Defines intensity, color, exposure.
• UsdPhysics — Rigid body simulation: RigidBodyAPI, CollisionAPI, Scene.
• UsdSkel — Skeletal animation: Skeleton, SkelAnimation, SkelRoot.
• UsdVol — Volumetric data: Volume, OpenVDBAsset.