Skip to content

3D engine that AI agents drive

21.6 KB
Raw Blame
# /// script
# requires-python = ">=3.10"
# dependencies = ["numpy"]
# ///
"""Convert an OpenVDB file of float grids (smoke, fire, explosions) to a Crucible volume grid file.

    uv run --no-project scripts/vdb-to-grid.py frame.vdb out.67vg --max-resolution 128
    uv run --no-project scripts/vdb-to-grid.py frame.vdb out.67vg --map flame=flames --map temperature=heat
    uv run --no-project scripts/vdb-to-grid.py "sim/smoke_*.vdb" blast --sequence --max-resolution 128

With --sequence the first argument is a glob and the second a name prefix: the matching files, in numeric order, become blast_0000.67vg,
blast_0001.67vg and so on, all on one box and resolution (the union of every frame's box) with the same channels (a channel any frame has, zero in the others), and the script prints the `frames` list for the
volume. Frame size at 128 cubed is 4 MiB per channel and at 256 cubed 32 MiB; a sequence may hold 256 MiB in all (docs/volumetric.md).

The reader is written here, so no OpenVDB build or wheel is needed (none is published for Windows). It reads OpenVDB file
versions 222 and later with float grids of tree shape 5-4-3 (the shape every DCC tool writes), stored as full or half floats,
uncompressed, zip or Blosc compressed. Blosc (openvdb's default) needs the optional `blosc` package, added per run with `uv run --no-project --with blosc
scripts/vdb-to-grid.py ...`; without it the error prints that command.

Output (docs/volumetric.md, "Grid volumes"): the bytes "67VG", a uint32 version (1), a uint32 header length, a JSON header padded
to 4 bytes, then each channel as half floats with x fastest, then y, then z. The axes are y up: a Z up VDB (Blender, EmberGen)
is turned so its z becomes y.
"""
import argparse
import glob
import importlib
import json
import re
import struct
import sys
import zlib
from pathlib import Path

import numpy

MAGIC = 0x56444220
LEAF_DIMENSION = 8
MAXIMUM_SEQUENCE_FRAMES = 512  # src/volume-grid-sequence.js
MAXIMUM_SEQUENCE_BYTES = 256 * 1024 * 1024
LEVEL_LOG2 = (3, 4, 5)  # leaf, first internal node, second internal node (child counts 8^3, 16^3, 32^3 per node)
COMPRESS_ZIP = 0x1
COMPRESS_ACTIVE_MASK = 0x2
COMPRESS_BLOSC = 0x4
MAXIMUM_AXIS = 256
blosc_decoder = None  # loaded on the first Blosc block, so zip and uncompressed files never import it
CHANNEL_NAMES = ("density", "temperature", "flame")
DEFAULT_SOURCE_NAMES = {
    "density": ("density",),
    "temperature": ("temperature", "heat", "temp"),
    "flame": ("flame", "flames", "fire", "fuel"),
}
# Mask metadata of OpenVDB's compressed value blocks.
NO_MASK_OR_INACTIVE_VALS, NO_MASK_AND_MINUS_BG, NO_MASK_AND_ONE_INACTIVE_VAL, MASK_AND_NO_INACTIVE_VALS, MASK_AND_ONE_INACTIVE_VAL, MASK_AND_TWO_INACTIVE_VALS, NO_MASK_AND_ALL_VALS = range(7)


class Reader:
    def __init__(self, data):
        self.data = memoryview(data)
        self.offset = 0

    def take(self, count):
        end = self.offset + count
        if end > len(self.data):
            raise ValueError("the VDB file ends early; it is damaged or not an OpenVDB file")
        chunk = self.data[self.offset:end]
        self.offset = end
        return chunk

    def unpack(self, form):
        return struct.unpack("<" + form, self.take(struct.calcsize("<" + form)))

    def string(self):
        (length,) = self.unpack("I")
        return bytes(self.take(length)).decode("utf-8", errors="replace")

    def metadata(self):
        (count,) = self.unpack("I")
        result = {}
        for _ in range(count):
            name = self.string()
            type_name = self.string()
            (size,) = self.unpack("I")
            raw = bytes(self.take(size))
            if type_name == "string":
                result[name] = raw[4:].decode("utf-8", errors="replace")
            elif type_name == "vec3i":
                result[name] = struct.unpack("<3i", raw)
            elif type_name == "vec3d":
                result[name] = struct.unpack("<3d", raw)
            elif type_name == "float":
                result[name] = struct.unpack("<f", raw)[0]
            elif type_name == "int64":
                result[name] = struct.unpack("<q", raw)[0]
        return result


