@nodetool-ai/blender-nodes 0.8.1

package/README.md

@@ -0,0 +1,36 @@
+# @nodetool-ai/blender-nodes
+
+Headless Blender nodes for NodeTool: render glTF scenes to images, image
+sequences and render passes, and prepare meshes for a game engine.
+
+The nodes shell out to a Blender binary, resolved by `blender-binary.ts` from
+`BLENDER_PATH` or the platform's usual install locations. Without a
+Blender install the nodes fail their preflight with the path they looked for —
+they never silently produce an empty render.
+
+## Nodes
+
+| Node | Does |
+|---|---|
+| `RenderImage` | One frame of a glTF scene |
+| `RenderAnimation` | A frame range, returned as a video |
+| `RenderPasses` | Per-pass output (depth, normal, cryptomatte, …) |
+| `PrepareForEngine` | Mesh cleanup, decimation and export for engine import |
+| `ExportModel` | Convert a scene between the formats Blender writes |
+
+## Usage
+
+Install the package alongside the runtime and it registers with the node
+registry like any other node package:
+
+```bash
+npm install @nodetool-ai/blender-nodes
+```
+
+Run a single node without a graph:
+
+```bash
+nodetool node run nodetool.blender.RenderImage --props '{"scene": "..."}'
+```
+
+See [AGENTS.md](../../AGENTS.md) for the repo-wide build and test commands.

package/blender_ops/depth.py

@@ -0,0 +1,133 @@
+"""Depth normalization for the `render_passes` op (D4).
+
+Pure Python, no `bpy` import, so `tests/test_depth.py` runs under system
+Python as well as Blender's own interpreter.
+
+Contracts:
+
+- `depth`: linear distance along the camera view axis, in scene units, from
+  the Z pass. `png16` (default) normalizes to `[0, 65535]` between
+  `depth_near` and `depth_far` — the min and max finite depth over the
+  foreground (masked) pixels — with background `65535`. `exr` keeps the raw
+  float with background `+inf`, rewritten from the `1e10` sentinel the
+  staged file carries.
+"""
+
+import struct
+import zlib
+
+#: 16-bit value written for background (masked-out or non-finite) pixels.
+BACKGROUND16 = 65535
+
+_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def _isfinite(value):
+    return value != float("inf") and value != float("-inf") and value == value
+
+
+def depth_range(depths, foreground):
+    """Min/max finite depth over the foreground pixels.
+
+    `depths` is the Z channel in row-major order, `foreground` a parallel
+    mask (nonzero is foreground). Returns `(near, far)`. Raises
+    `ValueError` when no foreground pixel carries a finite depth.
+    """
+    near = float("inf")
+    far = float("-inf")
+    for depth, mask in zip(depths, foreground):
+        if not mask:
+            continue
+        if not _isfinite(depth):
+            continue
+        if depth < near:
+            near = depth
+        if depth > far:
+            far = depth
+    if near == float("inf"):
+        raise ValueError("no foreground pixel carries a finite depth")
+    return near, far
+
+
+def normalize_to_u16(depths, foreground, near, far):
+    """Map depths to `[0, 65535]`: foreground `near -> 0`, `far -> 65535`.
+
+    Background (unmasked) and non-finite pixels map to `65535`. A degenerate
+    range (`far <= near`, e.g. one fronto-parallel plane) maps finite
+    foreground to `0` instead of dividing by zero.
+    """
+    span = far - near
+    values = []
+    for depth, mask in zip(depths, foreground):
+        if not mask or not _isfinite(depth):
+            values.append(BACKGROUND16)
+        elif span <= 0:
+            values.append(0)
+        else:
+            scaled = (depth - near) / span
+            if scaled < 0:
+                scaled = 0
+            elif scaled > 1:
+                scaled = 1
+            values.append(int(round(scaled * BACKGROUND16)))
+    return values
+
+
+def _chunk(kind, payload):
+    return (
+        struct.pack(">I", len(payload))
+        + kind
+        + payload
+        + struct.pack(">I", zlib.crc32(kind + payload) & 0xFFFFFFFF)
+    )
+
+
+def _check_fills(values, width, height, channels, label):
+    if len(values) != width * height * channels:
+        raise ValueError(
+            "%s values %d do not fill %dx%dx%d"
+            % (label, len(values), width, height, channels)
+        )
+
+
+def _write_png(path, width, height, bit_depth, color_type, raw):
+    ihdr = struct.pack(">IIBBBBB", width, height, bit_depth, color_type, 0, 0, 0)
+    with open(path, "wb") as handle:
+        handle.write(_PNG_SIGNATURE)
+        handle.write(_chunk(b"IHDR", ihdr))
+        handle.write(_chunk(b"IDAT", zlib.compress(bytes(raw))))
+        handle.write(_chunk(b"IEND", b""))
+
+
+def write_gray16_png(path, width, height, values):
+    """Write 16-bit grayscale PNG: big-endian samples, filter 0 per row."""
+    _check_fills(values, width, height, 1, "depth")
+    raw = bytearray()
+    for row in range(height):
+        raw.append(0)
+        for col in range(width):
+            raw += struct.pack(">H", values[row * width + col])
+    _write_png(path, width, height, 16, 0, raw)
+
+
+def write_gray8_png(path, width, height, values):
+    """Write 8-bit grayscale PNG (the mask pass): filter 0 per row."""
+    _check_fills(values, width, height, 1, "mask")
+    raw = bytearray()
+    for row in range(height):
+        raw.append(0)
+        for col in range(width):
+            raw.append(values[row * width + col])
+    _write_png(path, width, height, 8, 0, raw)
+
+
+def write_rgb8_png(path, width, height, values):
+    """Write 8-bit RGB PNG (the normal pass): filter 0 per row."""
+    _check_fills(values, width, height, 3, "normal")
+    raw = bytearray()
+    for row in range(height):
+        raw.append(0)
+        for col in range(width):
+            base = (row * width + col) * 3
+            raw += bytes(values[base : base + 3])
+    _write_png(path, width, height, 8, 2, raw)

