dymokomi/luce-usd
Source of release 0.9.6
0.9.6 / README.md
# luce-usd
Universal Scene Description for Luce, written in **Luce Base**. luce-usd
reads and writes USD layers (`.usda` text, `.usdc` crate, `.usdz` packages)
and converts composed stages to and from luce-geocore `GeometrySet`s. It is
a gradual rewrite of Pixar's [OpenUSD](https://github.com/PixarAnimationStudios/OpenUSD)
(release v26.08): the modules follow OpenUSD's libraries (Sdf, Pcp, Usd,
UsdGeom) and each names the OpenUSD sources it ports. `docs/PORT.md` tracks
what is ported.
Status: **M12 done** (splines, array edits, CAD faces as NurbsPatch). The Sdf
data model; usda, usdc and usdz read and written as OpenUSD does them
(against OpenUSD's own test corpus, 2,054 of 2,056 text layers print
byte-identical to `usdcat`, every crate and package reads identically, and
2,055 layers written as crates read back identically); attribute splines
(Ts: reading, writing, layer offsets, evaluation) and array edits; CAD
models (luce-cad) exported as NurbsPatch prims;
composition (sublayers,
references, payloads, variants, inherits, specializes, relocates,
instancing, expression variables; 147 of OpenUSD's 151 Pcp museum cases
compose identically, and the four left print Pcp's graph dumps or read
layers OpenUSD itself refuses); and stages converted to and from luce-geocore `GeometrySet`s
(docs/MAPPING.md), scene-graph instances as instances. Pixar's Kitchen Set
flattens byte-identical to `usdcat`, loads in about 0.2 s and exports as
usda in about 0.25 s (docs/BENCHMARKS.md).
## Luce API
```
from usd import Usd
let geometry = Usd.load("chair.usdc") # a GeometrySet
let later = Usd.load("chair.usdc", time = 24.0, flatten = true, convert_units = true)
print(Usd.warnings()) # what the last load left out
Usd.save(geometry, "out.usdz", root = "geo") # .usda, .usdc, .usd or .usdz
Usd.convert("in.usda", "out.usdc") # layer to layer, nothing lost
print(Usd.info("chair.usdc")) # format, units, prims by type
let clean = Usd.load("Kitchen_set.usd", variants = "/Kitchen_set/Props_grp/North_grp/NorthWall_grp/NailA_1{modelingVariant=NailB}",
payloads = "/Kitchen_set/Arch_grp*") # session selections, payload globs
print(Usd.composition("Kitchen_set.usd")) # layers, prims, instances, variant sets
Usd.flatten("Kitchen_set.usd", "flat.usda") # the composed stage, as usdcat --flatten
```
## Exports
- `usd`: the Luce API (`Usd`).
- `usd_kernel`: Base internals for Base code in other packages and for the
package's checks.
## Tests
`luc test` runs two test programs: `tests/checks` (the Base module checks,
under a heap that counts live blocks and fails allocations in turn) and
`tests/api` (the Luce API tests). Fixtures in `tests/fixtures/` are our own.
Parity with OpenUSD itself (byte-identical `usdcat` output over OpenUSD's
test corpus, composition baselines) is checked locally, not by `luc test`; see
`docs/PARITY.md`.
`python3 bench/run.py` prints the benchmark table (`docs/BENCHMARKS.md`).
## License
Apache License 2.0 (`LICENSE`). luce-usd is a derivative work of OpenUSD,
which is licensed under the Tomorrow Open Source Technology License 1.0
(`licenses/OPENUSD-TOST-1.0.txt`); see `NOTICE`.