def read_mask(reader, bit_count):
    words = numpy.frombuffer(bytes(reader.take(bit_count // 8)), dtype="<u8")
    return numpy.unpackbits(words.view(numpy.uint8), bitorder="little")[:bit_count].astype(bool)


def load_blosc_decoder():
    """Returns a function that decodes one Blosc frame, from the optional `blosc` or `blosc2` package, or raises with the command that adds one."""
    for module_name in ("blosc", "blosc2"):
        try:
            return importlib.import_module(module_name).decompress
        except ImportError:
            continue
    raise ValueError("this VDB uses Blosc compression (openvdb's default) and no Blosc decoder is installed; run the script with one added: "
                     "uv run --no-project --with blosc scripts/vdb-to-grid.py <the same arguments>")


def decompress_blosc(frame):
    global blosc_decoder
    if blosc_decoder is None:
        blosc_decoder = load_blosc_decoder()
    return bytes(blosc_decoder(frame))


def read_values(reader, count, compression, from_half, bytes_per_value=None):
    width = 2 if from_half else 4
    expected = count * width
    if compression & (COMPRESS_ZIP | COMPRESS_BLOSC):
        (stored,) = reader.unpack("q")
        raw = bytes(reader.take(stored)) if stored > 0 else bytes(reader.take(expected))
        if stored > 0:
            raw = decompress_blosc(raw) if compression & COMPRESS_BLOSC else zlib.decompress(raw)
    else:
        raw = bytes(reader.take(expected))
    if len(raw) != expected:
        raise ValueError(f"a value block holds {len(raw)} bytes where {expected} were expected; the file layout is not the one this reader knows")
    if from_half:
        return numpy.frombuffer(raw, dtype="<f2").astype(numpy.float32)
    return numpy.frombuffer(raw, dtype="<f4").copy()


def read_compressed_values(reader, count, value_mask, compression, from_half, background):
    (metadata,) = reader.unpack("b")
    inactive_first = background if metadata == NO_MASK_OR_INACTIVE_VALS else -background
    inactive_second = background
    if metadata in (NO_MASK_AND_ONE_INACTIVE_VAL, MASK_AND_ONE_INACTIVE_VAL, MASK_AND_TWO_INACTIVE_VALS):
        (inactive_first,) = reader.unpack("f")
        if metadata == MASK_AND_TWO_INACTIVE_VALS:
            (inactive_second,) = reader.unpack("f")
    selection = None
    if (compression & COMPRESS_ACTIVE_MASK) and metadata in (MASK_AND_NO_INACTIVE_VALS, MASK_AND_ONE_INACTIVE_VAL, MASK_AND_TWO_INACTIVE_VALS):
        selection = read_mask(reader, count)
    if (compression & COMPRESS_ACTIVE_MASK) and metadata != NO_MASK_AND_ALL_VALS:
        stored = read_values(reader, int(value_mask.sum()), compression, from_half)
        values = numpy.empty(count, dtype=numpy.float32)
        values[value_mask] = stored
        inactive = ~value_mask
        values[inactive] = inactive_first
        if selection is not None:
            values[inactive & selection] = inactive_second
        return values
    return read_values(reader, count, compression, from_half)


class Node:
    def __init__(self, level, origin):
        self.level = level  # 0 leaf, 1 and 2 internal
        self.origin = origin
        self.child_mask = None
        self.value_mask = None
        self.tile_values = None
        self.children = []
        self.data = None


def read_node_topology(reader, level, origin, compression, from_half, background):
    node = Node(level, origin)
    if level == 0:
        node.value_mask = read_mask(reader, LEAF_DIMENSION ** 3)
        return node
    log2 = LEVEL_LOG2[level]
    slots = 1 << (3 * log2)
    node.child_mask = read_mask(reader, slots)
    node.value_mask = read_mask(reader, slots)
    node.tile_values = read_compressed_values(reader, slots, node.value_mask, compression, from_half, background)
    child_extent = 1 << sum(LEVEL_LOG2[:level])
    side = 1 << log2
    for slot in numpy.flatnonzero(node.child_mask):
        x, y, z = int(slot) >> (2 * log2), (int(slot) >> log2) & (side - 1), int(slot) & (side - 1)
        child_origin = (origin[0] + x * child_extent, origin[1] + y * child_extent, origin[2] + z * child_extent)
        node.children.append(read_node_topology(reader, level - 1, child_origin, compression, from_half, background))
    return node


def read_node_buffers(reader, node, compression, from_half, background):
    if node.level == 0:
        node.value_mask = read_mask(reader, LEAF_DIMENSION ** 3)  # a leaf stores its mask again ahead of its values
        node.data = read_compressed_values(reader, LEAF_DIMENSION ** 3, node.value_mask, compression, from_half, background)
        return
    for child in node.children:
        read_node_buffers(reader, child, compression, from_half, background)


def read_grid(reader, descriptor, version):
    (compression,) = reader.unpack("I") if version >= 222 else (0,)
    metadata = reader.metadata()
    transform_name = reader.string()
    if "ScaleTranslate" not in transform_name:
        raise ValueError(f"the transform {transform_name} is not supported; use a UniformScaleTranslateMap grid")
    values = reader.unpack("18d")  # translation, scale values, voxel size, then three derived vec3d
    translation, voxel_size = values[0:3], values[6:9]
    (buffer_count,) = reader.unpack("i")
    background = reader.unpack("f")[0]
    tile_count, child_count = reader.unpack("II")
    from_half = descriptor["type"].endswith("_HalfFloat")
    tiles = []
    for _ in range(tile_count):
        x, y, z = reader.unpack("3i")
        (value,) = reader.unpack("f")
        (active,) = reader.unpack("?")
        tiles.append(((x, y, z), value, active))
    roots = []
    for _ in range(child_count):
        origin = reader.unpack("3i")
        roots.append(read_node_topology(reader, 2, origin, compression, from_half, background))
    for root in roots:
        read_node_buffers(reader, root, compression, from_half, background)
    return {"metadata": metadata, "voxel_size": voxel_size, "translation": translation, "background": background, "tiles": tiles, "roots": roots}


def read_vdb(path):
    reader = Reader(Path(path).read_bytes())
    (magic,) = reader.unpack("q")
    if magic != MAGIC:
        raise ValueError(f"{path} is not an OpenVDB file (wrong magic number)")
    (version,) = reader.unpack("I")
    if version < 222:
        raise ValueError(f"{path} is OpenVDB file version {version}; this reader needs 222 or later, so re-save it from a current tool")
    reader.unpack("II")  # library version
    (has_offsets,) = reader.unpack("b")
    if not has_offsets:
        raise ValueError("this VDB has no grid offsets; re-save it with a current tool")
    reader.take(36)  # file UUID
    reader.metadata()
    (grid_count,) = reader.unpack("I")
    grids = {}
    for _ in range(grid_count):
        name = reader.string().split("\x1e")[0]
        type_name = reader.string()
        reader.string()  # instance parent
        grid_start, block_start, grid_end = reader.unpack("3q")
        descriptor = {"name": name, "type": type_name}
        if not type_name.startswith("Tree_float_5_4_3"):
            reader.offset = grid_end
            print(f"skipping grid '{name}' ({type_name}); only float grids are read", file=sys.stderr)
            continue
        grid = read_grid(reader, descriptor, version)
        reader.offset = grid_end
        grids[name] = grid
    return grids


def leaves_of(grid):
    leaves = []

    def collect(node):
        if node.level == 0:
            leaves.append(node)
        else:
            for child in node.children:
                collect(child)

    for root in grid["roots"]:
        collect(root)
    return leaves


def bounds_of(leaves):
    origins = numpy.array([leaf.origin for leaf in leaves])
    return origins.min(axis=0), origins.max(axis=0) + LEAF_DIMENSION


def densify(leaves, box_minimum, box_shape):
    """Writes the leaves into a dense array[x][y][z] over the box, clipping what falls outside it."""
    dense = numpy.zeros(box_shape, dtype=numpy.float32)
    for leaf in leaves:
        start = [int(leaf.origin[axis] - box_minimum[axis]) for axis in range(3)]
        cut_low = [max(0, -start[axis]) for axis in range(3)]
        cut_high = [min(LEAF_DIMENSION, box_shape[axis] - start[axis]) for axis in range(3)]
        if any(cut_high[axis] <= cut_low[axis] for axis in range(3)):
            continue
        block = leaf.data.reshape(8, 8, 8)
        target = tuple(slice(start[axis] + cut_low[axis], start[axis] + cut_high[axis]) for axis in range(3))
        source_block = tuple(slice(cut_low[axis], cut_high[axis]) for axis in range(3))
        dense[target] = block[source_block]
    return dense


def resample(dense, target):
    """Box-average `dense` down to `target` (each target axis divides evenly after padding)."""
    result = dense
    for axis in range(3):
        factor = -(-result.shape[axis] // target[axis])
        padded = factor * target[axis]
        pad = [(0, 0)] * 3
        pad[axis] = (0, padded - result.shape[axis])
        result = numpy.pad(result, pad)
        shape = list(result.shape)
        shape[axis:axis + 1] = [target[axis], factor]
        result = result.reshape(shape).mean(axis=axis + 1)
    return result


def write_grid(path, channels, size, source):
    resolution = list(next(iter(channels.values())).shape)
    header = json.dumps({"resolution": resolution, "channels": list(channels), "size": size, "source": source}, separators=(",", ":")).encode()
    header += b" " * (-len(header) % 4)
    with open(path, "wb") as output:
        output.write(b"67VG" + struct.pack("<II", 1, len(header)) + header)
        for array in channels.values():
            output.write(numpy.ascontiguousarray(array.transpose(2, 1, 0)).astype("<f2").tobytes())  # x fastest


def natural_key(path):
    """Sorts frame_2 before frame_10: digit runs compare as numbers."""
    return [int(part) if part.isdigit() else part for part in re.split(r"(\d+)", str(path))]


def choose_channels(grids, name_map, source_name):
    """The VDB grid each channel is read from. Stops with the file's name when it has no density grid."""
    chosen = {}
    for channel in CHANNEL_NAMES:
        for candidate in name_map.get(channel, DEFAULT_SOURCE_NAMES[channel]):
            if candidate in grids:
                chosen[channel] = candidate
                break
    if "density" not in chosen:
        raise SystemExit(f"{source_name}: no density grid; the file holds: {', '.join(grids) or 'no float grids'}. Pass --map density=<grid name>")
    return chosen


def output_resolution(box_shape, arguments):
    """The resolution a box is written at, and its edge lengths in voxels, in the output's axis order."""
    scale = min(1.0, arguments.max_resolution / max(box_shape))
    target = tuple(max(1, round(extent * scale)) for extent in box_shape)
    if arguments.up == "z":
        target = (target[0], target[2], target[1])
    return target


def convert(grids, chosen, density_leaves, box_minimum, box_maximum, arguments, source_name, output_path, channel_names=None):
    """Writes one grid file on the box [box_minimum, box_maximum). Returns the target resolution and its size in VDB units.

    `channel_names` (sequence mode) lists the channels every frame carries: one this frame lacks, or holds no voxels of, is written as zeros, so
    all the frames of a sequence have the same channels. Without it a channel that is empty in the file is left out.
    """
    box_shape = tuple(int(extent) for extent in box_maximum - box_minimum)
    voxel = grids[chosen["density"]]["voxel_size"]
    wanted = channel_names or list(chosen)
    aligned = {}
    for channel in wanted:
        leaves = density_leaves if channel == "density" else (leaves_of(grids[chosen[channel]]) if channel in chosen else [])
        if leaves or channel_names:
            aligned[channel] = densify(leaves, box_minimum, box_shape)
        else:
            print(f"channel {channel} ({chosen[channel]}) is empty in {source_name} and is left out", file=sys.stderr)
    size_metres = [box_shape[axis] * voxel[axis] for axis in range(3)]
    target = output_resolution(box_shape, arguments)
    if arguments.up == "z":
        # (x, y, z) -> (x, z, -y): rotate the z-up box to y up without mirroring it.
        aligned = {channel: numpy.flip(array, axis=1).transpose(0, 2, 1) for channel, array in aligned.items()}
        size_metres = [size_metres[0], size_metres[2], size_metres[1]]
    outputs = {channel: resample(array, target) for channel, array in aligned.items()}
    write_grid(output_path, outputs, [round(extent, 6) for extent in size_metres], source_name)
    peaks = {channel: float(array.max()) for channel, array in outputs.items()}
    voxels = int(numpy.prod(target))
    print(f"wrote {output_path}: {target[0]}x{target[1]}x{target[2]} voxels, channels {list(outputs)}, "
          f"{voxels * 2 * len(outputs)} bytes of data, size {size_metres} (VDB units), channel maxima {peaks}")
    return target, size_metres


def convert_sequence(files, name_map, arguments):
    # Pass one reads only what the plan needs from each frame: its density box and which channels hold voxels. Every frame is then put on the union of
    # the boxes and carries the union of the channels, so the whole sequence has one resolution and one channel list.
    union_minimum = union_maximum = None
    present = set()
    for file in files:
        grids = read_vdb(file)
        chosen = choose_channels(grids, name_map, file)
        density_leaves = leaves_of(grids[chosen["density"]])
        if density_leaves:
            present.add("density")
            frame_minimum, frame_maximum = bounds_of(density_leaves)
            union_minimum = frame_minimum if union_minimum is None else numpy.minimum(union_minimum, frame_minimum)
            union_maximum = frame_maximum if union_maximum is None else numpy.maximum(union_maximum, frame_maximum)
        else:
            print(f"{file}: the density grid has no voxels; this frame is written empty", file=sys.stderr)
        present.update(channel for channel in chosen if channel != "density" and leaves_of(grids[chosen[channel]]))
    if union_minimum is None:
        raise SystemExit(f"no density voxels in any of the {len(files)} files matching {arguments.vdb!r}")
    channel_names = [channel for channel in CHANNEL_NAMES if channel in present]
    box_shape = tuple(int(extent) for extent in union_maximum - union_minimum)
    shape = output_resolution(box_shape, arguments)
    total = int(numpy.prod(shape)) * 2 * len(channel_names) * len(files)
    if total > MAXIMUM_SEQUENCE_BYTES:
        raise SystemExit(f"{len(files)} frames of {shape[0]}x{shape[1]}x{shape[2]} with {len(channel_names)} channels ({', '.join(channel_names)}) are {total} bytes, "
                         f"over the {MAXIMUM_SEQUENCE_BYTES} byte limit of a sequence; nothing was written. Use a lower --max-resolution or fewer frames")
    names = []
    for index, file in enumerate(files):
        grids = read_vdb(file)
        chosen = choose_channels(grids, name_map, file)
        density_leaves = leaves_of(grids[chosen["density"]])
        name = f"{arguments.output}_{index:04d}.67vg"
        convert(grids, chosen, density_leaves, union_minimum, union_maximum, arguments, Path(file).name, name, channel_names)
        names.append(Path(name).name)
    print(f"{len(files)} frames of {shape[0]}x{shape[1]}x{shape[2]}, channels {channel_names}, {total} bytes in all (a sequence may hold {MAXIMUM_SEQUENCE_BYTES}); the volume's frames:")
    print(json.dumps(names))


def main():
    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    parser.add_argument("vdb", help="a VDB file, or with --sequence a glob such as 'sim/smoke_*.vdb'")
    parser.add_argument("output", help="the grid file, or with --sequence the name prefix of the numbered files")
    parser.add_argument("--max-resolution", type=int, default=128, help=f"longest axis in voxels, at most {MAXIMUM_AXIS} (default 128)")
    parser.add_argument("--map", action="append", default=[], metavar="CHANNEL=GRID", help="read a channel from another VDB grid name, e.g. flame=fire")
    parser.add_argument("--up", choices=("y", "z"), default="z", help="the VDB's up axis (default z, as Blender and EmberGen write); the output is y up")
    parser.add_argument("--sequence", action="store_true", help="convert every file the glob matches, in numeric order, onto one shared box, resolution and channel list")
    arguments = parser.parse_args()
    if not 2 <= arguments.max_resolution <= MAXIMUM_AXIS:
        parser.error(f"--max-resolution must be 2 to {MAXIMUM_AXIS}")
    name_map = {}
    for entry in arguments.map:
        channel, _, grid_name = entry.partition("=")
        if channel not in CHANNEL_NAMES or not grid_name:
            parser.error(f"--map takes CHANNEL=GRID with CHANNEL one of {', '.join(CHANNEL_NAMES)}")
        name_map[channel] = (grid_name,)
    if not arguments.sequence:
        grids = read_vdb(arguments.vdb)
        chosen = choose_channels(grids, name_map, arguments.vdb)
        density_leaves = leaves_of(grids[chosen["density"]])
        if not density_leaves:
            raise SystemExit(f"{arguments.vdb}: the density grid has no voxels")
        box_minimum, box_maximum = bounds_of(density_leaves)
        convert(grids, chosen, density_leaves, box_minimum, box_maximum, arguments, Path(arguments.vdb).name, arguments.output)
        return
    files = sorted(glob.glob(arguments.vdb), key=natural_key)
    if not files:
        raise SystemExit(f"no file matches {arguments.vdb!r}; quote the glob so the shell passes it on")
    if len(files) > MAXIMUM_SEQUENCE_FRAMES:
        raise SystemExit(f"{len(files)} files match, over the {MAXIMUM_SEQUENCE_FRAMES} frames a sequence may hold; narrow the glob")
    convert_sequence(files, name_map, arguments)


if __name__ == "__main__":
    main()