lightusd 1.0.0__tar.gz

lightusd-1.0.0/.gitattributes

@@ -0,0 +1,5 @@
+# Unified diffs preserve whitespace in upstream context lines.
+tests/verification/repros/*.patch -whitespace
+
+# Radiance HDR must not undergo CRLF conversion on Windows checkouts.
+*.hdr binary

lightusd-1.0.0/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.0/LICENSE.3rdparty

@@ -0,0 +1,82 @@
+# 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` |
+| string_id | zlib | `src/external/string_id/LICENSE` |
+| ghc/filesystem | MIT | `src/external/filesystem/LICENSE` |
+| 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` |
+| tinyobjloader C11 loader and tessellator | MIT | `src/external/tinyobjloader-c/LICENSE` |
+| 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` |
+| nanozlib | Apache 2.0 | `src/external/nanozlib.h` |
+| 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.0/MANIFEST.in

@@ -0,0 +1,127 @@
+# 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/core/mtlx-dom.cc src/core/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/core
+prune src/tsd
+prune src/osd
+prune src/tydra/mcp
+prune tools
+prune subprojects
+prune @draft
+exclude resume-*.md
+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 *.inl *.txt
+include src/core/color-transform.cc src/core/logger.cc src/core/minijson.cc
+include src/mtlx-xml-tokenizer.cc src/mtlx-xml-parser.cc src/core/mtlx-dom.cc
+include src/ptx-loader.cc
+recursive-include src/external/textools/ptex/src *.c
+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
+# Configure-time inputs: src/next and tydra-next CMake define these targets
+# even though the wheel only builds the four library targets, so every source
+# they list must exist in the sdist (a missing file fails `cmake -S`).
+include src/core/host-services.cc src/image-loader.cc src/image-writer.cc src/io-util.cc src/usdVol.cc
+include tests/next/lusdcat.cc
+recursive-include src/external/tinyvdb *.c *.h
+recursive-include src/external/mimalloc *.c *.h
+recursive-include tools/lusdpreview *.cc *.hh *.h
+recursive-include cmake *.cmake
+
+# 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
+
+# Native scene imports used by the Python wheel (including all parser includes).
+recursive-include src/tydra/asset-import *.cc *.hh
+recursive-include src/external/tinyobjloader-c *.c *.h *.inc *.txt LICENSE
+include src/external/pugixml.cpp
+include src/unicode-xid-c.c
+include src/external/zmij/zmij.cc
+recursive-include cmake *.cmake *.in
+recursive-include src/next *.cmake

lightusd-1.0.0/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: lightusd
+Version: 1.0.0
+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.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.11
+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:
+
+- `cp311-abi3` — one stable-ABI wheel covers CPython **3.11+**
+- `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)
+```
+
+Large USDC crates (district/full-LOD scenes) can exceed the secure default
+structural-table caps before the memory budget is reached. Raise them
+explicitly for trusted data with `max_crate_elements`:
+
+```python
+stage = lightusd.load("district.usdc", max_memory=4 << 30,
+                      max_crate_elements=100_000_000)
+```
+
+Zero (the default) keeps the secure library limits; the memory budget still
+bounds actual allocations.
+
+## 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
+```
+
+## Asset resolution
+
+```python
+from lightusd import AssetResolver
+
+resolver = AssetResolver()
+path, exists, is_package = resolver.resolve_new("sub/new.usda", "/proj/look/layer.usda")
+
+with resolver.bind_context("/proj/assets"):
+    path, exists, is_package = resolver.resolve("tex.png")
+
+with resolver.cache_scope():
+    resolver.resolve("tex.png")                # memoized for the scope
+
+resolver.register_package(".pkg", lambda package, entry: f"virtual:{package}|{entry}")
+path, exists, is_package = resolver.resolve("bundle.pkg[dir/entry.usda]")
+
+resolver.register_scheme(
+    "studio",
+    lambda identifier, anchor, scheme_context: identifier,
+    lambda identifier: b"#usda 1.0\n",
+)
+assert resolver.read("studio:layer.usda").startswith(b"#usda")
+
+resolver.register_memory("usd-anon:generated.usda", b"#usda 1.0\n")
+data = resolver.read("usd-anon:generated.usda")
+info = resolver.asset_info("usd-anon:generated.usda")   # name/repository/exists
+stamp = resolver.modification_timestamp("tex.png")      # (seconds, ns) or None
+key = resolver.create_identifier("future.usda", "/proj/look/layer.usda")
+report, ok = resolver.dependency_report("usd-anon:generated.usda")
+count, bytes_used, peak = resolver.memory_stats
+
+with resolver.bind_context("/proj/assets", scheme_contexts={"https": "/cache"}):
+    path, exists, is_package = resolver.resolve("https://example.com/tex.png")
+
+stage = lightusd.load("root.usda", resolver=resolver)
+```
+
+Resolver and package callbacks are retained until replaced, unregistered, or
+the resolver is destroyed. Composition may invoke them from worker threads;
+exceptions raised by callbacks are re-raised by `resolve`, `read`, or `load`.
+
+## Notes
+
+- Arrays implement Python's read-only buffer protocol. Use `memoryview(array)`
+  or `np.asarray(array)`; `Array.memoryview()` and `__array_interface__` have
+  been removed. A view retains its C11 storage after attribute replacement,
+  stage closure, or render-scene deletion. Later writes detach shared storage.
+- Numeric authoring accepts sequences and typed buffers, including strided and
+  big-endian buffers. Shared native descriptors validate and convert components;
+  integer overflow rejects the write without changing the attribute.
+- 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.
+- Source builds can set `LIGHTUSD_PY_ENABLE_THREAD=0` to omit optional
+  parser/composition/render worker threads while retaining API-level
+  synchronization and free-threaded-CPython safety.
+
+Apache 2.0. Part of [LightUSD](https://github.com/lighttransport/LightUSD).
+
+
+### Native OBJ, URDF and MuJoCo imports
+
+`lightusd.load(path)` also accepts `.obj`, `.urdf`, `.mjcf` and robot/MuJoCo
+`.xml` files. XML is identified by its root element. These imports run inside
+the native extension; Node, MuJoCo and Newton are not required.
+
+```python
+import lightusd
+from lightusd import physics, tydra
+
+stage = lightusd.import_urdf("robot.urdf", packages={"robot_assets": "assets"})
+# Equivalent automatic dispatch: lightusd.load("robot.urdf")
+for joint in physics.inspect(stage).joints:
+    print(joint.prim_path, joint.attributes, joint.relationships)
+
+actuator = physics.define_prim(
+    stage, "/World/Drive", "NewtonActuator",
+    api_schemas=["NewtonPDControlAPI"],
+    attributes={"newton:kp": 100.0, "newton:kd": 5.0},
+    relationships={"newton:targets": ["/World/Joints/hinge"]},
+)
+physics.apply_schema(actuator, "NewtonMaxEffortClampingAPI",
+                     attributes={"newton:maxEffort": 10.0})
+print(tydra.to_render_scene(stage).physics["joints"])
+stage.save_usdz("robot.usdz")  # includes imported textures
+```
+
+`import_obj`, `import_urdf` and `import_mjcf` return ordinary editable `Stage`
+objects. Import options are `up_axis="Z"`, `asset_dirs=()`, `packages=None`,
+`allow_missing=False`, `tessellate_collision_shapes=False`, `max_memory=0`,
+and `resolver=None`. Positive `max_memory` bounds input and aggregate import
+estimates; zero selects finite defaults. Dependencies resolve relative to the
+file that declares them. Supply asset directories or package mappings for
+external asset roots. Resolver callbacks also work for memory-backed inputs.
+
+For bytes, pass an explicit import format and a source anchor when needed:
+`lightusd.load_bytes(data, format="mjcf", source="scene.xml", resolver=resolver)`.
+`loads()` remains a USDA-text parser, and `is_usd()` remains USD-specific.
+
+OBJ imports preserve polygon meshes, normals, smoothing groups, UVs, object/group
+names and MTL material assignments. Common MTL colors, PBR scalars and texture
+maps become USD PreviewSurface networks. Missing MTL/textures warn; missing
+meshes/includes fail unless `allow_missing=True`. Bump-to-normal conversion,
+free-form OBJ surfaces and unsupported MTL shading features are not synthesized.
+Loose USD exports refer to source textures; USDZ exports retain and package them.
+Repeated maps and aliases resolving to the same texture share retained bytes
+within an import and one USDZ entry. A stage can still save those bytes after
+its resolver is unregistered. USDZ path rewriting leaves the source stage intact.
+
+`stage.import_report()` returns native conversion counts, coded diagnostics,
+dependency reads, timing and memory estimates without draining warnings.
+Failed-import exceptions expose `error.import_report`. Native imports also
+accept independent `max_input` (bytes), `max_depth` and
+`unsupported_policy="warn"|"error"|"preserve"` options. Preservation retains
+known unsupported source records as non-executable USD layer metadata.
+See [import reports and policies](../doc/import-report.md) for scope and limits.
+
+`physics.inspect(stage, array_views=True)` uses the shared native physics query
+and retains read-only numeric buffers for large state arrays. Snapshots include
+property types, variability, blocks and collision groups and survive stage
+closure. See [typed physics snapshots](../doc/physics-query.md).
+
+`physics.validate(stage, samples=True)` returns an immutable native validation
+report with rule IDs, locations, sample times and coverage. Findings do not
+raise exceptions; inspect `report.valid` and `report.complete`. Diagnostic
+limits report omissions and prevent a truncated result from passing. See
+[physics validation](../doc/physics-validation.md) for coverage and C/C++ APIs.
+OBJ layers also work in references, payloads and sublayers. Direct imports emit
+linear BasisCurves for `l` and Points for `p`. The zero-based `vw` extension
+becomes vertex SkelBindingAPI primvars, preserving every signed influence without
+normalizing; the containing USD supplies the skeleton and joint order. See
+[OBJ mapping and skin binding](../doc/usdobj.md) for details.
+
+Physics inspection snapshots authored values, arrays and relationship targets,
+including `mjc:*` and `newton:*`; it does not run a simulator. Authoring helpers
+use canonical USD property names, stage length units, degrees for joint angles,
+and real-first quaternions. For a property without a built-in type, pass
+`attributes={"mjc:custom:example": ("double[]", [1.0, 2.0])}`.
+`RenderScene.physics` exposes the existing C annotation records and textual
+extension summaries; use `physics.inspect(stage)` for complete typed engine data.
+
+MJCF flex/deformables and unsupported equality types remain unsupported;
+tendon surface wrapping remains approximate. Import warnings are available
+through `stage.warnings()`.
+
+## Performance and memory
+
+- `lightusd.load` runs the same next core as the CLI; the binding does not add
+  a second copy of geometry. Numeric attributes are zero-copy buffer views, and
+  `Stage.flattened()` is the one call that deliberately builds a second stage.
+- Live memory is released on `Stage.close()`. RSS may stay high afterwards
+  because glibc retains freed composition arenas; `malloc_trim` (or process
+  exit) reclaims them.
+- For large scenes, preload jemalloc — the allocator the native CLI links:
+
+  ```sh
+  LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2 python your_app.py
+  ```
+
+  On the 10 GB Caldera scene an eager load drops from 1.63 s / 17.3 s CPU to
+  1.14 s / 10.9 s CPU at the same ~1.9 GiB peak. Do not link an allocator into
+  the wheel; the choice belongs to the process embedding the extension.
+- Measurements, A/B method and binding-vs-CLI parity:
+  [large-scene profile §2.6.9](../doc/large-scene.md#269-python-binding-abi3-loadcompose-profile-2026-10).
+
+For diagnostics, `attribute.resolve(time=None)` performs a USD DefaultTime query;
+`resolve(time=2.5)` evaluates numeric samples and clips, including schema
+fallbacks. Connections are followed only with `follow_connections=True`.
+`has_authored_default` and `is_default_blocked` distinguish a composed authored
+value, a value block, and an absent default. Keep these states separate from the
+resolved value: physics schemas use sentinel defaults such as zero mass to
+request automatic computation. `get()` retains its existing compatibility
+behavior, including its earliest-sample fallback when no default exists.
+
+
+`load(path, preserve_native_instances=True)` retains shared native prototypes
+for traversal and diagnostics. Instance descendants keep their logical paths,
+parent navigation and evaluated attributes. The default remains the self-contained
+holder representation for export/save round trips; native prototype metadata is
+an in-memory representation and does not provide a self-contained USDA export.
+
+A valid leaf `Prim` is truthy even when `len(prim) == 0`. Boolean conversion,
+like other prim operations, self-heals surviving logical handles and raises
+`StaleHandleError` for a removed prim. Test `prim is None` when distinguishing
+an absent optional lookup from a present handle.
+
+`stage.traverse()` visits active, loaded, defined, nonabstract prims, including
+native instance proxies. `stage.traverse(all_prims=True)` and `iter(stage)` also
+include undefined overs, class prims and inactive subtrees.
+
+`load`, `load_bytes` and `flatten_file` accept `max_array_elements` independently
+of the byte budget. Zero retains the finite default (16 million elements).
+Large trusted datasets can explicitly raise this count; for example,
+`load(path, max_memory=30 * 1024**3, max_array_elements=64 * 1024**2)`.
+Failed referenced asset loads, including resource-limit failures, fail the
+default untrusted composed load instead of returning incomplete geometry.
+
+File-backed clip evaluation retains the file load's explicit byte/array limits
+and absolute source directory. Changing the working directory after loading a
+basename does not change its clip anchor. Evaluation errors such as a rejected
+clip load raise an exception; a genuinely unauthored or blocked value still
+resolves to `None`. Custom resolver handles remain borrowed during the load call;
+retaining their callbacks for later clip evaluation is not supported by this API.
+
+`load`, `load_bytes`, and `flatten_file` accept `max_threads=0` for bounded
+automatic workers, `1` for serial parsing/composition, or a positive fixed
+worker hint. Negative, noninteger and overflowing values are rejected.
+`input_policy="untrusted"` remains the default. Explicit `"trusted"` selects
+the existing C API compatibility policy, including file-backed crate mmap and
+relaxed missing-dependency behavior. Use that profile only for known immutable
+inputs; it is a distinct policy, not a change to secure defaults. Performance
+reports must record the policy and verify matching complete scene work.

lightusd-1.0.0/README.md

@@ -0,0 +1,85 @@
+# LightUSD
+
+LightUSD is a full-featured, dependency-free, lightweight USD library written
+in C++17. It reads and writes USDA, USDC, and USDZ, and includes MaterialX and USD Physics support.
+(Previously known as TinyUSDZ)
+
+The `src/next` product is the default for native, Python, and WASM consumers.
+The legacy product is deprecated, but remains in the repository and in CI for
+existing integrations. Select it explicitly with
+`-DLIGHTUSD_NATIVE_PRODUCT=legacy` or `-DLIGHTUSD_WASM_PRODUCT=legacy`.
+
+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. MCP interface provided.
+
+[![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)
+[![PyPI version](https://img.shields.io/pypi/v/lightusd.svg)](https://pypi.org/project/lightusd/)
+[![npm version](https://img.shields.io/npm/v/lightusd.svg)](https://www.npmjs.com/package/lightusd)
+
+## Releases
+
+* v1.0.0 (26.11)
+  * First stable release.
+  * Add Lean formalization of the USD (AOUSD Core) spec: https://usdspec-conformance.lighttransport.workers.dev/
+
+## 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)
+- [AOUSD conformance](aousd/verif.md) — LightUSD verification against the AOUSD Core Specification v1.1.0 (v1.0.1 plan + v1.1 delta audit)
+- [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.0/cmake/ClangClCMakeCompileRules.cmake

@@ -0,0 +1,9 @@
+# macOS paths usually start with /Users/*. Unfortunately, clang-cl interprets
+# paths starting with /U as macro undefines, so we need to put a -- before the
+# input file path to force it to be treated as a path. CMake's compilation rules
+# should be tweaked accordingly, but until that's done, and to support older
+# CMake versions, overriding compilation rules works well enough. This file will
+# be included by cmake after the default compilation rules have already been set
+# up, so we can just modify them instead of duplicating them entirely.
+string(REPLACE "-c <SOURCE>" "-c -- <SOURCE>" CMAKE_C_COMPILE_OBJECT "${CMAKE_C_COMPILE_OBJECT}")
+string(REPLACE "-c <SOURCE>" "-c -- <SOURCE>" CMAKE_CXX_COMPILE_OBJECT "${CMAKE_CXX_COMPILE_OBJECT}")

lightusd-1.0.0/cmake/LightUSDConfig.cmake.in

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+@PACKAGE_INIT@
+include(CMakeFindDependencyMacro)
+if(@LIGHTUSD_NEXT_ENABLE_THREAD@)
+  find_dependency(Threads)
+endif()
+include("${CMAKE_CURRENT_LIST_DIR}/LightUSDTargets.cmake")
+check_required_components(LightUSD)