lightusd 1.0.0rc4__tar.gz

lightusd-1.0.0rc4/LICENSE

@@ -0,0 +1,16 @@
+Apache 2.0 License 
+
+Copyright (c) 2020-2023 Syoyo Fujita
+Copyright (c) 2024-Present Light Transport Entertainment Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lightusd-1.0.0rc4/LICENSE.3rdparty

@@ -0,0 +1,87 @@
+# Third-Party Notices
+
+This file summarizes third-party code and data redistributed in this repository.
+The authoritative license text is the license file or source header referenced
+in each entry.
+
+## Core And Runtime Dependencies
+
+| Component | License | Location |
+| --- | --- | --- |
+| nonstd optional-lite, expected-lite, span-lite, string-view-lite | Boost Software License 1.0 | `src/nonstd/*.hpp` |
+| LZ4 | BSD 2-Clause | `src/lz4/LICENSE` |
+| miniz | MIT | `src/external/LICENSE.miniz` |
+| Zstandard | BSD-style or GPLv2 | `src/external/zstd.h`, `src/external/zstd.c` |
+| yyjson | MIT | `src/external/yyjson.LICENSE` |
+| pugixml | MIT | `src/external/pugixml.LICENSE` |
+| nlohmann/json | MIT | `src/external/jsonhpp/LICENSE.MIT` |
+| fast_float | Apache 2.0, Boost Software License 1.0, or MIT | `src/external/fast_float/` |
+| Dragonbox | Boost Software License 1.0 or Apache 2.0 with LLVM exception | `src/external/dragonbox/` |
+| Mapbox earcut.hpp | ISC | `src/external/mapbox/earcut/LICENSE` |
+| Mapbox eternal | ISC | `src/external/mapbox/eternal/LICENSE.md` |
+| simple_match | Boost Software License 1.0 | `src/external/simple_match/LICENSE_1_0.txt` |
+| string_id | zlib | `src/external/string_id/LICENSE` |
+| ghc/filesystem | MIT | `src/external/filesystem/LICENSE` |
+| p-ranav/glob | MIT | `src/external/glob/LICENSE` |
+| nanoflann | BSD 2-Clause | `src/external/nanoflann.COPYING` |
+| linalg.h | Unlicense | `src/external/linalg.UNLICENSE` |
+| jeaiii_to_text | MIT | `src/external/jeaiii_to_text.LICENSE` |
+| xxHash | BSD 2-Clause | `src/external/xxhash.LICENSE` |
+| tinycolorio | MIT | `src/external/tinycolorio.LICENSE` |
+| stb_image, stb_image_resize, stb_image_write, stb_truetype | Public domain or MIT | `src/external/stb_*.h` |
+| TinyEXR and included OpenEXR code | BSD-style | `src/external/tinyexr.h` |
+| TinyDNG | MIT | `src/external/tiny_dng_loader.h`, `src/external/tiny_dng_writer.h` |
+| tinyobjloader | MIT | `src/external/tiny_obj_loader.h` |
+| tinygltf | MIT | `src/external/tiny_gltf.h` |
+| pystring | BSD 3-Clause | `src/external/pystring.LICENSE` |
+| fpng | Unlicense | `src/external/fpng.h`, `src/external/fpng.cpp` |
+| Wuffs unsupported snapshot | Apache 2.0 | `src/external/wuffs-unsupported-snapshot.c` |
+| MikkTSpace | zlib | `src/external/mikktspace/LICENSE` |
+| sRGB transform by Project Nayuki | MIT | `src/image-util.cc` |
+| OpenSubdiv | Modified Apache 2.0 | `src/osd/LICENSE.txt` |
+| MaterialX data | Apache 2.0 | `data/materialx/LICENSE` |
+
+## Optional Feature Dependencies
+
+| Component | License | Location |
+| --- | --- | --- |
+| meshoptimizer | MIT | `src/external/meshoptimizer/LICENSE.md` |
+| OpenFBX | MIT | `src/external/OpenFBX/LICENSE` |
+| ALAC | Apache 2.0 | `src/external/alac/LICENSE` |
+| dr_wav, dr_mp3 | Public domain or MIT-0 | `src/external/dr_wav.h`, `src/external/dr_mp3.h` |
+| ogt_vox | MIT | `src/external/LICENSE.ogt_vox.md` |
+| WebAssembly Micro Runtime (WAMR) | Apache 2.0 | `src/external/wamr/LICENSE` |
+| QuickJS-ng | MIT | `src/external/quickjs-ng/LICENSE` |
+| civetweb | MIT | `src/external/civetweb/LICENSE.md` |
+| Remotery | Apache 2.0 | `src/external/Remotery/Remotery.LICENSE` |
+| libsais | Apache 2.0 | `src/external/libsais/libsais.LICENSE` |
+| nanozlib | Apache 2.0 | `src/external/nanozlib.h` |
+| nanobind | BSD 3-Clause | `src/external/nanobind/LICENSE` |
+| pybind11 | BSD 3-Clause | `src/external/pybind11/LICENSE` |
+| tir image resizer (tinyexr tools) | BSD 3-Clause | `src/external/textools/resize/LICENSE` |
+| texcomp texture compressor (tinyexr tools) | Apache 2.0 | `src/external/textools/texcomp/LICENSE`, `NOTICE.md` |
+| texpipe texture pipeline (tinyexr tools) | Apache 2.0 | `src/external/textools/texpipe/LICENSE` |
+| envmap IBL library (tinyexr tools) | Apache 2.0 | `src/external/textools/envmap/LICENSE` |
+
+## Examples, Tools, And Development Assets
+
+| Component | License | Location |
+| --- | --- | --- |
+| SDL2-related viewer dependencies | zlib/MIT-style, see bundled notices | `examples/sdlviewer/README.md` |
+| GLFW | zlib/libpng | `examples/common/glfw-3.3.6/LICENSE.md` |
+| Dear ImGui | MIT | `examples/common/imgui/LICENSE.txt` |
+| imnodes | MIT | `examples/common/imnodes/LICENSE.md` |
+| nativefiledialog-extended | zlib | `examples/common/nativefiledialog-extended/LICENSE` |
+| virtualGizmo3D | BSD 2-Clause | `examples/common/virtualGizmo3D/license.txt` |
+| miniaudio | Public domain or MIT-0 | `examples/common/miniaudio.LICENSE` |
+| cuew | Apache 2.0 | `examples/common/cuew/LICENSE` |
+| volk | MIT | `examples/common/volk/LICENSE.md` |
+| Vulkan-Headers | Apache 2.0 | `examples/common/vulkan-headers/include/vulkan/vulkan_core.h` |
+| bvh | MIT | `examples/common/bvh/LICENSE.txt` |
+| Metal-cpp | Apache 2.0 | `examples/common/metalcpp/LICENSE.txt` |
+| Roboto Mono embedded assets | Apache 2.0 | `examples/common/LICENSE.roboto_mono_embed.md` |
+| Vulkan sample camera code by Sascha Willems | MIT | `examples/common/viewport_camera.hh` |
+| Silicon Graphics trackball code | SGI permissive notice | `examples/common/trackball.h`, `examples/common/trackball.cc` |
+| par_shapes | MIT | `examples/common/par_shapes.h` |
+| criterion benchmark helper | MIT | `benchmarks/criterion.LICENSE` |
+| acutest | MIT | `tests/unit/LICENSE.acutest` |

