@nodetool-ai/blender-nodes 0.8.1

package/blender_ops/ops/render_passes.py

@@ -0,0 +1,363 @@
+"""The `render_passes` op: glTF bytes in, control passes out (D4).
+
+Same scene setup as `render_image` (`ops/common.py`), plus a compositor
+node tree staging the raw float passes:
+
+- `color`: the beauty render, straight through `scene.render.filepath`.
+- `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 pixels, both returned in stats — with background `65535`.
+  `exr` keeps the raw float with background `+inf`, rewritten from the
+  `1e10` sentinel the staged file carries (see `BACKGROUND_DEPTH`).
+- `normal`: camera-space normals from the Normal pass, `[-1, 1]` mapped to
+  8-bit RGB, background `(128, 128, 255)`.
+- `mask`: 8-bit image, foreground `255`, from the object index pass — on
+  Cycles, where the pass exists. EEVEE's `CompositorNodeRLayers` exposes no
+  index socket (measured 5.2.1: `use_pass_object_index = True` is accepted
+  yet the node lists only Image/Alpha/Depth), so EEVEE keys the mask on
+  finite Z instead. The gate agrees with the index pass on opaque geometry
+  and disagrees for alpha-blended, holdout, and volume materials — a
+  recorded EEVEE-only deviation from D4, not an implementation of it.
+
+`params["passes"]` selects the subset to produce; the op writes and reports
+only those.
+
+Blender 5.x notes (measured, not assumed):
+
+- Compositing runs through `scene.compositing_node_group`; the legacy
+  `use_nodes`/`node_tree` pair is deprecated and `Scene.node_tree` is gone.
+  The legacy Math/Mix/MapRange nodes are gone too, so the tree stages RAW
+  passes only and every contract mapping runs in Python (`depth.py`).
+- A File Output node writes `<render-filepath>/<file_name>.<ext>`: the
+  base is the current render filepath, and an absolute `file_name` is
+  mangled (measured: `/tmp/wd/stage/x` lands at `/tmp/tmp/wd/stage/x.exr`
+  under the factory `/tmp/` base). The op therefore points the render
+  filepath at the workdir itself and stages through a relative subdir of
+  it, so a killed run leaves nothing outside the workdir — which the
+  runner deletes on every exit path.
+- A File Output node ignores its item-level format and always writes
+  multilayer EXR, so both staged passes are float EXR by construction.
+"""
+
+import os
+import shutil
+import time
+
+import bpy
+from mathutils import Vector
+
+from depth import depth_range, normalize_to_u16, write_gray8_png, write_gray16_png
+from depth import write_rgb8_png
+from errors import BadJob, RenderFailed
+from exr import read_exr_rgba, rewrite_background_to_inf
+from ops.common import setup_render_scene
+
+#: Staging directory for the raw float passes, inside the job's own
+#: working directory: one Blender runs per op invocation, and the runner
+#: deletes the workdir on every exit path, so no run can leak staged EXRs.
+#: A relative name, so the File Output node resolves it under the workdir
+#: the op points the render filepath at (see `run`).
+_STAGE_SUBDIR = "nodetool-passes-stage"
+
+
+#: Raw float passes the compositor stages.
+_DEPTH_RAW_SLOT = "depth_raw"
+_NORMAL_RAW_SLOT = "normal_raw"
+_INDEX_RAW_SLOT = "index_raw"
+
+#: Object index every mesh carries when the mask stages the index pass:
+#: background reads 0, so any positive index is foreground.
+_MASK_PASS_INDEX = 1
+
+#: Background constant for the normal map: exactly (128, 128, 255) in 8-bit.
+NORMAL_BACKGROUND = (128, 128, 255)
+
+#: No-hit Z value in the staged EXRs, measured on Blender 5.2.1: the
+#: staged Z pass is finite everywhere and off-geometry pixels read
+#: exactly this value on both EEVEE and Cycles. A real surface never
+#: reaches it (the far clip sits at distance + radius * 10, single
+#: digits), so foreground is finite depth below this value on both
+#: engines. This constant is a measured staging behavior, not a
+#: documented Blender API value: re-measure it if the version floor
+#: moves.
+BACKGROUND_DEPTH = 1e10
+
+
+def _is_foreground(value):
+    return value == value and value != float("inf") and value != float("-inf") and value < BACKGROUND_DEPTH
+
+
+def _selected_passes(params):
+    passes = params.get("passes", ["color", "depth", "normal", "mask"])
+    if not isinstance(passes, list) or not passes:
+        raise BadJob("render_passes needs a non-empty 'passes' list")
+    known = {"color", "depth", "normal", "mask"}
+    for name in passes:
+        if name not in known:
+            raise BadJob("unknown pass %r: choose from %s" % (name, sorted(known)))
+    return passes
+
+
+def _build_compositor(stage_index):
+    # Passes are enabled before the Render Layers node is created so its
+    # sockets exist when linked. Both raw passes always stage: the mask and
+    # the depth stats share the depth resolve, so depth is needed even when
+    # only the mask is selected. `file_name` stays relative so it resolves
+    # under the workdir the render filepath points at; an absolute value
+    # would be mangled under the factory `/tmp/` base instead.
+    scene = bpy.context.scene
+    view_layer = scene.view_layers[0]
+    view_layer.use_pass_z = True
+    view_layer.use_pass_normal = True
+    # The index socket only exists on Cycles (measured 5.2.1: EEVEE lists
+    # Image/Alpha/Depth with the flag on), so it is enabled only when the
+    # mask will actually stage it — and before the node is created.
+    if stage_index:
+        view_layer.use_pass_object_index = True
+
+    group = bpy.data.node_groups.new("NodeTool_Passes", "CompositorNodeTree")
+    scene.compositing_node_group = group
+    layers = group.nodes.new("CompositorNodeRLayers")
+
+    staged = [(_DEPTH_RAW_SLOT, "Depth"), (_NORMAL_RAW_SLOT, "Normal")]
+    if stage_index:
+        if "Object Index" not in [output.name for output in layers.outputs]:
+            raise RenderFailed(
+                "object index pass has no socket on %s" % (scene.render.engine,)
+            )
+        staged.append((_INDEX_RAW_SLOT, "Object Index"))
+    for slot, socket in staged:
+        node = group.nodes.new("CompositorNodeOutputFile")
+        node.file_output_items.clear()
+        node.file_output_items.new("RGBA", "Image")
+        node.file_name = os.path.join(_STAGE_SUBDIR, slot)
+        group.links.new(layers.outputs[socket], node.inputs[0])
+
+
+def _camera_basis(camera_obj):
+    """Rows of the world-to-camera rotation: maps world normals to camera space."""
+    return camera_obj.matrix_world.to_3x3().transposed()
+
+
+def _to_camera_space(basis, normal):
+    vector = basis @ Vector(normal)
+    length = vector.length
+    if length < 1e-12:
+        return None
+    return (vector.x / length, vector.y / length, vector.z / length)
+
+
+def _map_normal(rgb, basis):
+    """World-space normal to 8-bit RGB in camera space, `[-1, 1]` to `[0, 255]`."""
+    camera = _to_camera_space(basis, rgb)
+    if camera is None:
+        return None
+    out = []
+    for component in camera:
+        scaled = component * 0.5 + 0.5
+        if scaled < 0:
+            scaled = 0
+        elif scaled > 1:
+            scaled = 1
+        out.append(int(round(scaled * 255)))
+    return out
+
+
+def _collect_staged(workdir, stage_index):
+    """Move the staged EXRs into the workdir; fail loudly when one is missing."""
+    stage_dir = os.path.join(workdir, _STAGE_SUBDIR)
+    try:
+        seen = sorted(os.listdir(stage_dir))
+    except OSError:
+        seen = []
+    staged = {}
+    slots = [_DEPTH_RAW_SLOT, _NORMAL_RAW_SLOT]
+    if stage_index:
+        slots.append(_INDEX_RAW_SLOT)
+    for slot in slots:
+        src = os.path.join(stage_dir, slot + ".exr")
+        if not os.path.exists(src):
+            # Name the directory: a missing stage file means the File Output
+            # resolved elsewhere, and the guess list is what debugs it.
+            raise RenderFailed(
+                "compositor stage file %r is missing (staged: %s)"
+                % (slot + ".exr", seen)
+            )
+        dst = os.path.join(workdir, slot + ".exr")
+        os.replace(src, dst)
+        staged[slot] = dst
+    shutil.rmtree(stage_dir, ignore_errors=True)
+    return staged
+
+
+def run(job, workdir):
+    """Run `render_passes`. Returns `(produced, stats)`."""
+    params = job["job"]["params"]
+    outputs = job["outputs"]
+    passes = _selected_passes(params)
+    for name in passes:
+        if name not in outputs:
+            raise BadJob("render_passes pass %r declares no output file" % (name,))
+    depth_format = params.get("depth_format", "png16")
+    if "depth" in passes and depth_format not in ("png16", "exr"):
+        raise BadJob("unknown depth_format %r" % (depth_format,))
+
+    scene, meshes, center, radius, camera_obj = setup_render_scene(job, workdir)
+    stage_dir = os.path.join(workdir, _STAGE_SUBDIR)
+    os.makedirs(stage_dir, exist_ok=True)
+    try:
+        return _run_passes(job, workdir, params, outputs, passes, depth_format,
+                           scene, meshes, camera_obj)
+    finally:
+        # The stage subdir never lingers outside the workdir, and the runner
+        # deletes the workdir itself on every exit path — including the
+        # SIGKILL path where this `finally` never runs.
+        shutil.rmtree(stage_dir, ignore_errors=True)
+
+
+def _run_passes(job, workdir, params, outputs, passes, depth_format,
+                scene, meshes, camera_obj):
+    # The File Output base is the render filepath, snapshotted when the
+    # node is created — so the filepath points at the workdir itself
+    # (trailing separator: a directory, not a file) before the compositor
+    # is built, and the relative stage names resolve inside it. Color is
+    # saved from the Render Result afterwards, so its location stays exact
+    # either way.
+    scene.render.image_settings.file_format = "PNG"
+    scene.render.image_settings.color_mode = "RGBA"
+    scene.render.image_settings.color_depth = "8"
+    scene.render.filepath = workdir + os.sep
+    # The mask stages the object index pass where it exists (Cycles) and
+    # shares the depth resolve where it does not (EEVEE).
+    stage_index = "mask" in passes and scene.render.engine == "CYCLES"
+    if stage_index:
+        for obj in meshes:
+            obj.pass_index = _MASK_PASS_INDEX
+    _build_compositor(stage_index)
+
+    started = time.monotonic()
+    try:
+        bpy.ops.render.render()
+    except Exception as exc:
+        raise RenderFailed("render failed: %s" % (exc,))
+    render_seconds = time.monotonic() - started
+    if "color" in passes:
+        try:
+            bpy.data.images["Render Result"].save_render(
+                os.path.join(workdir, outputs["color"])
+            )
+        except Exception as exc:
+            raise RenderFailed("color save failed: %s" % (exc,))
+
+    produced = []
+    stats = {
+        "blender_version": bpy.app.version_string,
+        "render_seconds": render_seconds,
+        "objects": len(meshes),
+        "camera": camera_obj.name,
+    }
+    if "color" in passes:
+        produced.append("color")
+
+    # Depth stages whenever the mask, the normal background, or depth
+    # itself needs it: all three share the foreground resolve.
+    need_depth = bool({"depth", "mask", "normal"} & set(passes))
+    need_normal = "normal" in passes
+    staged = (
+        _collect_staged(workdir, stage_index)
+        if (need_depth or need_normal)
+        else {}
+    )
+
+    depths, foreground, width, height = None, None, 0, 0
+    if need_depth:
+        width, height, depths, _depth_g, _depth_b = read_exr_rgba(
+            staged[_DEPTH_RAW_SLOT]
+        )
+        # Foreground is finite Z below the no-hit sentinel: the staged
+        # EXR carries 1e10 off-geometry on both engines (measured
+        # 5.2.1). The EEVEE mask shares this resolve; the Cycles mask
+        # keys on its own index pass below.
+        foreground = [_is_foreground(value) for value in depths]
+    if "mask" in passes:
+        if stage_index:
+            index_width, index_height, index_r, _g, _b = read_exr_rgba(
+                staged[_INDEX_RAW_SLOT]
+            )
+            if need_depth and (index_width, index_height) != (width, height):
+                raise RenderFailed(
+                    "depth (%dx%d) and index (%dx%d) sizes disagree"
+                    % (width, height, index_width, index_height)
+                )
+            width, height = index_width, index_height
+            # Background reads exactly 0; every mesh carries
+            # `_MASK_PASS_INDEX`, so any positive index is foreground.
+            foreground = [value > 0.5 for value in index_r]
+        else:
+            assert depths is not None and foreground is not None
+        assert foreground is not None
+        write_gray8_png(
+            os.path.join(workdir, outputs["mask"]),
+            width,
+            height,
+            [255 if on else 0 for on in foreground],
+        )
+        produced.append("mask")
+    if "normal" in passes:
+        assert foreground is not None
+        normal_width, normal_height, nx, ny, nz = read_exr_rgba(
+            staged[_NORMAL_RAW_SLOT]
+        )
+        if (normal_width, normal_height) != (width, height):
+            raise RenderFailed(
+                "depth (%dx%d) and normal (%dx%d) sizes disagree"
+                % (width, height, normal_width, normal_height)
+            )
+        # The Normal pass is world-space (measured: axis-aligned on an
+        # orbit render); D4 wants camera space, so rotate by the camera.
+        basis = _camera_basis(camera_obj)
+        rgb = []
+        for i in range(width * height):
+            if not foreground[i]:
+                rgb += list(NORMAL_BACKGROUND)
+                continue
+            mapped = _map_normal((nx[i], ny[i], nz[i]), basis)
+            if mapped is None:
+                rgb += list(NORMAL_BACKGROUND)
+            else:
+                rgb += mapped
+        write_rgb8_png(os.path.join(workdir, outputs["normal"]), width, height, rgb)
+        produced.append("normal")
+    if "depth" in passes:
+        assert depths is not None and foreground is not None
+        try:
+            near, far = depth_range(depths, foreground)
+        except ValueError:
+            raise RenderFailed("depth pass has no finite foreground depth")
+        stats["depth_near"] = near
+        stats["depth_far"] = far
+        if depth_format == "exr":
+            # The staged EXR carries the 1e10 no-hit sentinel where the
+            # contract promises +inf: rewrite the background samples
+            # first, keyed on the same foreground resolve the png16 path
+            # uses. Foreground samples are untouched.
+            rewrite_background_to_inf(staged[_DEPTH_RAW_SLOT], foreground)
+            os.replace(
+                staged[_DEPTH_RAW_SLOT], os.path.join(workdir, outputs["depth"])
+            )
+        else:
+            values = normalize_to_u16(depths, foreground, near, far)
+            write_gray16_png(
+                os.path.join(workdir, outputs["depth"]), width, height, values
+            )
+            os.remove(staged[_DEPTH_RAW_SLOT])
+        produced.append("depth")
+
+    # Drop whichever staged EXR survived (unselected depth keeps its raw,
+    # and the index raw is consumed only into the mask).
+    for slot in (_DEPTH_RAW_SLOT, _NORMAL_RAW_SLOT, _INDEX_RAW_SLOT):
+        leftover = os.path.join(workdir, slot + ".exr")
+        if os.path.exists(leftover):
+            os.remove(leftover)
+    return produced, stats

