Attributes#

What is an Attribute?#

Attributes are the most common type of property that you’ll work with when creating scenes. An attribute can have one specific data type, such as a number, text, or a vector. Each attribute can have a default value, and it can also have different values at different points in time, called timeSamples.

How Does It Work?#

Attributes are name-value pairs (often referred to as key-value pairs) that store data associated with a prim.

Any given attribute has a single, defined data type associated with it. Each attribute is defined with the type of data that it can hold. A single attribute can represent various types of properties, such as the vertices of a piece of geometry, the diffuse color of a material, or the mass of an object. These are typically defined through the Sdf library.

Some common examples of attributes include:

Visibility - Controls the visibility of a prim in the scene.
Display color - Specifies the display color applied to a geometric prim.
Extent - Defines the boundaries of a geometric prim.

Attributes can be authored and stored within USD layers, which are files that describe different aspects of a scene. When a USD stage is composed, the attribute values from various layers are combined according to specific composition rules, allowing for flexible scene assembly.

Attributes can be animated by providing multiple keyframed values over time. OpenUSD’s timeSampling model ensures efficient storage and interpretation of animated data. We will learn more about timeSamples in the TimeCodes and TimeSamples lesson.

Working With Python#

To work with attributes in OpenUSD, we will generally use schema-specific APIs. Each schema-specific API has a function to grab its own attributes. Review the following examples to learn more.

# Get the radius value of sphere_prim that is of type UsdGeom.Sphere
sphere_prim.GetRadiusAttr().Get()

# Set the double-sided property of the prim
sphere_prim.GetDoubleSidedAttr().Set(True)

While there’s also a dedicated UsdAttribute API, in general, it’s preferred to use the schema-specific methods, if they exist, as they are more clear and less brittle. You can learn more about how to work with each specific schema on OpenUSD’s documentation.

Examples#

Example 1: Retrieving Properties of a Prim#

Properties are the other kind of namespace object in OpenUSD. Whereas prims provide the organization and indexing for a composed scene, properties contain the “real data”.

There are two types of properties: attributes and relationships.

To retrieve the properties of a prim, we would use the GetProperties method. For this demonstration we will be using GetPropertyNames() instead to retrieve the names of the properties. This will not grab the properties themselves, but a list of the names of the properties. Use GetProperties to retrieve the properties themselves.

Note

Relationships are only lightly discussed in this less. We’ll talk about relationships again in the Relationships lesson.

from pxr import Usd, UsdGeom, Gf

file_path = "_assets/attributes_ex1.usda"

stage: Usd.Stage = Usd.Stage.CreateNew(file_path)

world_xform: UsdGeom.Xform = UsdGeom.Xform.Define(stage, "/World")

# Define a sphere under the World xForm:
sphere: UsdGeom.Sphere = UsdGeom.Sphere.Define(stage, world_xform.GetPath().AppendPath("Sphere"))

# Define a cube under the World xForm and set it to be 5 units away from the sphere:
cube: UsdGeom.Cube = UsdGeom.Cube.Define(stage, world_xform.GetPath().AppendPath("Cube"))
UsdGeom.XformCommonAPI(cube).SetTranslate(Gf.Vec3d(5, 0, 0))

# Get the property names of the cube prim:
cube_prop_names = cube.GetPrim().GetPropertyNames()

# Print the property names:
for prop_name in cube_prop_names:
    print(prop_name)

stage.Save()

doubleSided
extent
orientation
primvars:displayColor
primvars:displayOpacity
proxyPrim
purpose
size
visibility
xformOp:translate
xformOpOrder

Loading your model...

_assets/attributes_ex1.usda

        #usda 1.0

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

    def Cube "Cube"
    {
        double3 xformOp:translate = (5, 0, 0)
        uniform token[] xformOpOrder = ["xformOp:translate"]
    }
}

Example 2: Getting Attribute Values#

Attributes are the most common type of property authored in most USD scenes.

An example of a simple attribute that describes the radius of a sphere:

def Sphere "Sphere"{
    double radius = 10
}

We interact with attributes through the UsdAttribute API.

Each prim type has their own set of properties and corresponding functions to retrieve them. Since our sphere is of type UsdGeom.Sphere, we can use the schema-specific API to get and set the radius attribute.

GetRadiusAttr() will return a UsdAttribute object that can be used to modify the attribute. Which means it will not retrieve the value of the attribute. To get the value of an attribute, use the Get() method.

For example, to get the value of the radius attribute, we would use the following snippet.

sphere_prim.GetRadiusAttr().Get()

Let’s use the Get() method for the radius, displayColor, and extent attributes.

Since we have not explicitly authored any attribute values, Get() will return the fallback value that was defined in the schema.

Note

The attribute values will not show up in .usda, however the values are coming from the fallback value defined in the sphere schema. USD is applying value resolution to retrieve the values.

from pxr import Usd, UsdGeom

file_path = "_assets/attributes_ex2.usda"
stage: Usd.Stage = Usd.Stage.CreateNew(file_path)

