Active and Inactive Prims

What are Active and Inactive Prims?

In OpenUSD, all prims are active by default. Making a prim inactive is effectively a non-destructive deletion of a prim from a stage. Deactivating a prim provides a way to temporarily remove, or prune, prims and their descendants from being composed and processed on the stage, which can make traversals more efficient.

An active prim and its active child prims will be visited and processed during stage traversals and operations. However, by making a prim inactive by setting its “active” metadata to false, we prevent that prim itself from being visited. This also prevents its descendant prims from being composed onto the stage.

# Make the prim at /Parent inactive
stage.GetPrimAtPath('/Parent').SetActive(False)

Deactivating a prim is a non-destructive operation–-the prim still exists in the scene description, but it is pruned from the composed stage view until reactivated. This is effectively the way to delete a prim from the stage.

How Does It Work?

Deactivation is useful for managing scene complexity and scalability by pruning unnecessary scene data. It provides a way to non-destructively remove parts of the scene graph without permanently deleting them.

When a prim is deactivated, it has the following effects:

• The prim itself will be excluded from default stage traversals as determined by the UsdPrimDefaultPredicate.

• All scene description for the deactivated prim’s descendants will not be composed onto the stage.

However, the inactive state can be overridden by stronger layer opinions that set the “active” metadata to true for that prim. This allows selective reactivation of pruned subtrees.

Working With Python

We can use the following Python functions to set the “active” metadata on a prim and check to see if the prim is currently active on the stage.

• UsdPrim.SetActive(bool) - Set the “active” metadata for a prim

• UsdPrim.IsActive() - Return whether a prim is currently active on the stage

Examples

Example 1: Setting Prims as Active/Inactive

Active/Inactive prim is a behavior that is non-destructive and provides reversible prim deletion from a stage. By default, all prims are active. Active prims are visited by stage traversals. If a prim is inactive that means it is not visited by stage traversals, and neither will its child prims.

UsdPrim::SetActive() is used to set whether the prim is active or inactive. Giving the value of False will make it inactive and True to make it active.

In this example, we will print out the contents of a stage at the start and then see how the contents change after deactivating a prim. Here’s is what the USDA for this stage looks like:

from pxr import Usd

# Open the USD stage from the specified file
file_path = "_assets/active-inactive.usda"
stage = Usd.Stage.Open(file_path)

# Iterate through all the prims on the stage
# Print the state of the stage before deactivation
print("Stage contents BEFORE deactivating:")
for prim in stage.Traverse():
    print(prim.GetPath())

# Get the "/World/Box" prim and deactivate it
box = stage.GetPrimAtPath("/World/Box")
# Passing in False to SetActive() will set the prim as Inactive and passing in True will set the prim as active
box.SetActive(False)

print("\n\nStage contents AFTER deactivating:")
for prim in stage.Traverse():
    print(prim.GetPath())

Stage contents BEFORE deactivating:
/World
/World/Box
/World/Box/Geometry
/World/Box/Geometry/Cube
/World/Box/Materials
/World/Box/Materials/BoxMat
/World/Environment
/World/Environment/SkyLight


Stage contents AFTER deactivating:
/World
/World/Environment
/World/Environment/SkyLight

You can see that the /World/Box prim and all of its descendant prims have be excluded on the second traversal because we deactivated /World/Box.

Key Takeaways

The active/inactive behavior in OpenUSD allows for non-destructive pruning of scene data from the composed stage view. Deactivating prims helps manage scene complexity by temporarily removing unnecessary scene elements, while still preserving the ability to reactivate them later. This pruning mechanism is an important tool for optimizing performance and managing large, complex USD scenes in production pipelines.