Boundable

The Boundable schema is the base class for all prims that can have extents calculated and stored. This is essential for performance optimization, as it allows renderers and other tools to quickly determine the spatial extent of geometry without having to compute it every time.

What is an Extent?

An extent is a bounding box that describes the spatial bounds of a prim in its local coordinate space at the layer and time in which the extent is authored. Think of it as a rectangular box that completely contains the geometry. Boundable’s extent has the following characteristics.

Rectilinear: The bounding box is axis-aligned (not rotated)
Local-space: The extent is defined in the prim’s own coordinate system, before any transforms are applied
Cached: The extent is stored as an attribute so it doesn’t need to be recalculated every time

Bounds vs Extents

Every 3D object needs to know its size and position in space. UsdGeom uses two related but different concepts:

Extents: Authored bounding box data stored as an attribute on geometry prims. This is a rectilinear (box-shaped) volume in local space that contains the geometry.
Bounds: Computed bounding boxes that can be calculated at runtime, often combining multiple extents or computing them dynamically.

Why both? Extents provide fast, pre-computed bounding information for performance, while bounds can be calculated on-demand for more complex scenarios. For animated geometry, extents should be authored using animated values such as timeSamples or splines.

For more details, see the USD Boundable API documentation.

Examples

Basic Extent Usage

This example shows a Sphere with authored extents.

#usda 1.0

def Sphere "MySphere"
{
    double radius = 2.0
    float3[] extent = [(-2, -2, -2), (2, 2, 2)]
}

Animated Extent

This example shows a Sphere with animated extents.

#usda 1.0
(
    startTimeCode = 1
    endTimeCode = 72
    timeCodesPerSecond = 24
)
def Sphere "AnimatedSphere"
{
    double radius.timeSamples = {
        0: 1.0,
        24: 3.0
    }
    float3[] extent.timeSamples = {
        0: [(-1, -1, -1), (1, 1, 1)],
        24: [(-3, -3, -3), (3, 3, 3)]
    }
}

Setting Extents

The following example uses Python to create a Sphere and set the Sphere’s radius and extents.

from pxr import Usd, UsdGeom

stage = Usd.Stage.CreateNew("extentsExample.usda")
sphere = UsdGeom.Sphere.Define(stage, "/MySphere")

# Set the sphere's radius
sphere.CreateRadiusAttr(5)

# Calculate and set the extent (bounding box)
sphere.CreateExtentAttr(UsdGeom.Boundable.ComputeExtentFromPlugins(sphere, 
    Usd.TimeCode.Default()))

stage.Save()

Best Practices

Always Author Extents: To avoid expensive runtime extent computation.
Update When Needed: When geometry properties change, update the extent accordingly.
Use ComputeExtent(): For dynamic extent calculation, use the appropriate ComputeExtent() methods.

Properties

extent

USD type: float3[]

The extent attribute defines a bounding box for the prim in its local coordinate space. It consists of two points: the minimum corner and maximum corner of the bounding box.

The extent is stored as an array of two float3 values:

First element: minimum corner (xmin, ymin, zmin)
Second element: maximum corner (xmax, ymax, zmax)

For animated geometry, the extent should be authored using animated values (timeSamples or splines) to capture the changing bounds over time. This allows renderers to efficiently cull geometry without having to compute the bounds at runtime.

Example:

float3[] extent = [(-1, -1, -1), (1, 1, 1)]  # Unit cube

Inherited Properties (Xformable)

xformOpOrder

USD type: token[]

The xformOpOrder attribute contains the names of transform operation attributes in the precise sequence they should be applied. This ensures transforms are evaluated in the correct order.

Special tokens:

“!resetXformStack!”: Indicates this prim should not inherit parent transforms. Can introduce uncertainty for some scene processing algorithms.
“!invert!”: Indicates an inverted operation (e.g., for pivot points). Automatically resolves to the negated value of its “paired op” (indicated in opName). See Xformable for an example using the invert op.

Inherited Properties (Imageable)

proxyPrim

USD type: rel (relationship)

The proxyPrim relationship allows linking a prim whose purpose is “render” to its (single target) purpose="proxy" prim. This is useful for providing a less complex proxy geometry representation of a prim optimized for interactive renders.

Typically you would author proxyPrim for prims whose purpose is “render”, although this is not required for render and proxy prims to draw properly in the appropriate circumstances. Rather, it is for users and DCC’s to reason more easily about the different representations.

purpose

USD type: token

Fallback value: default

Purpose classifies geometry into categories that can each be independently included or excluded from different operations, such as rendering or bounding-box computation.

Allowed values:

“default”: No special purpose, included in all traversals. This is the fallback value if a purpose has not been authored.
“render”: For final quality renders.
“proxy”: For lightweight interactive renders. For example, the prim might be a lower-complexity representation of a mesh for rendering in a DCC tool.
“guide”: For helper/visualization geometry. For example, the prim might be a spline used as a visual aid in a rigging tool.

Purpose is inherited down the scene namespace. If a prim is not imageable or does not have an authored opinion about its own purpose, then it will inherit the purpose of the closest imageable ancestor with an authored purpose opinion (or use the fallback purpose if no ancestor has an authored purpose).

visibility

USD type: token

Fallback value: inherited

Visibility is the simplest way to control whether geometry is shown or hidden. It can be animated, allowing a sub-tree of geometry to appear and disappear over time. Unlike deactivating geometry, invisible geometry is still available for inspection, positioning, and computing against. Note that visibility is strongly inherited down the namespace, so child prims of a prim set as invisible cannot be switched to visible.

Allowed values:

“inherited” (the fallback value): Inherits visibility from parent prims
“invisible”: Hides the prim and all its children from rendering