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.
- 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, andUsdShade. - 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,
EditTargetrouting to a specific layer, in-memory anonymous-root stages, and applied API schema authoring.
If you encounter a file that can't be read, please open an issue and attach the USD file for investigation.
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 | 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 | ☑️ 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 |
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.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" }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"] }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")?;
// Inspect any recoverable composition errors collected while loading.
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_referenceThe 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.
Licensed under the MIT License.