3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
"""Convert Crucible volume grid files (.67vg) to OpenVDB files, the reverse of scripts/vdb-to-grid.py. Runs inside Blender's Python, which ships `openvdb`.
blender -b --factory-startup --python scripts/grid-to-vdb.py -- blast.67vg out/
blender -b --factory-startup --python scripts/grid-to-vdb.py -- sim_frames_folder out/ --size 4 3 4
Each input is one .67vg file, a folder of them (numeric order) or several paths; every one becomes <name>.vdb in the output folder with FloatGrids
named density, temperature and flame (the channels the file has), plus velocity_x, velocity_y and velocity_z when it has the velocity channels. Used by scripts/cycles-volume-reference.py, which renders them in Cycles as the
reference for Crucible's grid volumes (docs/volumetric.md, "Cycles reference for grid volumes").
Placement convention (src/local-volumes.js, localVolumeGridSample): a grid volume fills the box [center - size/2, center + size/2] in Crucible's
y up world, texel i of an axis is centred at (i + 0.5) / resolution of the box (sampleVolumeGrid), and x is the fastest axis in the file. Here the
box is centred on the VDB origin (the render script moves it to the volume's `center`), the world size is the header `size` or `--size`, and the
voxel centres are on the same half-voxel offsets. Blender is z up, so Crucible (x, y, z) becomes Blender (x, -z, y), a rotation with no mirroring
(the inverse of the turn vdb-to-grid.py applies). Voxels may be anisotropic when size / resolution differs per axis. The size in Crucible units is
also stored as the grid's `crucible_size` metadata ("x y z"), so a render can rescale a grid to another `size`.
"""
import argparse
import json
import struct
import sys
from pathlib import Path
import numpy
import openvdb
CHANNEL_NAMES = ("density", "temperature", "flame")
# The gas velocity channels of a grid (#1759), written as three scalar grids in Blender's axes (x, -Crucible z, Crucible y) for Cycles' motion blur
# (Volume Data > Velocity X, Y, Z grid); the values stay in the header size units per second.
VELOCITY_GRIDS = (("velocity_x", "velocityX", 1.0), ("velocity_y", "velocityZ", -1.0), ("velocity_z", "velocityY", 1.0))
def read_volume_grid(path):
"""Returns (resolution, size or None, {channel: float32 array[x][y][z]}) from a .67vg file."""
data = Path(path).read_bytes()
if data[:4] != b"67VG":
raise ValueError(f"{path} is not a Crucible volume grid (missing the 67VG magic)")
version, header_length = struct.unpack_from("<II", data, 4)
if version != 1:
raise ValueError(f"{path} is grid file version {version}; this script reads version 1")
header = json.loads(data[12:12 + header_length].decode("utf-8"))
resolution = header["resolution"]
cell_count = resolution[0] * resolution[1] * resolution[2]
offset = 12 + header_length
channels = {}
for name in header["channels"]:
halves = numpy.frombuffer(data, dtype="<f2", count=cell_count, offset=offset)
offset += cell_count * 2
channels[name] = halves.astype(numpy.float32).reshape(resolution[2], resolution[1], resolution[0]).transpose(2, 1, 0)
return resolution, header.get("size"), channels
def write_vdb(path, resolution, size, channels):
size_x, size_y, size_z = size
voxel = (size_x / resolution[0], size_z / resolution[2], size_y / resolution[1]) # Blender axes: x, y = -Crucible z, z = Crucible y
minimum = (-size_x / 2, -size_z / 2, -size_y / 2)
transform = openvdb.createLinearTransform([
[voxel[0], 0, 0, 0],
[0, voxel[1], 0, 0],
[0, 0, voxel[2], 0],
[minimum[0] + voxel[0] / 2, minimum[1] + voxel[1] / 2, minimum[2] + voxel[2] / 2, 1],
])
grids = []
sources = [(name, channels[name]) for name in CHANNEL_NAMES if name in channels]
if all(source in channels for _, source, _ in VELOCITY_GRIDS):
sources += [(name, channels[source] * sign) for name, source, sign in VELOCITY_GRIDS]
for name, values in sources:
in_blender_axes = numpy.ascontiguousarray(numpy.flip(values, axis=2).transpose(0, 2, 1))
grid = openvdb.FloatGrid()
grid.name = name
grid.transform = transform
grid.copyFromArray(in_blender_axes)
grid["crucible_size"] = " ".join(f"{extent:.9g}" for extent in size)
grids.append(grid)
openvdb.write(str(path), grids)
def input_files(entries):
files = []
for entry in entries:
path = Path(entry)
if path.is_dir():
files.extend(sorted(path.glob("*.67vg")))
elif path.exists():
files.append(path)
else:
raise SystemExit(f"{entry} does not exist; pass a .67vg file or a folder of them")
if not files:
raise SystemExit("no .67vg files found")
return files
def main():
arguments_after_separator = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else sys.argv[1:]
parser = argparse.ArgumentParser(prog="grid-to-vdb.py", description=__doc__.split("\n")[0])
parser.add_argument("paths", nargs="+", help="one or more .67vg files or folders, then the output folder as the last item")
parser.add_argument("--size", nargs=3, type=float, metavar=("X", "Y", "Z"), help="world size in Crucible units when the header has none, or to override it")
arguments = parser.parse_args(arguments_after_separator)
if len(arguments.paths) < 2:
parser.error("give at least one input and the output folder")
output_folder = Path(arguments.paths[-1])
output_folder.mkdir(parents=True, exist_ok=True)
for path in input_files(arguments.paths[:-1]):
resolution, header_size, channels = read_volume_grid(path)
size = arguments.size or header_size
if not size:
raise SystemExit(f"{path} has no size in its header; pass --size X Y Z")
target = output_folder / (path.stem + ".vdb")
write_vdb(target, resolution, size, channels)
print(f"wrote {target}: {resolution[0]}x{resolution[1]}x{resolution[2]} voxels, channels {list(channels)}, size {list(size)}")
main()