Prim and Property Paths

What is a Path?

In OpenUSD, a path represents the location of a prim or property within a scenegraph. The string representation for a prim path consists of a sequence of prim names separated by forward slashes (/), similar to file paths in a directory structure. The stage pseudo-root, which serves as the starting point for the hierarchy, is represented by a forward slash (/).

For example, the path /World/Geometry/Box represents a prim named Box that is a child of a prim named Geometry, which is a child of the root prim named World.

How Does It Work?

Paths in OpenUSD are handled through the pxr.Sdf.Path class to encode path data including prims, properties (both attributes and relationships), and variants.

Prims are indicated by a slash separator, which indicates the namespace Child (ex: "/geo/box")

Period separators after an identifier is used to introduce a property (ex: "/geo/box.weight")

Variants are indicated by curly brackets, like this: (ex. "/geo/box{size=large}")

They are used to:

1. Uniquely identify prims and properties. Each prim and property in a scene has a unique path that distinguishes it from other prims and properties.

2. Navigate the scene hierarchy. Paths allow you to traverse the scene hierarchy via the USD stage and access specific prims.

3. Specify locations for authoring. When creating or modifying prims, paths are used to specify where the prims should be placed in the hierarchy on the USD stage.

4. Query and filter prims. Paths can be used to filter and select specific prims based on their location in the hierarchy using Sdf.PathExpression.

Working With Python

Here are a few Python functions relevant to paths in OpenUSD.

# Import the Sdf class
from pxr import Sdf

# Return the path of a Usd.Prim as an Sdf.Path object
Usd.Prim.GetPath()

# Retrieve a Usd.Prim at the specified path from the Stage
Usd.Stage.GetPrimAtPath()

Examples

Example 1: Getting, Validating, and Defining Prims at Path

Each prim has a path to describe its location in namespace.

For example, we defined a prim hello at path /hello and another prim world at path /hello/world.

We can retrieve prims using their path using GetPrimAtPath(). This will either return a valid or invalid prim. When using GetPrimAtPath() we should always check if the returned prim is valid before using it.

To check if a prim is valid we can use the IsValid() method. Valid means that the prim exists in the stage. Invalid is when the prim does not exist in the stage or when the path is invalid.

Note

When using GetPrimAtPath(), it will return type UsdPrim. If our prim is of type UsdGeom, we will not be able to use UsdGeom API schema on it.

from pxr import Usd

stage: Usd.Stage = Usd.Stage.CreateNew("_assets/paths.usda")
stage.DefinePrim("/hello")
stage.DefinePrim("/hello/world")

# Get the primitive at the path "/hello" from the current stage
hello_prim: Usd.Prim = stage.GetPrimAtPath("/hello")

# Get the primitive at the path "/hello/world" from the current stage
hello_world_prim: Usd.Prim = stage.GetPrimAtPath("/hello/world")

# Get the primitive at the path "/world" from the current stage
# Note: This will return an invalid prim because "/world" does not exist, but if changed to "/hello/world" it will return a valid prim
world_prim: Usd.Prim = stage.GetPrimAtPath("/world")

# Print whether the primitive is valid
print("Is /hello a valid prim? ", hello_prim.IsValid())
print("Is /hello/world a valid prim? ", hello_world_prim.IsValid())
print("Is /world a valid prim? ", world_prim.IsValid())

stage.Save()

Is /hello a valid prim?  True
Is /hello/world a valid prim?  True
Is /world a valid prim?  False

        #usda 1.0

def "hello"
{
    def "world"
    {
    }
}


    

Key Takeaways

Using Sdf.Path objects in OpenUSD provides a way to uniquely identify and locate objects (prims) within our scene hierarchy. We will use paths for authoring, querying, and navigating USD data effectively.