openusd

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

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).
• Domain schema readers (opt-in feature flags, layered on the composed stage) — UsdGeom, UsdLux, UsdPhysics, UsdRender, UsdSkel, and UsdShade.
• 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.

Area	Status	Notes
Text format parsing	:white_check_mark: Passes	10 tests against JSON baselines
Binary format parsing	:white_check_mark: Passes	42 tests manually backported from the reference suite's test_binary.py in tests/binary_format.rs
Composition	:white_check_mark: Passes	tests/composition.rs runs the full vendor suite (138 assets) through both the text and binary parsers, regenerating each pcp.txt dump to validate strength ordering, prim/property stacks, and time offsets
Value resolution	:ballot_box_with_check: Partial	8 tests in tests/value_resolution.rs (defaults, time samples, value clips). Excludes attribute fallbacks and splines
Combine chains	:white_check_mark: Passes	ListOp::combined_with and ListOp::reduced against JSON baselines

Getting started

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.5"

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

The core library (formats, composition, and the Stage API) is always available. Domain schema readers are gated behind opt-in features so you only pay for what you use:

Feature	Enables
geom	UsdGeom — Imageable, Boundable, Xformable, shapes, Camera, Mesh, Curves, PointInstancer
lux	UsdLux — light prims and Light/Shaping/Shadow APIs
physics	UsdPhysics — scenes, joints, collisions, limit/drive APIs
render	UsdRender — RenderSettings, RenderProduct, RenderVar, RenderPass
skel	UsdSkel — skeleton reader and skinning toolkit
shade	UsdShade — materials, shader networks, bindings, UsdPreviewSurface
serde	serde support for serializing core types

[dependencies]
openusd = { version = "0.5", features = ["geom", "lux"] }

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()?;

With the geom feature, read typed schema views over the composed stage — here a Mesh and its point positions and normals:

// `PointBased` is brought in so its inherited accessors resolve on the view.
use openusd::schemas::geom::{self, PointBased};
use openusd::{gf, usd};

let stage = usd::Stage::open("scene.usda")?;

if let Some(mesh) = geom::Mesh::get(&stage, "/World/Mesh")? {
    // `points_attr` / `normals_attr` are inherited from the `PointBased` trait
    // up the chain. `point3f[]` and `normal3f[]` both decode to `Vec<gf::Vec3f>`,
    // so `get` extracts them directly.
    let points = mesh.points_attr().get::<Vec<gf::Vec3f>>()?;
    let normals = mesh.normals_attr().get::<Vec<gf::Vec3f>>()?;

    if let Some(points) = points {
        println!("{} points, normals authored: {}", points.len(), normals.is_some());
    }
}

More runnable examples live in the examples/ directory:

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

Minimum supported Rust version (MSRV)

The project targets stable Rust and aims for the latest Rust editions. The MSRV is bumped on an as-needed basis, whenever it makes sense for the project. Please refer to rust-toolchain.toml for the exact version currently used by our CIs.

License

Licensed under the MIT License.