@deepblend/dsh-blender-provider-local 0.14.0 → 0.16.0

package/lib/index.js

@@ -44,6 +44,7 @@ import {
   BlenderWarningCode,
   assertKnownConfigKeys,
   managedBlenderCandidates,
+  normalizeShotCameraSelection,
   resolveWorkspaceRoot,
   warning,
 } from '@deepblend/dsh-blender-contracts'
@@ -55,6 +56,26 @@ export const BLENDER_RUNTIME_SERVICE = 'blenderRuntime'
 const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024
 /** Default cap for the spill file that holds the complete stream. */
 const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024
+/** Cumulative decoded scene images; individual image limits remain separate. */
+const DEFAULT_SCENE_IMAGE_MIB = 1024
+
+/**
+ * Build one scrubbed environment without requiring private receiver methods.
+ * @param {{ maxSceneImageMiB?: number }} config
+ * @param {unknown} jobId
+ * @returns {Record<string, string>}
+ */
+function bootstrapEnvironment(config, jobId) {
+  return {
+    PATH: process.env.PATH ?? '',
+    HOME: process.env.HOME ?? '',
+    TMPDIR: process.env.TMPDIR ?? '',
+    PYTHONUNBUFFERED: '1',
+    PYTHONDONTWRITEBYTECODE: '1',
+    DEEPBLEND_JOB_ID: String(jobId ?? ''),
+    DEEPBLEND_SCENE_IMAGE_BUDGET_MIB: String(config.maxSceneImageMiB ?? DEFAULT_SCENE_IMAGE_MIB),
+  }
+}
 
 /** Grace period between SIGTERM and SIGKILL when terminating Blender. */
 const TERMINATE_GRACE_MS = 10_000
