@deepblend/dsh-blender-provider-local 0.1.0

package/python/deepblend_util.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Shared helpers for the DeepBlend Blender-side bootstrap actions.
+
+Everything in this module runs inside Blender's embedded CPython interpreter. It
+is deliberately free of ``bpy`` imports: it is the part of the runtime that can
+be read, reasoned about and reviewed as plain Python.
+
+CONTRACT DISCIPLINE
+-------------------
+Two rules run through the whole Blender-side runtime and are worth stating once:
+
+1. **The result is a JSON document written to a caller-supplied path.** stdout is
+   never a result channel: Blender writes banners, add-on chatter and progress
+   lines to stdout, so anything that parses stdout is parsing around noise. Short
+   diagnostics go to stderr prefixed with ``[deepblend]`` and are informational.
+
+2. **The SceneSpec is the authority, not the .blend.** The compiler applies every
+   transform, visibility flag and animation TRACK, but it never treats a
+   pre-existing object as something to preserve. That is what makes a rebuild
+   reproducible and what makes "the spec changed" and "the scene changed" the
+   same statement (SPEC §8.1).
+
+Standard library only, plus whatever the caller's action module needs.
+"""
+
+import json
+import os
+import sys
+import tempfile
+import traceback
+
+#: Protocol version for the request/result envelope. Bumped only on a breaking
+#: wire change; ``bootstrap.py`` refuses a request that disagrees.
+PROTOCOL_VERSION = "deepblend.blender/v1"
+
+
+def eprint(message):
+    """Emit an informational diagnostic on stderr. Never part of the contract."""
+    try:
+        sys.stderr.write("[deepblend] %s\n" % (message,))
+        sys.stderr.flush()
+    except Exception:
+        # Diagnostics must never be able to break a run.
+        pass
+
+
+def as_text(value):
+    """Coerce a bpy value into plain JSON-safe text.
+
+    ``bpy.app.build_hash`` is ``bytes`` (``b'9e2066aef7ef'``) and blindly
+    JSON-encoding that fails, so every leaf scalar that reaches JSON passes
+    through here.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bytes):
+        try:
+            return value.decode("utf-8", "replace")
+        except Exception:
+            return repr(value)
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    try:
+        return str(value)
+    except Exception:
+        return None
+
+
+def error_text(exc):
+    """Render an exception as a compact, JSON-safe ``"Type: message"`` string."""
+    try:
+        return "%s: %s" % (type(exc).__name__, exc)
+    except Exception:
+        return "unprintable exception"
+
+
+#: Frame-sequence file naming. The host computes expected paths from the same
+#: rule (`frameFileName` in @deepblend/dsh-blender-contracts) to build the frame
+#: ledger, so the two must agree byte for byte — a disagreement makes every frame
+#: read as missing. These live here, in the bpy-free module, so the contract test
+#: can compare the two implementations WITHOUT launching Blender; a naming rule
+#: that can only be checked by a 1-second process launch is a rule that gets
+#: checked by nobody.
+FRAME_FILE_PREFIX = "frame_"
+FRAME_FILE_PADDING = 4
+
+
+def frame_file_name(frame, prefix=FRAME_FILE_PREFIX, padding=FRAME_FILE_PADDING):
+    """The exact file name one frame is written to.
+
+    MEASURED, and the reason the renderer sets its own output path: on Blender
+    5.2.1, `scene.render.frame_path(frame=f)` PREDICTS `<dir>/frame_0001.png`
+    while `bpy.ops.render.render(write_still=True)` writes `<dir>/frame_.png`.
+    """
+    return "%s%0*d.png" % (prefix, int(padding), int(frame))
+
+
+def frame_path(directory, frame, prefix=FRAME_FILE_PREFIX, padding=FRAME_FILE_PADDING):
+    """The absolute path one frame is written to."""
+    return os.path.join(directory, frame_file_name(frame, prefix, padding))
+
+
+def write_json_atomic(path, document):
+    """Write ``document`` as pretty JSON, atomically.
+
+    The temp file is a sibling so the final ``os.replace`` stays on one
+    filesystem, where it is atomic. A reader therefore sees either the previous
+    file or the complete new one, never a half-written document.
+    """
+    directory = os.path.dirname(os.path.abspath(path))
+    if directory and not os.path.isdir(directory):
+        os.makedirs(directory, exist_ok=True)
+    handle, temporary = tempfile.mkstemp(
+        prefix=os.path.basename(path) + ".", suffix=".tmp", dir=directory or None
+    )
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(document, stream, indent=2, ensure_ascii=False, sort_keys=False)
+            stream.write("\n")
+        os.replace(temporary, path)
+    except Exception:
+        try:
+            os.unlink(temporary)
+        except Exception:
+            pass
+        raise
+
+
+def read_json(path):
+    """Read a JSON document, raising a message that names the file."""
+    with open(path, "r", encoding="utf-8") as stream:
+        return json.load(stream)
+
+
+def parse_args(argv, known_options):
+    """Parse ``--opt value`` / ``--opt=value`` tokens after a bare ``--``.
+
+    Blender consumes its own arguments before the separator; everything after it
+    belongs to the bootstrap script. Returns ``(options, unknown)`` where
+    ``options`` is a dict of the recognised keys (absent when not supplied) and
+    ``unknown`` lists anything unexpected, so the caller can fail loudly on a
+    typo instead of silently running with a default.
+    """
+    options = {}
+    unknown = []
+
+    try:
+        separator = argv.index("--")
+    except ValueError:
+        return options, unknown
+
+    tokens = list(argv[separator + 1:])
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        index += 1
+
+        inline_value = None
+        name = token
+        if token.startswith("--") and "=" in token:
+            name, inline_value = token.split("=", 1)
+
+        if name in known_options:
+            if inline_value is not None:
+                value = inline_value
+            elif index < len(tokens):
+                value = tokens[index]
+                index += 1
+            else:
+                unknown.append("%s (missing value)" % (name,))
+                continue
+            options[name.lstrip("-").replace("-", "_")] = value
+        elif token.startswith("--"):
+            unknown.append(token)
+
+    return options, unknown
+
+
+def report_progress(stage, percent, detail=None):
+    """Report progress on stdout as one JSON object per line (SPEC §9.3).
+
+    This is the ONE thing that legitimately goes to stdout, and it is
+    distinguishable by construction: each line is a complete JSON document with a
+    ``type`` key, so a consumer can filter Blender's own output by parsing rather
+    than by pattern-matching prose. It is advisory only — the contract is still
+    the result file.
+    """
+    payload = {"type": "progress", "stage": stage, "percent": percent}
+    if detail is not None:
+        payload["detail"] = detail
+    try:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+        sys.stdout.flush()
+    except Exception:
+        pass
+
+
+def warning(code, message, detail=None):
+    """Build one warning entry. Warnings degrade a success; they never throw."""
+    entry = {"code": code, "message": message}
+    if detail is not None:
+        entry["detail"] = detail
+    return entry
+
+
+class Guard:
+    """Collects warnings, notices and per-item decisions for one action.
+
+    One collector per action run, passed down rather than returned up, so a
+    decision made five call levels deep still reaches the caller's envelope. A
+    decision that is only visible in a log — or worse, only in the render — is the
+    most expensive kind of bug to find, so nothing is allowed to decide silently.
+    """
+
+    def __init__(self):
+        self.warnings = []
+        self.notices = []
+
+    def warn(self, code, message, detail=None):
+        self.warnings.append(warning(code, message, detail))
+
+    def note(self, code, message, detail=None):
+        self.notices.append(warning(code, message, detail))
+
+
+class ActionError(Exception):
+    """A classified failure that must reach the caller as a stable code.
+
+    ``code`` is a ``BlenderErrorCode`` value from the contracts package. The
+    ``bootstrap.py`` dispatcher converts this into an error envelope and a
+    non-zero exit code, so an unsupported or refused action is never mistaken for
+    a success with empty output.
+    """
+
+    def __init__(self, code, message, detail=None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.detail = detail
+
+
+def guard(handler):
+    """Run ``handler`` and return ``(result, error)``.
+
+    Used by the dispatcher so that a single action cannot take the process down
+    with an unhandled exception: every failure becomes a classified error
+    envelope, and a genuinely unexpected one still carries its traceback in the
+    detail for post-mortem.
+    """
+
+    def wrapped(*args, **kwargs):
+        try:
+            return handler(*args, **kwargs), None
+        except ActionError as exc:
+            return None, {"code": exc.code, "message": exc.message, "detail": exc.detail}
+        except Exception as exc:  # noqa: BLE001 - the boundary must catch everything
+            return None, {
+                "code": "BLENDER_SCRIPT_ERROR",
+                "message": error_text(exc),
+                "detail": {"traceback": traceback.format_exc()},
+            }
+
+    return wrapped

package/python/deepblend_validate.py

@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""DeepBlend technical scene validation.
+
+The seam between the two validation layers of SPEC §13.2:
+
+* **JSON Schema + semantic rules** run in Node, before Blender is launched, and
+  answer "is this document a coherent scene?" (`deepblend/contracts/lib/scene-spec.js`).
+* **This module** runs inside Blender, after a compile, and answers "did that
+  document actually become a renderable scene?" — a different question, and the
+  only one that can be answered with the real depsgraph in hand.
+
+The distinction is not academic. A SceneSpec can be perfectly valid and still
+compile to something a camera cannot photograph: an entity whose primitive
+produced no geometry, a scale of 0 that collapsed an object to a point, a camera
+aimed at a hidden object, or a frames-per-second of 0. Every one of those passes
+schema validation and fails here.
+
+Findings carry a severity:
+  - ``error``   — the scene must not be committed.
+  - ``warning`` — suspicious but renderable; the caller decides.
+  - ``notice``  — something the compiler decided, recorded for the audit trail.
+
+Runs inside Blender's embedded interpreter.
+"""
+
+import bpy
+from mathutils import Vector
+
+from deepblend_scene import ENTITY_PREFIX
+from deepblend_util import as_text, warning
+
+
+def _evaluated_bounds(obj):
+    """World-space bounding box of an evaluated object, or ``None``.
+
+    The evaluated object is used rather than the raw mesh so a modifier's effect
+    is included — without it, a bevel or a subsurf would be scored as if it did
+    nothing. ``obj.bound_box`` is in local space, so every corner is transformed.
+    """
+    try:
+        from bpy import context
+        depsgraph = context.evaluated_depsgraph_get()
+        evaluated = obj.evaluated_get(depsgraph)
+        corners = [evaluated.matrix_world @ Vector(corner) for corner in evaluated.bound_box]
+    except Exception:
+        return None
+    if not corners:
+        return None
+    return {
+        "min": [round(min(corner[axis] for corner in corners), 6) for axis in range(3)],
+        "max": [round(max(corner[axis] for corner in corners), 6) for axis in range(3)],
+    }
+
+
+def _box_size(bounds):
+    if bounds is None:
+        return None
+    return [round(bounds["max"][axis] - bounds["min"][axis], 6) for axis in range(3)]
+
+
+def validate_scene(scene, spec, guard):
+    """Validate the live scene against the spec that produced it.
+
+    ``guard`` receives warnings and notices so nothing found here is lost; the
+    returned report carries the errors plus the structural facts a golden test
+    asserts on (counts, bounds, frame range, camera parameters).
+    """
+    errors = []
+    artifacts = []
+
+    def fail(code, message, detail=None):
+        entry = {"severity": "error", "code": code, "message": message}
+        if detail is not None:
+            entry["detail"] = detail
+        errors.append(entry)
+
+    objects = [obj for obj in scene.objects]
+    meshes = [obj for obj in objects if obj.type == "MESH"]
+    lights = [obj for obj in objects if obj.type == "LIGHT"]
+    cameras = [obj for obj in objects if obj.type == "CAMERA"]
+
+    spec_entities = spec.get("entities") or []
+    spec_lights = spec.get("lights") or []
+    spec_cameras = spec.get("cameras") or []
+    spec_materials = spec.get("materials") or []
+    spec_tracks = spec.get("animationTracks") or []
+    spec_shots = spec.get("shots") or []
+
+    expected_mesh_entities = [entity for entity in spec_entities if entity.get("type") != "empty"]
+    if len(meshes) < len(expected_mesh_entities):
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "the spec declares %d renderable entit(y/ies) but the scene holds %d mesh object(s)"
+            % (len(expected_mesh_entities), len(meshes)),
+            {
+                "expected": len(expected_mesh_entities),
+                "actual": len(meshes),
+                "objects": sorted(obj.name for obj in meshes),
+            },
+        )
+    if len(lights) != len(spec_lights):
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "the spec declares %d light(s) but the scene holds %d" % (len(spec_lights), len(lights)),
+        )
+    if len(cameras) != len(spec_cameras):
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "the spec declares %d camera(s) but the scene holds %d" % (len(spec_cameras), len(cameras)),
+        )
+
+    # ---- geometry ---------------------------------------------------------
+    total_vertices = 0
+    total_polygons = 0
+    degenerate = []
+    for obj in meshes:
+        vertices = len(obj.data.vertices)
+        polygons = len(obj.data.polygons)
+        total_vertices += vertices
+        total_polygons += polygons
+        if vertices == 0 or polygons == 0:
+            degenerate.append(obj.name)
+        bounds = _evaluated_bounds(obj)
+        size = _box_size(bounds)
+        if size is not None and max(size) <= 1e-6:
+            degenerate.append(obj.name)
+    if degenerate:
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "%d object(s) have no usable geometry: %s" % (len(degenerate), ", ".join(sorted(set(degenerate)))),
+            {"objects": sorted(set(degenerate))},
+        )
+    if not meshes:
+        fail("SCENE_VALIDATION_FAILED", "the compiled scene contains no mesh object, so nothing can be rendered")
+
+    # ---- visibility -------------------------------------------------------
+    hidden_renderable = [
+        obj.name for obj in meshes
+        if obj.hide_render or obj.hide_viewport
+    ]
+    if len(hidden_renderable) == len(meshes) and meshes:
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "every mesh object is hidden; a render would contain no geometry",
+            {"objects": hidden_renderable},
+        )
+
+    # ---- cameras ----------------------------------------------------------
+    if not cameras:
+        fail("SCENE_VALIDATION_FAILED", "the scene contains no camera")
+    else:
+        for camera in cameras:
+            if camera.data.lens <= 0:
+                fail(
+                    "SCENE_VALIDATION_FAILED",
+                    'camera "%s" has lens %.4f; a non-positive focal length cannot form an image'
+                    % (camera.name, camera.data.lens),
+                )
+            if camera.data.clip_start >= camera.data.clip_end:
+                fail(
+                    "SCENE_VALIDATION_FAILED",
+                    'camera "%s" has clip_start %.4f >= clip_end %.4f'
+                    % (camera.name, camera.data.clip_start, camera.data.clip_end),
+                )
+            if scene.camera is None:
+                fail("SCENE_VALIDATION_FAILED", "no camera is active in the scene")
+            elif camera is scene.camera:
+                # Framing check on the ACTIVE camera only: whether the subject is
+                # inside the frustum is the single most valuable technical fact a
+                # preview can be checked against before spending a render on it.
+                framing = camera_framing(scene, camera, meshes)
+                if framing is not None and not framing["subjectInFrame"]:
+                    guard.warn(
+                        "SCENE_VALIDATION_FAILED",
+                        'the active camera "%s" does not appear to contain the scene subject'
+                        % (camera.name,),
+                        framing,
+                    )
+                if framing is not None:
+                    artifacts.append({"kind": "framing", **framing})
+
+    # ---- frame range and animation ---------------------------------------
+    project = spec.get("project") or {}
+    if scene.frame_start >= scene.frame_end:
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "frame range %d..%d is empty" % (scene.frame_start, scene.frame_end),
+        )
+    if scene.render.fps <= 0:
+        fail("SCENE_VALIDATION_FAILED", "fps is %d; a frame rate must be positive" % (scene.render.fps,))
+    if project.get("frameStart") is not None and scene.frame_start != int(project["frameStart"]):
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "scene frame_start is %d but the spec asks for %d" % (scene.frame_start, int(project["frameStart"])),
+        )
+    if project.get("frameEnd") is not None and scene.frame_end != int(project["frameEnd"]):
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "scene frame_end is %d but the spec asks for %d" % (scene.frame_end, int(project["frameEnd"])),
+        )
+
+    animated = [obj.name for obj in objects if obj.animation_data is not None and obj.animation_data.action is not None]
+    if spec_tracks and not animated:
+        fail(
+            "SCENE_VALIDATION_FAILED",
+            "the spec declares %d animation track(s) but no object carries an action" % (len(spec_tracks),),
+        )
+
+    # ---- materials --------------------------------------------------------
+    materials_in_use = {
+        material.name
+        for obj in meshes
+        for material in obj.data.materials
+        if material is not None
+    }
+    if spec_materials and not materials_in_use:
+        fail("SCENE_VALIDATION_FAILED", "the spec declares materials but no mesh references one")
+
+    # ---- shots ------------------------------------------------------------
+    camera_ids = {camera.get("deepblend_id") for camera in cameras}
+    for shot in spec_shots:
+        if shot.get("cameraId") not in camera_ids:
+            fail(
+                "SCENE_VALIDATION_FAILED",
+                'shot "%s" references camera "%s", which does not exist in the compiled scene'
+                % (shot.get("id"), shot.get("cameraId")),
+            )
+        frame_range = shot.get("frameRange")
+        if frame_range and (frame_range[0] < scene.frame_start or frame_range[1] > scene.frame_end):
+            guard.warn(
+                "SCENE_VALIDATION_FAILED",
+                'shot "%s" spans frames %d..%d, outside the project range %d..%d'
+                % (shot.get("id"), frame_range[0], frame_range[1], scene.frame_start, scene.frame_end),
+                {"shotId": shot.get("id"), "frameRange": frame_range},
+            )
+
+    report = {
+        "ok": len(errors) == 0,
+        "errors": errors,
+        "counts": {
+            "objects": len(objects),
+            "meshObjects": len(meshes),
+            "lightObjects": len(lights),
+            "cameraObjects": len(cameras),
+            "materials": len(bpy.data.materials),
+            "actions": len(bpy.data.actions),
+            "specEntities": len(spec_entities),
+            "specLights": len(spec_lights),
+            "specCameras": len(spec_cameras),
+            "specMaterials": len(spec_materials),
+            "specShots": len(spec_shots),
+            "specAnimationTracks": len(spec_tracks),
+        },
+        "geometry": {
+            "totalVertices": total_vertices,
+            "totalPolygons": total_polygons,
+            "degenerateObjects": sorted(set(degenerate)),
+            "hiddenRenderableObjects": sorted(hidden_renderable),
+        },
+        "frameRange": [int(scene.frame_start), int(scene.frame_end)],
+        "fps": int(scene.render.fps),
+        "engine": scene.render.engine,
+        "activeCamera": scene.camera.name if scene.camera is not None else None,
+        "animatedObjects": sorted(animated),
+        "bounds": scene_bounds(meshes),
+        "subjectBounds": subject_bounds(meshes),
+        "cameraParameters": [
+            {
+                "id": camera.get("deepblend_id"),
+                "name": camera.name,
+                "lens": round(float(camera.data.lens), 6),
+                "sensorWidth": round(float(camera.data.sensor_width), 6),
+                "location": [round(float(value), 6) for value in camera.location],
+                "rotationEuler": [round(float(value), 6) for value in camera.rotation_euler],
+            }
+            for camera in cameras
+        ],
+        "artifacts": artifacts,
+    }
+    return report
+
+
+def subject_bounds(meshes):
+    """Aggregate world-space bounds of every mesh, ignoring nothing.
+
+    Entities tagged ``environment`` in the spec cannot be excluded here because
+    the tag lives in the spec, not in the blend; the caller correlates the two
+    when it needs the subject alone.
+    """
+    boxes = [bounds for bounds in (_evaluated_bounds(obj) for obj in meshes) if bounds is not None]
+    if not boxes:
+        return None
+    return {
+        "min": [round(min(box["min"][axis] for box in boxes), 6) for axis in range(3)],
+        "max": [round(max(box["max"][axis] for box in boxes), 6) for axis in range(3)],
+    }
+
+
+def scene_bounds(meshes):
+    """Alias kept explicit so a reader can see both are intentionally reported."""
+    return subject_bounds(meshes)
+
+
+def camera_framing(scene, camera, meshes):
+    """Project the scene's mesh centres into the active camera's frustum.
+
+    Deliberately cheap: the eight corners of each object's bound box are projected
+    with ``world_to_camera_view`` and compared against the unit frame. This is not
+    a hidden-surface analysis and does not claim to be one — it answers "is the
+    subject somewhere in front of the lens", which is the question worth asking
+    before paying for a render.
+    """
+    try:
+        from bpy_extras.object_utils import world_to_camera_view
+    except Exception:
+        return None
+    if not meshes:
+        return None
+
+    inside = 0
+    considered = 0
+    projected = []
+    for obj in meshes:
+        bounds = _evaluated_bounds(obj)
+        if bounds is None:
+            continue
+        considered += 1
+        corners = [
+            Vector((bounds["min"][0] if bit & 1 else bounds["max"][0],
+                    bounds["min"][1] if bit & 2 else bounds["max"][1],
+                    bounds["min"][2] if bit & 4 else bounds["max"][2]))
+            for bit in range(8)
+        ]
+        in_frame = False
+        for corner in corners:
+            coordinate = world_to_camera_view(scene, camera, corner)
+            if coordinate.z > 0 and 0.0 <= coordinate.x <= 1.0 and 0.0 <= coordinate.y <= 1.0:
+                in_frame = True
+        if in_frame:
+            inside += 1
+            centre = Vector(((bounds["min"][0] + bounds["max"][0]) / 2,
+                             (bounds["min"][1] + bounds["max"][1]) / 2,
+                             (bounds["min"][2] + bounds["max"][2]) / 2))
+            coordinate = world_to_camera_view(scene, camera, centre)
+            projected.append({
+                "object": obj.name,
+                "uv": [round(coordinate.x, 4), round(coordinate.y, 4)],
+                "depth": round(coordinate.z, 4),
+            })
+
+    return {
+        "cameraId": camera.get("deepblend_id"),
+        "consideredObjects": considered,
+        "objectsInFrame": inside,
+        "subjectInFrame": inside > 0,
+        "projectedCentres": projected,
+    }