@deepblend/dsh-blender-provider-local 0.20.0 → 0.22.0

package/lib/index.js

@@ -39,6 +39,11 @@ import {
   SURFACE_PLACEMENT_LIMITS,
   validateSurfacePlacementSelection,
   verifySurfacePlacementReport,
+  validateAssemblyPlacementSelection,
+  verifyAssemblyPlacementReport,
+  CAMERA_FIT_LIMITS,
+  validateCameraFitSelection,
+  verifyCameraFitReport,
   BlenderError,
   BlenderErrorCode,
   CANDIDATE_RENDER_ENGINES,
@@ -276,7 +281,7 @@ export const SESSION_ROUTABLE_ACTIONS = Object.freeze([
   'render_preview',
   'render_views',
 ])
-export const ISOLATED_BOOTSTRAP_ACTIONS = Object.freeze(['inspect_geometry', 'inspect_surface_placement'])
+export const ISOLATED_BOOTSTRAP_ACTIONS = Object.freeze(['inspect_geometry', 'inspect_surface_placement', 'inspect_camera_fit'])
 
 /**
  * A live Blender, presented as one shape whatever carries the bytes.
@@ -1644,7 +1649,17 @@ export default class LocalBlenderRuntime extends Service {
 
   /** Measure both actual meshes in a private batch; candidate verification also pins its baseline. */
   async inspectSurfacePlacement(request) {
-    validateSurfacePlacementSelection(request)
+    return this._inspectSurfacePlacement(request, false)
+  }
+
+  async inspectAssemblyPlacement(request) {
+    return this._inspectSurfacePlacement(request, true)
+  }
+
+  async _inspectSurfacePlacement(request, assembly) {
+    const validate = assembly ? validateAssemblyPlacementSelection : validateSurfacePlacementSelection
+    const verifyReport = assembly ? verifyAssemblyPlacementReport : verifySurfacePlacementReport
+    validate(request)
     const aborted = () => {
       if (request.signal?.aborted) throw new BlenderError(BlenderErrorCode.ABORTED, 'Surface placement cancelled.')
     }
@@ -1682,8 +1697,11 @@ export default class LocalBlenderRuntime extends Service {
       const run = await this.runBootstrap({ action: 'inspect_surface_placement', jobId: correlationId,
         payload: { subjectEntityId: request.subjectEntityId, supportEntityId: request.supportEntityId,
           frame: request.frame, clearanceMm: request.clearanceMm ?? 0, checkpointSha256: request.checkpointSha256,
+          ...(assembly ? { scope: 'recipe-assembly', memberEntityIds: request.memberEntityIds, pose: request.pose } : {}),
           ...(sources.length === 1 ? {} : { baselineCheckpointPath: sources[1].snapshot,
-            baselineCheckpointSha256: request.baselineCheckpointSha256, expectedTranslationMeters: request.expectedTranslationMeters }) } },
+            baselineCheckpointSha256: request.baselineCheckpointSha256,
+            ...(assembly ? { expectedWorldMatrixMeters: request.expectedWorldMatrixMeters }
+              : { expectedTranslationMeters: request.expectedTranslationMeters }) }) } },
       { signal: request.signal, session: false, args: ['--blend', sources[0].snapshot] })
       aborted()
       if (run.exitCode !== 0) throw new BlenderError(BlenderErrorCode.NONZERO_EXIT,
@@ -1693,7 +1711,74 @@ export default class LocalBlenderRuntime extends Service {
         throw new BlenderError(BlenderErrorCode.PROTOCOL_VERSION_MISMATCH,
           'Native placement inspection did not return a successful response for this request.')
       }
-      const report = verifySurfacePlacementReport(run.envelope?.result, request)
+      const report = verifyReport(run.envelope?.result, request)
+      for (const source of sources) {
+        await verify(source.path, source.sha256)
+        await verify(source.snapshot, source.sha256)
+      }
+      aborted()
+      return { report, envelope: run.envelope, durationMs: run.durationMs, stdout: run.stdout, stderr: run.stderr }
+    } catch (cause) {
+      aborted()
+      throw cause
+    } finally {
+      this._cleanup(directory)
+    }
+  }
+
+  /** Read-only full-selection proposal or candidate check in a hash-pinned private batch. */
+  async inspectCameraFit(request) {
+    validateCameraFitSelection(request)
+    const aborted = () => {
+      if (request.signal?.aborted) throw new BlenderError(BlenderErrorCode.ABORTED, 'Camera fit cancelled.')
+    }
+    aborted()
+    if (!existsSync(this.workspaceRoot)) throw new BlenderError(BlenderErrorCode.PATH_OUTSIDE_WORKSPACE, 'The camera-fit workspace does not exist.')
+    const root = realpathSync(this.workspaceRoot)
+    const boundedSource = path => {
+      if (typeof path !== 'string' || !isAbsolute(path) || !existsSync(path)) throw new BlenderError(BlenderErrorCode.REVISION_CHECKPOINT_MISSING, 'Camera fit needs an absolute native checkpoint path.')
+      const source = realpathSync(path), local = relative(root, source)
+      if (!local || local === '..' || local.startsWith('..' + sep) || isAbsolute(local)) throw new BlenderError(BlenderErrorCode.PATH_OUTSIDE_WORKSPACE, 'The camera-fit checkpoint is outside the runtime workspace.')
+      const info = statSync(source)
+      if (!info.isFile() || info.size > CAMERA_FIT_LIMITS.checkpointBytes) throw new BlenderError(BlenderErrorCode.SCENE_TOO_HEAVY, 'The camera-fit checkpoint is not a bounded native file.')
+      return source
+    }
+    const sources = [{ path: boundedSource(request.checkpointPath), sha256: request.checkpointSha256, name: 'camera-fit-source.blend' }]
+    if (request.baselineCheckpointPath !== undefined) sources.push({ path: boundedSource(request.baselineCheckpointPath), sha256: request.baselineCheckpointSha256, name: 'camera-fit-baseline.blend' })
+    const digest = async path => {
+      const hash = createHash('sha256')
+      for await (const bytes of createReadStream(path, { signal: request.signal })) hash.update(bytes)
+      return hash.digest('hex')
+    }
+    const verify = async (path, expected) => {
+      if (await digest(path) !== expected) throw new BlenderError(BlenderErrorCode.SCENE_VALIDATION_FAILED, 'A camera-fit checkpoint differs from its pinned native source.')
+    }
+    const { directory, jobId } = this._createWorkingDirectory()
+    const correlationId = typeof request.jobId === 'string' && request.jobId.length > 0 ? request.jobId : jobId
+    try {
+      for (const source of sources) {
+        await verify(source.path, source.sha256)
+        source.snapshot = join(directory, source.name)
+        await copyFile(source.path, source.snapshot)
+        aborted()
+        await verify(source.snapshot, source.sha256)
+      }
+      const run = await this.runBootstrap({ action: 'inspect_camera_fit', jobId: correlationId,
+        payload: { entityIds: request.entityIds, assetInstanceIds: request.assetInstanceIds,
+          frame: request.frame, cameraId: request.cameraId, fittedCameraId: request.fittedCameraId,
+          margin: request.margin, checkpointSha256: request.checkpointSha256,
+          ...(sources.length === 1 ? {} : { baselineCheckpointPath: sources[1].snapshot,
+            baselineCheckpointSha256: request.baselineCheckpointSha256 }) } },
+      { signal: request.signal, session: false, args: ['--blend', sources[0].snapshot] })
+      aborted()
+      if (run.exitCode !== 0) throw new BlenderError(BlenderErrorCode.NONZERO_EXIT,
+        'Native camera-fit inspection did not exit successfully; its result was refused.')
+      if (run.envelope?.protocolVersion !== BLENDER_PROTOCOL_VERSION || run.envelope.status !== 'success' ||
+          run.envelope.action !== 'inspect_camera_fit' || run.envelope.jobId !== correlationId || run.envelope.error !== null) {
+        throw new BlenderError(BlenderErrorCode.PROTOCOL_VERSION_MISMATCH,
+          'Native camera-fit inspection did not return a successful response for this request.')
+      }
+      const report = verifyCameraFitReport(run.envelope?.result, request)
       for (const source of sources) {
         await verify(source.path, source.sha256)
         await verify(source.snapshot, source.sha256)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.20.0",
+  "version": "0.22.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.20.0"
+    "@deepblend/dsh-blender-contracts": "0.22.0"
   },
   "license": "MIT",
   "repository": {

package/python/bootstrap.py

@@ -107,6 +107,7 @@ SUPPORTED_ACTIONS = (
     "compile_scene",
     "inspect_geometry",
     "inspect_surface_placement",
+    "inspect_camera_fit",
     "render_preview",
     "render_views",
     "render_frames",
@@ -497,10 +498,12 @@ KNOWN_SESSION_OPTIONS = (
 
 from deepblend_inspect_geometry import inspect_geometry
 from deepblend_surface_placement import inspect_surface_placement
+from deepblend_product_framing import inspect_camera_fit
 
 ACTIONS = {
     "inspect_geometry": inspect_geometry,
     "inspect_surface_placement": inspect_surface_placement,
+    "inspect_camera_fit": inspect_camera_fit,
     "get_capabilities": action_get_capabilities,
     "compile_scene": action_compile_scene,
     "render_preview": action_render_preview,
@@ -615,7 +618,7 @@ def _session_dispatch(request, options):
             % (request.get("protocolVersion"), PROTOCOL_VERSION),
         }, [], [])
 
-    if action in ('inspect_geometry', 'inspect_surface_placement'):
+    if action in ('inspect_geometry', 'inspect_surface_placement', 'inspect_camera_fit'):
         return build_envelope(job_id, action, None, {
             'code': 'BLENDER_UNSUPPORTED_ACTION',
             'message': 'Native geometry inspection requires an isolated batch and cannot open a checkpoint in a kept or live Blender session.',

package/python/deepblend_assembly_placement.py

@@ -0,0 +1,249 @@
+"""Read-only whole-assembly pose/settle measurement and complete candidate proof.
+
+The public Host owns recipe provenance and complete membership. This native layer
+measures the exact supplied union, then independently reopens both pinned files
+and checks every evaluated member against one rigid upright world transform.
+"""
+import math
+import re
+
+from deepblend_util import ActionError
+from deepblend_surface_placement import (
+    _capture_checkpoint, _verified_checkpoint, _unsupported, _finite_number, _active_animation,
+    solve_surface_placement, SurfacePlacementError, MAX_MESH_OBJECTS, MAX_VERTICES,
+    MAX_TRIANGLES, MAX_HIERARCHY_OBJECTS, TRANSLATION_TOLERANCE_METERS,
+)
+
+BASIS_TOLERANCE = 1e-6
+UV_TOLERANCE = 1e-6
+IDENTITY = [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]
+
+
+def _fail(message):
+    raise ActionError('SCENE_VALIDATION_FAILED', message)
+
+
+def _matrix_product(a, b):
+    return [[sum(a[i][k] * b[k][j] for k in range(4)) for j in range(4)] for i in range(4)]
+
+
+def _point(matrix, point):
+    return tuple(sum(matrix[i][j] * point[j] for j in range(3)) + matrix[i][3] for i in range(3))
+
+
+def _valid_pose(pose):
+    return (isinstance(pose, dict) and set(pose) == {'translationMm', 'yawDegrees', 'pivotMm'}
+            and all(isinstance(pose[key], list) and len(pose[key]) == 3
+                    and all(_finite_number(value) and abs(value) <= 1_000_000 for value in pose[key])
+                    for key in ('translationMm', 'pivotMm'))
+            and _finite_number(pose['yawDegrees']) and abs(pose['yawDegrees']) <= 360)
+
+
+def _pose_matrix(pose):
+    angle = pose['yawDegrees'] * math.pi / 180
+    c, s = math.cos(angle), math.sin(angle)
+    x, y = (value / 1000 for value in pose['pivotMm'][:2])
+    dx, dy, dz = (value / 1000 for value in pose['translationMm'])
+    return [[c, -s, 0, x-c*x+s*y+dx], [s, c, 0, y-s*x-c*y+dy],
+            [0, 0, 1, dz], [0, 0, 0, 1]]
+
+
+def _upright_matrix(matrix):
+    if (not isinstance(matrix, list) or len(matrix) != 4
+            or any(not isinstance(row, list) or len(row) != 4
+                   or any(not _finite_number(value) or abs(value) > 1e6 for value in row) for row in matrix)):
+        return False
+    near = lambda a, b: abs(a-b) <= 1e-9
+    return (all(near(matrix[3][i], value) for i, value in enumerate((0, 0, 0, 1)))
+            and all(near(matrix[2][i], value) for i, value in enumerate((0, 0, 1)))
+            and near(matrix[0][2], 0) and near(matrix[1][2], 0)
+            and near(matrix[0][0], matrix[1][1]) and near(matrix[0][1], -matrix[1][0])
+            and near(matrix[0][0]**2+matrix[1][0]**2, 1))
+
+
+def _cycle(values):
+    values = tuple(values)
+    return min(values[i:] + values[:i] for i in range(len(values)))
+
+
+def _socket_value(value):
+    if isinstance(value, (str, bool, int, float)):
+        return value
+    if hasattr(value, '__len__') and not hasattr(value, 'bl_rna'):
+        return tuple(value)
+    if value is None:
+        return None
+    return (getattr(getattr(value, 'bl_rna', None), 'identifier', type(value).__name__), getattr(value, 'name', None))
+
+
+def _material_facts(material):
+    if material is None:
+        return None
+    tree = material.node_tree
+    if _active_animation(material) or _active_animation(tree):
+        _unsupported('animated-assembly-material', 'Complete assembly placement requires static materials.')
+    nodes = []
+    for node in tree.nodes if tree else []:
+        properties = tuple((key, getattr(node, key)) for key in ('operation', 'blend_type', 'noise_dimensions',
+            'normalize', 'noise_type', 'distribution', 'subsurface_method', 'gradient_type', 'voronoi_dimensions',
+            'feature', 'distance', 'interpolation', 'extension', 'projection', 'vector_type', 'convert_from', 'convert_to')
+            if hasattr(node, key))
+        nodes.append((node.name, node.bl_idname, properties,
+                      tuple((socket.identifier, _socket_value(socket.default_value)) for socket in node.inputs
+                            if hasattr(socket, 'default_value'))))
+    links = sorted((link.from_node.name, link.from_socket.identifier, link.to_node.name, link.to_socket.identifier)
+                   for link in tree.links) if tree else []
+    return (material.name, tuple(material.diffuse_color), bool(material.use_nodes), sorted(nodes), links)
+
+
+def _capture(path, expected, frame, member_ids, support_id):
+    """Reuse the static, visibility, source hash and cross-object checks of v1."""
+    import bpy
+    captures = _capture_checkpoint(path, expected, frame, member_ids, support_id)
+    graph = bpy.context.evaluated_depsgraph_get()
+    for capture in captures:
+        for part in capture['parts']:
+            obj = bpy.data.objects[part['identity'][0]]
+            evaluated = obj.evaluated_get(graph)
+            mesh = evaluated.to_mesh()
+            try:
+                # Polygon order and cyclic start are not identity. Preserve the
+                # complete oriented faces, per-face material and loop UV data.
+                faces = []
+                for face in mesh.polygons:
+                    corners = []
+                    for loop_index in face.loop_indices:
+                        corners.append((mesh.loops[loop_index].vertex_index,
+                                        tuple(tuple(layer.uv[loop_index].vector) for layer in mesh.uv_layers)))
+                    faces.append((_cycle(corners), face.material_index, bool(face.use_smooth)))
+                part['appearance'] = (tuple(layer.name for layer in mesh.uv_layers), sorted(faces),
+                                      tuple(_material_facts(slot.material) for slot in obj.material_slots))
+            finally:
+                evaluated.to_mesh_clear()
+    total_meshes = sum(item['metadata']['meshObjectCount'] for item in captures[:-1])
+    total_vertices = sum(item['metadata']['vertexCount'] for item in captures[:-1])
+    total_triangles = sum(item['metadata']['triangleCount'] for item in captures[:-1])
+    if (total_meshes > MAX_MESH_OBJECTS or total_vertices > MAX_VERTICES or total_triangles > MAX_TRIANGLES
+            or sum(len(item['hierarchyIdentity']) for item in captures[:-1]) > MAX_HIERARCHY_OBJECTS):
+        _unsupported('geometry-budget-exceeded', 'The complete subject union exceeds the bounded native geometry budget.')
+    _verified_checkpoint(path, expected)
+    return captures
+
+
+def _transformed(capture, matrix):
+    triangles = [tuple(_point(matrix, point) for point in triangle) for triangle in capture['triangles']]
+    parts = [{**part, 'vertices': [_point(matrix, point) for point in part['vertices']]} for part in capture['parts']]
+    points = [point for part in parts for point in part['vertices']]
+    metadata = {**capture['metadata'], 'rootWorldMatrix': _matrix_product(matrix, capture['metadata']['rootWorldMatrix']),
+                'worldBoundsMeters': {'min': [min(point[a] for point in points) for a in range(3)],
+                                     'max': [max(point[a] for point in points) for a in range(3)]}}
+    return {**capture, 'parts': parts, 'triangles': triangles, 'metadata': metadata}
+
+
+def _compare_appearance(old, new, label):
+    if old[0] != new[0] or old[2] != new[2] or len(old[1]) != len(new[1]):
+        _fail(label + ' native UV layers, materials or mesh faces changed.')
+    maximum_uv_error = 0.0
+    for a, b in zip(old[1], new[1]):
+        if a[1:] != b[1:] or len(a[0]) != len(b[0]):
+            _fail(label + ' native face identity, material indices or smooth flags changed.')
+        for ac, bc in zip(a[0], b[0]):
+            if ac[0] != bc[0] or len(ac[1]) != len(bc[1]):
+                _fail(label + ' native oriented topology or loop UV identity changed.')
+            for auv, buv in zip(ac[1], bc[1]):
+                maximum_uv_error = max(maximum_uv_error, max(abs(a-b) for a, b in zip(auv, buv)))
+    if maximum_uv_error > UV_TOLERANCE:
+        _fail(label + ' evaluated UV coordinates changed beyond float32 reconstruction tolerance.')
+    return maximum_uv_error
+
+
+def _compare_rigid(baseline, current, matrix, label):
+    if baseline['hierarchyIdentity'] != current['hierarchyIdentity'] or len(baseline['parts']) != len(current['parts']):
+        _fail(label + ' hierarchy identity changed.')
+    maximum, maximum_uv_error = 0.0, 0.0
+    for old, new in zip(baseline['parts'], current['parts']):
+        if old['identity'] != new['identity'] or len(old['vertices']) != len(new['vertices']):
+            _fail(label + ' mesh topology or identity changed.')
+        maximum_uv_error = max(maximum_uv_error, _compare_appearance(old['appearance'], new['appearance'], label))
+        for before, after in zip(old['vertices'], new['vertices']):
+            maximum = max(maximum, math.dist(_point(matrix, before), after))
+    expected = _matrix_product(matrix, baseline['metadata']['rootWorldMatrix'])
+    actual = current['metadata']['rootWorldMatrix']
+    position_error = max(abs(expected[i][3]-actual[i][3]) for i in range(3))
+    basis_error = max(abs(expected[i][j]-actual[i][j]) for i in range(4) for j in range(4) if j != 3)
+    if maximum > TRANSLATION_TOLERANCE_METERS or position_error > TRANSLATION_TOLERANCE_METERS or basis_error > BASIS_TOLERANCE:
+        _fail(label + ' did not follow the complete rigid world transform.')
+    return {'rigidTransform': True, 'maxVertexErrorMeters': maximum,
+            'maxRootPositionErrorMeters': position_error, 'maxRootBasisError': basis_error, 'maxUvError': maximum_uv_error}
+
+
+def inspect_assembly_placement(request, options):
+    import bpy
+    payload = request.get('payload')
+    allowed = {'scope', 'subjectEntityId', 'memberEntityIds', 'supportEntityId', 'frame', 'clearanceMm', 'pose',
+               'checkpointSha256', 'baselineCheckpointPath', 'baselineCheckpointSha256', 'expectedWorldMatrixMeters'}
+    valid_id = lambda value: isinstance(value, str) and re.fullmatch(r'[A-Za-z][A-Za-z0-9._-]{0,127}', value) is not None
+    valid_hash = lambda value: isinstance(value, str) and re.fullmatch('[a-f0-9]{64}', value) is not None
+    if not isinstance(payload, dict) or set(payload) - allowed or payload.get('scope') != 'recipe-assembly':
+        _fail('Unsupported complete assembly measurement payload.')
+    ids, subject, support = payload.get('memberEntityIds'), payload.get('subjectEntityId'), payload.get('supportEntityId')
+    frame, expected, pose, clearance = payload.get('frame'), payload.get('checkpointSha256'), payload.get('pose'), payload.get('clearanceMm', 0)
+    if (not isinstance(ids, list) or not 1 <= len(ids) <= MAX_MESH_OBJECTS or not all(valid_id(value) for value in ids)
+            or ids != sorted(set(ids)) or not valid_id(subject) or subject not in ids or not valid_id(support) or support in ids
+            or type(frame) is not int or not 0 <= frame <= 1_000_000 or not valid_hash(expected)
+            or not _valid_pose(pose) or not _finite_number(clearance) or not 0 <= clearance <= 1000):
+        _fail('Complete assembly selection, pose, frame or checkpoint binding is invalid.')
+    baseline_fields = {'baselineCheckpointPath', 'baselineCheckpointSha256', 'expectedWorldMatrixMeters'}
+    has_baseline = bool(baseline_fields & set(payload))
+    baseline = None
+    if has_baseline:
+        if (not baseline_fields <= set(payload) or not valid_hash(payload['baselineCheckpointSha256'])
+                or not isinstance(payload['baselineCheckpointPath'], str) or not _upright_matrix(payload['expectedWorldMatrixMeters'])):
+            _fail('Complete candidate verification requires a pinned baseline and a rigid upright matrix.')
+        baseline = _capture(payload['baselineCheckpointPath'], payload['baselineCheckpointSha256'], frame, ids, support)
+    checkpoint = options.get('blend')
+    current = _capture(checkpoint, expected, frame, ids, support)
+    verification = None
+    if has_baseline:
+        members = [{'entityId': entity_id, **_compare_rigid(baseline[index], current[index], payload['expectedWorldMatrixMeters'], entity_id)}
+                   for index, entity_id in enumerate(ids)]
+        support_proof = _compare_rigid(baseline[-1], current[-1], IDENTITY, support)
+        _verified_checkpoint(payload['baselineCheckpointPath'], payload['baselineCheckpointSha256'])
+        verification = {'checkpointSha256': payload['baselineCheckpointSha256'], 'checkpointUnchanged': True,
+                        'worldMatrixMeters': payload['expectedWorldMatrixMeters'], 'members': members,
+                        'supportUnchanged': True, 'supportMaxErrorMeters': support_proof['maxVertexErrorMeters'],
+                        'toleranceMeters': TRANSLATION_TOLERANCE_METERS, 'basisTolerance': BASIS_TOLERANCE, 'uvTolerance': UV_TOLERANCE}
+    matrix = _pose_matrix(pose)
+    transformed = [_transformed(item, matrix) for item in current[:-1]]
+    triangles = [triangle for item in transformed for triangle in item['triangles']]
+    support_capture = current[-1]
+    try:
+        solution = solve_surface_placement(triangles, support_capture['triangles'], clearance / 1000)
+    except SurfacePlacementError as exc:
+        _unsupported(exc.reason, str(exc))
+    result_matrix = [list(row) for row in matrix]; result_matrix[2][3] += solution['deltaZ']
+    members = [{'entityId': entity_id, 'geometry': transformed[index]['metadata']} for index, entity_id in enumerate(ids)]
+    offset, contact_member = 0, None
+    for member in members:
+        count = member['geometry']['triangleCount']
+        if offset <= solution['subjectTriangleIndex'] < offset + count:
+            contact_member = member['entityId']
+        offset += count
+    union = {key: sum(member['geometry'][key] for member in members) for key in ('meshObjectCount', 'vertexCount', 'triangleCount')}
+    union['rootWorldMatrix'] = next(member['geometry']['rootWorldMatrix'] for member in members if member['entityId'] == subject)
+    union['worldBoundsMeters'] = {'min': [min(member['geometry']['worldBoundsMeters']['min'][a] for member in members) for a in range(3)],
+                                 'max': [max(member['geometry']['worldBoundsMeters']['max'][a] for member in members) for a in range(3)]}
+    report = {'schemaVersion': 'deepblend.assembly-placement/v1', 'axis': 'world-z', 'checkpointSha256': expected,
+              'checkpointUnchanged': True, 'frame': frame, 'blenderVersion': bpy.app.version_string,
+              'subjectEntityId': subject, 'memberEntityIds': ids, 'members': members, 'supportEntityId': support,
+              'pose': pose, 'poseMatrixMeters': matrix, 'resultWorldMatrixMeters': result_matrix,
+              'clearanceMm': clearance, 'translationMeters': [0, 0, solution['deltaZ']],
+              'subjectContactEntityId': contact_member, 'subjectContactMeters': solution['subjectContactMeters'],
+              'supportContactMeters': solution['supportContactMeters'], 'placedSubjectContactMeters': solution['placedSubjectContactMeters'],
+              'subjectTriangleIndex': solution['subjectTriangleIndex'], 'supportTriangleIndex': solution['supportTriangleIndex'],
+              'statistics': {'candidatePairs': solution['statistics']['candidatePairs']},
+              'subject': union, 'support': support_capture['metadata']}
+    if verification is not None:
+        report['baselineVerification'] = verification
+    _verified_checkpoint(checkpoint, expected)
+    return report, [], []

package/python/deepblend_product_framing.py

@@ -0,0 +1,306 @@
+"""Fit an explicit static view without changing the evaluated viewing rotation.
+
+The perspective solve uses every selected vertex, in camera coordinates. The
+verification path must project the compiled candidate independently of this
+formula; a proposed location alone is never evidence of a successful fit.
+"""
+import math
+import hashlib
+import json
+import os
+import re
+import struct
+
+from deepblend_util import ActionError
+
+VERSION = 'deepblend.camera-fit/v1'
+TOLERANCE = .00002
+
+
+def _refuse(message, code='SCENE_VALIDATION_FAILED'):
+    raise ActionError(code, 'Camera fit: '+message)
+
+
+def fit_perspective_points(points, limits, clipping, margin):
+    """Return the new origin in the source camera's normalized local frame.
+
+    Recenter the vertex bounds and find a distance satisfying all four frustum
+    planes and the near clip. Shifted frusta are handled by moving the origin
+    opposite their midpoint slope. Far clipping is a hard refusal.
+    """
+    if (not isinstance(points, (list, tuple)) or len(limits) != 4 or len(clipping) != 2 or
+            not all(math.isfinite(x) for x in [*limits, *clipping, margin]) or
+            not 0 <= margin <= .25 or not 0 < clipping[0] < clipping[1]):
+        raise ValueError('Invalid perspective calibration')
+    left, right, bottom, top = limits
+    if not left < right or not bottom < top:
+        raise ValueError('Degenerate perspective calibration')
+    width, height = right-left, top-bottom
+    left, right = left+width*margin, right-width*margin
+    bottom, top = bottom+height*margin, top-height*margin
+    middle_x, middle_y = (left+right)/2, (bottom+top)/2
+    half_x, half_y = (right-left)/2, (top-bottom)/2
+    low, high, count = [math.inf]*3, [-math.inf]*3, 0
+    for point in points:
+        count += 1
+        if count > 2_000_000 or len(point) != 3 or not all(math.isfinite(x) and abs(x) <= 1e6 for x in point):
+            raise ValueError('Invalid or excessive evaluated vertices')
+        for axis in range(3):
+            low[axis], high[axis] = min(low[axis], point[axis]), max(high[axis], point[axis])
+    if count == 0:
+        raise ValueError('No evaluated vertices')
+    center = [(low[i]+high[i])/2 for i in range(3)]
+    distance = 0.0
+    for point in points:
+        x, y, z = [point[i]-center[i] for i in range(3)]
+        distance = max(distance, (x+right*z)/half_x, -(x+left*z)/half_x,
+                       (y+top*z)/half_y, -(y+bottom*z)/half_y,
+                       clipping[0]+z)
+    # Recompilation and matrix operations use Blender's single-precision values.
+    distance += max(.0001, distance*1e-5)
+    nearest, farthest = distance-(high[2]-center[2]), distance-(low[2]-center[2])
+    if not math.isfinite(distance) or farthest >= clipping[1]-.00001:
+        raise ValueError('The complete selection cannot fit inside the camera clip range')
+    return {'origin': [center[0]-middle_x*distance, center[1]-middle_y*distance, center[2]+distance],
+            'center': center, 'distanceMeters': distance,
+            'nearestDepthMeters': nearest, 'farthestDepthMeters': farthest,
+            'vertexCount': count}
+
+
+def _hash_file(path, expected):
+    from deepblend_inspect_geometry import file_digest
+    if not isinstance(path, str) or not os.path.isfile(path) or file_digest(path) != expected:
+        _refuse('The checkpoint differs from its pinned native source.')
+
+
+def _camera_settings(camera):
+    data = camera.data
+    if (data.type != 'PERSP' or data.dof.aperture_blades != 0 or
+            data.dof.aperture_rotation != 0 or data.dof.aperture_ratio != 1):
+        _refuse('This camera has unsupported projection or aperture settings.', 'BLENDER_UNSUPPORTED_ACTION')
+    return {'lens': float(data.lens), 'sensorWidth': float(data.sensor_width),
+            'sensorHeight': float(data.sensor_height), 'sensorFit': data.sensor_fit,
+            'shift': [float(data.shift_x), float(data.shift_y)],
+            'clipping': [float(data.clip_start), float(data.clip_end)],
+            **({'fStop': float(data.dof.aperture_fstop)} if data.dof.use_dof else {})}
+
+
+def canonical_face(indices):
+    """Face order and cyclic starting corners do not change oriented topology."""
+    values = tuple(indices)
+    if not values:
+        _refuse('An evaluated face has no corners.')
+    start = min(range(len(values)), key=values.__getitem__)
+    return values[start:]+values[:start]
+
+
+def _capture(path, expected, selection, camera_id):
+    import bpy
+    from mathutils import Vector
+    from bpy_extras.object_utils import world_to_camera_view
+    from deepblend_geometry_framing import framing_camera
+    _hash_file(path, expected)
+    bpy.ops.wm.open_mainfile(filepath=path, load_ui=False, use_scripts=False)
+    scene = bpy.context.scene
+    if len(scene.objects) > 100_000:
+        _refuse('The native scene exceeds the original-object verification budget.', 'SCENE_TOO_HEAVY')
+    if bpy.data.libraries or abs(scene.unit_settings.scale_length-1) > 1e-8:
+        _refuse('A self-contained checkpoint with metre units is required.', 'BLENDER_UNSUPPORTED_ACTION')
+    scene.frame_set(selection['frame'])
+    if scene.frame_current != selection['frame']:
+        _refuse('The requested frame was not evaluated.')
+    graph = bpy.context.evaluated_depsgraph_get()
+    inverse, limits, _ = framing_camera(scene, graph, camera_id, selection['margin'])
+    camera = bpy.data.objects['db_camera__'+camera_id].evaluated_get(graph)
+    settings = _camera_settings(camera)
+    matrix = camera.matrix_world.normalized().copy()
+    if (matrix.to_3x3().determinant() < 0 or
+            any(abs(matrix.col[a].to_3d().dot(matrix.col[b].to_3d())) > 1e-6
+                for a in range(3) for b in range(a+1, 3))):
+        _refuse('A nonsheared viewing rotation is required.', 'BLENDER_UNSUPPORTED_ACTION')
+    render_visible, visited, pending = set(), set(), [scene.collection]
+    while pending:
+        collection = pending.pop()
+        pointer = collection.as_pointer()
+        if pointer in visited or collection.hide_render:
+            continue
+        visited.add(pointer)
+        render_visible.update(obj.as_pointer() for obj in collection.objects)
+        pending.extend(collection.children)
+    parts, members, total_vertices, total_polygons = [], [], 0, 0
+    owned = set()
+    all_world = []
+    asset_ids = selection.get('assetInstanceIds', [])
+    for entity_id in selection['entityIds']:
+        obj = bpy.data.objects.get('db_entity__'+entity_id)
+        if obj is None:
+            _refuse('The selected native entity does not exist: '+entity_id, 'SCENE_SPEC_INVALID')
+        if entity_id not in asset_ids and (obj.type != 'MESH' or obj.children):
+            _refuse('Select whole mesh entities or explicit asset instances.', 'BLENDER_UNSUPPORTED_ACTION')
+        pending, hierarchy, meshes = [obj], [], []
+        while pending:
+            part = pending.pop()
+            pointer = part.as_pointer()
+            if pointer in owned or len(owned) >= 4096:
+                _refuse('Overlapping selections or an excessive hierarchy cannot be fitted.', 'BLENDER_UNSUPPORTED_ACTION')
+            owned.add(pointer)
+            if part != obj and part.name.startswith(('db_entity__', 'db_camera__', 'db_light__')):
+                if not (part.name.startswith(obj.name+'_') and part.get('deepblend_id') == entity_id and
+                        part.get('deepblend_kind') == 'entity' and isinstance(part.get('deepblend_part_id'), str) and part['deepblend_part_id']):
+                    _refuse('An asset hierarchy includes another managed entity.', 'BLENDER_UNSUPPORTED_ACTION')
+            if (part.type not in ('EMPTY', 'MESH') or part.instance_type != 'NONE' or
+                    not part.visible_get(view_layer=bpy.context.view_layer) or part.hide_render or
+                    pointer not in render_visible):
+                _refuse('Hidden, instanced or nonmesh hierarchy parts cannot be silently omitted.', 'BLENDER_UNSUPPORTED_ACTION')
+            if part.rigid_body is not None or part.rigid_body_constraint is not None:
+                _refuse('Physics-dependent geometry is outside a static fitted view.', 'BLENDER_UNSUPPORTED_ACTION')
+            for modifier in part.modifiers:
+                if (modifier.show_viewport != modifier.show_render or
+                        modifier.type in ('CLOTH', 'SOFT_BODY', 'FLUID', 'PARTICLE_SYSTEM', 'NODES') or
+                        modifier.type == 'SUBSURF' and modifier.levels != modifier.render_levels):
+                    _refuse('The selected viewport geometry does not provide a bounded render-equivalent mesh.', 'BLENDER_UNSUPPORTED_ACTION')
+            hierarchy.append([part.name, part.parent.name if part.parent else None, part.type])
+            if part.type == 'MESH':
+                meshes.append(part)
+            pending.extend(sorted(part.children, key=lambda p: p.name, reverse=True))
+        if not meshes or len(parts)+len(meshes) > 128:
+            _refuse('Select 1–128 mesh objects in total.', 'SCENE_TOO_HEAVY')
+        world, low, high, digest = [], [math.inf]*3, [-math.inf]*3, hashlib.sha256()
+        for part in meshes:
+            evaluated = part.evaluated_get(graph)
+            mesh = evaluated.to_mesh()
+            try:
+                if mesh is None or not mesh.vertices or not mesh.polygons:
+                    _refuse('A selected mesh is empty.')
+                total_vertices += len(mesh.vertices)
+                total_polygons += len(mesh.polygons)
+                if total_vertices > 2_000_000 or total_polygons > 2_000_000:
+                    _refuse('The complete selection exceeds two million vertices or polygons.', 'SCENE_TOO_HEAVY')
+                vertices = []
+                for vertex in mesh.vertices:
+                    point = tuple(float(x) for x in evaluated.matrix_world @ vertex.co)
+                    if not all(math.isfinite(x) and abs(x) <= 1e6 for x in point):
+                        _refuse('Nonfinite or excessive world coordinates.')
+                    digest.update(struct.pack('<3d', *point))
+                    vertices.append(point)
+                    for axis in range(3):
+                        low[axis], high[axis] = min(low[axis], point[axis]), max(high[axis], point[axis])
+                topology = sorted(canonical_face(p.vertices) for p in mesh.polygons)
+                digest.update(json.dumps(topology, separators=(',', ':')).encode())
+                parts.append({'name': part.name, 'vertices': vertices, 'topology': topology})
+                world.extend(vertices)
+            finally:
+                evaluated.to_mesh_clear()
+        projected = [world_to_camera_view(scene, camera, Vector(p)) for p in world]
+        nearest, farthest = min(p.z for p in projected), max(p.z for p in projected)
+        projection = {'containedInClip': nearest >= settings['clipping'][0] and farthest <= settings['clipping'][1],
+                      'nearestDepthMeters': nearest, 'farthestDepthMeters': farthest,
+                      'containedInFrame': False}
+        if nearest > 1e-8:
+            minimum, maximum = [min(p[i] for p in projected) for i in range(2)], [max(p[i] for p in projected) for i in range(2)]
+            projection.update(normalizedBounds={'min': minimum, 'max': maximum},
+                              containedInFrame=all(minimum[i] >= selection['margin'] and maximum[i] <= 1-selection['margin'] for i in range(2)))
+        members.append({'entityId': entity_id, 'meshObjectCount': len(meshes), 'vertexCount': len(world),
+                        'worldBoundsMeters': {'min': low, 'max': high}, 'geometrySha256': digest.hexdigest(),
+                        'projection': projection, 'hierarchy': hierarchy})
+        all_world.extend(world)
+    # Preserve original scene objects, cameras and lights at this same frame.
+    states = {}
+    for obj in scene.objects:
+        evaluated = obj.evaluated_get(graph)
+        state = {'type': obj.type, 'matrix': [list(row) for row in evaluated.matrix_world]}
+        if obj.type == 'CAMERA':
+            from deepblend_render import _camera_facts
+            state['camera'] = _camera_facts(scene, obj)
+        if obj.type == 'LIGHT':
+            state['light'] = {'type': evaluated.data.type, 'energy': float(evaluated.data.energy), 'color': list(evaluated.data.color)}
+        states[obj.name] = state
+    view = {'resolution': [scene.render.resolution_x, scene.render.resolution_y],
+            'percentage': scene.render.resolution_percentage,
+            'pixelAspect': [float(scene.render.pixel_aspect_x), float(scene.render.pixel_aspect_y)],
+            'activeCamera': scene.camera.name if scene.camera else None}
+    _hash_file(path, expected)
+    return {'matrix': matrix, 'inverse': inverse, 'limits': limits, 'settings': settings,
+            'world': all_world, 'parts': parts, 'members': members, 'states': states, 'view': view,
+            'focusDistance': float(camera.data.dof.focus_distance),
+            'focusObject': camera.data.dof.focus_object.name if camera.data.dof.focus_object else None}
+
+
+def _near_tree(a, b):
+    if isinstance(a, (int, float)) and not isinstance(a, bool):
+        return isinstance(b, (int, float)) and math.isfinite(a) and math.isfinite(b) and abs(a-b) <= 1e-6
+    if isinstance(a, dict):
+        return isinstance(b, dict) and a.keys() == b.keys() and all(_near_tree(a[k], b[k]) for k in a)
+    if isinstance(a, (list, tuple)):
+        return isinstance(b, (list, tuple)) and len(a) == len(b) and all(_near_tree(x, y) for x, y in zip(a, b))
+    return type(a) is type(b) and a == b
+
+
+def inspect_camera_fit(request, options):
+    """Read-only proposal or independent candidate verification in a private batch."""
+    import bpy
+    from mathutils import Vector
+    payload = request.get('payload')
+    required = {'entityIds', 'assetInstanceIds', 'frame', 'cameraId', 'fittedCameraId', 'margin', 'checkpointSha256'}
+    baseline_keys = {'baselineCheckpointPath', 'baselineCheckpointSha256'}
+    candidate = isinstance(payload, dict) and bool(baseline_keys & payload.keys())
+    if (not isinstance(payload, dict) or set(payload) != required | (baseline_keys if candidate else set()) or
+            not isinstance(payload.get('entityIds'), list) or not 1 <= len(payload['entityIds']) <= 64 or
+            len(set(payload['entityIds'])) != len(payload['entityIds']) or
+            not isinstance(payload.get('assetInstanceIds'), list) or len(set(payload['assetInstanceIds'])) != len(payload['assetInstanceIds']) or
+            not set(payload['assetInstanceIds']) <= set(payload['entityIds']) or
+            any(not isinstance(x, str) or not re.fullmatch(r'[A-Za-z][A-Za-z0-9._-]{0,127}', x)
+                for x in [*payload['entityIds'], payload.get('cameraId'), payload.get('fittedCameraId')]) or
+            payload['cameraId'] == payload['fittedCameraId'] or
+            type(payload.get('frame')) is not int or not 0 <= payload['frame'] <= 1_000_000 or
+            type(payload.get('margin')) not in (int, float) or not math.isfinite(payload['margin']) or not 0 <= payload['margin'] <= .25 or
+            not isinstance(payload.get('checkpointSha256'), str) or not re.fullmatch(r'[a-f0-9]{64}', payload['checkpointSha256']) or
+            candidate and (not isinstance(payload.get('baselineCheckpointSha256'), str) or not re.fullmatch(r'[a-f0-9]{64}', payload['baselineCheckpointSha256']))):
+        _refuse('Expected one bounded frame, camera, distinct new camera and complete selection.', 'SCENE_SPEC_INVALID')
+    path = options.get('blend')
+    measured = _capture(path, payload['checkpointSha256'], payload, payload['fittedCameraId'] if candidate else payload['cameraId'])
+    report = {'schemaVersion': VERSION, **{k: payload[k] for k in required},
+              'checkpointUnchanged': True, 'blenderVersion': bpy.app.version_string,
+              'members': [{k: v for k, v in member.items() if k != 'hierarchy'} for member in measured['members']],
+              'view': measured['view'], 'camera': {'id': payload['fittedCameraId'] if candidate else payload['cameraId'],
+                  **measured['settings'], 'matrixWorld': [list(row) for row in measured['matrix']],
+                  'focusDistance': measured['focusDistance'], 'focusObject': measured['focusObject']}}
+    if candidate:
+        baseline = _capture(payload['baselineCheckpointPath'], payload['baselineCheckpointSha256'], payload, payload['cameraId'])
+        if not all(m['projection']['containedInFrame'] and m['projection']['containedInClip'] for m in measured['members']):
+            _refuse('The compiled candidate does not contain the complete selection.')
+        if len(baseline['parts']) != len(measured['parts']):
+            _refuse('The candidate changed selected mesh ownership.')
+        max_error = 0.0
+        for a, b in zip(baseline['parts'], measured['parts']):
+            if a['name'] != b['name'] or a['topology'] != b['topology'] or len(a['vertices']) != len(b['vertices']):
+                _refuse('The candidate changed selected geometry topology.')
+            for p, q in zip(a['vertices'], b['vertices']):
+                max_error = max(max_error, math.dist(p, q))
+        original_states = dict(measured['states'])
+        new_state = original_states.pop('db_camera__'+payload['fittedCameraId'], None)
+        if (max_error > TOLERANCE or new_state is None or not _near_tree(original_states, baseline['states']) or
+                not _near_tree(measured['view'], baseline['view']) or
+                not _near_tree(measured['settings'], baseline['settings']) or
+                any(abs(measured['matrix'][i][j]-baseline['matrix'][i][j]) > 1e-6 for i in range(3) for j in range(3))):
+            _refuse('The candidate changed original geometry, photography or viewing direction.')
+        report['baselineVerification'] = {'checkpointSha256': payload['baselineCheckpointSha256'], 'checkpointUnchanged': True,
+            'selectedGeometryUnchanged': True, 'originalObjectsUnchanged': True, 'opticsAndRotationPreserved': True,
+            'maxVertexErrorMeters': max_error, 'toleranceMeters': TOLERANCE,
+            'originalObjectCount': len(baseline['states'])}
+    else:
+        if 'db_camera__'+payload['fittedCameraId'] in measured['states']:
+            _refuse('The new camera ID is already in use.', 'SCENE_SPEC_INVALID')
+        try:
+            fitted = fit_perspective_points([list(measured['inverse'] @ Vector(p)) for p in measured['world']],
+                                            measured['limits'], measured['settings']['clipping'], payload['margin'])
+        except ValueError as exc:
+            _refuse(str(exc))
+        camera = {'id': payload['fittedCameraId'], 'role': 'detail', **measured['settings'],
+                  'transform': {'location': list(measured['matrix'] @ Vector(fitted['origin'])),
+                                'rotationEuler': list(measured['matrix'].to_euler('XYZ')), 'scale': [1, 1, 1]}}
+        if 'fStop' in camera:
+            camera['focusDistance'] = fitted['distanceMeters']
+        report['proposal'] = camera
+    _hash_file(path, payload['checkpointSha256'])
+    return report, [], []

package/python/deepblend_scene.py

@@ -892,6 +892,9 @@ def build_camera(spec, entity_positions):
     data = bpy.data.cameras.new(name="%s%s" % (CAMERA_PREFIX, camera_id))
     data.lens = float(spec.get("lens", 50.0))
     data.sensor_width = float(spec.get("sensorWidth", 36.0))
+    data.sensor_height = float(spec.get("sensorHeight", 24.0))
+    data.sensor_fit = spec.get("sensorFit", "AUTO")
+    data.shift_x, data.shift_y = spec.get("shift", [0.0, 0.0])
     clipping = spec.get("clipping")
     if clipping:
         data.clip_start = float(clipping[0])
@@ -947,7 +950,9 @@ def build_camera(spec, entity_positions):
         focus_object = None
         if target_entity is not None:
             focus_object = bpy.data.objects.get("%s%s" % (ENTITY_PREFIX, target_entity))
-        if focus_object is not None:
+        if spec.get("focusDistance") is not None:
+            data.dof.focus_distance = float(spec["focusDistance"])
+        elif focus_object is not None:
             # Focusing the object rather than a distance keeps a MOVING subject
             # sharp for the whole shot instead of only at the frame it was
             # measured on.

package/python/deepblend_surface_placement.py

@@ -520,7 +520,8 @@ def _capture_checkpoint(path, expected, frame, subject_id, support_id):
         render_visible.update(item.as_pointer() for item in collection.objects)
         pending_collections.extend(collection.children)
     result = []
-    for entity_id in (subject_id, support_id):
+    entity_ids = [*subject_id, support_id] if isinstance(subject_id, list) else [subject_id, support_id]
+    for entity_id in entity_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)
@@ -559,6 +560,9 @@ def inspect_surface_placement(request, options):
     """Inspect a hash-bound checkpoint, optionally proving a saved rigid move."""
     import bpy
     payload = request.get('payload')
+    if isinstance(payload, dict) and payload.get('scope') == 'recipe-assembly':
+        from deepblend_assembly_placement import inspect_assembly_placement
+        return inspect_assembly_placement(request, options)
     allowed = {'subjectEntityId', 'supportEntityId', 'frame', 'clearanceMm', 'checkpointSha256',
                'baselineCheckpointPath', 'baselineCheckpointSha256', 'expectedTranslationMeters'}
     if not isinstance(payload, dict) or set(payload) - allowed: