openusd 0.8.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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

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

`openusd` covers the core USD workflow: read and write `.usda`, `.usdc`, and
`.usdz` files; compose layers with references, payloads, variants, instancing,
relocates, and variable expressions; then explore or edit the result through
the `Stage` API. It supports predicate-based traversal, typed value resolution,
layer- and stage-level authoring, and transferable diffs for live sync.

For higher-level domain APIs, the companion
[`openusd-schemas`](https://github.com/mxpv/openusd/tree/main/crates/openusd-schemas)
crate provides typed `Stage` views for geometry, shading, lighting, animation,
physics, rendering, and more.

## Features

- File formats — reads and writes `.usda` (text), `.usdc` (binary), and `.usdz` (archive).
- A fully featured [composition engine](https://github.com/mxpv/openusd/tree/main/crates/openusd/src/pcp) — [LIVRPS](https://docs.nvidia.com/learn-openusd/latest/creating-composition-arcs/strength-ordering/what-is-liverps.html) strength ordering over a per-prim node graph, with [list editing](https://openusd.org/release/glossary.html#usdglossary-listediting), scene-graph [instancing](https://openusd.org/release/glossary.html#usdglossary-instancing), non-destructive [relocates](https://openusd.org/release/glossary.html#usdglossary-relocates), and [variable expressions](https://openusd.org/dev/user_guides/variable_expressions.html).
- A composed [`Stage`](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/usd/stage.rs) — 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](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/sdf/layer.rs)- and [stage](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/usd/stage.rs)-tier APIs, with typed [spec views](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/sdf/spec.rs), composed [prim/attribute/relationship handles](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/usd/prim.rs) 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`](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/usd/diff.rs) for live mirroring across processes.

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](https://github.com/mxpv/openusd/tree/main/vendor/core-spec-supplemental-release_dec2025/file_formats/tests/assets/text) | :white_check_mark: Passes | 10 tests against JSON baselines |
| [Binary format parsing](https://github.com/mxpv/openusd/tree/main/vendor/core-spec-supplemental-release_dec2025/file_formats/tests/assets/binary) | :white_check_mark: Passes | 42 tests manually backported from the reference suite's `test_binary.py` in [`tests/binary_format.rs`](https://github.com/mxpv/openusd/blob/main/crates/openusd/tests/binary_format.rs) |
| [Composition](https://github.com/mxpv/openusd/tree/main/vendor/core-spec-supplemental-release_dec2025/composition/tests/assets) | :white_check_mark: Passes | [`tests/composition.rs`](https://github.com/mxpv/openusd/blob/main/crates/openusd/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](https://github.com/mxpv/openusd/tree/main/vendor/core-spec-supplemental-release_dec2025/value_resolution) | :ballot_box_with_check: Partial | 8 tests in [`tests/value_resolution.rs`](https://github.com/mxpv/openusd/blob/main/crates/openusd/tests/value_resolution.rs) (defaults, time samples, value clips). Excludes attribute fallbacks and splines |
| [Combine chains](https://github.com/mxpv/openusd/tree/main/vendor/core-spec-supplemental-release_dec2025/data_types/tests/combine_chain) | :white_check_mark: Passes | [`ListOp::combined_with`](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/sdf/list_op.rs) and [`ListOp::reduced`](https://github.com/mxpv/openusd/blob/main/crates/openusd/src/sdf/list_op.rs) against JSON baselines |

## Getting started

Add the crate to your `Cargo.toml` (or run `cargo add openusd`):

```toml
[dependencies]
openusd = "0.8"
```

If you need the latest unreleased changes, depend on the crate directly from the
git repository:

```toml
[dependencies]
openusd = { git = "https://github.com/mxpv/openusd.git" }
```

To pin a specific revision, add a `rev` field:

```toml
[dependencies]
openusd = { git = "https://github.com/mxpv/openusd.git", rev = "4c02084" }
```

### Feature flags

| Feature | Enables |
|---------|---------|
| `mmap` | Memory-mapped reads of layer files, enabled per resolver with `ar::DefaultResolver::map_files` |
| `serde` | `serde` support for serializing core types |

## Example

```rust,no_run
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()?;
```

To read typed schema views (a `Mesh` and its points, a `Skeleton`, a `Material`)
over the composed stage, add [`openusd-schemas`](https://github.com/mxpv/openusd/tree/main/crates/openusd-schemas) alongside
this crate.

More runnable examples live in the [`examples/`](https://github.com/mxpv/openusd/tree/main/crates/openusd/examples) directory:

```bash
cargo run -p openusd --example dump_usdc -- path/to/file.usdc
cargo run -p openusd --example write_usda
cargo run -p openusd --example author_variant_and_reference
```

## License

Licensed under the
[MIT License](https://github.com/mxpv/openusd/blob/main/LICENSE), except for
`src/usd/core_schemas.rs`, which is generated from OpenUSD's own schema
definitions and covered by the Tomorrow Open Source Technology License 1.0.
`third-party/` carries that license and upstream's notice;
`vendor/OpenUSD/README.md` in the repository records where the file comes from.