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).
• Fully featured composition engine
  • LIVRPS strength ordering with sublayers, inherits, variants, references, payloads, and specializes.
  • List-edit composition across layers.
  • Per-prim node graph with namespace mapping across composition arcs.
  • Non-destructive namespace remapping via relocates.
  • Variable expressions with string interpolation and built-in functions.
  • Passes AOUSD compliance tests.
• Composed Stage
  • Recursive layer collection with cycle detection and pluggable asset resolution.
  • Lazy per-prim composition with caching, depth-first traversal, and typed field access.
  • Prim status, schema, and model-hierarchy queries on composed prims.
  • Predicate-based traversal that prunes inactive, unloaded, or abstract subtrees.
  • Working-set control via population masks and initial payload-loading rules.
  • Session layer and variant fallback selections via StageBuilder.
  • Recoverable error handling via StageBuilder::on_error callback.
• Authoring API
  • Build USD scenes through layer- and stage-tier APIs.
  • Typed spec views for compile-time-checked per-kind editing.
  • Composed prim, attribute, and relationship handles with chained fluent edits.
  • EditTarget routing of opinions to a specific layer; in-memory stages for anonymous-root authoring.
  • Applied API schema authoring.
• Domain schema readers (opt-in feature flags, layered on the composed stage)
  • UsdGeom — Imageable / Boundable / Xformable, intrinsic shapes, Camera, Mesh, Curves, PointInstancer.
  • UsdLux — concrete light prims plus LightAPI / ShapingAPI / ShadowAPI and friends.
  • UsdPhysics — scene, joints, collisions, and per-DOF limit / drive APIs.
  • UsdRender — RenderSettings / RenderProduct / RenderVar / RenderPass plus render-product/var conformance helpers.
  • UsdSkel — schema reader plus a pure-math skinning toolkit (topology, anim mapping, LBS, blend shapes).
  • UsdShade — Material / NodeGraph / Shader, connectable inputs / outputs, MaterialBindingAPI, and UsdPreviewSurface.

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	✅ Passes	10 tests against JSON baselines
Binary format parsing	✅ Passes	42 tests manually backported from the reference suite's test_binary.py in tests/binary_format.rs
Composition	✅ Passes	All 276 tests covering text and binary formats, including 20 relocation tests
Value resolution	☑️ Partial	8 tests in tests/value_resolution.rs (defaults, time samples, value clips). Excludes attribute fallbacks and splines
Combine chains	✅ Passes	ListOp::combined_with and ListOp::reduced against JSON baselines

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

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.4", features = ["geom", "lux"] }

Example

use openusd::{ar, sdf, 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())
    // Handle composition errors instead of failing (default: hard error).
    .on_error(|err| {
        eprintln!("warning: {err}");
        Ok(()) // skip missing dependency and continue
    })
    // Leave payload arcs unloaded (default: LoadAll).
    .initial_load_set(usd::InitialLoadSet::LoadNone)
    // Restrict the stage to a subtree of interest.
    .population_mask(usd::StagePopulationMask::new(["/World/Hero"]))
    .open("scene.usda")?;

// 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.
let active = stage.is_active("/World/Hero")?;
let is_model = stage.is_model("/World/Hero")?;
let type_name = stage.type_name("/World/Hero")?;

// Read a typed field value.
let visible: Option<bool> = stage.field("/World/Hero", sdf::FieldKey::Active)?;

// Access children composed across layers, references, and payloads.
let children = stage.prim_children("/World/Hero")?;
let properties = stage.prim_properties("/World/Hero")?;

// Author into an in-memory stage.
let stage = usd::Stage::builder().in_memory("anon.usda")?;
let mesh = stage
    .define_prim("/World/Mesh")?
    .set_type_name("Mesh")?
    .set_kind("component")?;
let radius = mesh
    .create_attribute("radius", "double")?
    .set_variability(sdf::Variability::Uniform)?
    .set(sdf::Value::Double(1.0))?;
let binding = mesh
    .create_relationship("material:binding")?
    .add_target(sdf::Path::new("/World/Material")?)?;

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.