xuvdb 0.1.0__py3-none-any.whl

xuvdb/__init__.py

@@ -0,0 +1,64 @@
+"""XUVDB（太虚）: genesis' own sparse-volume format, built on the quadrants kernel.
+
+The name reads 太虚 (tàixū) - from《庄子·知北游》「不游乎太虚」and 张载《正蒙》「太虚无形，
+气之本体」: the closest Chinese rendering of an unbounded, sparse index domain - unbounded (the
+root hash domain has no extent), formless (unallocated space has no shape; sampling it returns the
+background). The name lives at the concept layer only (docs, logs, visualization labels); API
+identifiers stay English (`xuvdb.prune()`, never `xuvdb.sunyi()`), and the native extension
+`.xuvdb` never uses `.vdb` - every major volume tool parses that suffix as OpenVDB and fails
+opaquely on foreign bytes. Interop with OpenVDB is an explicit, separate export.
+
+`VdbGrid` is a mutable sparse voxel tree (dictionary of dense leaf blocks) that fills the gap this
+module was designed for: OpenVDB trees are CPU-bound and NanoVDB grids are GPU read-only, while an
+XUVDB grid can be structurally edited from Python (allocate/fill/stamp/CSG/prune leaves at any time)
+and its packed value buffer can additionally be *written* by quadrants kernels
+(`GpuVolume.write_voxels`) without a host round trip.
+
+Interoperability with OpenVDB is first-class and needs no OpenVDB installation:
+
+- `write_vdb` / `read_vdb` read and write real `.vdb` files (the published stream format, verified
+  against the OpenVDB sources; file version 224, active-mask compression, zip readable, blosc not)
+- `to_openvdb` / `from_openvdb` convert live grids through `pyopenvdb` when the bindings exist
+  (Houdini hython, Blender Python, conda-forge)
+- `save` / `load` use the native compact `.xuvdb` format
+
+Typical flows against the engine's existing dense solvers:
+
+- rigid SDF (落点 1): bake `geom.sdf_val` dense grids with `VdbGrid.from_dense`, edit/CSG them
+  sparsely, sample on device via `GpuVolume.sample` / `sdf_normal` and cast rays with
+  `ray_surface_hit`
+- MPM / smoke (落点 2, 3): pull density or velocity fields off the dense `qd.field` after a step,
+  sparsify, and hand `.vdb` files to Houdini/Blender for volume rendering, or bring Houdini caches
+  back in for initial conditions
+- liquid & oil (落点 4, SPH): rasterize particles to fog density volumes with `scatter_particles`
+  (unit-integral SPH kernels; one grid per phase gives mixture fractions) or build particle
+  level-set surface proxies with `union_spheres`; import Houdini container/initial-surface `.vdb`
+  caches as collision/initialization SDFs sampled on device
+
+Kernels run on any quadrants backend; call `init_runtime()` once before the first kernel call if
+`gs.init()` has not run (mirroring `genesis.occ`).
+"""
+
+from .gpu import GpuVolume
+from .io import load, save
+from .openvdb_bridge import from_openvdb, to_openvdb
+from .openvdb_file import read_vdb, write_vdb
+from .ray import ray_surface_hit
+from .runtime import init_runtime
+from .tree import Leaf, VdbGrid
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GpuVolume",
+    "Leaf",
+    "VdbGrid",
+    "from_openvdb",
+    "init_runtime",
+    "load",
+    "ray_surface_hit",
+    "read_vdb",
+    "save",
+    "to_openvdb",
+    "write_vdb",
+]

xuvdb/gpu.py

