NCP-OUSD cheat sheet

A USD file is a crate (binary), usda (text), or usdc file holding a layer; a stage is a composed, in-memory view over one or more layers rooted at a root layer.

Prim paths are absolute (/World/Geom/Cube) or relative; sibling paths use ../, and property paths append .attribute or .relationship to a prim path.

Composition arcs, strongest to weakest: local sublayers (reverse order), then references, payloads, inherits, specializes, and variant sets, with the root layer's own opinions strongest within a layer.

LIVRPS ordering governs opinion strength across arcs: Local, Inherits, Variants, References, Payloads, Specializes.

Sdf.Path and Sdf.Layer are the low-level API; Usd.Stage, Usd.Prim, Usd.Attribute, and Usd.Relationship are the composed high-level API.

A prim is defined (has a def), over (has an over that adds opinions without a type), or a class; only defs with a schema type can be instantiated as typed prims.

Metadata (defaultPrim, metersPerUnit, upAxis, customLayerData) lives on layers or prims and does not compose like attribute opinions, except via layer stacking.

Time samples are stored per-attribute in Sdf.TimeSamples; default value and time samples coexist, and get() returns the resolved value at the current Usd.TimeCode.

Sublayers compose in reverse order: the last sublayer listed is weakest, and the root layer's own opinions beat all sublayers.

A reference (Sdf.Reference) pulls a prim or layer subtree in at reference strength; a payload is a deferred reference that can be loaded/unloaded via Usd.Stage.Load/Unload or the payloads metadata.

Inherits apply class opinions to a prim at inherit strength; specializes are weaker than everything else and are used for fallback/default behavior.

Variant sets (variantSets metadata plus variant selections) let one prim carry multiple authored alternatives; only the selected variant contributes opinions at variant strength.

Use Usd.Stage.GetPrimAtPath and Usd.PrimCompositionQuery to inspect which layers and arcs contribute opinions to a prim.

The layer stack order is root layer first, then sublayers depth-first; Usd.Stage.Flatten() bakes the composed result into a single layer for debugging.

An 'over' in a stronger layer can add or override opinions on a prim defined in a weaker layer without redefining its type.

Instancing and payloads interact: a payloaded reference still composes at payload strength, and unloading a payload removes its opinions from the composed stage.

A schema is a C++/Python class generated from a schema definition (usda) via usdGenSchema; it declares typed properties, applied API schemas, and fallback values.

IsA schemas (typed prims) derive from UsdTyped; applied API schemas (e.g., UsdShadeMaterialBindingAPI) attach to any prim via API schemas metadata.

Multiple-apply API schemas can be applied more than once per prim and are namespaced by instance name (e.g., MaterialBindingAPI:foo).

Fallback values are authored in the schema's generated C++ (GetDefaultValue) and are returned when no authored opinion exists; they are not stored in layers.

Schema versioning uses the schema's plugin metadata and Usd.SchemaRegistry; bumping a schema requires regenerating and rebuilding the plugin.

Custom properties are declared with custom = true and do not require a schema; built-in schema properties must match the schema's declared type and variability.

Usd.SchemaRegistry.GetSchemaTypeName and IsConcrete let tools test whether a type name maps to a registered, instantiable schema.

Hydra is the rendering abstraction: a UsdStage is adapted by a UsdImagingDelegate into Hydra prims, which a render delegate (e.g., Storm, or a GPU renderer) consumes.

The scene index (HdSceneIndex) is a graph of HdSceneIndexPrim entries keyed by SdfPath; filters and observers wrap and transform the graph.

Legacy Hydra uses HdRenderIndex plus HdRprim/HdSprim/HdBprim; the newer scene-index API replaces the sync protocol for many renderers.

UsdImagingStageSceneIndex builds a scene index from a stage; HdRetainedSceneIndex and HdMergingSceneIndex let tools inject or combine prims.

Dirty propagation uses HdDirtyBits (e.g., DirtyTransform, DirtyPoints, DirtyVisibility); a render delegate must honor the bits it receives in Sync.

Storm is the reference rasterizing delegate; UsdView's renderer menu selects among registered Hydra render delegates.