package/blender_ops/run_job.py

@@ -0,0 +1,110 @@
+"""Blender entry point: read `job.json`, run the op, always write `result.json`.
+
+Invocation (built by `LocalBlenderRunner`):
+
+    blender -b --factory-startup --disable-autoexec \\
+        --python-exit-code 64 --python <asset_dir>/run_job.py -- job.json
+
+`job.json` carries the `BlenderJob` (D4): version, logical input/output file
+names, and `{ op, params }`. `result.json` carries the `BlenderResult`:
+`ok: true` with the produced names and stats, or `ok: false` with a code and
+a message. Exit code 64 is reserved for "the script raised", distinct from
+Blender's own crash codes.
+
+`sys.excepthook` is installed before the op modules are imported, so an
+import error also lands in `result.json` instead of only on stderr.
+"""
+
+import json
+import os
+import sys
+import traceback
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from errors import BlenderOpError  # noqa: E402 — stdlib-only, cannot fail
+
+JOB_VERSION = 1
+
+
+def _result_path():
+    return os.path.join(os.getcwd(), "result.json")
+
+
+def _write_result(payload):
+    try:
+        with open(_result_path(), "w", encoding="utf-8") as handle:
+            json.dump(payload, handle)
+    except Exception as exc:  # noqa: BLE001 — last resort must not raise
+        sys.stderr.write("run_job: cannot write result.json: %s\n" % (exc,))
+
+
+def _code_of(exc):
+    code = getattr(exc, "code", None)
+    if isinstance(code, str) and code:
+        return code
+    return "render_failed"
+
+
+def _install_excepthook():
+    def _hook(exc_type, exc_value, exc_tb):
+        message = "".join(
+            traceback.format_exception(exc_type, exc_value, exc_tb)
+        ).strip()[-2000:]
+        _write_result(
+            {"ok": False, "error": {"code": _code_of(exc_value), "message": message}}
+        )
+        sys.__excepthook__(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _hook
+
+
+_install_excepthook()
+
+from ops import DISPATCH  # noqa: E402 — after the excepthook on purpose
+
+
+def _job_path():
+    candidates = [arg for arg in sys.argv[1:] if arg != "--"]
+    if candidates:
+        path = candidates[-1]
+    else:
+        path = "job.json"
+    if not os.path.isabs(path):
+        path = os.path.join(os.getcwd(), path)
+    return path
+
+
+def main():
+    path = _job_path()
+    try:
+        with open(path, encoding="utf-8") as handle:
+            job = json.load(handle)
+    except Exception as exc:
+        raise BlenderOpError("cannot read job.json: %s" % (exc,), "bad_job")
+
+    if not isinstance(job, dict) or job.get("version") != JOB_VERSION:
+        version = job.get("version") if isinstance(job, dict) else None
+        raise BlenderOpError(
+            "unsupported job version %r: run_job.py speaks version %d"
+            % (version, JOB_VERSION),
+            "bad_job",
+        )
+
+    inner = job.get("job")
+    if not isinstance(inner, dict) or not isinstance(inner.get("op"), str):
+        raise BlenderOpError("job carries no op name", "bad_job")
+    op_name = inner["op"]
+    run = DISPATCH.get(op_name)
+    if run is None:
+        raise BlenderOpError(
+            "unknown op %r: this run_job.py serves %s" % (op_name, sorted(DISPATCH)),
+            "bad_job",
+        )
+
+    produced, stats = run(job, os.getcwd())
+    _write_result({"ok": True, "produced": produced, "stats": stats})
+
+
+if __name__ == "__main__":
+    main()

package/blender_ops/tests/test_camera_lens.py

@@ -0,0 +1,107 @@
+"""Pin `apply_camera_lens` to the vertical fov, with no Blender in sight.
+
+`framing.apply_camera_lens` writes onto a camera datablock but imports no bpy,
+so this file runs under plain `python3` as well as under Blender's own
+interpreter. `tests/camera-lens.test.ts` drives it both ways.
+
+The stub below reproduces the two RNA properties that matter, from Blender's
+`rna_camera.cc`: `angle` reads and writes `lens` against whichever sensor axis
+`sensor_fit` names, while `angle_y` always uses `sensor_height`. That
+difference is the bug this file guards: the still ops built the orbit camera
+and wrote `angle` while the fit was still `AUTO` (so, the 36mm width), and the
+sampled bake wrote `angle` again on the same camera once the fit was
+`VERTICAL` (the 24mm height). Same params, two focal lengths, two pictures.
+
+Plain asserts only: Blender's Python has no pytest.
+"""
+
+import math
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
+
+from framing import apply_camera_lens, compute_framing
+
+
+class FakeCameraData(object):
+    """`bpy.types.Camera`'s lens properties, as Blender computes them."""
+
+    def __init__(self):
+        # What `bpy.data.cameras.new()` returns.
+        self.sensor_width = 36.0
+        self.sensor_height = 24.0
+        self.sensor_fit = "AUTO"
+        self.lens = 50.0
+        self.clip_start = 0.1
+        self.clip_end = 100.0
+
+    def _fit_sensor(self):
+        if self.sensor_fit == "VERTICAL":
+            return self.sensor_height
+        return self.sensor_width
+
+    @property
+    def angle(self):
+        return 2 * math.atan(self._fit_sensor() / (2 * self.lens))
+
+    @angle.setter
+    def angle(self, value):
+        self.lens = self._fit_sensor() / (2 * math.tan(value / 2))
+
+    @property
+    def angle_y(self):
+        return 2 * math.atan(self.sensor_height / (2 * self.lens))
+
+    @angle_y.setter
+    def angle_y(self, value):
+        self.lens = self.sensor_height / (2 * math.tan(value / 2))
+
+
+def check(label, actual, expected, tolerance=1e-6):
+    if abs(actual - expected) > tolerance:
+        print("MISMATCH %s: got %r want %r" % (label, actual, expected))
+        sys.exit(1)
+
+
+FOV = 35.0
+RADIUS = 1.5
+ASPECT = 160.0 / 120.0
+FRAMING = compute_framing(RADIUS, FOV, ASPECT, 1.0)
+
+# 1. The requested fov is the vertical one, and the clips come from the framing.
+fresh = FakeCameraData()
+apply_camera_lens(fresh, FOV, FRAMING)
+check("vertical fov", math.degrees(fresh.angle_y), FOV, 1e-9)
+check("sensor fit", 1.0 if fresh.sensor_fit == "VERTICAL" else 0.0, 1.0)
+check("clip_start", fresh.clip_start, FRAMING["near"])
+check("clip_end", fresh.clip_end, FRAMING["far"])
+
+# 2. The lens does not depend on the fit the camera arrived with. A camera the
+#    sampled bake re-places is already VERTICAL; a camera `make_orbit_camera`
+#    just created is AUTO. Writing `angle` gave those two 57.09mm and 38.06mm.
+placed_again = FakeCameraData()
+placed_again.sensor_fit = "VERTICAL"
+apply_camera_lens(placed_again, FOV, FRAMING)
+check("lens is fit-independent", placed_again.lens, fresh.lens, 1e-9)
+check("lens", fresh.lens, 24.0 / (2 * math.tan(math.radians(FOV) / 2)), 1e-9)
+
+# 3. The lens and the distance `compute_framing` returned describe one camera:
+#    the bounding sphere the distance was fitted to is inside the frame. The
+#    36mm-wide reading failed this — 0.3007 of a sphere against a 0.2102 frame.
+half_height = math.tan(fresh.angle_y / 2)
+if RADIUS / FRAMING["distance"] > half_height + 1e-9:
+    print(
+        "MISMATCH sphere fit: radius/distance %r exceeds tan(vfov/2) %r"
+        % (RADIUS / FRAMING["distance"], half_height)
+    )
+    sys.exit(1)
+
+# 4. The fov clamp matches `compute_framing`'s, so a degenerate fov still
+#    leaves the lens and the distance agreeing.
+tiny = FakeCameraData()
+tiny_framing = compute_framing(RADIUS, 0.0, ASPECT, 1.0)
+apply_camera_lens(tiny, 0.0, tiny_framing)
+check("clamped fov", math.degrees(tiny.angle_y), 1.0, 1e-9)
+
+print("camera lens ok")