@@ -0,0 +1,96 @@
+"""Host-side packing of a `VdbGrid` into flat buffers consumed by `kernels.py`.
+
+A `GpuVolume` is the read-mostly, kernel-writable view of a scalar grid - the XUVDB counterpart of
+a NanoVDB device buffer, except that values are mutable from kernels. Topology is frozen at pack
+time; call `sync_to_host()` to pull kernel-written values back into the host tree, and re-create
+the volume after structural edits (leaf allocation, prune, load).
+"""
+
+import numpy as np
+
+from . import kernels
+from .runtime import init_runtime
+from .tree import VdbGrid
+
+_KEY_OFF = 1 << 19
+
+
+def _pack_key(kx, ky, kz):
+    return (int(kx) + _KEY_OFF) * (1 << 40) + (int(ky) + _KEY_OFF) * (1 << 20) + (int(kz) + _KEY_OFF)
+
+
+class GpuVolume:
+    """Flat, key-sorted leaf table of a scalar grid plus kernel entry points."""
+
+    def __init__(self, grid):
+        if not isinstance(grid, VdbGrid):
+            raise TypeError("GpuVolume wraps an xuvdb.VdbGrid")
+        if grid.is_vec or grid.type_code == 1:
+            raise TypeError("kernel packing currently supports float32 scalar grids")
+        if grid.n_leaves == 0:
+            raise ValueError("grid has no leaves")
+        init_runtime()
+        self.grid = grid
+        leaves = grid.leaves()
+        keys = np.array([_pack_key(*key) for key in sorted(grid._leaves)], dtype=np.int64)
+        if not np.all(keys[:-1] < keys[1:]):
+            raise ValueError("leaf keys out of range or duplicated")
+        per_leaf = grid.leaf_dim**3
+        values = np.empty(len(leaves) * per_leaf, dtype=np.float32)
+        for i, leaf in enumerate(leaves):
+            values[i * per_leaf:(i + 1) * per_leaf] = leaf.values.ravel()  # z-fastest C order
+        self.keys = keys
+        self.values = values
+        self.background = float(grid.background)
+        self._dirty = False
+
+    # ------------------------------------------------------------------ queries
+
+    def sample(self, points, linear=False):
+        """Sample the packed volume at world-space points (N,3)."""
+        points = np.ascontiguousarray(points, dtype=np.float32).reshape(-1, 3)
+        out = np.empty(len(points), dtype=np.float32)
+        kernel = kernels.kernel_sample_linear if linear else kernels.kernel_sample_nearest
+        kernel(
+            self.keys, self.values, int(self.grid.n_leaves), int(self.grid.leaf_log2), float(self.background),
+            *(float(v) for v in self.grid.origin_world), *(float(v) for v in self.grid.voxel_size),
+            points, out,
+        )
+        return out
+
+    def sdf_normal(self, points):
+        """Central-difference SDF gradient (world-space, normalized) at world-space points."""
+        points = np.ascontiguousarray(points, dtype=np.float32).reshape(-1, 3)
+        out = np.empty((len(points), 3), dtype=np.float32)
+        kernels.kernel_sdf_normal(
+            self.keys, self.values, int(self.grid.n_leaves), int(self.grid.leaf_log2), float(self.background),
+            *(float(v) for v in self.grid.origin_world), *(float(v) for v in self.grid.voxel_size),
+            points, out,
+        )
+        return out
+
+    # ------------------------------------------------------------------ mutation
+
+    def write_voxels(self, points, new_values):
+        """Overwrite voxel values from kernels; call `sync_to_host` to publish into the tree."""
+        points = np.ascontiguousarray(points, dtype=np.float32).reshape(-1, 3)
+        new_values = np.ascontiguousarray(new_values, dtype=np.float32).reshape(-1)
+        if len(new_values) != len(points):
+            raise ValueError("new_values must have one entry per point")
+        kernels.kernel_write_voxels(
+            self.keys, self.values, int(self.grid.n_leaves), int(self.grid.leaf_log2),
+            *(float(v) for v in self.grid.origin_world), *(float(v) for v in self.grid.voxel_size),
+            points, new_values,
+        )
+        self._dirty = True
+        return self
+
+    def sync_to_host(self):
+        """Copy kernel-written values back into the host grid's leaves."""
+        per_leaf = self.grid.leaf_dim**3
+        for i, leaf in enumerate(self.grid.leaves()):
+            leaf.values[...] = self.values[i * per_leaf:(i + 1) * per_leaf].reshape(
+                self.grid.leaf_dim, self.grid.leaf_dim, self.grid.leaf_dim
+            )
+        self._dirty = False
+        return self.grid