package/blender_ops/errors.py

@@ -0,0 +1,46 @@
+"""Error classes shared by `run_job.py` and the op modules.
+
+An op failure carries its `result.json` error code on the class, so
+`run_job.py` turns it into `ok: false` with the code from the class and the
+message from the exception. Imported before `sys.excepthook` is installed:
+this module imports nothing, so the import itself cannot fail.
+"""
+
+
+class BlenderOpError(Exception):
+    """An op failure with a `result.json` error code on the class."""
+
+    code = "render_failed"
+
+    def __init__(self, message="", code=None):
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+
+
+class BadJob(BlenderOpError):
+    code = "bad_job"
+
+
+class ImportFailed(BlenderOpError):
+    code = "import_failed"
+
+
+class NoGeometry(BlenderOpError):
+    code = "no_geometry"
+
+
+class NoCamera(BlenderOpError):
+    code = "no_camera"
+
+
+class RenderFailed(BlenderOpError):
+    code = "render_failed"
+
+
+class ExportFailed(BlenderOpError):
+    code = "export_failed"
+
+
+class BakeFailed(BlenderOpError):
+    code = "bake_failed"

package/blender_ops/exr.py

@@ -0,0 +1,205 @@
+"""Minimal OpenEXR reader for the compositor's staged passes.
+
+Blender's File Output node writes multilayer scanline EXR that this
+Blender's own `bpy.data.images.load` surfaces as a 0x0 image, so the op
+reads the bytes directly. Only the shape Blender writes under
+`--factory-startup` is supported, and the reader refuses anything else
+rather than guessing:
+
+- single-part scanline image, increasing line order,
+- `NO_COMPRESSION` (Blender's default for file outputs),
+- `FLOAT` channels (depth and normal passes are float),
+- one chunk per scanline holding every channel in file order.
+
+Pure Python, no `bpy`: `tests/test_exr.py` (inside `test_depth.py`) covers
+it with a synthetic file, and the T4 passes suite covers it against Blender.
+"""
+
+import struct
+
+_MAGIC = b"v/1\x01"
+
+_NO_COMPRESSION = 0
+
+_FLOAT = 2
+_HALF = 1
+
+_TYPE_SIZES = {_FLOAT: 4, _HALF: 2}
+
+
+class ExrError(ValueError):
+    """The file is not the scanline EXR shape this reader supports."""
+
+
+def _read_cstring(blob, pos):
+    end = blob.index(b"\x00", pos)
+    return blob[pos:end].decode("utf-8"), end + 1
+
+
+def _parse_header(blob):
+    if blob[:4] != _MAGIC:
+        raise ExrError("not an EXR file")
+    (version,) = struct.unpack("<I", blob[4:8])
+    if version & 0x200:
+        raise ExrError("tiled EXR is not supported")
+    if version & 0x800:
+        raise ExrError("multipart EXR is not supported")
+    if version & 0x400:
+        raise ExrError("long-name EXR is not supported")
+    pos = 8
+    attrs = {}
+    while True:
+        name, pos = _read_cstring(blob, pos)
+        if name == "":
+            break
+        _type, pos = _read_cstring(blob, pos)
+        (size,) = struct.unpack("<i", blob[pos : pos + 4])
+        pos += 4
+        attrs[name] = blob[pos : pos + size]
+        pos += size
+    return attrs, pos
+
+
+def _parse_channels(raw):
+    channels = []
+    pos = 0
+    while pos < len(raw):
+        name, pos = _read_cstring(raw, pos)
+        if name == "":
+            break
+        pixel_type = struct.unpack("<i", raw[pos : pos + 4])[0]
+        x_sampling = struct.unpack("<i", raw[pos + 8 : pos + 12])[0]
+        y_sampling = struct.unpack("<i", raw[pos + 12 : pos + 16])[0]
+        pos += 16
+        channels.append((name, pixel_type, x_sampling, y_sampling))
+    return channels
+
+
+def read_exr_rgba(path):
+    """Read R, G, B channels as float lists in row-major order.
+
+    Returns `(width, height, r, g, b)`. Channel lookup is by suffix: the
+    compositor writes `*.R`, `*.G`, `*.B` (multilayer prefixes the socket
+    layer, e.g. `Image.R`). Raises `ExrError` on any other shape.
+    """
+    with open(path, "rb") as handle:
+        blob = handle.read()
+    attrs, pos = _parse_header(blob)
+    (compression,) = struct.unpack("B", attrs["compression"][:1])
+    if compression != _NO_COMPRESSION:
+        raise ExrError("compressed EXR (codec %d) is not supported" % (compression,))
+    (x0, y0, x1, y1) = struct.unpack("<iiii", attrs["dataWindow"])
+    width, height = x1 - x0 + 1, y1 - y0 + 1
+    channels = _parse_header_channels(attrs)
+    if any(s != (1, 1) for _, _, s in channels):
+        raise ExrError("subsampled EXR channels are not supported")
+    for _, pixel_type, _ in channels:
+        if pixel_type not in _TYPE_SIZES:
+            raise ExrError("non-float EXR channel is not supported")
+
+    offsets = struct.unpack("<%dq" % (height,), blob[pos : pos + 8 * height])
+    found = {}
+    for row, offset in enumerate(offsets):
+        (y,) = struct.unpack("<i", blob[offset : offset + 4])
+        if y != y0 + row:
+            raise ExrError("scanline %d out of order" % (row,))
+        (size,) = struct.unpack("<i", blob[offset + 4 : offset + 8])
+        cursor = offset + 8
+        for name, pixel_type, _ in channels:
+            count = width * _TYPE_SIZES[pixel_type]
+            chunk = blob[cursor : cursor + count]
+            if len(chunk) != count:
+                raise ExrError("scanline %d is truncated" % (row,))
+            cursor += count
+            values = _decode(chunk, pixel_type)
+            found.setdefault(name, []).extend(values)
+        if cursor != offset + 8 + size:
+            raise ExrError("scanline %d size mismatch" % (row,))
+
+    def channel(suffix):
+        for name, values in found.items():
+            if name == suffix or name.endswith("." + suffix):
+                return values
+        raise ExrError("EXR has no .%s channel" % (suffix,))
+
+    return width, height, channel("R"), channel("G"), channel("B")
+
+
+def _parse_header_channels(attrs):
+    raw = attrs.get("channels")
+    if raw is None:
+        raise ExrError("EXR has no channel list")
+    channels = [
+        (name, pixel_type, (xs, ys))
+        for name, pixel_type, xs, ys in _parse_channels(raw)
+    ]
+    if not channels:
+        raise ExrError("EXR has no channels")
+    return channels
+
+
+def _is_color_channel(name):
+    return name in ("R", "G", "B") or name.endswith((".R", ".G", ".B"))
+
+
+def rewrite_background_to_inf(path, foreground):
+    """Set every non-foreground sample of a staged depth EXR to `+inf`.
+
+    The compositor stages the raw Z pass, whose off-geometry pixels carry
+    the no-hit sentinel (`1e10`, measured on Blender 5.2.1 on both EEVEE
+    and Cycles) instead of the `+inf` the `render_passes` contract
+    promises for `depth_format: "exr"`. `foreground` is the row-major
+    mask the op resolved from this same file (`True` is foreground):
+    every other sample becomes `+inf` in each R/G/B-suffixed float
+    channel, foreground samples are untouched. Refuses files outside
+    the shape `read_exr_rgba` supports.
+    """
+    with open(path, "rb") as handle:
+        blob = bytearray(handle.read())
+    attrs, pos = _parse_header(blob)
+    (compression,) = struct.unpack("B", attrs["compression"][:1])
+    if compression != _NO_COMPRESSION:
+        raise ExrError("compressed EXR (codec %d) is not supported" % (compression,))
+    (x0, y0, x1, y1) = struct.unpack("<iiii", attrs["dataWindow"])
+    width, height = x1 - x0 + 1, y1 - y0 + 1
+    if len(foreground) != width * height:
+        raise ValueError(
+            "foreground mask %d does not fill %dx%d"
+            % (len(foreground), width, height)
+        )
+    channels = _parse_header_channels(attrs)
+    if any(s != (1, 1) for _, _, s in channels):
+        raise ExrError("subsampled EXR channels are not supported")
+    for _, pixel_type, _ in channels:
+        if pixel_type not in _TYPE_SIZES:
+            raise ExrError("non-float EXR channel is not supported")
+
+    offsets = struct.unpack("<%dq" % (height,), blob[pos : pos + 8 * height])
+    for row, offset in enumerate(offsets):
+        (y,) = struct.unpack("<i", blob[offset : offset + 4])
+        if y != y0 + row:
+            raise ExrError("scanline %d out of order" % (row,))
+        (size,) = struct.unpack("<i", blob[offset + 4 : offset + 8])
+        cursor = offset + 8
+        for name, pixel_type, _ in channels:
+            sample = _TYPE_SIZES[pixel_type]
+            if _is_color_channel(name):
+                if pixel_type == _FLOAT:
+                    inf = struct.pack("<f", float("inf"))
+                else:
+                    inf = struct.pack("<e", float("inf"))
+                for col in range(width):
+                    if not foreground[row * width + col]:
+                        start = cursor + col * sample
+                        blob[start : start + sample] = inf
+            cursor += width * sample
+        if cursor != offset + 8 + size:
+            raise ExrError("scanline %d size mismatch" % (row,))
+    with open(path, "wb") as handle:
+        handle.write(bytes(blob))
+
+
+def _decode(chunk, pixel_type):
+    if pixel_type == _FLOAT:
+        return list(struct.unpack("<%df" % (len(chunk) // 4,), chunk))
+    return list(struct.unpack("<%de" % (len(chunk) // 2,), chunk))

package/blender_ops/framing.py

@@ -0,0 +1,75 @@
+"""Auto-framing math for the Blender orbit camera.
+
+A line-for-line port of `computeFraming` and `orbitOffset` from
+`packages/video-nodes/src/nodes/model3d/render3d-core.ts`: same math, same
+names (snake_cased). The two sides are pinned to the same golden camera
+position by `tests/framing.test.ts` (TypeScript) and
+`blender_ops/tests/test_framing.py` (this interpreter).
+
+The offsets are in the three.js convention (Y up). `ops/render_image.py`
+rotates them rigidly into Blender space when placing the camera; the
+functions here stay identical so the cross-language pin holds.
+
+`apply_camera_lens` is the one function here that is not part of that port:
+it writes the framing onto a camera datablock, and lives beside the math so
+that what `fov` means (the vertical axis) is decided in one place. It touches
+no bpy API, so `tests/test_camera_lens.py` exercises it without Blender.
+"""
+
+import math
+
+
+def compute_framing(radius, fov_deg, aspect, zoom):
+    """Distance fitting a bounding sphere of `radius` into the frame.
+
+    `zoom` > 1 moves closer. Returns a dict with `distance`, `near`, `far`.
+    """
+    safe_radius = max(radius, 1e-6)
+    v_fov = (max(fov_deg, 1) * math.pi) / 180
+    h_fov = 2 * math.atan(math.tan(v_fov / 2) * max(aspect, 1e-6))
+    fit_v = safe_radius / math.sin(v_fov / 2)
+    fit_h = safe_radius / math.sin(h_fov / 2)
+    distance = max(fit_v, fit_h) / max(zoom, 1e-3)
+    return {
+        "distance": distance,
+        "near": max(distance - safe_radius * 4, distance / 100, 1e-4),
+        "far": distance + safe_radius * 10,
+    }
+
+
+def orbit_offset(azimuth_deg, elevation_deg, distance):
+    """Spherical-to-cartesian offset for the orbit camera (Y up)."""
+    az = (azimuth_deg * math.pi) / 180
+    el = (min(max(elevation_deg, -89.9), 89.9) * math.pi) / 180
+    return {
+        "x": distance * math.cos(el) * math.sin(az),
+        "y": distance * math.sin(el),
+        "z": distance * math.cos(el) * math.cos(az),
+    }
+
+
+def apply_camera_lens(data, fov_deg, framing):
+    """Give a camera datablock the vertical fov `fov_deg` and `framing`'s clips.
+
+    `fov` means the *vertical* field of view on both sides of this stack:
+    `compute_framing` fits the bounding sphere against `v_fov`, and the
+    three.js preview sets `PerspectiveCamera.fov`, which is vertical too. So
+    the fit is `VERTICAL` and the angle is written through `angle_y`, which
+    always resolves against `sensor_height`.
+
+    Bare `angle` would not: it resolves against whichever axis `sensor_fit`
+    names, so writing it before the fit is set means the 36mm sensor *width*
+    and leaves a 35 degree request as a 23.7 degree camera — a 1.52x tighter
+    crop that no longer fits the sphere `compute_framing` measured. Two
+    callers wrote `angle` in opposite orders and rendered the same model at
+    two sizes; `angle_y` makes the order irrelevant.
+
+    Takes the datablock instead of importing bpy, so the rule is testable
+    outside Blender (`tests/test_camera_lens.py`).
+    """
+    data.sensor_fit = "VERTICAL"
+    # The same clamp `compute_framing` applies, so the lens and the distance
+    # it computed always describe one camera.
+    data.angle_y = math.radians(max(fov_deg, 1))
+    data.clip_start = framing["near"]
+    data.clip_end = framing["far"]

package/blender_ops/ops/__init__.py

@@ -0,0 +1,24 @@
+"""Blender op modules. Stage 3 adds `prepare_for_engine` and `export_model`.
+
+Each op exposes `run(job, workdir) -> (produced, stats)` where `job` is the
+parsed `job.json` dict, `workdir` the scratch directory holding the inputs,
+`produced` the logical output names written, and `stats` the fields for
+`result.json`. An op raises `BlenderOpError` (or a subclass) on failure;
+`run_job.py` turns it into `ok: false` with the code from the class.
+"""
+
+from ops.export_model import run as export_model
+from ops.prepare_for_engine import run as prepare_for_engine
+from ops.render_animation import run as render_animation
+from ops.render_image import run as render_image
+from ops.render_passes import run as render_passes
+
+DISPATCH = {
+    "render_image": render_image,
+    "render_passes": render_passes,
+    "render_animation": render_animation,
+    "prepare_for_engine": prepare_for_engine,
+    "export_model": export_model,
+}
+
+__all__ = ["DISPATCH"]