openusd 0.3.0

Rust native USD library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# openusd

[![Crates.io Version](https://img.shields.io/crates/v/openusd)](https://crates.io/crates/openusd)
[![docs.rs](https://img.shields.io/docsrs/openusd)](https://docs.rs/crate/openusd/latest)
[![CI](https://github.com/mxpv/openusd/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mxpv/openusd/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mxpv/openusd/graph/badge.svg?token=LAPV2T3AI8)](https://codecov.io/gh/mxpv/openusd)
[![dependency status](https://deps.rs/repo/github/mxpv/openusd/status.svg)](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 `.usda` (text), `.usdc` (binary), and `.usdz` (archive) with format auto-detection.
- 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/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.
  - [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.

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::FieldKey, Stage};

// Open a stage with default settings (DefaultResolver, strict errors).
let stage = Stage::open("scene.usda")?;

// Or configure via the builder:
let stage = 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
    })
    .open("scene.usda")?;

// Traverse all prims in the composed scene graph.
stage.traverse(|path| {
    println!("{path}");
})?;

// Read a typed field value (generic over TryFrom<Value>).
let active: Option<bool> = stage.field("/World/Cube", FieldKey::Active)?;

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

## 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.