Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-usd

Source of release 0.9.3

0.9.3 / 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`.