xuvdb 0.1.0__tar.gz

xuvdb-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 xuvdb contributors
+
+   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.

xuvdb-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: xuvdb
+Version: 0.1.0
+Summary: Editable sparse voxel volumes with OpenVDB interop, built on quadrants kernels
+License-Expression: Apache-2.0
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: quadrants
+Provides-Extra: genesis
+Requires-Dist: genesis-world; extra == "genesis"
+Provides-Extra: openvdb
+Requires-Dist: pyopenvdb; extra == "openvdb"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# XUVDB 太虚 — genesis 自研稀疏体素格式（可编辑 · 与 OpenVDB 互转）
+
+> 「不游乎太虚。」——《庄子·知北游》
+> 「太虚无形，气之本体。」——张载《正蒙·太和》
+
+`xuvdb` 取「太虚」之音：这是中文里对 VDB「无界而稀疏的索引域」最准确的翻译——无界
+（root 哈希域不设上限），无形（未分配的空间没有形态，采样即得背景值）。
+
+`xuvdb` 基于 quadrants 内核：**自己的 `.xuvdb` 格式**（可修改、可在内核里写值），
+以及**与 OpenVDB 的双向互转**（原生 `.vdb` 文件读写，无需安装 OpenVDB；有 `pyopenvdb`
+绑定时还能内存级互转）。
+
+## 命名规范（三层名字，各归其位）
+
+| 层 | 名字 | 规则 |
+|---|---|---|
+| 项目名 | `xuvdb` | 拼音；不用 Open 前缀（ASWF 语境下暗示基金会血统） |
+| 命名空间 / 扩展名 | `xuvdb` / `.xuvdb` | API 标识符一律英文：`xuvdb.prune()`、`xuvdb.VdbGrid`，绝不是 `xuvdb.sunyi()`。道家词只活在概念层（文档题词、日志、可视化标签） |
+| 互转文件 | `.vdb` | **自有格式绝不写 `.vdb` 后缀**（Houdini／Blender／Cycles／Arnold 按扩展名当 OpenVDB 解析，格式不符时静默出错或崩溃，极难定位；`save()` 对 `.vdb` 路径直接拒绝）。要互通就单独导出：`write_vdb()` 产出真正的 OpenVDB 流 |
+
+## 为什么是它
+
+|  | OpenVDB | NanoVDB | XUVDB |
+|---|---|---|---|
+| 结构 | 5 层 B+树，CPU C++ | 同构只读缓冲，GPU | 两级：dict 叶根 + 稠密叶块 |
+| 可修改 | ✅（CPU） | ❌ GPU 只读 | ✅ Python 端任意结构编辑；**内核端可写值** |
+| 可微分包差 | ❌ | ❌ | 值缓冲可被 quadrants 内核读写（拓扑固定） |
+| Python 依赖 | pyopenvdb（需自行构建） | — | 仅 numpy + quadrants |
+
+定位不是替换任何求解器，而是补齐 README 物理栈背后的**空间表示层**（落点见下文）。
+
+## 安装
+
+独立 Python 包（src 布局，`import xuvdb` 即用）：
+
+```bash
+uv pip install .            # 或 pip install .
+uv pip install -e ".[test]" # 开发模式 + pytest
+```
+
+可选 extras：`[openvdb]`（pyopenvdb 内存级互转）、`[genesis]`（运行引擎侧示例需要 genesis-world）、
+`[test]`（pytest）。
+
+## 快速上手
+
+```python
+import numpy as np
+import xuvdb
+
+# 1) 编辑：窄带 level set 球（体素 0.05，带宽 3 体素）
+grid = xuvdb.VdbGrid(background=3 * 0.05, voxel_size=0.05, leaf_log2=4,
+                     name="shield", grid_class="level set")
+grid.stamp_sphere((0.3, 0.2, 0.1), radius=0.25, band=3.0)
+grid.stamp_sphere((0.5, 0.2, 0.1), radius=0.10)          # CSG：并入第二个球
+grid.fill_box((-2, -2, -2), (2, 2, 2), value=0.0)         # 任意稠密填充（示例）
+grid.prune()
+
+# 2) 自有格式落盘 / 读回（多网格、f32/f64/vec3）
+xuvdb.save("scene.xuvdb", [grid])
+grids = xuvdb.load("scene.xuvdb")
+
+# 3) 与 OpenVDB 互通（显式导出：真正的 OpenVDB 流，Houdini/Blender 直接打开）
+xuvdb.write_vdb("scene.vdb", [grid])
+back = xuvdb.read_vdb("scene.vdb", grid_name="shield")
+
+# 4) 内核采样 / 写值（等同 Warp example_nvdb 的用法，但值可写）
+vol = xuvdb.GpuVolume(grid)
+pts = np.array([[0.3, 0.2, 0.36]], dtype=np.float32)
+d = vol.sample(pts, linear=True)          # SDF 距离
+n = vol.sdf_normal(pts)                   # 有限差分表面法向
+vol.write_voxels(pts, np.array([-0.01], np.float32)); vol.sync_to_host()
+
+# 5) 粒子 ⇄ 体积（液体/油，见落点④）
+drops = np.array([[0.1, 0.0, 0.0], [0.2, 0.0, 0.0]])
+fog = xuvdb.VdbGrid(voxel_size=0.05, name="liquid", grid_class="fog volume")
+fog.scatter_particles(drops, h=4 * 0.05, weights=1.0)     # SPH cubic 核密度 splat
+surf = xuvdb.VdbGrid(background=3 * 0.05, voxel_size=0.05, grid_class="level set")
+surf.union_spheres(drops, radius=0.03)                    # particle level set 表面代理
+
+# 6) DDA 射线（空叶块按块跳过，交叉点二分细化到亚体素）
+t, point, value = xuvdb.ray_surface_hit(grid, (0.3, 0.2, 2.0), (0, 0, -1))
+```
+
+与引擎稠密场的桥：
+
+```python
+# 稠密 qd.field / numpy SDF（如 rigid geom 的 sdf_val）→ 稀疏
+sparse = xuvdb.VdbGrid.from_dense(dense_sdf, origin=ijk_min, voxel_size=h,
+                                  background=band_h, grid_class="level set")
+dense, ijk_min = sparse.to_dense()        # 反向：渲染器 / 求解器输入
+```
+
+## 格式
+
+### `.xuvdb`（自有格式，小端）
+
+```
+"XUVDB" | u8 version=1 | u8 flags | u16 n_grids
+per grid:
+  str name | u8 type(0=f32,1=f64,2=vec3f) | u8 leaf_log2 | u8 class | u8 rsv
+  f64[3] voxel_size | f64[3] origin_world | background
+  u32 n_leaves
+  per leaf（按叶原点排序）: i32[3] origin | u64[dim³/64] active mask | 值稠密数组
+```
+
+- 叶内线性序 `n = x·dim² + y·dim + z`（z 最快），**与 OpenVDB leaf 序一致**，互转零转置。
+- 叶块与 OpenVDB LeafNode 同为稠密缓冲：level set 内部体素的 `-background` 值在
+  save/load 后保留。
+- 变换约定与 OpenVDB 线性映射一致：`world = index · voxel_size + origin_world`，
+  体素中心在整数索引处。
+
+### `.vdb`（OpenVDB 官方流格式，仅显式导出用）
+
+字节布局逐一对照 OpenVDB 源码实现（`io/Archive.cc`、`GridDescriptor.cc`、`Compression.h`、
+`tree/*.h`、`math/Maps.h`、`Metadata.h`）：
+
+- 头 57B：`int64 magic 0x56444220`、u32 文件版本、u32 库主/次版本、u8 offsets 标志、36 字符 UUID；
+- 文件级元数据表 → i32 网格数 → **描述符与网格流交错**（描述符、i64×3 偏移、网格流、下一描述符…）；
+- 网格流：u32 压缩标志 → 元数据表（name/class/file_* 统计）→ 变换（ScaleTranslate 家族
+  = 类型字符串 + 6×Vec3d）→ 树（`i32 buffer_count`、root 背景 + tiles + 子节点）；
+- 树：root → InternalNode(5)（32³ 桌、512×u64 双掩码、值表）→ InternalNode(4)（64 项）→
+  LeafNode(8³)（拓扑段只有值掩码，origin 由树路径隐含；缓冲段掩码重写一遍 + 值块）；
+- 值块：`io::writeCompressedValues` 语义 —— 1 字节 metadata（0=惰性值全为 +bg、1=-bg、
+  2/4/5=带 1~2 个惰性值/选择掩码、6=全量数组）+ 值（按 ACTIVE_MASK 只存 active）。
+
+写侧：文件版本 224、压缩 = `COMPRESS_ACTIVE_MASK`（无 zip/blosc），任何 OpenVDB ≥ 9 可读。
+读侧：支持 `COMPRESS_NONE` / `COMPRESS_ZIP`（stdlib zlib）/ `COMPRESS_ACTIVE_MASK` /
+`_HalfFloat` 网格；Blosc 抛出明确错误；root/internode 活动 tile 物化为稠密叶
+（受 `max_tile_voxels` 上限保护）。
+
+## 已知边界
+
+- `GpuVolume` 只支持 f32 标量网格；写入只改值不改拓扑、不动 active 掩码（掩码是宿主侧
+  状态）。结构性编辑后需重新打包。
+- `scatter_particles`／`union_spheres` 是 Python 循环 + 叶切片向量化：千级粒子适用，
+  大规模生产需按叶批处理（未做）。`union_spheres` 的 min-of-spheres 距离在重叠粒子间
+  的凹桥区是真实距离的上界（Lipschitz 精确），做碰撞/渲染代理足够，精确表面请离线
+  用正规表面重建精修。
+- `.vdb` 读侧不支持：Blosc 压缩、实例化网格（instance parent）、点云网格（PointDataGrid）、
+  `5_4_3` 以外的树形。写侧不产生 root tile（全部以叶表达）。
+- 与求解器自动微分的边界：XUVDB 提供的是**采样/写入原语**；把 VDB 值直接接入反传图需要
+  包一层自定义求导规则（这正是 FastSweeping 等算子不可微的同一边界）。
+
+## 与引擎四个落点的对接
+
+对应《Genesis × OpenVDB 重合度报告》（`genesis_openvdb_overlap.html`）的结论：
+
+1. **刚性 SDF（`utils/sdf.py`，风险最低）**：`geom.sdf_val` 稠密体 → `VdbGrid.from_dense`
+   窄带化 → `GpuVolume.sample/sdf_normal` 做内核内碰撞采样；粗块最小值下界的带宽门控
+   对应这里"空叶块直接跳过"——稀疏性免费获得。维护/雕刻工装（`csg` + `stamp_sphere`）
+   可离线改碰撞体。
+2. **MPM 背景网格（解除 1e9 上限）**：`use_sparse_grid` 被移除的原因在 GPU 端动态拓扑；
+   XUVDB 的分工是"拓扑宿主端冻结 + 值内核端可写"。粒子覆盖块用 `fill_box` 声明、每步
+   `write_voxels` 回写网格值，是向稀疏 MPM 过渡的最小代价路径（需自行验证与现有
+   dense reset 的性能对比）。
+3. **烟尘 / 稳定流体（收益上限最高）**：压力投影每帧回写全网格，短期不建议动求解器；
+   现实路径是**出口侧**：每 N 步 `from_dense(density_field)` → `write_vdb` 交给
+   Houdini/Blender 体渲染；进口侧用 Houdini 烘的 `.vdb` 作初始条件（`read_vdb` →
+   `to_dense`）。
+4. **液体与油（SPH，粒子 ⇄ 体积）**：Genesis 的液体是 Lagrangian SPH（hash grid 邻域，
+   VDB 不做邻居搜索），与稀疏体积的接口在两端——
+   - **出口（每步/每 N 步）**：`scatter_particles(pos, h, mass)` 把粒子 splat 成密度
+     fog 网格（SPH cubic 核、单位积分，质量守恒已测）→ `write_vdb` 给 Houdini/Blender
+     体渲染液体，比逐粒子渲染便宜得多；要表面就 `union_spheres(pos, r, band)` 出
+     particle level set 表面代理（喷雾/液滴场景），离线可用 OpenVDB 生态精修。
+   - **进口**：Houdini 烘的液面/容器 `.vdb` level set → `read_vdb` → `GpuVolume.sample`
+     做容器碰撞 SDF 或装液初始条件（与落点①同一套采样机制，SPH 边界碰撞即刚体 SDF
+     碰撞的复用）。
+   - **油（高黏/两相）**：黏性在 SPH 求解器侧，体积层只管表征——两相液体（油-水、
+     油-气）每相一个 fog 网格，即混合分数场 α：`scatter_particles` 按相内粒子各 splat
+     一份，导出双网格 `.vdb`，渲染端做 α 混合；界面 SDF 用两相 `union_spheres` 之差
+     （`csg 'diff'`）。
+   - **在线更新**：`GpuVolume.write_voxels` 可增量回写密度值做实时可视化；拓扑（叶
+     集合）按粒子包围盒周期性重打包（拓扑宿主端冻结的同一分工）。
+
+## 许可证
+
+Apache-2.0（与上游 quadrants、genesis-world 一致），见 [LICENSE](LICENSE)。
+
+## 测试
+
+```
+pytest tests/ -q
+```
+
+覆盖：树编辑/CSG/稠密互转、粒子 splat（质量守恒、可加性、vec3 速度场、双核函数）、
+`union_spheres`（表面/窄带/逐粒子半径/射线命中/与 stamp 复合）、`.xuvdb` 多网格多类型
+往返、`.vdb` 头部字节与偏移校验、f32/f64/vec3/fog/level-set 往返、多叶尺寸重分块、
+负坐标、惰性值压缩路径、`save()` 拒绝 `.vdb` 后缀、GPU 采样对齐宿主三线性、内核写值
+往返、DDA 射线（含空块跳跃、内部出发、tmax 截断、变换偏移）。