lightusd-1.0.0rc4/MANIFEST.in

@@ -0,0 +1,107 @@
+# sdist contents for the lightusd PyPI package.
+# Everything needed to run `python -m build --wheel` from the sdist itself.
+# The wheel builds only the "next" core, Tydra-next, the C API, and the Python
+# extension, but those targets reuse selected sources and headers elsewhere in
+# src/. Keep those transitive build inputs in the sdist.
+
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+
+# next core + tydra-next + C API + extension sources.
+recursive-include src/next *.cc *.c *.h *.hh *.inc *.txt
+recursive-include src/tydra/next *.cc *.hh *.txt
+recursive-include src/c-api *.cc *.h *.hh
+recursive-include src/python *.c *.h
+include src/lz4/lz4.c src/lz4/lz4.h
+recursive-include src/external/fast_float/include *.h
+include src/external/dragonbox/dragonbox.h
+include src/mtlx-xml-tokenizer.cc src/mtlx-xml-tokenizer.hh
+include src/mtlx-xml-parser.cc src/mtlx-xml-parser.hh
+include src/mtlx-dom.cc src/mtlx-dom.hh
+
+# Python package + tests.
+recursive-include python *.py *.pyi py.typed README.md
+recursive-include python/tests *.py
+
+# Small USDA assets used by the pytest suite (skip-if-missing otherwise).
+recursive-include tests/usda *.usda
+
+# setuptools_scm's git file-finder would otherwise include every tracked
+# file; prune everything the wheel build does not need.
+prune examples
+prune web
+prune models
+prune sandbox
+prune doc
+prune benchmark
+prune benchmarks
+prune blender
+prune aousd
+prune schema
+prune data
+prune container
+prune cmake
+prune android
+prune ios
+prune tests/usdc
+prune tests/feat
+prune tests/unit
+prune tests/fuzzer
+prune tests/next
+prune tests/tydra
+prune tests/c-api
+prune tests/composition
+prune src/external
+prune src/blender
+prune src/core
+prune src/tsd
+prune src/osd
+prune src/tydra/mcp
+prune tools
+prune subprojects
+prune scripts
+exclude src/*.cc src/*.cpp
+# Transitive standalone-next inputs. Headers are inexpensive and keeping the
+# complete src/ header surface avoids a fragile hand-maintained include graph.
+recursive-include src *.h *.hh *.hpp *.inc *.txt
+include src/color-transform.cc
+include src/mtlx-xml-tokenizer.cc src/mtlx-xml-parser.cc src/mtlx-dom.cc
+include src/ptx-loader.cc
+include src/core/path-expression.cc src/core/path-expression-eval.cc
+recursive-include src/tsd *.cc
+include src/external/miniz.c src/external/mikktspace/mikktspace.c
+
+# Strip build artefacts.
+global-exclude *.pyc *.pyo *.so *.pyd __pycache__
+prune build
+prune build_py_ext_next
+prune build-next
+prune dist
+prune .git
+prune .github
+prune .clusterfuzzlite
+prune .serena
+prune screenshots
+
+# Repository-only metadata and alternate build-system entry points are not
+# needed to build the Python extension from an sdist.
+exclude .cirrus.yml
+exclude .clang-format
+exclude .gitignore
+exclude .gitleaksignore
+exclude AGENTS.md
+exclude CLAUDE.md
+exclude CMakeLists.txt
+exclude CMakePresets.json
+exclude CMakeSettings.json
+exclude exporter-fix.md
+exclude lgtm.yaml
+exclude meson.build
+exclude meson.options
+exclude resume-aousd.md
+exclude resume-dev.md
+exclude vk_layer_settings.txt
+exclude xmake.lua
+exclude *.bat

lightusd-1.0.0rc4/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: lightusd
+Version: 1.0.0rc4
+Summary: Lightweight, dependency-free USD/USDA/USDC/USDZ loader + Tydra render-scene access, with NumPy-friendly zero-copy arrays (CPython abi3 + free-threaded wheels).
+Author-email: Syoyo Fujita <syoyo@lighttransport.com>, "Light Transport Entertainment, Inc." <syoyo@lighttransport.com>
+License: Apache 2.0 License 
+        
+        Copyright (c) 2020-2023 Syoyo Fujita
+        Copyright (c) 2024-Present Light Transport Entertainment Inc.
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://github.com/lighttransport/LightUSD
+Project-URL: Repository, https://github.com/lighttransport/LightUSD
+Project-URL: Issues, https://github.com/lighttransport/LightUSD/issues
+Keywords: usd,usda,usdc,usdz,pixar,3d,scene
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE.3rdparty
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: numpy<3,>=2.2; extra == "test"
+Dynamic: license-file
+
+# lightusd
+
+Lightweight, dependency-free **USD** (Universal Scene Description) library for
+Python: load and author USDA / USDC / USDZ, resolve composition, and extract
+GPU-ready render data — with **zero-copy NumPy interop**.
+
+Built on the LightUSD *next* core + *tydra-next* (no pxrUSD install required,
+no legacy core in the wheel; native `cmake -S .` and WASM still
+provide the legacy path via `web/binding.cc`). **v1.0.0**, npm `preview`
+dist-tag. Wheels:
+
+- `cp310-abi3` — one stable-ABI wheel covers CPython **3.10+**
+- `cp314t` — native **free-threaded** (GIL-less) CPython 3.14 wheel
+
+```bash
+pip install lightusd
+```
+
+## Reading
+
+```python
+import numpy as np
+import lightusd
+
+stage = lightusd.load("scene.usdz")          # usda / usdc / usdz, composed
+for prim in stage:                            # depth-first traversal
+    print(prim.path, prim.type_name)
+
+mesh = stage.prim_at("/World/Mesh")
+points = np.asarray(mesh["points"])           # zero-copy (N, 3) float32
+attr = mesh.attribute("xformOp:translate")
+if attr.has_timesamples:
+    value = attr.get(time=12.0)               # linear interpolation
+print(mesh.relationship("material:binding").targets)
+```
+
+## Authoring
+
+```python
+st = lightusd.Stage.create()
+st.up_axis = "Y"
+grid = st.define_prim("/World/Grid", "Mesh")
+grid.set("points", np.zeros((64, 3), np.float32), type="point3f[]")
+grid.set("purpose", "render", uniform=True)
+grid.set("xformOp:translate", (0.0, 1.0, 0.0), time=0.0)
+st.set_default_prim("World")
+st.save("out.usdc")                           # or .usda / .usdz
+```
+
+## Render extraction (tydra)
+
+```python
+from lightusd import tydra
+
+scene = tydra.to_render_scene(stage)          # triangulated, GPU-friendly
+for mesh in scene.meshes:
+    vertices = np.asarray(mesh.points)                # (N, 3) float32
+    indices = np.asarray(mesh.triangulated_indices)   # (T,) uint32
+    material = scene.materials[mesh.material_id]
+    base_color = material.param("diffuse_color")      # tuple or RenderTexture
+```
+
+## Notes
+
+- NumPy is optional (interop only, not a dependency).
+- `lightusd.flatten_file(src, dst)` runs a low-memory compose+flatten
+  pipeline that streams large arrays through without decoding them.
+- Free-threaded CPython: concurrent reads of one `Stage` are safe; do not
+  author to a stage while other threads read it.
+
+Apache 2.0. Part of [LightUSD](https://github.com/lighttransport/LightUSD).

lightusd-1.0.0rc4/README.md

@@ -0,0 +1,72 @@
+# LightUSD
+
+LightUSD is a full-featured, dependency-free, lightweight USD library written
+in C++17. It reads and writes USDA, USDC, and USDZ without requiring the
+OpenUSD runtime, and includes MaterialX and USD Physics support.
+
+LightUSD is designed for applications that need USD to be compact, portable,
+and fast: high-performance 3D interchange and DCC tools, render and asset
+pipelines, generative AI, and Physical AI systems that connect scene
+understanding with simulation and robotics. The same core runs across desktop,
+mobile, WebAssembly, and sandboxed environments, with explicit resource limits
+for untrusted assets.
+
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/lighttransport)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/lighttransport/lightusd)
+[![npm version](https://img.shields.io/npm/v/lightusd.svg)](https://www.npmjs.com/package/lightusd)
+
+## Packages
+
+Python:
+
+```sh
+python -m pip install lightusd
+```
+
+```python
+import lightusd
+
+stage = lightusd.load("scene.usdz")
+for prim in lightusd.traverse(stage):
+    print(prim.type_name, prim.name)
+```
+
+See [python/README.md](python/README.md) for Python usage. WebAssembly and
+JavaScript packages live under [web/](web/).
+
+## Build
+
+LightUSD requires a C++17 compiler and normally uses CMake:
+
+```sh
+cmake -S . -B build_ninja -G Ninja \
+  -DLIGHTUSD_BUILD_TESTS=ON -DLIGHTUSD_BUILD_EXAMPLES=ON
+cmake --build build_ninja
+ctest --test-dir build_ninja --output-on-failure
+```
+
+See [doc/build-and-examples.md](doc/build-and-examples.md) for integration,
+build options, and examples.
+
+## Documentation
+
+- [Documentation index](doc/README.md)
+- [API and schema status](doc/api-status.md)
+- [MaterialX](doc/materialx.md)
+- [USD Physics](doc/usd-physics.md)
+- [Composition](doc/composition.md)
+- [Python bindings](doc/python_binding.md)
+- [Testing](doc/testing-cpp.md)
+- [Release and CI](doc/ci.md)
+
+## Security
+
+Use `USDLoadOptions::max_memory_limit_in_mb` for unknown inputs. For hostile or
+internet-sourced assets, also isolate loading in a sandboxed process or WASI
+environment.
+
+## License
+
+LightUSD is primarily licensed under Apache 2.0. Some helper code uses MIT or
+similarly permissive licenses. See [LICENSE.3rdparty](LICENSE.3rdparty) for
+third-party notices.

lightusd-1.0.0rc4/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = [
+    "setuptools>=68",
+    "setuptools_scm>=8",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lightusd"
+dynamic = ["version"]
+description = "Lightweight, dependency-free USD/USDA/USDC/USDZ loader + Tydra render-scene access, with NumPy-friendly zero-copy arrays (CPython abi3 + free-threaded wheels)."
+readme = "python/README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Syoyo Fujita", email = "syoyo@lighttransport.com" },
+    { name = "Light Transport Entertainment, Inc.", email = "syoyo@lighttransport.com" },
+]
+keywords = ["usd", "usda", "usdc", "usdz", "pixar", "3d", "scene"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+]
+
+[project.urls]
+Homepage = "https://github.com/lighttransport/LightUSD"
+Repository = "https://github.com/lighttransport/LightUSD"
+Issues = "https://github.com/lighttransport/LightUSD/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7", "numpy>=2.2,<3"]
+
+[tool.setuptools]
+package-dir = {"" = "python"}
+packages = ["lightusd"]
+
+[tool.setuptools.package-data]
+lightusd = ["py.typed", "*.pyi"]
+
+[tool.setuptools_scm]
+version_file = "python/lightusd/_version.py"
+
+# --------------------------------------------------------------------------
+# cibuildwheel configuration
+# --------------------------------------------------------------------------
+# Two wheels per platform:
+#   cp310-abi3 : Py_LIMITED_API=0x030A0000, covers CPython >= 3.10
+#   cp314t     : free-threaded CPython 3.14 (non-limited; Py_mod_gil declared)
+[tool.cibuildwheel]
+build = ["cp310-*", "cp314t-*"]
+enable = ["cpython-freethreading"]
+# No PyPy; lightusd is CPython-only.
+skip = [
+    "pp*",
+    "*-musllinux*",
+    "*-win32",
+    "*-manylinux_i686",
+]
+build-frontend = "build"
+archs = ["auto64"]
+test-skip = ["*-win_arm64"]
+test-command = "pytest {project}/python/tests -k \"not slow and not large and not usd_assets and not aousd\" -q"
+test-extras = "test"
+
+[tool.cibuildwheel.linux]
+manylinux-x86_64-image = "quay.io/pypa/manylinux_2_28_x86_64:2025.10.10-1"
+manylinux-aarch64-image = "quay.io/pypa/manylinux_2_28_aarch64:2025.10.10-1"
+archs = ["x86_64", "aarch64"]
+before-build = "yum install -y ninja-build || apt-get install -y ninja-build || true"
+
+[tool.cibuildwheel.macos]
+archs = ["x86_64", "arm64"]
+environment = { MACOSX_DEPLOYMENT_TARGET = "11.0" }
+
+[tool.cibuildwheel.windows]
+archs = ["AMD64", "ARM64"]
+
+# Free-threaded wheel: run the suite with the GIL forced off so a module
+# that silently re-enables it (missing Py_mod_gil) fails loudly.
+[[tool.cibuildwheel.overrides]]
+select = "cp314t-*"
+test-environment = { PYTHON_GIL = "0" }
+
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "large: marks tests requiring /mnt/disk1/data (alab/island/caldera)",
+    "usd_assets: marks tests requiring USD assets corpus",
+    "aousd: marks tests requiring AOUSD supplemental",
+]

lightusd-1.0.0rc4/python/README.md

@@ -0,0 +1,71 @@
+# lightusd
+
+Lightweight, dependency-free **USD** (Universal Scene Description) library for
+Python: load and author USDA / USDC / USDZ, resolve composition, and extract
+GPU-ready render data — with **zero-copy NumPy interop**.
+
+Built on the LightUSD *next* core + *tydra-next* (no pxrUSD install required,
+no legacy core in the wheel; native `cmake -S .` and WASM still
+provide the legacy path via `web/binding.cc`). **v1.0.0**, npm `preview`
+dist-tag. Wheels:
+
+- `cp310-abi3` — one stable-ABI wheel covers CPython **3.10+**
+- `cp314t` — native **free-threaded** (GIL-less) CPython 3.14 wheel
+
+```bash
+pip install lightusd
+```
+
+## Reading
+
+```python
+import numpy as np
+import lightusd
+
+stage = lightusd.load("scene.usdz")          # usda / usdc / usdz, composed
+for prim in stage:                            # depth-first traversal
+    print(prim.path, prim.type_name)
+
+mesh = stage.prim_at("/World/Mesh")
+points = np.asarray(mesh["points"])           # zero-copy (N, 3) float32
+attr = mesh.attribute("xformOp:translate")
+if attr.has_timesamples:
+    value = attr.get(time=12.0)               # linear interpolation
+print(mesh.relationship("material:binding").targets)
+```
+
+## Authoring
+
+```python
+st = lightusd.Stage.create()
+st.up_axis = "Y"
+grid = st.define_prim("/World/Grid", "Mesh")
+grid.set("points", np.zeros((64, 3), np.float32), type="point3f[]")
+grid.set("purpose", "render", uniform=True)
+grid.set("xformOp:translate", (0.0, 1.0, 0.0), time=0.0)
+st.set_default_prim("World")
+st.save("out.usdc")                           # or .usda / .usdz
+```
+
+## Render extraction (tydra)
+
+```python
+from lightusd import tydra
+
+scene = tydra.to_render_scene(stage)          # triangulated, GPU-friendly
+for mesh in scene.meshes:
+    vertices = np.asarray(mesh.points)                # (N, 3) float32
+    indices = np.asarray(mesh.triangulated_indices)   # (T,) uint32
+    material = scene.materials[mesh.material_id]
+    base_color = material.param("diffuse_color")      # tuple or RenderTexture
+```
+
+## Notes
+
+- NumPy is optional (interop only, not a dependency).
+- `lightusd.flatten_file(src, dst)` runs a low-memory compose+flatten
+  pipeline that streams large arrays through without decoding them.
+- Free-threaded CPython: concurrent reads of one `Stage` are safe; do not
+  author to a stage while other threads read it.
+
+Apache 2.0. Part of [LightUSD](https://github.com/lighttransport/LightUSD).