https://github.com/mxpv/openusd
Native Rust USD library
https://github.com/mxpv/openusd
gamedev openusd rust usd usdz
Last synced: 5 days ago
JSON representation
Native Rust USD library
- Host: GitHub
- URL: https://github.com/mxpv/openusd
- Owner: mxpv
- License: mit
- Created: 2024-01-02T19:26:20.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-05-25T19:24:50.000Z (8 days ago)
- Last Synced: 2026-05-25T21:24:55.715Z (8 days ago)
- Topics: gamedev, openusd, rust, usd, usdz
- Language: Rust
- Homepage: https://openusd.org
- Size: 7.35 MB
- Stars: 100
- Watchers: 4
- Forks: 13
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-openusd - Native Rust USD library - An implementation of Universal Scene Description written in native Rust. (Libraries & Tools / Technical Explanation)
README
# openusd
[](https://crates.io/crates/openusd)
[](https://docs.rs/crate/openusd/latest)
[](https://github.com/mxpv/openusd/actions/workflows/ci.yml)
[](https://codecov.io/gh/mxpv/openusd)
[](https://deps.rs/repo/github/mxpv/openusd)
`openusd` is a Rust implementation of Pixar's [Universal Scene Description](https://openusd.org/release/index.html) (USD) format with no C++ dependencies.
For a detailed comparison with the C++ reference implementation and current progress, see the [Roadmap](ROADMAP.md).
## Features
- File formats — reads and writes `.usda` (text), `.usdc` (binary), and `.usdz` (archive).
- Fully featured [composition engine](src/pcp)
- [LIVRPS](https://docs.nvidia.com/learn-openusd/latest/creating-composition-arcs/strength-ordering/what-is-liverps.html) strength ordering with sublayers, inherits, variants, references, payloads, and specializes.
- [List-edit composition](https://openusd.org/release/glossary.html#usdglossary-listediting) across layers.
- Per-prim node graph with namespace mapping across composition arcs.
- Non-destructive namespace remapping via [relocates](https://openusd.org/release/glossary.html#usdglossary-relocates).
- [Variable expressions](https://openusd.org/dev/user_guides/variable_expressions.html) with string interpolation and built-in functions.
- Passes [AOUSD compliance tests](vendor/core-spec-supplemental-release_dec2025/composition/tests/assets).
- Composed [`Stage`](src/usd/stage.rs)
- 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](https://openusd.org/release/glossary.html#usdglossary-sessionlayer) and [variant fallback](https://openusd.org/release/glossary.html#usdglossary-variantset) selections via `StageBuilder`.
- Recoverable error handling via `StageBuilder::on_error` callback.
- Authoring API
- Build USD scenes through [layer](src/sdf/layer.rs)- and [stage](src/usd/stage.rs)-tier APIs.
- Typed [spec views](src/sdf/spec.rs) for compile-time-checked per-kind editing.
- Composed [prim, attribute, and relationship handles](src/usd/prim.rs) 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 (feature-gated, layered on the composed stage)
- [`UsdGeom`](src/schemas/geom) — Imageable / Boundable / Xformable, intrinsic shapes, Camera, Mesh, Curves, PointInstancer.
- [`UsdLux`](src/schemas/lux) — concrete light prims plus LightAPI / ShapingAPI / ShadowAPI and friends.
- [`UsdPhysics`](src/schemas/physics) — scene, joints, collisions, and per-DOF limit / drive APIs.
- [`UsdSkel`](src/schemas/skel) — schema reader plus a pure-math skinning toolkit (topology, anim mapping, LBS, blend shapes).
If you encounter a file that can't be read, please open an [issue](https://github.com/mxpv/openusd/issues) and attach the USD file for investigation.
## Compliance
The [AOUSD Core Specification 1.0](https://aousd.org/blog/foundations-of-open-3d-development-introducing-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](vendor/core-spec-supplemental-release_dec2025/file_formats/tests/assets/text) | :white_check_mark: Passes | 10 tests against JSON baselines |
| [Binary format parsing](vendor/core-spec-supplemental-release_dec2025/file_formats/tests/assets/binary) | :construction: Planned | Baselines are generated by a Python script. Needs a JSON export step or a bridge layer to produce comparable output |
| [Composition](vendor/core-spec-supplemental-release_dec2025/composition/tests/assets) | :white_check_mark: Passes | All 276 tests covering text and binary formats, including 20 relocation tests |
| [Value resolution](vendor/core-spec-supplemental-release_dec2025/value_resolution) | :construction: Planned | Requires time-sample support in the core |
| [Combine chains](vendor/core-spec-supplemental-release_dec2025/data_types/tests/combine_chain) | :white_check_mark: Passes | [`ListOp::combined_with`](src/sdf/list_op.rs) and [`ListOp::reduced`](src/sdf/list_op.rs) against JSON baselines |
## Getting started
> [!WARNING]
> This crate is under active development. No API stability is guaranteed until version 1.0.
To begin, simply clone the repository including its submodules.
Make sure you have [`Rust`](https://www.rust-lang.org/tools/install) installed on your system, `rustup` will do the rest.
```bash
# Clone the project
git clone --recurse-submodules https://github.com/mxpv/openusd.git
cd openusd
# Run examples
cargo run --example dump_usdc -- ~/caldera/layers/cameras.usd
```
## Example
```rust,no_run
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 all prims, or filter with a predicate (skips inactive/unloaded/abstract subtrees).
stage.traverse(|path| println!("{path}"))?;
stage.traverse_with_predicate(usd::PrimPredicate::DEFAULT, |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 = 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")?)?;
```
## Minimum supported Rust version (MSRV)
The project typically targets the latest stable Rust version. Please refer to [rust-toolchain.toml](./rust-toolchain.toml) for exact version currently used by our CIs.