xuvdb-0.1.0/README.md

@@ -0,0 +1,190 @@
+# XUVDB 太虚 — genesis 自研稀疏体素格式（可编辑 · 与 OpenVDB 互转）
+
+> 「不游乎太虚。」——《庄子·知北游》
+> 「太虚无形，气之本体。」——张载《正蒙·太和》
+
+`xuvdb` 取「太虚」之音：这是中文里对 VDB「无界而稀疏的索引域」最准确的翻译——无界
+（root 哈希域不设上限），无形（未分配的空间没有形态，采样即得背景值）。
+
+`xuvdb` 基于 quadrants 内核：**自己的 `.xuvdb` 格式**（可修改、可在内核里写值），
+以及**与 OpenVDB 的双向互转**（原生 `.vdb` 文件读写，无需安装 OpenVDB；有 `pyopenvdb`
+绑定时还能内存级互转）。
+
+## 命名规范（三层名字，各归其位）
+
+| 层 | 名字 | 规则 |
+|---|---|---|
+| 项目名 | `xuvdb` | 拼音；不用 Open 前缀（ASWF 语境下暗示基金会血统） |
+| 命名空间 / 扩展名 | `xuvdb` / `.xuvdb` | API 标识符一律英文：`xuvdb.prune()`、`xuvdb.VdbGrid`，绝不是 `xuvdb.sunyi()`。道家词只活在概念层（文档题词、日志、可视化标签） |
+| 互转文件 | `.vdb` | **自有格式绝不写 `.vdb` 后缀**（Houdini／Blender／Cycles／Arnold 按扩展名当 OpenVDB 解析，格式不符时静默出错或崩溃，极难定位；`save()` 对 `.vdb` 路径直接拒绝）。要互通就单独导出：`write_vdb()` 产出真正的 OpenVDB 流 |
+
+## 为什么是它
+
+|  | OpenVDB | NanoVDB | XUVDB |
+|---|---|---|---|
+| 结构 | 5 层 B+树，CPU C++ | 同构只读缓冲，GPU | 两级：dict 叶根 + 稠密叶块 |
+| 可修改 | ✅（CPU） | ❌ GPU 只读 | ✅ Python 端任意结构编辑；**内核端可写值** |
+| 可微分包差 | ❌ | ❌ | 值缓冲可被 quadrants 内核读写（拓扑固定） |
+| Python 依赖 | pyopenvdb（需自行构建） | — | 仅 numpy + quadrants |
+
+定位不是替换任何求解器，而是补齐 README 物理栈背后的**空间表示层**（落点见下文）。
+
+## 安装
+
+独立 Python 包（src 布局，`import xuvdb` 即用）：
+
+```bash
+uv pip install .            # 或 pip install .
+uv pip install -e ".[test]" # 开发模式 + pytest
+```
+
+可选 extras：`[openvdb]`（pyopenvdb 内存级互转）、`[genesis]`（运行引擎侧示例需要 genesis-world）、
+`[test]`（pytest）。
+
+## 快速上手
+
+```python
+import numpy as np
+import xuvdb
+
+# 1) 编辑：窄带 level set 球（体素 0.05，带宽 3 体素）
+grid = xuvdb.VdbGrid(background=3 * 0.05, voxel_size=0.05, leaf_log2=4,
+                     name="shield", grid_class="level set")
+grid.stamp_sphere((0.3, 0.2, 0.1), radius=0.25, band=3.0)
+grid.stamp_sphere((0.5, 0.2, 0.1), radius=0.10)          # CSG：并入第二个球
+grid.fill_box((-2, -2, -2), (2, 2, 2), value=0.0)         # 任意稠密填充（示例）
+grid.prune()
+
+# 2) 自有格式落盘 / 读回（多网格、f32/f64/vec3）
+xuvdb.save("scene.xuvdb", [grid])
+grids = xuvdb.load("scene.xuvdb")
+
+# 3) 与 OpenVDB 互通（显式导出：真正的 OpenVDB 流，Houdini/Blender 直接打开）
+xuvdb.write_vdb("scene.vdb", [grid])
+back = xuvdb.read_vdb("scene.vdb", grid_name="shield")
+
+# 4) 内核采样 / 写值（等同 Warp example_nvdb 的用法，但值可写）
+vol = xuvdb.GpuVolume(grid)
+pts = np.array([[0.3, 0.2, 0.36]], dtype=np.float32)
+d = vol.sample(pts, linear=True)          # SDF 距离
+n = vol.sdf_normal(pts)                   # 有限差分表面法向
+vol.write_voxels(pts, np.array([-0.01], np.float32)); vol.sync_to_host()
+
+# 5) 粒子 ⇄ 体积（液体/油，见落点④）
+drops = np.array([[0.1, 0.0, 0.0], [0.2, 0.0, 0.0]])
+fog = xuvdb.VdbGrid(voxel_size=0.05, name="liquid", grid_class="fog volume")
+fog.scatter_particles(drops, h=4 * 0.05, weights=1.0)     # SPH cubic 核密度 splat
+surf = xuvdb.VdbGrid(background=3 * 0.05, voxel_size=0.05, grid_class="level set")
+surf.union_spheres(drops, radius=0.03)                    # particle level set 表面代理
+
+# 6) DDA 射线（空叶块按块跳过，交叉点二分细化到亚体素）
+t, point, value = xuvdb.ray_surface_hit(grid, (0.3, 0.2, 2.0), (0, 0, -1))
+```
+
+与引擎稠密场的桥：
+
+```python
+# 稠密 qd.field / numpy SDF（如 rigid geom 的 sdf_val）→ 稀疏
+sparse = xuvdb.VdbGrid.from_dense(dense_sdf, origin=ijk_min, voxel_size=h,
+                                  background=band_h, grid_class="level set")
+dense, ijk_min = sparse.to_dense()        # 反向：渲染器 / 求解器输入
+```
+
+## 格式
+
+### `.xuvdb`（自有格式，小端）
+
+```
+"XUVDB" | u8 version=1 | u8 flags | u16 n_grids
+per grid:
+  str name | u8 type(0=f32,1=f64,2=vec3f) | u8 leaf_log2 | u8 class | u8 rsv
+  f64[3] voxel_size | f64[3] origin_world | background
+  u32 n_leaves
+  per leaf（按叶原点排序）: i32[3] origin | u64[dim³/64] active mask | 值稠密数组
+```
+
+- 叶内线性序 `n = x·dim² + y·dim + z`（z 最快），**与 OpenVDB leaf 序一致**，互转零转置。
+- 叶块与 OpenVDB LeafNode 同为稠密缓冲：level set 内部体素的 `-background` 值在
+  save/load 后保留。
+- 变换约定与 OpenVDB 线性映射一致：`world = index · voxel_size + origin_world`，
+  体素中心在整数索引处。
+
+### `.vdb`（OpenVDB 官方流格式，仅显式导出用）
+
+字节布局逐一对照 OpenVDB 源码实现（`io/Archive.cc`、`GridDescriptor.cc`、`Compression.h`、
+`tree/*.h`、`math/Maps.h`、`Metadata.h`）：
+
+- 头 57B：`int64 magic 0x56444220`、u32 文件版本、u32 库主/次版本、u8 offsets 标志、36 字符 UUID；
+- 文件级元数据表 → i32 网格数 → **描述符与网格流交错**（描述符、i64×3 偏移、网格流、下一描述符…）；
+- 网格流：u32 压缩标志 → 元数据表（name/class/file_* 统计）→ 变换（ScaleTranslate 家族
+  = 类型字符串 + 6×Vec3d）→ 树（`i32 buffer_count`、root 背景 + tiles + 子节点）；
+- 树：root → InternalNode(5)（32³ 桌、512×u64 双掩码、值表）→ InternalNode(4)（64 项）→
+  LeafNode(8³)（拓扑段只有值掩码，origin 由树路径隐含；缓冲段掩码重写一遍 + 值块）；
+- 值块：`io::writeCompressedValues` 语义 —— 1 字节 metadata（0=惰性值全为 +bg、1=-bg、
+  2/4/5=带 1~2 个惰性值/选择掩码、6=全量数组）+ 值（按 ACTIVE_MASK 只存 active）。
+
+写侧：文件版本 224、压缩 = `COMPRESS_ACTIVE_MASK`（无 zip/blosc），任何 OpenVDB ≥ 9 可读。
+读侧：支持 `COMPRESS_NONE` / `COMPRESS_ZIP`（stdlib zlib）/ `COMPRESS_ACTIVE_MASK` /
+`_HalfFloat` 网格；Blosc 抛出明确错误；root/internode 活动 tile 物化为稠密叶
+（受 `max_tile_voxels` 上限保护）。
+
+## 已知边界
+
+- `GpuVolume` 只支持 f32 标量网格；写入只改值不改拓扑、不动 active 掩码（掩码是宿主侧
+  状态）。结构性编辑后需重新打包。
+- `scatter_particles`／`union_spheres` 是 Python 循环 + 叶切片向量化：千级粒子适用，
+  大规模生产需按叶批处理（未做）。`union_spheres` 的 min-of-spheres 距离在重叠粒子间
+  的凹桥区是真实距离的上界（Lipschitz 精确），做碰撞/渲染代理足够，精确表面请离线
+  用正规表面重建精修。
+- `.vdb` 读侧不支持：Blosc 压缩、实例化网格（instance parent）、点云网格（PointDataGrid）、
+  `5_4_3` 以外的树形。写侧不产生 root tile（全部以叶表达）。
+- 与求解器自动微分的边界：XUVDB 提供的是**采样/写入原语**；把 VDB 值直接接入反传图需要
+  包一层自定义求导规则（这正是 FastSweeping 等算子不可微的同一边界）。
+
+## 与引擎四个落点的对接
+
+对应《Genesis × OpenVDB 重合度报告》（`genesis_openvdb_overlap.html`）的结论：
+
+1. **刚性 SDF（`utils/sdf.py`，风险最低）**：`geom.sdf_val` 稠密体 → `VdbGrid.from_dense`
+   窄带化 → `GpuVolume.sample/sdf_normal` 做内核内碰撞采样；粗块最小值下界的带宽门控
+   对应这里"空叶块直接跳过"——稀疏性免费获得。维护/雕刻工装（`csg` + `stamp_sphere`）
+   可离线改碰撞体。
+2. **MPM 背景网格（解除 1e9 上限）**：`use_sparse_grid` 被移除的原因在 GPU 端动态拓扑；
+   XUVDB 的分工是"拓扑宿主端冻结 + 值内核端可写"。粒子覆盖块用 `fill_box` 声明、每步
+   `write_voxels` 回写网格值，是向稀疏 MPM 过渡的最小代价路径（需自行验证与现有
+   dense reset 的性能对比）。
+3. **烟尘 / 稳定流体（收益上限最高）**：压力投影每帧回写全网格，短期不建议动求解器；
+   现实路径是**出口侧**：每 N 步 `from_dense(density_field)` → `write_vdb` 交给
+   Houdini/Blender 体渲染；进口侧用 Houdini 烘的 `.vdb` 作初始条件（`read_vdb` →
+   `to_dense`）。
+4. **液体与油（SPH，粒子 ⇄ 体积）**：Genesis 的液体是 Lagrangian SPH（hash grid 邻域，
+   VDB 不做邻居搜索），与稀疏体积的接口在两端——
+   - **出口（每步/每 N 步）**：`scatter_particles(pos, h, mass)` 把粒子 splat 成密度
+     fog 网格（SPH cubic 核、单位积分，质量守恒已测）→ `write_vdb` 给 Houdini/Blender
+     体渲染液体，比逐粒子渲染便宜得多；要表面就 `union_spheres(pos, r, band)` 出
+     particle level set 表面代理（喷雾/液滴场景），离线可用 OpenVDB 生态精修。
+   - **进口**：Houdini 烘的液面/容器 `.vdb` level set → `read_vdb` → `GpuVolume.sample`
+     做容器碰撞 SDF 或装液初始条件（与落点①同一套采样机制，SPH 边界碰撞即刚体 SDF
+     碰撞的复用）。
+   - **油（高黏/两相）**：黏性在 SPH 求解器侧，体积层只管表征——两相液体（油-水、
+     油-气）每相一个 fog 网格，即混合分数场 α：`scatter_particles` 按相内粒子各 splat
+     一份，导出双网格 `.vdb`，渲染端做 α 混合；界面 SDF 用两相 `union_spheres` 之差
+     （`csg 'diff'`）。
+   - **在线更新**：`GpuVolume.write_voxels` 可增量回写密度值做实时可视化；拓扑（叶
+     集合）按粒子包围盒周期性重打包（拓扑宿主端冻结的同一分工）。
+
+## 许可证
+
+Apache-2.0（与上游 quadrants、genesis-world 一致），见 [LICENSE](LICENSE)。
+
+## 测试
+
+```
+pytest tests/ -q
+```
+
+覆盖：树编辑/CSG/稠密互转、粒子 splat（质量守恒、可加性、vec3 速度场、双核函数）、
+`union_spheres`（表面/窄带/逐粒子半径/射线命中/与 stamp 复合）、`.xuvdb` 多网格多类型
+往返、`.vdb` 头部字节与偏移校验、f32/f64/vec3/fog/level-set 往返、多叶尺寸重分块、
+负坐标、惰性值压缩路径、`save()` 拒绝 `.vdb` 后缀、GPU 采样对齐宿主三线性、内核写值
+往返、DDA 射线（含空块跳跃、内部出发、tmax 截断、变换偏移）。

xuvdb-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xuvdb"
+description = "Editable sparse voxel volumes with OpenVDB interop, built on quadrants kernels"
+readme = "README.md"
+dynamic = ["version"]
+requires-python = ">=3.10,<3.14"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+dependencies = [
+    "numpy",
+    "quadrants",
+]
+
+[project.optional-dependencies]
+# engine-side example (examples/test_packages.py) drives a genesis-world simulation
+genesis = ["genesis-world"]
+# in-memory OpenVDB bridge (to_openvdb / from_openvdb) via the official bindings
+openvdb = ["pyopenvdb"]
+test = ["pytest"]
+
+[tool.setuptools.dynamic]
+version = { attr = "xuvdb.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xuvdb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+