openusd

openusd is a Rust implementation of Pixar's Universal Scene Description (USD) format with no C++ dependencies.

openusd covers the core USD workflow: read and write .usda, .usdc, and .usdz files; compose layers with references, payloads, variants, instancing, relocates, and variable expressions; then explore or edit the result through the Stage API. It supports predicate-based traversal, typed value resolution, layer- and stage-level authoring, and transferable diffs for live sync.

For higher-level domain APIs, the companion openusd-schemas crate provides typed Stage views for geometry, shading, lighting, animation, physics, rendering, and more.

Features

• File formats — reads and writes .usda (text), .usdc (binary), and .usdz (archive).
• A fully featured composition engine — LIVRPS strength ordering over a per-prim node graph, with list editing, scene-graph instancing, non-destructive relocates, and variable expressions.
• A composed Stage — lazy cached per-prim composition with typed value resolution, predicate-based traversal, and full prim/property query API over the composed scene.
• An authoring API — build scenes through layer- and stage-tier APIs, with typed spec views, composed prim/attribute/relationship handles with chained fluent edits, EditTarget routing to a specific layer, in-memory anonymous-root stages, and applied API schema authoring.
• Live sync friendly — listen to Stage edit events and capture each edit as a transferable, replayable Diff for live mirroring across processes.

If you encounter a file that can't be read, please open an issue and attach the USD file for investigation.

Compliance

The AOUSD Core Specification 1.0 has been officially ratified. As part of the specification, sample implementations for compliance testing are provided as Python scripts with JSON baselines. Where JSON baselines are available, the crate parses them and verifies that its output matches.

Getting started

Add the crate to your Cargo.toml (or run cargo add openusd):

[dependencies]
openusd = "0.8"

If you need the latest unreleased changes, depend on the crate directly from the git repository:

[dependencies]
openusd = { git = "https://github.com/mxpv/openusd.git" }

To pin a specific revision, add a rev field:

[dependencies]
openusd = { git = "https://github.com/mxpv/openusd.git", rev = "4c02084" }

Feature flags

Example

use openusd::{ar, usd};

// Open a stage with default settings (DefaultResolver, strict errors, all payloads loaded).
let stage = usd::Stage::open("scene.usda")?;

// Or configure via the builder:
let stage = usd::Stage::builder()
    // Use a custom asset resolver (default: DefaultResolver).
    .resolver(ar::DefaultResolver::new())
    // Leave payload arcs unloaded (default: LoadAll).
    .load(usd::InitialLoadSet::LoadNone)
    // Restrict the stage to a subtree of interest.
    .mask(usd::StagePopulationMask::new(["/World/Hero"]))
    .open("scene.usda")?;

// Recoverable composition errors discovered so far: the root layer stack at
// open, plus reference/payload diagnostics that accrue as prims are traversed.
for err in stage.composition_errors() {
    eprintln!("warning: {err}");
}

// Traverse prims filtered by a predicate. DEFAULT skips inactive/unloaded/abstract
// subtrees and stops at instances; ALL visits every composed prim.
stage.traverse(usd::PrimPredicate::DEFAULT, |path| println!("{path}"))?;
stage.traverse(usd::PrimPredicate::ALL, |path| println!("{path}"))?;

// Composed prim queries go through a `Prim` handle (mirroring C++ `UsdPrim`).
let hero = stage.prim_at("/World/Hero");
let active = hero.is_active()?;
let is_model = hero.is_model()?;
let type_name = hero.type_name()?;

// Access children and properties composed across layers, references, and payloads.
let children = hero.children()?;
let properties = hero.property_names()?;

To read typed schema views (a Mesh and its points, a Skeleton, a Material) over the composed stage, add openusd-schemas alongside this crate.

More runnable examples live in the examples/ directory:

cargo run -p openusd --example dump_usdc -- path/to/file.usdc
cargo run -p openusd --example write_usda
cargo run -p openusd --example author_variant_and_reference

License

Licensed under the MIT License, except for src/usd/core_schemas.rs, which is generated from OpenUSD's own schema definitions and covered by the Tomorrow Open Source Technology License 1.0. third-party/ carries that license and upstream's notice; vendor/OpenUSD/README.md in the repository records where the file comes from.