Module usd 

High-level USD composition and authoring APIs.

This module mirrors OpenUSD’s pxr/usd/usd layer. The stage implementation lives in the local stage module, while this module re-exports the public Usd* surface under openusd::usd.

Structs

Attribute

Stage-composed attribute handle. Mirrors C++ UsdAttribute.

AttributeQuery

Cached value query for one attribute. Mirrors C++ UsdAttributeQuery.

ClipsAPI

Read/write view of the value-clip metadata on a prim (C++ UsdClipsAPI).

Collection

A handle to one UsdCollectionAPI instance: the prim it is applied to plus the instance name. Cheap to construct and clone; reads pull from the stage on demand.

CommittedChange

A committed edit handed to StageSink::after_commit (the data the former ObjectsChanged notice carried).

ConnectionGraph

A directed index of every authored attribute connection on a stage.

Diff

A transferable diff of one stage edit, produced by a diff recorder (ReplayStage, UndoStage) and replayed by Stage::apply_diff.

EditContext

RAII guard that scopes a Stage edit-target switch, restoring the previous target when dropped. Created by Stage::edit_context; mirrors C++ UsdEditContext.

EditTarget

Identifies which layer in a Stage receives authored opinions, and how stage-namespace paths map into that layer’s namespace.

FieldValue

A field and its authored value, as carried by Edit::Create.

MembershipQuery

A resolved, stage-free membership predicate for a collection (the relationship-linking mode). Build it once (see compute_membership_query) and query is_path_included cheaply; it clones freely so consumers can cache one per collection path.

NamespaceEditor

Batches namespace edits — prim/property renames, reparents, and deletes — and applies them to a Stage with full target/connection/reference fixup. Mirrors C++ UsdNamespaceEditor.

PendingChange

A staged, not-yet-committed edit to one of the stage’s layers, handed to StageSink::before_commit — the stage-tier view of one layer’s sdf::PendingLayerChange.

Prim

Stage-composed prim handle. Mirrors C++ UsdPrim.

PrimIndexRef

A handle to a single prim’s composition index, the analog of C++ PcpPrimIndex reached via UsdPrim::GetPrimIndex.

PrimPredicate

Predicate used to filter prim traversal by resolved status bits.

PrimStatus

Resolved stage-level status bits for a prim.

Relationship

Stage-composed relationship handle. Mirrors C++ UsdRelationship.

ReplayStage

A Stage that records the forward Diff of every edit it commits.

Stage

A composed USD stage.

StageBuilder

Builder for configuring and opening a Stage.

StagePopulationMask

Population mask limiting which prim paths are exposed by a Stage.

TimeCode

A numeric time code identifying when an attribute value is resolved. Mirrors C++ UsdTimeCode.

UndoStage

A Stage that records the inverse of every edit it commits, for undo.

VariantSets

The variant sets composed onto a prim. Mirrors C++ UsdVariantSets, reached through Prim::variant_sets.

WeakStage

A non-owning handle to a Stage (C++ UsdStageWeakPtr).

Enums

ApplyMode

How Stage::apply_diff interprets a Diff’s paths.

Edit

One operation of a Diff, in the edited layer’s namespace.

EditTargetArc

Composition arc kind selecting which arc on a prim an arc-based EditTarget writes into (C++ UsdEditTarget::Reference / Inherit / Specialize / Payload). Built via Stage::edit_target_for_node or Prim::edit_target_for_arc.

ExpansionRule

How a collection’s includes/excludes targets expand to members (collection:<name>:expansionRule).

InitialLoadSet

Initial payload loading behavior for a stage.

InterpolationType

Stage-level interpolation mode for time-sampled attributes.

LoadPolicy

How deeply a Stage::load call expands payloads. Mirrors C++ UsdLoadPolicy.

NamespaceEditError

Errors raised while staging, validating, or applying a namespace edit.

PathRule

The rule attached to one path in a resolved MembershipQuery map, including the Exclude sentinel that marks an excluded subtree.

Provenance

Where a committed edit originated, which determines the namespace its CommittedChange paths are reported in.

SchemaKind

How a schema relates to its prim (C++ UsdSchemaKind).

StageAuthoringError

Errors raised by Stage’s authoring methods.

Traits

SchemaBase

Common surface shared by every schema view type (C++ UsdSchemaBase).

StageSink

An observer of a Stage’s composed-scene changes and lifecycle events.

Functions

apply_collection

Apply UsdCollectionAPI to prim with instance name name (adds CollectionAPI:<name> to apiSchemas) and return a handle. Author its membership via the returned Collection’s setters / include_path / exclude_path.

collections_on

Every UsdCollectionAPI instance applied to prim, decoded from its apiSchemas (CollectionAPI:<name>).

compute_included_paths

Enumerate the paths that query includes on stage, restricted to the prims predicate admits (spec §15.2). Returns prim members in traversal order; under expandPrimsAndProperties each included prim’s member properties follow it, and explicitly listed property targets are included too.

is_collection_api_path

If path is a collection identity path <prim>.collection:<name>, return (prim, name). Used to detect when an includes target points at another collection (chained collections). A deeper property path like collection:<name>:includes is not a collection identity and yields None.

Type Aliases

PathExpansionRuleMap

Maps each authored/derived path to the rule that governs it (the Exclude sentinel marks excluded subtrees). The resolved form of a collection’s includes/excludes/expansionRule/includeRoot opinions.

StageSinkId

A sink::Id for a StageSink installed on a Stage.