@@ -140,6 +161,8 @@ export const ProviderConfig = z.object({
   maxOutputBytes: z.number().default(DEFAULT_MAX_OUTPUT_BYTES),
   /** Cap on the spill file holding the complete stream. */
   maxSpillBytes: z.number().default(DEFAULT_MAX_SPILL_BYTES),
+  /** Pre-build decoded-image estimate in MiB; scene/tool arguments cannot raise it. */
+  maxSceneImageMiB: z.number().min(16).max(8192).step(1).default(DEFAULT_SCENE_IMAGE_MIB),
   /** Extra directories added to the executable allowlist. */
   executableAllowlist: z.array(z.string()).default([]),
   /** How long a capabilities result may be reused before re-probing. */
@@ -614,6 +637,10 @@ export default class LocalBlenderRuntime extends Service {
     // See the host's constructor: a key this row does not read is a startup error, because the schema
     // accepts it silently (SPEC §17's nested groups versus this package's flat keys).
     assertKnownConfigKeys(ProviderConfig, config, 'deepblend-blender-runtime')
+    const imageMiB = config.maxSceneImageMiB ?? DEFAULT_SCENE_IMAGE_MIB
+    if (!Number.isInteger(imageMiB) || imageMiB < 16 || imageMiB > 8192) {
+      throw new Error('maxSceneImageMiB must be an integer from 16 through 8192 MiB.')
+    }
     // A CONFIGURED ACTION THAT CANNOT BE ROUTED IS REFUSED AT STARTUP, not ignored. Naming a render
     // here would leave the operator believing their renders now run in their own Blender, while the
     // render quietly kept its own process — the same shape as a key this row does not read, which the
@@ -623,7 +650,7 @@ export default class LocalBlenderRuntime extends Service {
       throw new Error(
         `sessionActions names ${unroutable.map(action => `"${action}"`).join(', ')}, and this provider can only ` +
         `serve ${SESSION_ROUTABLE_ACTIONS.join(', ')} from a kept session. The renders that must be cancellable ` +
-        '(`render_frames`) spawn their own process on purpose: cancelling one kills exactly that render, and a ' +
+        '(`render_frames`, `render_shot_frames`) spawn their own process on purpose: cancelling one kills exactly that render, and a ' +
         'request inside a kept session cannot be killed without ending the session — which, attached, is the ' +
         'user\'s own Blender.',
       )
@@ -859,6 +886,7 @@ export default class LocalBlenderRuntime extends Service {
     }
   }
 
+
   /**
    * Run one bootstrap action end-to-end.
    *
@@ -902,6 +930,7 @@ export default class LocalBlenderRuntime extends Service {
    * @param {{ cwd?: string, args?: string[], signal?: AbortSignal }} [options]
    * @returns {Promise<{ pid: number|null, run: (request: object, options?: object) => Promise<object>, close: () => Promise<void> }>}
    */
+
   async openSession(options = {}) {
     if (!existsSync(this.bootstrapPath)) {
       throw new BlenderError(
@@ -945,6 +974,7 @@ export default class LocalBlenderRuntime extends Service {
       },
       graceMs: TERMINATE_GRACE_MS,
       signal: options.signal,
+      env: bootstrapEnvironment(this.config, jobId),
     })
 
     const session = new BlenderSession({
@@ -975,6 +1005,11 @@ export default class LocalBlenderRuntime extends Service {
    * @returns {Promise<{ pid: number|null, run: Function, close: Function }>}
    */
   async attachSession(socketPath, options = {}) {
+    if ((this.config.maxSceneImageMiB ?? DEFAULT_SCENE_IMAGE_MIB) !== DEFAULT_SCENE_IMAGE_MIB) {
+      throw new BlenderError(BlenderErrorCode.UNSUPPORTED_ACTION,
+        'A custom maxSceneImageMiB requires a managed Blender process. Clear sessionSocket, ' +
+        'or use the default 1024 MiB when attaching to an existing Blender.')
+    }
     if (typeof socketPath !== 'string' || socketPath.length === 0) {
       throw new BlenderError(
         BlenderErrorCode.RUNTIME_UNAVAILABLE,
@@ -1207,17 +1242,9 @@ export default class LocalBlenderRuntime extends Service {
         },
         graceMs: TERMINATE_GRACE_MS,
         signal: composedSignal,
-        env: {
-          // Scrub anything that could carry a secret into the child (SPEC §15.5:
-          // the DeepSeek API key must never reach the Blender subprocess).
-          PATH: process.env.PATH ?? '',
-          HOME: process.env.HOME ?? '',
-          TMPDIR: process.env.TMPDIR ?? '',
-          // Deterministic, unbuffered Python so partial output is never lost.
-          PYTHONUNBUFFERED: '1',
-          PYTHONDONTWRITEBYTECODE: '1',
-          DEEPBLEND_JOB_ID: correlationId,
-        },
+        // The operator budget and scrubbed environment apply to every owned
+        // process; caller payloads and inherited environment cannot raise it.
+        env: bootstrapEnvironment(this.config, correlationId),
       })
     } catch (cause) {
       clearTimeout(timer)
@@ -1587,6 +1614,8 @@ export default class LocalBlenderRuntime extends Service {
       assertDigest(await digest(snapshot))
       const run = await this.runBootstrap({ action: 'inspect_geometry', jobId: request.jobId,
         payload: { entityIds: request.entityIds, frame: request.frame, checkpointSha256: expected,
+          ...(request.assetInstanceIds === undefined ? {} : { assetInstanceIds: request.assetInstanceIds }),
+          ...(request.cameraId === undefined ? {} : { cameraId: request.cameraId, cameraMargin: request.cameraMargin ?? .03 }),
           ...(request.objectAxes === true ? { objectAxes: true } : {}),
           ...(request.surfaceSamples === undefined ? {} : { surfaceSamples: request.surfaceSamples }) } },
       { signal: request.signal, session: false, args: ['--blend', snapshot] })
@@ -1597,6 +1626,7 @@ export default class LocalBlenderRuntime extends Service {
       if (request.objectAxes === true && run.envelope?.result?.schemaVersion !== 'deepblend.geometry-inspection/v3') {
         throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Blender bootstrap does not support object-local native bounds. Upgrade DeepBlend; ordinary reads remain available.')
       }
+      if ((request.assetInstanceIds !== undefined || request.cameraId !== undefined) && run.envelope?.result?.schemaVersion !== 'deepblend.geometry-inspection/v4') throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Blender bootstrap does not support aggregate asset bounds; upgrade DeepBlend.')
       const report = verifyGeometryReport(run.envelope?.result, request)
       assertDigest(await digest(source))
       aborted()
@@ -1730,6 +1760,18 @@ export default class LocalBlenderRuntime extends Service {
    *   processPath: string, argv: string[], startedAt: number, executable: string}>}
    */
   async startFrameSequence(request) {
+    return LocalBlenderRuntime.prototype._startFrameSequence.call(this, request, { action: 'render_frames' })
+  }
+
+  /** Explicit opt-in; an older bootstrap refuses the distinct action before rendering. */
+  async startShotFrameSequence(request) {
+    if (request?.cameraId != null) throw new BlenderError(BlenderErrorCode.SCENE_SPEC_INVALID,
+      'A shot-camera sequence cannot also select one camera.')
+    const cameraSelection = normalizeShotCameraSelection(request?.cameraSelection, request?.frames)
+    return LocalBlenderRuntime.prototype._startFrameSequence.call(this, request, { action: 'render_shot_frames', cameraSelection })
+  }
+
+  async _startFrameSequence(request, selection) {
     if (typeof request?.checkpointPath !== 'string' || request.checkpointPath.length === 0) {
       throw new BlenderError(
         BlenderErrorCode.REVISION_CHECKPOINT_MISSING,
@@ -1808,6 +1850,7 @@ export default class LocalBlenderRuntime extends Service {
       attemptToken: request.attemptToken ?? null,
       checkpoint: request.checkpointPath,
       cameraId: request.cameraId ?? null,
+      ...(selection.cameraSelection === undefined ? {} : { cameraSelection: selection.cameraSelection }),
       profileName: request.profileName ?? null,
       profile: request.profile ?? {},
       frameRange: request.frameRange ?? null,
@@ -1820,7 +1863,7 @@ export default class LocalBlenderRuntime extends Service {
     writeFileSync(requestPath, JSON.stringify({
       protocolVersion: BLENDER_PROTOCOL_VERSION,
       jobId: request.jobId ?? null,
-      action: 'render_frames',
+      action: selection.action,
     }, null, 2), 'utf8')
 
     const argv = [
@@ -1859,14 +1902,7 @@ export default class LocalBlenderRuntime extends Service {
         // timeout indistinguishable from a caller's cancellation in the record.
         // Cancellation goes through `handle.terminate()`, which the host calls
         // from `cancelJob`.
-        env: {
-          PATH: process.env.PATH ?? '',
-          HOME: process.env.HOME ?? '',
-          TMPDIR: process.env.TMPDIR ?? '',
-          PYTHONUNBUFFERED: '1',
-          PYTHONDONTWRITEBYTECODE: '1',
-          DEEPBLEND_JOB_ID: String(request.jobId ?? ''),
-        },
+        env: bootstrapEnvironment(this.config, request.jobId),
       })
     } catch (cause) {
       throw new BlenderError(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "description": "Local Blender Provider: the BlenderRuntime Service over ctx.subprocess (batch execution).",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.14.0"
+    "@deepblend/dsh-blender-contracts": "0.16.0"
   },
   "license": "MIT",
   "repository": {

package/python/bootstrap.py

@@ -33,6 +33,8 @@ ACTIONS (M3)
                       at a named SceneSpec render profile, into a persistent
                       directory. Long-running and resumable: the host passes only
                       the frames the frame ledger says are missing.
+``render_shot_frames`` the same isolated process boundary, with a strict saved-shot
+                      selection and actual per-frame camera/PNG attribution.
 
 ACTIONS (M2)
 ------------
@@ -103,6 +105,7 @@ SUPPORTED_ACTIONS = (
     "render_preview",
     "render_views",
     "render_frames",
+    "render_shot_frames",
 )
 
 # Process exit codes. 0 is reserved for a successfully written success envelope.
@@ -370,7 +373,7 @@ def action_render_views(request, options):
     return payload, guard.warnings, guard.notices
 
 
-def action_render_frames(request, options):
+def action_render_frames(request, options, require_camera_selection=False):
     """Render an explicit frame list at a named render profile (M3).
 
     The plan travels as a FILE for the same reason the view plan does, and the
@@ -408,10 +411,14 @@ def action_render_frames(request, options):
     plan["events"] = options.get("events") or plan.get("events")
 
     guard = Guard()
-    payload = render_frames(plan, guard)
+    payload = render_frames(plan, guard, require_camera_selection=require_camera_selection)
     return payload, guard.warnings, guard.notices
 
 
+def action_render_shot_frames(request, options):
+    return action_render_frames(request, options, require_camera_selection=True)
+
+
 def write_process_identity(path, job_id, action, attempt_token=None):
     """Record this process's own pid, atomically, before any Blender work.
 
@@ -449,11 +456,11 @@ def write_process_identity(path, job_id, action, attempt_token=None):
 def _attempt_token_from_plan(action, options):
     """The attempt token, when the action's input document carries one.
 
-    Only `render_frames` has a plan file; every other action answers None, and the
+    Both frame actions have a plan file; every other action answers None, and the
     identity document simply records no token. Read here rather than threaded
     through every action because the token belongs to the PROCESS, not to the work.
     """
-    if action != "render_frames":
+    if action not in ("render_frames", "render_shot_frames"):
         return None
     plan_path = options.get("frames")
     if not plan_path or not os.path.isfile(plan_path):
@@ -492,6 +499,7 @@ ACTIONS = {
     "render_preview": action_render_preview,
     "render_views": action_render_views,
     "render_frames": action_render_frames,
+    "render_shot_frames": action_render_shot_frames,
 }
 
 

package/python/deepblend_frames.py

@@ -48,6 +48,7 @@ Runs inside Blender's embedded interpreter.
 import hashlib
 import json
 import os
+import re
 import time
 
 import bpy
@@ -258,7 +259,55 @@ def verify_frame(path, expected_width, expected_height):
     return {"ok": True, "bytes": size, "width": width, "height": height}
 
 
-def render_frames(plan, guard):
+def shot_camera_selection(scene, plan, requested, required):
+    value = plan.get("cameraSelection")
+    if not required:
+        if value is not None:
+            raise ActionError("SCENE_SPEC_INVALID", "Shot camera selection requires render_shot_frames; the legacy render action never guesses cuts.")
+        return None, {}
+    fail = lambda message: ActionError("SCENE_SPEC_INVALID", "Shot camera selection: " + message)
+    if (not isinstance(value, dict) or set(value) != {"schemaVersion", "mode", "shots"}
+            or value.get("schemaVersion") != "deepblend.shot-camera-selection/v1" or value.get("mode") != "shots"
+            or not isinstance(value.get("shots"), list) or not 1 <= len(value["shots"]) <= 64
+            or plan.get("cameraId") is not None):
+        raise fail("an explicit bounded saved-shot selection without a single-camera override is required.")
+    if any(isinstance(frame, bool) or not isinstance(frame, int) or abs(frame) > 9007199254740991 for frame in plan.get("frames", [])):
+        raise fail("requested frames must be safe integers.")
+    shots, seen = [], set()
+    for shot in value["shots"]:
+        if not isinstance(shot, dict) or set(shot) != {"id", "cameraId", "frameRange"}:
+            raise fail("each shot needs exactly id, cameraId and frameRange.")
+        for key in ("id", "cameraId"):
+            if not isinstance(shot[key], str) or not re.fullmatch(r"[a-zA-Z][a-zA-Z0-9._-]{0,127}", shot[key]):
+                raise fail("shot and camera IDs must be saved identifiers.")
+        bounds = shot["frameRange"]
+        if (shot["id"] in seen or not isinstance(bounds, list) or len(bounds) != 2
+                or any(isinstance(v, bool) or not isinstance(v, int) or abs(v) > 9007199254740991 for v in bounds)
+                or bounds[0] > bounds[1]):
+            raise fail("distinct shots need ordered integer frame ranges.")
+        seen.add(shot["id"])
+        shots.append({"id": shot["id"], "cameraId": shot["cameraId"], "frameRange": list(bounds)})
+    shots.sort(key=lambda shot: (shot["frameRange"][0], shot["id"]))
+    for before, after in zip(shots, shots[1:]):
+        if after["frameRange"][0] <= before["frameRange"][1]:
+            raise fail("saved shot ranges overlap.")
+    selection = {"schemaVersion": "deepblend.shot-camera-selection/v1", "mode": "shots", "shots": shots}
+    if len(json.dumps(selection, separators=(",", ":")).encode("utf-8")) > 8192:
+        raise fail("selection exceeds its 8192-byte metadata budget.")
+    # Resolve every named native camera before writing any frame. An absent
+    # camera is a refusal, never a fallback to the checkpoint's active camera.
+    cameras = {shot["cameraId"]: find_camera(scene, shot["cameraId"])[0] for shot in shots}
+    selected = {}
+    for frame in requested:
+        matches = [shot for shot in shots if shot["frameRange"][0] <= frame <= shot["frameRange"][1]]
+        if len(matches) != 1:
+            raise fail("frame %d must belong to exactly one saved shot." % frame)
+        shot = matches[0]
+        selected[frame] = (cameras[shot["cameraId"]], shot["id"], shot["cameraId"])
+    return selection, selected
+
+
+def render_frames(plan, guard, require_camera_selection=False):
     """Render every frame in ``plan`` and return the per-frame artifact report.
 
     ``plan`` is a document (not a flag list) for the same reason the view plan is:
@@ -293,9 +342,11 @@ def render_frames(plan, guard):
     report_progress("open_checkpoint", 2)
     scene = open_checkpoint(checkpoint)
 
-    camera_id = plan.get("cameraId")
-    camera, _ = find_camera(scene, camera_id)
-    scene.camera = camera
+    camera_selection, selected_cameras = shot_camera_selection(scene, plan, requested, require_camera_selection)
+    camera = None
+    if camera_selection is None:
+        camera, _ = find_camera(scene, plan.get("cameraId"))
+        scene.camera = camera
 
     profile = plan.get("profile") or {}
     report_progress("configure_render", 4)
@@ -328,6 +379,11 @@ def render_frames(plan, guard):
         percent = 5 + int(90 * index / total)
         report_progress("frame", percent, {"frame": frame, "index": index, "total": total})
         scene.frame_set(frame)
+        if camera_selection is not None:
+            camera, shot_id, selected_id = selected_cameras[frame]
+            # Apply AFTER native animation/marker evaluation; no native file is
+            # saved and the legacy single-camera route remains unchanged.
+            scene.camera = camera
         path = frame_path(output_directory, frame, prefix, padding)
         # Explicit, absolute, WITH the extension — see the naming trap above.
         scene.render.filepath = path
@@ -342,6 +398,13 @@ def render_frames(plan, guard):
                 {"frame": frame, "engine": scene.render.engine},
             )
         elapsed_ms = int((time.time() - started) * 1000)
+        camera_evidence = {}
+        if camera_selection is not None:
+            actual_id = scene.camera.get("deepblend_id") if scene.camera is not None else None
+            if actual_id != selected_id:
+                append_event(events_path, {"type": "frame_failed", "frame": frame, "expectedCameraId": selected_id, "actualCameraId": actual_id})
+                raise ActionError("RENDER_NO_OUTPUT", "Frame %d did not retain its selected shot camera; no camera attribution was accepted." % frame)
+            camera_evidence = {"cameraId": actual_id, "shotId": shot_id}
         verdict = verify_frame(path, expected_width, expected_height)
         if not verdict.get("ok"):
             append_event(events_path, {"type": "frame_failed", "frame": frame, "verify": verdict})
@@ -359,6 +422,7 @@ def render_frames(plan, guard):
             "width": verdict["width"],
             "height": verdict["height"],
             "ms": elapsed_ms,
+            **camera_evidence,
         }
         entries.append(entry)
         written.append(frame)
@@ -370,7 +434,7 @@ def render_frames(plan, guard):
             for chunk in iter(lambda: stream.read(256 * 1024), b""):
                 digest.update(chunk)
         append_event(events_path, {"type": "frame", "frame": frame, "bytes": verdict["bytes"], "ms": elapsed_ms,
-                                   "attemptToken": attempt_token, "sha256": digest.hexdigest()})
+                                   "attemptToken": attempt_token, "sha256": digest.hexdigest(), **camera_evidence})
 
     report_progress("frames_done", 97, {"rendered": len(written)})
     append_event(events_path, {"type": "frames_done", "rendered": written})
@@ -379,8 +443,9 @@ def render_frames(plan, guard):
         "renderKind": "frame-sequence",
         "profileName": plan.get("profileName"),
         "checkpoint": checkpoint,
-        "cameraId": camera.get("deepblend_id") or camera.name,
-        "cameraName": camera.name,
+        "cameraId": (camera.get("deepblend_id") or camera.name) if camera_selection is None else None,
+        "cameraName": camera.name if camera_selection is None else None,
+        **({"cameraSelection": camera_selection} if camera_selection is not None else {}),
         "outputDirectory": output_directory,
         "filePrefix": prefix,
         "padding": padding,

package/python/deepblend_geometry_framing.py

@@ -0,0 +1,68 @@
+"""Read-only perspective projection of actual evaluated vertices at one frame."""
+import math
+import bpy
+from deepblend_util import ActionError
+
+
+def framing_camera(scene, graph, camera_id, margin):
+    # A full-camera frustum cannot certify a masked/cropped render region or
+    # multiple eye views. Keep manual settings intact and refuse that claim.
+    if scene.render.use_border or scene.render.use_multiview:
+        raise ActionError('BLENDER_UNSUPPORTED_ACTION', 'Native camera framing does not support render borders or multiview; manual settings are unchanged. Geometry inspection without a camera remains available.')
+    obj = bpy.data.objects.get('db_camera__' + camera_id)
+    if obj is None or obj.type != 'CAMERA':
+        raise ActionError('SCENE_SPEC_INVALID', 'Selected native framing camera does not exist.')
+    camera = obj.evaluated_get(graph)
+    if camera.data.type != 'PERSP':
+        raise ActionError('BLENDER_UNSUPPORTED_ACTION', 'Native vertex framing currently requires a perspective camera.')
+    # Blender's camera projection ignores object scale (world_to_camera_view
+    # normalizes the matrix too). Respect old projects' manual camera scale.
+    normalized = camera.matrix_world.normalized()
+    if not math.isfinite(normalized.determinant()) or abs(normalized.determinant()) < 1e-12:
+        raise ActionError('SCENE_VALIDATION_FAILED', 'Degenerate native camera transform.')
+    inverse = normalized.inverted()
+    corners = camera.data.view_frame(scene=scene)
+    slopes = [(p.x/-p.z, p.y/-p.z) for p in corners]
+    limits = [min(p[0] for p in slopes), max(p[0] for p in slopes), min(p[1] for p in slopes), max(p[1] for p in slopes)]
+    if not all(math.isfinite(v) for v in limits) or limits[0] >= limits[1] or limits[2] >= limits[3]:
+        raise ActionError('SCENE_VALIDATION_FAILED', 'Invalid native camera frustum.')
+    return inverse, limits, {'id': camera_id, 'type': 'PERSP', 'margin': margin,
+                             'clipStartMeters': float(camera.data.clip_start), 'clipEndMeters': float(camera.data.clip_end)}
+
+
+def project_geometry(obj, aggregate, graph, calibration):
+    inverse, (left, right, bottom, top), camera = calibration
+    parts = ([obj] + list(obj.children_recursive)) if aggregate else [obj]
+    meshes = [p for p in parts if p.type == 'MESH']
+    if any(p.hide_render for p in parts):
+        return {'status': 'unavailable-render-hidden'}
+    low, high, nearest, farthest, count = [math.inf]*2, [-math.inf]*2, math.inf, -math.inf, 0
+    for part in meshes:
+        evaluated = part.evaluated_get(graph)
+        mesh = evaluated.to_mesh()
+        try:
+            count += len(mesh.vertices) if mesh else 0
+            if count > 2000000:
+                return {'status': 'geometry-budget-exceeded'}
+            if mesh is None or not mesh.vertices:
+                raise ActionError('SCENE_VALIDATION_FAILED', 'Geometry disappeared during framing inspection.')
+            for vertex in mesh.vertices:
+                point = inverse @ (evaluated.matrix_world @ vertex.co)
+                depth = -float(point.z)
+                if not all(math.isfinite(v) for v in point):
+                    raise ActionError('SCENE_VALIDATION_FAILED', 'Non-finite native framing vertex.')
+                nearest, farthest = min(nearest, depth), max(farthest, depth)
+                if depth > 1e-8:
+                    uv = [(float(point.x)/depth-left)/(right-left), (float(point.y)/depth-bottom)/(top-bottom)]
+                    for axis in range(2):
+                        low[axis], high[axis] = min(low[axis], uv[axis]), max(high[axis], uv[axis])
+        finally:
+            evaluated.to_mesh_clear()
+    result = {'status': 'not-fully-in-front' if nearest <= 1e-8 else 'measured',
+              'nearestDepthMeters': nearest, 'farthestDepthMeters': farthest,
+              'containedInClip': nearest >= camera['clipStartMeters'] and farthest <= camera['clipEndMeters']}
+    if result['status'] == 'measured':
+        margin = camera['margin']
+        result.update(normalizedBounds={'min': low, 'max': high},
+                      containedInFrame=all(low[i] >= margin and high[i] <= 1-margin for i in range(2)))
+    return result

package/python/deepblend_images.py

@@ -11,6 +11,18 @@ SOCKETS = {'baseColor': 'Base Color', 'roughness': 'Roughness', 'metallic': 'Met
            'normal': 'Normal', 'alpha': 'Alpha', 'emissionColor': 'Emission Color'}
 
 
+def scene_image_budget_bytes():
+    """Read the managed process's operator limit; scene data cannot raise it.
+
+    This changes only the cumulative scene allocation. Individual image, header,
+    format and per-import limits retain their existing resource boundaries.
+    """
+    value = os.environ.get('DEEPBLEND_SCENE_IMAGE_BUDGET_MIB', str(MAX_IMAGE_DECODE_BYTES // (1024 * 1024)))
+    if not 1 <= len(value) <= 4 or not value.isascii() or not value.isdecimal() or not 16 <= int(value) <= 8192:
+        raise ActionError('SCENE_SPEC_INVALID', 'operator scene image budget must be an integer from 16 through 8192 MiB')
+    return int(value) * 1024 * 1024
+
+
 def image_asset_path(asset, project_root):
     root = os.path.realpath(project_root or '.')
     path = os.path.realpath(os.path.join(root, asset['path']))
@@ -26,6 +38,8 @@ def check_scene_image_budget(spec, project_root):
     cache of header facts must not collapse their allocation costs. glTF/GLB/OBJ
     image declarations are conservatively counted per imported instance.
     """
+    limit = scene_image_budget_bytes()
+    label = '1 GiB' if limit == MAX_IMAGE_DECODE_BYTES else '%d MiB' % (limit // (1024 * 1024))
     assets = {asset['id']: asset for asset in spec.get('assets') or []}
     bindings = []
     environment = (spec.get('world') or {}).get('environment')
@@ -43,8 +57,8 @@ def check_scene_image_budget(spec, project_root):
         if path not in facts:
             facts[path] = check_image_header(path)
         total += facts[path]['decodedBytes']
-        if total > MAX_IMAGE_DECODE_BYTES:
-            raise ActionError('ASSET_CONTENT_MISMATCH', 'declared scene images exceed the 1 GiB decoded pixel budget')
+        if total > limit:
+            raise ActionError('ASSET_CONTENT_MISMATCH', 'declared scene images exceed the %s decoded pixel budget' % label)
     imported_images, imported_facts = 0, {}
     for entity in spec.get('entities') or []:
         if entity.get('type') != 'asset-instance':
@@ -58,9 +72,9 @@ def check_scene_image_budget(spec, project_root):
             imported_facts[key] = inspect(project_root, asset)
         total += imported_facts[key]['decodedBytes']
         imported_images += imported_facts[key]['images']
-        if total > MAX_IMAGE_DECODE_BYTES:
-            raise ActionError('ASSET_CONTENT_MISMATCH', 'declared and imported scene images exceed the 1 GiB decoded pixel budget')
-    return {'bindings': len(bindings), 'importedImages': imported_images, 'decodedBytes': total}
+        if total > limit:
+            raise ActionError('ASSET_CONTENT_MISMATCH', 'declared and imported scene images exceed the %s decoded pixel budget' % label)
+    return {'bindings': len(bindings), 'importedImages': imported_images, 'decodedBytes': total, 'limitBytes': limit}
 
 
 def pack_imported_material_images(objects):

package/python/deepblend_inspect_geometry.py

@@ -29,6 +29,72 @@ def object_axis_frame(matrix):
     return lengths, basis
 
 
+def measure_asset_bounds(obj, graph):
+    """Whole imported instance, never a partial/declared or transformed AABB guess."""
+    import bpy
+    entry = {'type': 'ASSET_MESH_SET', 'available': False}
+    def unavailable(reason):
+        return {**entry, 'unavailableReason': reason}
+    pending, parts, visited = [obj], [], set()
+    while pending:
+        part = pending.pop()
+        if part.as_pointer() in visited or len(visited) >= 4096:
+            return unavailable('unsupported-hierarchy')
+        visited.add(part.as_pointer())
+        if part != obj and part.name.startswith(('db_entity__', 'db_camera__', 'db_light__')):
+            # Reused imports carry the owning entity prefix on their parts.
+            # Only that explicit ownership/part marker is exempt; another
+            # entity root or an unmarked manual object remains unsupported.
+            owner = obj.get('deepblend_id')
+            own_part = (isinstance(owner, str) and bool(owner)
+                        and part.name.startswith(obj.name + '_')
+                        and part.get('deepblend_id') == owner
+                        and part.get('deepblend_kind') == 'entity'
+                        and isinstance(part.get('deepblend_part_id'), str)
+                        and bool(part.get('deepblend_part_id')))
+            if not own_part:
+                return unavailable('unsupported-hierarchy')
+        if part.type not in ('EMPTY', 'MESH') or part.instance_type != 'NONE':
+            return unavailable('unsupported-hierarchy')
+        if not part.visible_get(view_layer=bpy.context.view_layer):
+            return unavailable('viewport-disabled')
+        if part.type == 'MESH':
+            parts.append(part)
+        if len(parts) > 128:
+            return unavailable('geometry-budget-exceeded')
+        pending.extend(part.children)
+    if not parts:
+        return unavailable('empty-or-invalid-geometry')
+    low, high, vertices, polygons = [math.inf]*3, [-math.inf]*3, 0, 0
+    for part in parts:
+        evaluated = part.evaluated_get(graph)
+        mesh = evaluated.to_mesh()
+        try:
+            if mesh is None or not mesh.vertices:
+                return unavailable('empty-or-invalid-geometry')
+            vertices += len(mesh.vertices)
+            polygons += len(mesh.polygons)
+            if vertices > 2000000 or polygons > 2000000:
+                return unavailable('geometry-budget-exceeded')
+            for vertex in mesh.vertices:
+                point = evaluated.matrix_world @ vertex.co
+                if not all(math.isfinite(x) for x in point):
+                    return unavailable('empty-or-invalid-geometry')
+                for axis in range(3):
+                    low[axis] = min(low[axis], float(point[axis]))
+                    high[axis] = max(high[axis], float(point[axis]))
+        finally:
+            evaluated.to_mesh_clear()
+    matrix = [[float(x) for x in row] for row in obj.evaluated_get(graph).matrix_world]
+    scale = [float(x) for x in obj.scale]
+    if not all(math.isfinite(x) for row in matrix for x in row) or not all(math.isfinite(x) for x in scale):
+        return unavailable('empty-or-invalid-geometry')
+    return {**entry, 'available': True, 'worldBoundsMeters': {'min': low, 'max': high},
+            'worldAxisExtentMm': [(high[i]-low[i])*1000 for i in range(3)],
+            'worldMatrix': matrix, 'scale': scale, 'vertexCount': vertices,
+            'polygonCount': polygons, 'meshObjectCount': len(parts)}
+
+
 def inspect_geometry(request, options):
     import bpy
     payload = request.get('payload')
@@ -43,6 +109,17 @@ def inspect_geometry(request, options):
     object_axes = payload.get('objectAxes', False)
     if type(object_axes) is not bool:
         raise ActionError('BLENDER_SCRIPT_ERROR', 'objectAxes must be boolean.')
+    camera_id = payload.get('cameraId')
+    camera_margin = payload.get('cameraMargin', .03)
+    if camera_id is not None and (not isinstance(camera_id, str) or re.fullmatch(r'[a-zA-Z][a-zA-Z0-9._-]{0,127}', camera_id) is None or object_axes or 'surfaceSamples' in payload):
+        raise ActionError('BLENDER_SCRIPT_ERROR', 'Framing requires one explicit camera without axes or samples.')
+    if 'cameraMargin' in payload and camera_id is None or type(camera_margin) not in (int, float) or not math.isfinite(camera_margin) or not 0 <= camera_margin <= .25:
+        raise ActionError('BLENDER_SCRIPT_ERROR', 'Framing margin must be finite from 0 to 0.25 and requires cameraId.')
+    asset_ids = payload.get('assetInstanceIds')
+    if asset_ids is not None and (not isinstance(asset_ids, list) or not asset_ids or
+            any(not isinstance(x, str) or x not in ids for x in asset_ids) or len(set(asset_ids)) != len(asset_ids) or
+            object_axes or 'surfaceSamples' in payload):
+        raise ActionError('BLENDER_SCRIPT_ERROR', 'Asset bounds require distinct selected asset roots without object axes or surface samples.')
     samples = payload.get('surfaceSamples')
     if 'surfaceSamples' in payload:
         from deepblend_inspect_surface import validate_surface_selection
@@ -66,13 +143,19 @@ def inspect_geometry(request, options):
     if measured_frame != frame:
         raise ActionError('SCENE_VALIDATION_FAILED', 'Blender did not evaluate the requested inspection frame.')
     graph = bpy.context.evaluated_depsgraph_get()
+    calibration = None
+    if camera_id is not None:
+        from deepblend_geometry_framing import framing_camera, project_geometry
+        calibration = framing_camera(bpy.context.scene, graph, camera_id, camera_margin)
     objects = []
     for entity_id in ids:
         obj = bpy.data.objects.get('db_entity__' + entity_id)
         if obj is None:
             raise ActionError('SCENE_SPEC_INVALID', 'The selected native entity does not exist: ' + entity_id)
         entry = {'entityId': entity_id, 'type': obj.type, 'available': False}
-        if obj.type != 'MESH':
+        if asset_ids is not None and entity_id in asset_ids:
+            entry = {'entityId': entity_id, **measure_asset_bounds(obj, graph)}
+        elif obj.type != 'MESH':
             entry['unavailableReason'] = 'not-mesh'
         elif not obj.visible_get(view_layer=bpy.context.view_layer):
             entry['unavailableReason'] = 'viewport-disabled'
@@ -114,6 +197,8 @@ def inspect_geometry(request, options):
                                          objectAxisExtentMm=[(local_high[i] - local_low[i]) * 1000 for i in range(3)])
             finally:
                 evaluated.to_mesh_clear()
+        if calibration is not None and entry['available']:
+            entry['cameraProjection'] = project_geometry(obj, asset_ids is not None and entity_id in asset_ids, graph, calibration)
         objects.append(entry)
     report = {'schemaVersion': 'deepblend.geometry-inspection/v1', 'checkpointSha256': expected,
               'checkpointUnchanged': True, 'frame': measured_frame, 'blenderVersion': bpy.app.version_string,
@@ -125,6 +210,10 @@ def inspect_geometry(request, options):
     if object_axes:
         report['schemaVersion'] = 'deepblend.geometry-inspection/v3'
         report['objectAxisBasis'] = 'evaluated-object-axes-scaled'
+    if calibration is not None:
+        report['camera'] = calibration[2]
+    if asset_ids is not None or calibration is not None:
+        report['schemaVersion'] = 'deepblend.geometry-inspection/v4'
     if file_digest(checkpoint) != expected:
         raise ActionError('SCENE_VALIDATION_FAILED', 'The checkpoint changed during geometry inspection.')
     return report, [], []

package/python/deepblend_scatter.py

@@ -51,7 +51,44 @@ def _inside(target, point):
     return votes >= 2
 
 
-def _target(entity_id, obj):
+def _world_matrices(objects):
+    """Evaluate reference poses without retaining any visibility changes.
+
+    Viewport-disabled objects can keep an identity/stale matrix_world after
+    their local transform is authored. Scatter has no native modifier
+    dependency to make Blender evaluate those hidden reference objects.
+    Snapshot their current poses while references and ancestors are enabled;
+    keep render visibility untouched and restore every viewport flag.
+    """
+    objects = list(dict.fromkeys(objects))
+    references = set(objects)
+    for obj in objects:
+        parent = obj.parent
+        while parent is not None and parent not in references:
+            references.add(parent)
+            parent = parent.parent
+    layer = bpy.context.view_layer
+    if any(obj.name not in layer.objects for obj in references):
+        _refuse('reference transform is outside the active view layer')
+    states = [(obj, obj.hide_viewport, obj.hide_get(view_layer=layer)) for obj in references]
+    try:
+        for obj, hidden, local_hidden in states:
+            if hidden:
+                obj.hide_viewport = False
+            if local_hidden:
+                obj.hide_set(False, view_layer=layer)
+        layer.update()
+        return {obj: obj.matrix_world.copy() for obj in objects}
+    finally:
+        for obj, hidden, local_hidden in states:
+            if obj.hide_get(view_layer=layer) != local_hidden:
+                obj.hide_set(local_hidden, view_layer=layer)
+            if obj.hide_viewport != hidden:
+                obj.hide_viewport = hidden
+        layer.update()
+
+
+def _target(entity_id, obj, matrix):
     mesh = obj.data
     bm = bmesh.new()
     try:
@@ -60,7 +97,7 @@ def _target(entity_id, obj):
             _refuse('target "%s" needs a closed, non-degenerate solid mesh' % entity_id)
     finally:
         bm.free()
-    points = [obj.matrix_world @ vertex.co for vertex in mesh.vertices]
+    points = [matrix @ vertex.co for vertex in mesh.vertices]
     if any(not all(math.isfinite(value) for value in point) for point in points):
         _refuse('target has non-finite world coordinates')
     mesh.calc_loop_triangles()
@@ -104,7 +141,8 @@ def apply_surface_scatter(obj, targets, entry):
         _refuse('targets exceed the 131072-polygon surface budget')
     if sum(max(0, len(polygon.vertices) - 2) for _, target in targets for polygon in target.data.polygons) > MAX_TARGET_TRIANGLES:
         _refuse('targets exceed the 262144-triangle surface budget before triangulation')
-    target_records = [_target(key, target) for key, target in targets]
+    matrices = _world_matrices([obj] + [target for _, target in targets])
+    target_records = [_target(key, target, matrices[target]) for key, target in targets]
     if sum(len(target['triangles']) for target in target_records) > MAX_TARGET_TRIANGLES:
         _refuse('targets exceed the 262144-triangle surface budget')
     weighted, areas, total = [], [], 0.0
@@ -131,7 +169,7 @@ def apply_surface_scatter(obj, targets, entry):
     material_indices = [polygon.material_index for polygon in source.polygons]
     materials = list(source.materials)
     uv_maps = [(layer.name, [(item.uv.x, item.uv.y) for item in layer.data]) for layer in source.uv_layers]
-    matrix = obj.matrix_world.copy()
+    matrix = matrices[obj]
     try:
         inverse = matrix.inverted()
     except ValueError:

package/python/deepblend_scene.py

@@ -39,6 +39,7 @@ from mathutils import Vector
 from deepblend_util import ActionError, Guard, as_text, error_text, report_progress, warning
 from deepblend_asset_bundle import verify_asset_bundle, verify_unbundled_gltf_asset, verify_unbundled_obj_asset
 from deepblend_geometry import create_lathe, create_curve, apply_model_modifiers
+from deepblend_image_headers import MAX_IMAGE_DECODE_BYTES
 from deepblend_images import build_image_maps, build_environment, pack_imported_material_images, check_scene_image_budget
 from deepblend_parts import isolated_import_names, stamp_imported_parts, apply_material_bindings
 from deepblend_anisotropy import build_anisotropy, validate_anisotropy_material, validate_anisotropy_usage, validate_native_material_usage
@@ -2000,7 +2001,11 @@ def build_scene(spec, options, guard):
         verify_unbundled_gltf_asset(options.get("project_root") or "", asset)
         verify_unbundled_obj_asset(options.get("project_root") or "", asset)
 
-    check_scene_image_budget(spec, options.get('project_root'))
+    image_budget = check_scene_image_budget(spec, options.get('project_root'))
+    if image_budget['limitBytes'] != MAX_IMAGE_DECODE_BYTES:
+        guard.note('SCENE_COMPILER_DECISION', 'using an explicit operator scene image budget',
+                   {'kind': 'scene-image-budget', **image_budget,
+                    'allocationPolicy': 'conservative-per-imported-instance'})
     report_progress("reset_scene", 5)
     scene = reset_scene()