Hydra 2.0 scene index filters (e.g., HdLegacyPrimTypeSceneIndex, HdDependencyForwardingSceneIndex) are how modern pipelines add culling, instancing, or overrides.

USD supports import/export to/from glTF, FBX, OBJ, Alembic, and MaterialX via plugins (usdGltf, usdFbx, usdAbc, usdMtlx); each converter has its own schema mapping and limitations.

UsdUtils provides layer/asset utilities: UsdUtils.ComputeAllDependencies, UsdUtils.FlattenLayerStack, and UsdUtils.StitchLayers for packaging.

USDZ is an uncompressed zip archive with USD files and textures; it requires the .usdz extension, 64-byte alignment for some readers, and no external references.

MaterialX interop maps MaterialX nodes to UsdShade networks; UsdMtlx.readMaterialX reads .mtlx into a stage, and UsdShadeMaterialBindingAPI links materials to prims.

Alembic interop preserves geometry and transforms but not USD composition arcs; it is a baked representation, not a live reference.

UsdUtils.ComputeAllDependencies returns referenced layers and asset paths so a package can be relocated without broken external references.

Coordinate and unit conventions (metersPerUnit, upAxis) differ between DCCs; converters must reconcile them or geometry will be scaled or rotated incorrectly.

Instancing is enabled by authoring instanceable = true on a prim with a reference or payload; all instances share one prototype (an implicit prototype prim under /_Prototype).

Point instancing (UsdGeomPointInstancer) uses per-instance transforms, positions, and prototype indices; it is lighter than native instancing for many copies.

Native instancing requires identical composition; differing overrides on an instanceable prim break instancing and force a unique prototype.

Payloads defer loading heavy subtrees; use Usd.Stage.Load/Unload or the payloads metadata to control memory and load time.

Asset structure convention: a top-level asset prim with defaultPrim set, geometry under /Geom, materials under /Materials, and a layer or sublayer per department.

Performance tools include Usd.Stage.GetUsedLayers, the UsdUtils dependency graph, and the usdview statistics panel; avoid deep composition chains and excessive sublayers.

A prototype is not directly authorable; edit the source prim or use Usd.Prim.GetPrototype to inspect the composed prototype.

Large scenes benefit from scene index filters that cull or merge prims before they reach the render delegate.

USD ships Python bindings (pxr.Usd, pxr.Sdf, pxr.UsdGeom, pxr.UsdShade) and C++ headers; most pipeline tools are Python scripts driving the stage API.

The USD plugin system uses plugInfo.json files discovered via PXR_PLUGINPATH_NAME; schema and file-format plugins are registered at runtime.

usdview is the reference inspection tool; usdcat, usdedit, usddiff, and sdfdump are CLI tools for converting, editing, diffing, and dumping layers.

Asset resolvers (ArResolver) map asset paths to files; custom resolvers implement ArResolver for studio pathing, and PXR_AR_DEFAULT_SEARCH_PATH sets fallback search paths.

Usd.Stage.Open takes a layer or file path plus Usd.Stage.OpenMask (e.g., LoadAll, LoadNone) to control payload loading at open time.

Headless pipeline jobs should use Usd.Stage.Open with explicit masks and close stages to release memory; long-running tools should avoid holding stale prim handles across composition changes.

Version pinning matters: USD's C++ ABI and Python API change across releases, so pipelines should pin the USD version and rebuild plugins together.

UsdUtils.ComplianceChecker runs validation rules (e.g., missing defaultPrim, unresolved references, invalid usdz packaging) and reports errors and warnings.

usdchecker is the CLI wrapper around the compliance checker; run it on a packaged asset before delivery to catch structural issues.

Common composition bugs: wrong sublayer order (strongest opinions lost), missing defaultPrim, and references to layers without a matching prim path.

Use Usd.PrimCompositionQuery to list arcs and their strengths, and Usd.Stage.Flatten() to inspect the composed result when debugging overrides.

usddiff and sdfdump reveal layer-level differences and raw Sdf data, which helps isolate whether a bug is in authoring or composition.

Unresolved asset paths usually mean a missing ArResolver mapping or a broken relative path; check the layer's resolved path and the asset resolver search paths.

Instancing bugs often come from per-instance overrides that break instancing; check whether the prim is still instanceable and whether a prototype exists.