world_xform: UsdGeom.Xform = UsdGeom.Xform.Define(stage, "/World")

sphere: UsdGeom.Sphere = UsdGeom.Sphere.Define(stage, world_xform.GetPath().AppendPath("Sphere"))
cube: UsdGeom.Cube = UsdGeom.Cube.Define(stage, world_xform.GetPath().AppendPath("Cube"))
UsdGeom.XformCommonAPI(cube).SetTranslate(Gf.Vec3d(5, 0, 0))

# Get the attributes of the cube prim
cube_attrs = cube.GetPrim().GetAttributes()
for attr in cube_attrs:
    print(attr)

# Get the size, display color, and extent attributes of the cube
cube_size: Usd.Attribute = cube.GetSizeAttr()
cube_displaycolor: Usd.Attribute = cube.GetDisplayColorAttr()
cube_extent: Usd.Attribute = cube.GetExtentAttr()

print(f"Size: {cube_size.Get()}")
print(f"Display Color: {cube_displaycolor.Get()}")
print(f"Extent: {cube_extent.Get()}")

stage.Save()

Usd.Prim(</World/Cube>).GetAttribute('doubleSided')
Usd.Prim(</World/Cube>).GetAttribute('extent')
Usd.Prim(</World/Cube>).GetAttribute('orientation')
Usd.Prim(</World/Cube>).GetAttribute('primvars:displayColor')
Usd.Prim(</World/Cube>).GetAttribute('primvars:displayOpacity')
Usd.Prim(</World/Cube>).GetAttribute('purpose')
Usd.Prim(</World/Cube>).GetAttribute('size')
Usd.Prim(</World/Cube>).GetAttribute('visibility')
Usd.Prim(</World/Cube>).GetAttribute('xformOp:translate')
Usd.Prim(</World/Cube>).GetAttribute('xformOpOrder')
Size: 2.0
Display Color: None
Extent: [(-1, -1, -1), (1, 1, 1)]

Loading your model...

_assets/attributes_ex2.usda

        #usda 1.0

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

    def Cube "Cube"
    {
        double3 xformOp:translate = (5, 0, 0)
        uniform token[] xformOpOrder = ["xformOp:translate"]
    }
}

Example 3: Setting Attribute Values#

In the last example, we used the Get() method to retrieve the value of the attribute. To set the values, we use the Set() method.

Here is an example of setting a value to the radius attribute.

sphere_prim.GetRadiusAttr().Set(100.0)

When run, it will modify the sphere in the example scene to look like this:

def Sphere "Sphere"{
    double radius = 100
}

Based on our last modification, if we were to use Get() it would return 100.

When getting attribute values, USD will apply value resolution, since we authored a default value. The Get() method will retrieve the value of the attribute. To set the values, we use the Set() method. This will resolve to the authored value rather than the fallback value from the sphere schema.

Now let’s modify the radius, displayColor, and extent attributes of the sphere by using Set().

from pxr import Usd, UsdGeom

file_path = "_assets/attributes_ex3.usda"
stage: Usd.Stage = Usd.Stage.CreateNew(file_path)

world_xform: UsdGeom.Xform = UsdGeom.Xform.Define(stage, "/World")

sphere: UsdGeom.Sphere = UsdGeom.Sphere.Define(stage, world_xform.GetPath().AppendPath("Sphere"))
cube: UsdGeom.Cube = UsdGeom.Cube.Define(stage, world_xform.GetPath().AppendPath("Cube"))
UsdGeom.XformCommonAPI(cube).SetTranslate(Gf.Vec3d(5,0,0))

# Get the size, display color, and extent attributes of the sphere
cube_size: Usd.Attribute = cube.GetSizeAttr()
cube_displaycolor: Usd.Attribute = cube.GetDisplayColorAttr()
cube_extent: Usd.Attribute = cube.GetExtentAttr()

# Modify the radius, extent, and display color attributes:
cube_size.Set(cube_size.Get() * 2)
cube_extent.Set(cube_extent.Get() * 2)
cube_displaycolor.Set([(0.0, 1.0, 0.0)])

stage.Save()

Loading your model...

_assets/attributes_ex3.usda

        #usda 1.0

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

    def Cube "Cube"
    {
        float3[] extent = [(-2, -2, -2), (2, 2, 2)]
        color3f[] primvars:displayColor = [(0, 1, 0)]
        double size = 4
        double3 xformOp:translate = (5, 0, 0)
        uniform token[] xformOpOrder = ["xformOp:translate"]
    }
}

Key Takeaways#

In summary,

Attributes are values with a name and data type that define the properties of prims in a USD scene.
Attributes are the primary means of storing data in USD.
Each attribute has a single, defined data type.
Attributes are authored and stored within USD layers, enabling efficient scene composition.
Attributes can be animated by providing keyframed values over time.
They can be queried, modified and animated using the USD API.

Understanding attributes is essential for creating rich and detailed 3D scenes, enabling efficient collaboration and interoperability across various tools and pipelines.