xuvdb/io.py

@@ -0,0 +1,173 @@
+"""Serialization of XUVDB grids to the native `.xuvdb` binary format.
+
+The extension is deliberately not `.vdb`: Houdini, Blender, Cycles and Arnold all parse `.vdb` as
+OpenVDB, and foreign bytes under that suffix fail silently or crash - `save()` refuses such paths
+outright. Interop with OpenVDB is an explicit, separate export (`openvdb_file.write_vdb`), which
+emits a real OpenVDB stream.
+
+Format (little-endian throughout; `u` = unsigned, `i` = signed, `f` = IEEE float):
+
+    magic    5 bytes "XUVDB"
+    version  u8       (currently 1)
+    flags    u8       (0)
+    n_grids  u16
+
+    per grid:
+      name           u32 length + utf-8 bytes
+      type_code      u8     (0 = float32, 1 = float64, 2 = vec3 float32)
+      leaf_log2      u8
+      class_code     u8     (0 unknown, 1 level set, 2 fog volume, 3 staggered)
+      reserved       u8
+      voxel_size     f64[3]
+      origin_world   f64[3]
+      background     f32 / f64 / f32[3]  (per type_code)
+      n_leaves       u32
+      per leaf, sorted by leaf origin (i, then j, then k):
+        origin      i32[3]                 (in voxels, of the leaf's (0,0,0) corner)
+        mask        u64[dim^3 / 64]        (active bits, z-fastest bit order)
+        values      value_type[dim^3]      (full dense leaf, z-fastest order)
+
+The z-fastest voxel order (linear index `n = x*dim^2 + y*dim + z`) matches the OpenVDB leaf layout,
+so round trips through `openvdb_file.py` are transpose-free. Like OpenVDB leaf nodes, a leaf's full
+dense buffer is stored - inactive values (e.g. a level set's -background interior) survive a save /
+load cycle.
+"""
+
+import struct
+
+import numpy as np
+
+from .tree import GRID_CLASSES, VdbGrid
+
+MAGIC = b"XUVDB"
+VERSION = 1
+
+_TYPE_BY_CODE = {0: np.float32, 1: np.float64}
+_CODE_BY_TYPE = {np.dtype(np.float32): 0, np.dtype(np.float64): 1}
+
+
+def _pack_str(s):
+    b = s.encode("utf-8")
+    return struct.pack("<I", len(b)) + b
+
+
+def _mask_words(active):
+    """Pack a bool (dim,dim,dim) mask into u64 words, bit n = voxel n (z-fastest C order)."""
+    bits = np.packbits(active.reshape(-1), bitorder="little")
+    return np.pad(bits, (0, (-len(bits)) % 8)).view(np.uint64)
+
+
+def _mask_from_words(words, count):
+    bits = words.view(np.uint8)
+    active = np.unpackbits(bits[: (count + 7) // 8], count=count, bitorder="little")
+    return active.astype(bool)
+
+
+def save(path, grids):
+    """Write one or more grids to a `.xuvdb` file."""
+    path = str(path)
+    if path.lower().endswith(".vdb"):
+        raise ValueError(
+            f"refusing to write the XUVDB native format to {path!r}: every major volume tool "
+            "(Houdini, Blender, Cycles, Arnold) parses '.vdb' as OpenVDB and fails opaquely on "
+            "foreign bytes. Use the '.xuvdb' extension, or export a real OpenVDB stream with "
+            "write_vdb()."
+        )
+    grids = list(grids)
+    buf = bytearray()
+    buf += MAGIC
+    buf += struct.pack("<BBI", VERSION, 0, len(grids))
+    for grid in grids:
+        buf += _pack_str(grid.name)
+        bg = np.asarray(grid.background, dtype=np.float64).reshape(-1)
+        buf += struct.pack("<BBBB", grid.type_code, grid.leaf_log2, GRID_CLASSES.index(grid.grid_class), 0)
+        buf += grid.voxel_size.astype("<f8").tobytes()
+        buf += grid.origin_world.astype("<f8").tobytes()
+        if grid.type_code == 0:
+            buf += struct.pack("<f", float(bg[0]))
+        elif grid.type_code == 1:
+            buf += struct.pack("<d", float(bg[0]))
+        else:
+            buf += bg.astype("<f4").tobytes()
+        leaves = grid.leaves()
+        buf += struct.pack("<I", len(leaves))
+        for leaf in leaves:
+            buf += leaf.origin.astype("<i4").tobytes()
+            mask = _mask_words(leaf.active)
+            buf += mask.astype("<u8").tobytes()
+            vals = leaf.values.reshape(-1)  # z-fastest C order
+            if grid.type_code == 1:
+                buf += vals.astype("<f8").tobytes()
+            else:
+                buf += vals.astype("<f4").tobytes()
+    with open(path, "wb") as f:
+        f.write(buf)
+    return len(buf)
+
+
+class _Reader:
+    def __init__(self, data):
+        self.data = data
+        self.pos = 0
+
+    def read(self, n):
+        if self.pos + n > len(self.data):
+            raise ValueError("truncated .xuvdb stream")
+        out = self.data[self.pos:self.pos + n]
+        self.pos += n
+        return out
+
+
+def load(path):
+    """Read all grids from a `.xuvdb` file."""
+    with open(path, "rb") as f:
+        data = f.read()
+    r = _Reader(data)
+    if r.read(len(MAGIC)) != MAGIC:
+        raise ValueError(f"{path} is not an XUVDB file")
+    version, flags, n_grids = struct.unpack("<BBI", r.read(6))
+    if version != VERSION:
+        raise ValueError(f"unsupported XUVDB version {version}")
+    if flags != 0:
+        raise ValueError(f"unsupported XUVDB flags {flags}")
+    grids = []
+    for _ in range(n_grids):
+        (name_len,) = struct.unpack("<I", r.read(4))
+        name = r.read(name_len).decode("utf-8")
+        type_code, leaf_log2, class_code, _res = struct.unpack("<BBBB", r.read(4))
+        voxel_size = np.frombuffer(r.read(24), dtype="<f8")
+        origin_world = np.frombuffer(r.read(24), dtype="<f8")
+        if type_code == 0:
+            (background,) = struct.unpack("<f", r.read(4))
+        elif type_code == 1:
+            (background,) = struct.unpack("<d", r.read(8))
+        else:
+            background = np.frombuffer(r.read(12), dtype="<f4").copy()
+        grid = VdbGrid(
+            dtype=_TYPE_BY_CODE.get(type_code, None) if type_code != 2
+            else np.dtype([("x", np.float32), ("y", np.float32), ("z", np.float32)]),
+            background=background,
+            voxel_size=voxel_size,
+            origin_world=origin_world,
+            leaf_log2=leaf_log2,
+            name=name,
+            grid_class=GRID_CLASSES[class_code],
+        )
+        (n_leaves,) = struct.unpack("<I", r.read(4))
+        dim = 1 << leaf_log2
+        words = dim**3 // 64
+        per_voxel = 3 if type_code == 2 else 1
+        item = np.dtype("<f4") if type_code != 1 else np.dtype("<f8")
+        for _leaf in range(n_leaves):
+            origin = np.frombuffer(r.read(12), dtype="<i4").astype(np.int64)
+            mask_words = np.frombuffer(r.read(words * 8), dtype="<u8")
+            active = _mask_from_words(mask_words, dim**3)
+            values_flat = np.frombuffer(r.read(dim**3 * per_voxel * item.itemsize), dtype=item)
+            leaf = grid._get_or_create_leaf((origin[0] >> leaf_log2, origin[1] >> leaf_log2, origin[2] >> leaf_log2))
+            if grid.is_vec:
+                leaf.values[...] = values_flat.reshape(dim, dim, dim, 3)
+            else:
+                leaf.values[...] = values_flat.reshape(dim, dim, dim)
+            leaf.active[...] = active.reshape(dim, dim, dim)
+        grids.append(grid)
+    return grids

xuvdb/kernels.py

@@ -0,0 +1,258 @@
+"""Quadrants kernels for GPU-side sampling and mutation of packed XUVDB volumes.
+
+The host packs a scalar grid's leaves into a flat, key-sorted table (`gpu.GpuVolume`): sorted
+`int64` leaf keys, one flat float32 value buffer, and the world-space transform scalars. Kernels
+resolve a world point to its leaf by packing the leaf coordinates into a 60-bit key and binary
+searching the sorted key array - no hash table, so the same buffer is valid on CPU and GPU
+backends.
+
+Value mutation (`kernel_write_voxels`) writes the packed buffer in place: unlike NanoVDB grids,
+values are writable from kernels. Topology stays fixed for the lifetime of a packed volume; the
+host re-packs after structural edits (leaf allocation, prune, load).
+"""
+
+import quadrants as qd
+
+_KEY_OFF = 1 << 19  # per-axis leaf coordinate offset; supports +-524288 leaves per axis
+
+
+@qd.func
+def xuvdb_pack_key(kx: qd.i64, ky: qd.i64, kz: qd.i64) -> qd.i64:
+    return (kx + qd.i64(_KEY_OFF)) * qd.i64(1 << 40) + (ky + qd.i64(_KEY_OFF)) * qd.i64(1 << 20) + (
+        kz + qd.i64(_KEY_OFF)
+    )
+
+
+@qd.func
+def xuvdb_find_leaf(
+    keys: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    kx: qd.i64,
+    ky: qd.i64,
+    kz: qd.i64,
+) -> int:
+    key = xuvdb_pack_key(kx, ky, kz)
+    lo = 0
+    hi = n_leaves
+    while lo < hi:
+        mid = (lo + hi) // 2
+        if keys[mid] < key:
+            lo = mid + 1
+        else:
+            hi = mid
+    found = lo
+    if lo >= n_leaves or keys[lo] != key:
+        found = -1
+    return found
+
+
+@qd.func
+def xuvdb_voxel_value(
+    keys: qd.types.ndarray(ndim=1),
+    values: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    leaf_log2: int,
+    background: float,
+    xi: qd.i64,
+    yi: qd.i64,
+    zi: qd.i64,
+) -> float:
+    dim = 1 << leaf_log2
+    leaf_idx = xuvdb_find_leaf(keys, n_leaves, xi >> leaf_log2, yi >> leaf_log2, zi >> leaf_log2)
+    lx = xi & qd.i64(dim - 1)
+    ly = yi & qd.i64(dim - 1)
+    lz = zi & qd.i64(dim - 1)
+    n = lx * qd.i64(dim * dim) + ly * qd.i64(dim) + lz
+    value = background
+    if leaf_idx >= 0:
+        value = values[leaf_idx * qd.i64(dim * dim * dim) + n]
+    return value
+
+
+@qd.func
+def xuvdb_sample_nearest(
+    keys: qd.types.ndarray(ndim=1),
+    values: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    leaf_log2: int,
+    background: float,
+    o_x: float,
+    o_y: float,
+    o_z: float,
+    s_x: float,
+    s_y: float,
+    s_z: float,
+    x: float,
+    y: float,
+    z: float,
+) -> float:
+    xi = qd.i64(qd.floor((x - o_x) / s_x + 0.5))
+    yi = qd.i64(qd.floor((y - o_y) / s_y + 0.5))
+    zi = qd.i64(qd.floor((z - o_z) / s_z + 0.5))
+    return xuvdb_voxel_value(keys, values, n_leaves, leaf_log2, background, xi, yi, zi)
+
+
+@qd.func
+def xuvdb_sample_linear(
+    keys: qd.types.ndarray(ndim=1),
+    values: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    leaf_log2: int,
+    background: float,
+    o_x: float,
+    o_y: float,
+    o_z: float,
+    s_x: float,
+    s_y: float,
+    s_z: float,
+    x: float,
+    y: float,
+    z: float,
+) -> float:
+    cx = (x - o_x) / s_x
+    cy = (y - o_y) / s_y
+    cz = (z - o_z) / s_z
+    bx = qd.i64(qd.floor(cx))
+    by = qd.i64(qd.floor(cy))
+    bz = qd.i64(qd.floor(cz))
+    fx = cx - qd.floor(cx)
+    fy = cy - qd.floor(cy)
+    fz = cz - qd.floor(cz)
+    out = qd.f32(0.0)
+    for dx in range(2):
+        wx = fx if dx == 1 else 1.0 - fx
+        for dy in range(2):
+            wy = fy if dy == 1 else 1.0 - fy
+            for dz in range(2):
+                wz = fz if dz == 1 else 1.0 - fz
+                out += qd.f32(
+                    wx * wy * wz
+                ) * qd.f32(
+                    xuvdb_voxel_value(keys, values, n_leaves, leaf_log2, background,
+                                     bx + qd.i64(dx), by + qd.i64(dy), bz + qd.i64(dz))
+                )
+    return out
+
+
+@qd.kernel
+def kernel_sample_nearest(
+    keys: qd.types.ndarray(ndim=1),
+    values: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    leaf_log2: int,
+    background: float,
+    o_x: float,
+    o_y: float,
+    o_z: float,
+    s_x: float,
+    s_y: float,
+    s_z: float,
+    points: qd.types.ndarray(ndim=2),
+    out: qd.types.ndarray(ndim=1),
+):
+    for i in range(points.shape[0]):
+        out[i] = xuvdb_sample_nearest(
+            keys, values, n_leaves, leaf_log2, background, o_x, o_y, o_z, s_x, s_y, s_z,
+            points[i, 0], points[i, 1], points[i, 2],
+        )
+
+
+@qd.kernel
+def kernel_sample_linear(
+    keys: qd.types.ndarray(ndim=1),
+    values: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    leaf_log2: int,
+    background: float,
+    o_x: float,
+    o_y: float,
+    o_z: float,
+    s_x: float,
+    s_y: float,
+    s_z: float,
+    points: qd.types.ndarray(ndim=2),
+    out: qd.types.ndarray(ndim=1),
+):
+    for i in range(points.shape[0]):
+        out[i] = xuvdb_sample_linear(
+            keys, values, n_leaves, leaf_log2, background, o_x, o_y, o_z, s_x, s_y, s_z,
+            points[i, 0], points[i, 1], points[i, 2],
+        )
+
+
+@qd.kernel
+def kernel_sdf_normal(
+    keys: qd.types.ndarray(ndim=1),
+    values: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    leaf_log2: int,
+    background: float,
+    o_x: float,
+    o_y: float,
+    o_z: float,
+    s_x: float,
+    s_y: float,
+    s_z: float,
+    points: qd.types.ndarray(ndim=2),
+    out: qd.types.ndarray(ndim=2),
+):
+    """Central-difference surface normal of the SDF field at each point (world-space, normalized)."""
+    for i in range(points.shape[0]):
+        x = points[i, 0]
+        y = points[i, 1]
+        z = points[i, 2]
+        nx = xuvdb_sample_linear(keys, values, n_leaves, leaf_log2, background, o_x, o_y, o_z, s_x, s_y, s_z,
+                                x + s_x, y, z) - xuvdb_sample_linear(keys, values, n_leaves, leaf_log2,
+                                                                    background, o_x, o_y, o_z, s_x, s_y, s_z,
+                                                                    x - s_x, y, z)
+        ny = xuvdb_sample_linear(keys, values, n_leaves, leaf_log2, background, o_x, o_y, o_z, s_x, s_y, s_z,
+                                x, y + s_y, z) - xuvdb_sample_linear(keys, values, n_leaves, leaf_log2,
+                                                                    background, o_x, o_y, o_z, s_x, s_y, s_z,
+                                                                    x, y - s_y, z)
+        nz = xuvdb_sample_linear(keys, values, n_leaves, leaf_log2, background, o_x, o_y, o_z, s_x, s_y, s_z,
+                                x, y, z + s_z) - xuvdb_sample_linear(keys, values, n_leaves, leaf_log2,
+                                                                    background, o_x, o_y, o_z, s_x, s_y, s_z,
+                                                                    x, y, z - s_z)
+        norm = qd.sqrt(nx * nx + ny * ny + nz * nz)
+        if norm > 1e-12:
+            out[i, 0] = nx / norm
+            out[i, 1] = ny / norm
+            out[i, 2] = nz / norm
+        else:
+            out[i, 0] = 0.0
+            out[i, 1] = 0.0
+            out[i, 2] = 0.0
+
+
+@qd.kernel
+def kernel_write_voxels(
+    keys: qd.types.ndarray(ndim=1),
+    values: qd.types.ndarray(ndim=1),
+    n_leaves: int,
+    leaf_log2: int,
+    o_x: float,
+    o_y: float,
+    o_z: float,
+    s_x: float,
+    s_y: float,
+    s_z: float,
+    points: qd.types.ndarray(ndim=2),
+    new_values: qd.types.ndarray(ndim=1),
+):
+    """Overwrite the value of the voxel nearest each point (in-place; topology unchanged).
+
+    The active mask is host-side state and is not touched: deactivating/reactivating voxels or
+    allocating leaves requires re-packing on the host.
+    """
+    dim = 1 << leaf_log2
+    for i in range(points.shape[0]):
+        xi = qd.i64(qd.floor((points[i, 0] - o_x) / s_x + 0.5))
+        yi = qd.i64(qd.floor((points[i, 1] - o_y) / s_y + 0.5))
+        zi = qd.i64(qd.floor((points[i, 2] - o_z) / s_z + 0.5))
+        leaf_idx = xuvdb_find_leaf(keys, n_leaves, xi >> leaf_log2, yi >> leaf_log2, zi >> leaf_log2)
+        if leaf_idx >= 0:
+            lx = xi & qd.i64(dim - 1)
+            ly = yi & qd.i64(dim - 1)
+            lz = zi & qd.i64(dim - 1)
+            n = lx * qd.i64(dim * dim) + ly * qd.i64(dim) + lz
+            values[leaf_idx * qd.i64(dim * dim * dim) + n] = new_values[i]

xuvdb/openvdb_bridge.py

@@ -0,0 +1,101 @@
+"""Optional in-memory bridge to `pyopenvdb` (the OpenVDB Python bindings).
+
+Used when the bindings are importable (Houdini's hython, Blender's bundled Python, conda-forge).
+The file-level interop path that needs no bindings at all is `openvdb_file.py`.
+"""
+
+import numpy as np
+
+try:
+    import pyopenvdb
+except ImportError:  # the module stays importable; the converters raise on use
+    pyopenvdb = None
+
+
+def _require_bindings():
+    if pyopenvdb is None:
+        raise ImportError(
+            "pyopenvdb is not installed; use xuvdb.openvdb_file.read_vdb/write_vdb for "
+            "file-level interop instead"
+        )
+
+
+def _openvdb_grid_class(name):
+    _require_bindings()
+    return {
+        "unknown": pyopenvdb.GridClass.UNKNOWN,
+        "level set": pyopenvdb.GridClass.LEVEL_SET,
+        "fog volume": pyopenvdb.GridClass.FOG_VOLUME,
+        "staggered": pyopenvdb.GridClass.STAGGERED,
+    }[name]
+
+
+def _xuvdb_grid_class(ovdb_value):
+    _require_bindings()
+    for name, value in (
+        ("unknown", pyopenvdb.GridClass.UNKNOWN),
+        ("level set", pyopenvdb.GridClass.LEVEL_SET),
+        ("fog volume", pyopenvdb.GridClass.FOG_VOLUME),
+        ("staggered", pyopenvdb.GridClass.STAGGERED),
+    ):
+        if int(value) == int(ovdb_value):
+            return name
+    return "unknown"
+
+
+def to_openvdb(grid):
+    """Convert a `VdbGrid` into a live `pyopenvdb` grid (FloatGrid / DoubleGrid / Vec3SGrid)."""
+    _require_bindings()
+    if grid.is_vec:
+        ovdb = pyopenvdb.Vec3SGrid(background=tuple(float(v) for v in grid.background))
+    elif grid.type_code == 1:
+        ovdb = pyopenvdb.DoubleGrid(background=float(grid.background))
+    else:
+        ovdb = pyopenvdb.FloatGrid(background=float(grid.background))
+    ovdb.name = grid.name
+    ovdb.gridClass = _openvdb_grid_class(grid.grid_class)
+
+    matrix = np.eye(4)
+    matrix[:3, :3] = np.diag(grid.voxel_size)
+    matrix[:3, 3] = grid.origin_world
+    ovdb.transform = pyopenvdb.createLinearTransform(matrix=matrix)
+
+    acc = ovdb.getAccessor()
+    for coord, value in grid.iter_voxels():
+        acc.setValueOn(coord, tuple(float(v) for v in value) if grid.is_vec else float(value))
+    return ovdb
+
+
+def from_openvdb(ovdb_grid, leaf_log2=3):
+    """Convert a `pyopenvdb` grid into a `VdbGrid` (active tiles are materialized into leaves)."""
+    _require_bindings()
+    from .tree import VdbGrid
+
+    value_type = ovdb_grid.valueType
+    if value_type == "vec3s":
+        dtype = np.dtype([("x", np.float32), ("y", np.float32), ("z", np.float32)])
+        background = np.asarray(ovdb_grid.backgroundValue, dtype=np.float64).reshape(3)
+    elif value_type == "double":
+        dtype = np.float64
+        background = float(ovdb_grid.backgroundValue)
+    else:
+        dtype = np.float32
+        background = float(ovdb_grid.backgroundValue)
+
+    matrix = np.array(ovdb_grid.transform.matrix)
+    voxel_size = np.array([matrix[0, 0], matrix[1, 1], matrix[2, 2]])
+    origin_world = np.array([matrix[0, 3], matrix[1, 3], matrix[2, 3]])
+    grid_class = _xuvdb_grid_class(ovdb_grid.gridClass)
+
+    grid = VdbGrid(dtype=dtype, background=background, voxel_size=voxel_size, origin_world=origin_world,
+                   leaf_log2=leaf_log2, name=ovdb_grid.name or "grid", grid_class=grid_class)
+
+    acc = ovdb_grid.getConstAccessor()
+    for bbox in ovdb_grid.iterActiveTiles():
+        lo, hi = np.array(bbox.min), np.array(bbox.max)
+        value = acc.getValue(tuple(int(v) for v in lo))
+        grid.fill_box(lo, hi, value, active=True)
+    for coord in ovdb_grid.iterActiveVoxels():
+        value = acc.getValue(tuple(coord))
+        grid.set_value(tuple(coord), tuple(float(v) for v in value) if grid.is_vec else float(value))
+    return grid