openusd

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

The core library: it reads and writes the .usda, .usdc, and .usdz file formats, composes layers into a scene graph, and exposes the composed result through a Stage API for traversal, value resolution, and authoring.

Typed schema views over that stage — Mesh, Camera, Material, Skeleton, and the rest — live in a separate crate, openusd-schemas.

For a detailed comparison with the C++ reference implementation and current progress, see the Roadmap.

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.

Getting started

[!WARNING] This crate is under active development. No API stability is guaranteed until version 1.0.

Make sure you have Rust installed on your system, rustup will do the rest.

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

[dependencies]
openusd = "0.7"

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

Feature	Enables
`serde`	`serde` support for serializing core types

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