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

package/lib/index.js

@@ -1587,12 +1587,16 @@ 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.objectAxes === true ? { objectAxes: true } : {}),
           ...(request.surfaceSamples === undefined ? {} : { surfaceSamples: request.surfaceSamples }) } },
       { signal: request.signal, session: false, args: ['--blend', snapshot] })
       aborted()
       if (request.surfaceSamples !== undefined && run.envelope?.result?.schemaVersion === 'deepblend.geometry-inspection/v1') {
         throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Blender bootstrap does not support local surface sampling. Upgrade DeepBlend; ordinary native geometry reads remain available.')
       }
+      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.')
+      }
       const report = verifyGeometryReport(run.envelope?.result, request)
       assertDigest(await digest(source))
       aborted()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.13.0",
+  "version": "0.14.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.13.0"
+    "@deepblend/dsh-blender-contracts": "0.14.0"
   },
   "license": "MIT",
   "repository": {

package/python/deepblend_features.py

@@ -1,2 +1,2 @@
 """Scene vocabulary implemented by this runtime's compiler, not a Blender hardware claim."""
-SCENE_FEATURES = ("geometry.primitive.dimensions",)
+SCENE_FEATURES = ("geometry.primitive.dimensions", "geometry.procedural.mesh", "geometry.modifier.subdivision", "geometry.modifier.surface_scatter")

package/python/deepblend_geometry.py

@@ -5,7 +5,7 @@ import bpy
 from deepblend_util import ActionError
 
 
-def apply_model_modifiers(entities, entity_meshes):
+def apply_model_modifiers(entities, entity_meshes, animation_tracks=None):
     """Apply dependency-ordered, bounded mesh operations to actual geometry."""
     by_id = {entity["id"]: entity for entity in entities}
     done, active = set(), set()
@@ -21,12 +21,43 @@ def apply_model_modifiers(entities, entity_meshes):
         if entity_id in done:
             return
         if entity_id in active:
-            raise ActionError("SCENE_SPEC_INVALID", "boolean dependency cycle: " + entity_id)
+            raise ActionError("SCENE_SPEC_INVALID", "modifier dependency cycle: " + entity_id)
         active.add(entity_id)
         entity = by_id[entity_id]
-        for entry in entity.get("modifiers", []):
+        for index, entry in enumerate(entity.get("modifiers", [])):
             kind = entry["type"]
             obj = single_mesh(entity_id)
+            if kind == 'surface_scatter':
+                from deepblend_scatter import apply_surface_scatter
+                targets = entry.get('targetEntityIds')
+                if not isinstance(targets, list) or not 1 <= len(targets) <= 8 or any(not isinstance(key, str) for key in targets) or len(set(targets)) != len(targets):
+                    raise ActionError('SCENE_SPEC_INVALID', 'surface_scatter needs 1 to 8 distinct target IDs')
+                if index != len(entity.get('modifiers', [])) - 1 or entity_id in targets:
+                    raise ActionError('SCENE_SPEC_INVALID', 'surface_scatter must be last and cannot target itself')
+                animated = {track.get('targetEntityId') for track in animation_tracks or []
+                            if str(track.get('property', '')).split('.')[0] in ('location', 'rotationEuler', 'scale')}
+                dependency_keys = set()
+                def collect(key):
+                    if key in dependency_keys:
+                        return
+                    dependency_keys.add(key)
+                    for value in by_id.get(key, {}).get('modifiers', []):
+                        if value.get('type') == 'boolean':
+                            collect(value.get('targetEntityId'))
+                for key in [entity_id] + targets:
+                    collect(key)
+                for key in dependency_keys:
+                    part = by_id.get(key)
+                    if part is None or part.get('type') != 'generator' or key in animated or any(
+                            part.get(field) is not None for field in ('armatureId', 'rigidBody', 'cloth', 'softBody', 'fluid')):
+                        raise ActionError('SCENE_SPEC_INVALID', 'surface_scatter requires static generated mesh parts without rigs or physics')
+                    if key != entity_id and any(value.get('type') == 'surface_scatter' for value in part.get('modifiers', [])):
+                        raise ActionError('SCENE_SPEC_INVALID', 'nested surface_scatter targets are unavailable')
+                for target in targets:
+                    visit(target)
+                apply_surface_scatter(obj, [(key, single_mesh(key)) for key in targets], entry)
+                bpy.context.view_layer.update()
+                continue
             if kind == "boolean":
                 target = entry["targetEntityId"]
                 if target not in by_id:
@@ -34,9 +65,16 @@ def apply_model_modifiers(entities, entity_meshes):
                 visit(target)
                 operand = single_mesh(target)
             estimate = len(obj.data.polygons) * (entry.get("count", 1) if kind == "array" else 1)
+            if kind == "subdivision":
+                levels = entry.get('levels')
+                if isinstance(levels, bool) or not isinstance(levels, int) or not 1 <= levels <= 3:
+                    raise ActionError('SCENE_SPEC_INVALID', 'subdivision needs 1 to 3 levels')
+                if entry.get('scheme', 'catmull-clark') not in ('catmull-clark', 'simple') or entry.get('boundaryMode', 'all') not in ('all', 'preserve-corners'):
+                    raise ActionError('SCENE_SPEC_INVALID', 'invalid subdivision scheme or boundary mode')
+                estimate = sum(len(polygon.vertices) for polygon in obj.data.polygons) * 4 ** (levels - 1)
             if estimate > 500_000:
                 raise ActionError("SCENE_SPEC_INVALID", "modifier exceeds the 500000 polygon per-entity budget")
-            modifier = obj.modifiers.new("db_model_" + kind, kind.upper())
+            modifier = obj.modifiers.new("db_model_" + kind, 'SUBSURF' if kind == 'subdivision' else kind.upper())
             if kind == "solidify":
                 modifier.thickness = float(entry["thickness"])
                 modifier.offset = float(entry.get("offset", -1))
@@ -49,6 +87,10 @@ def apply_model_modifiers(entities, entity_meshes):
                 modifier.use_relative_offset = False
                 modifier.use_constant_offset = True
                 modifier.constant_offset_displace = entry["offset"]
+            elif kind == 'subdivision':
+                modifier.subdivision_type = 'SIMPLE' if entry.get('scheme') == 'simple' else 'CATMULL_CLARK'
+                modifier.levels = modifier.render_levels = entry['levels']
+                modifier.boundary_smooth = 'PRESERVE_CORNERS' if entry.get('boundaryMode') == 'preserve-corners' else 'ALL'
             elif kind == "boolean":
                 modifier.operation = entry["operation"].upper()
                 modifier.solver = "EXACT"

package/python/deepblend_inspect_geometry.py

@@ -15,6 +15,20 @@ def file_digest(path):
     return digest.hexdigest()
 
 
+def object_axis_frame(matrix):
+    values = [[float(x) for x in row] for row in matrix]
+    if not all(math.isfinite(x) for row in values for x in row) or values[3] != [0, 0, 0, 1]:
+        return None
+    lengths = [math.sqrt(sum(values[row][axis] ** 2 for row in range(3))) for axis in range(3)]
+    if any(not math.isfinite(x) or x <= 1e-12 for x in lengths):
+        return None
+    columns = [[values[row][axis] / lengths[axis] for row in range(3)] for axis in range(3)]
+    if any(abs(sum(columns[a][row] * columns[b][row] for row in range(3))) > 1e-6 for a in range(3) for b in range(a + 1, 3)):
+        return None
+    basis = [[columns[axis][row] for axis in range(3)] + [values[row][3]] for row in range(3)] + [[0, 0, 0, 1]]
+    return lengths, basis
+
+
 def inspect_geometry(request, options):
     import bpy
     payload = request.get('payload')
@@ -26,6 +40,9 @@ def inspect_geometry(request, options):
             len(set(ids)) != len(ids) or type(frame) is not int or not 0 <= frame <= 1000000 or
             not isinstance(expected, str) or re.fullmatch('[a-f0-9]{64}', expected) is None):
         raise ActionError('BLENDER_SCRIPT_ERROR', 'Geometry inspection requires 1–8 distinct entity IDs, an explicit frame and checkpoint SHA256.')
+    object_axes = payload.get('objectAxes', False)
+    if type(object_axes) is not bool:
+        raise ActionError('BLENDER_SCRIPT_ERROR', 'objectAxes must be boolean.')
     samples = payload.get('surfaceSamples')
     if 'surfaceSamples' in payload:
         from deepblend_inspect_surface import validate_surface_selection
@@ -61,6 +78,7 @@ def inspect_geometry(request, options):
             entry['unavailableReason'] = 'viewport-disabled'
         else:
             evaluated = obj.evaluated_get(graph)
+            axis_frame = object_axis_frame(evaluated.matrix_world) if object_axes else None
             mesh = evaluated.to_mesh()
             try:
                 if mesh is None or not mesh.vertices:
@@ -68,13 +86,17 @@ def inspect_geometry(request, options):
                 else:
                     low = [math.inf] * 3
                     high = [-math.inf] * 3
+                    local_low, local_high = [math.inf] * 3, [-math.inf] * 3
                     finite = True
                     for vertex in mesh.vertices:
                         point = evaluated.matrix_world @ vertex.co
-                        if not all(math.isfinite(x) for x in point):
+                        if not all(math.isfinite(x) for x in point) or not all(math.isfinite(x) for x in vertex.co):
                             finite = False
                             break
                         for axis in range(3):
+                            if object_axes and axis_frame is not None:
+                                local_low[axis] = min(local_low[axis], float(vertex.co[axis]) * axis_frame[0][axis])
+                                local_high[axis] = max(local_high[axis], float(vertex.co[axis]) * axis_frame[0][axis])
                             low[axis] = min(low[axis], float(point[axis]))
                             high[axis] = max(high[axis], float(point[axis]))
                     matrix = [[float(x) for x in row] for row in evaluated.matrix_world]
@@ -85,6 +107,11 @@ def inspect_geometry(request, options):
                         entry.update(available=True, worldBoundsMeters={'min': low, 'max': high},
                                      worldAxisExtentMm=[(high[i] - low[i]) * 1000 for i in range(3)],
                                      worldMatrix=matrix, scale=scale, vertexCount=len(mesh.vertices), polygonCount=len(mesh.polygons))
+                        if object_axes and axis_frame is None:
+                            entry['objectAxisStatus'] = 'unsupported-object-axis-basis'
+                        elif object_axes:
+                            entry.update(objectAxisStatus='measured', objectAxisWorldMatrix=axis_frame[1], objectAxisBoundsMeters={'min': local_low, 'max': local_high},
+                                         objectAxisExtentMm=[(local_high[i] - local_low[i]) * 1000 for i in range(3)])
             finally:
                 evaluated.to_mesh_clear()
         objects.append(entry)
@@ -95,6 +122,9 @@ def inspect_geometry(request, options):
         from deepblend_inspect_surface import inspect_surface_samples
         report['schemaVersion'] = 'deepblend.geometry-inspection/v2'
         report['surfaceSamples'] = inspect_surface_samples(samples, graph)
+    if object_axes:
+        report['schemaVersion'] = 'deepblend.geometry-inspection/v3'
+        report['objectAxisBasis'] = 'evaluated-object-axes-scaled'
     if file_digest(checkpoint) != expected:
         raise ActionError('SCENE_VALIDATION_FAILED', 'The checkpoint changed during geometry inspection.')
     return report, [], []

package/python/deepblend_mesh.py

@@ -0,0 +1,80 @@
+"""Bounded indexed control geometry. Inputs are data, never executable text."""
+import math
+
+import bpy
+from deepblend_util import ActionError
+
+
+def create_mesh(name, spec):
+    vertices, faces = spec.get('vertices'), spec.get('faces')
+
+    def invalid(message):
+        raise ActionError('SCENE_SPEC_INVALID', 'mesh: ' + message)
+
+    def number(value):
+        return not isinstance(value, bool) and isinstance(value, (int, float)) and math.isfinite(value)
+
+    if not isinstance(vertices, list) or not 3 <= len(vertices) <= 32768:
+        invalid('requires 3 to 32768 local-space vertices')
+    if any(not isinstance(point, list) or len(point) != 3 or
+           any(not number(value) or abs(value) > 1e6 for value in point) for point in vertices):
+        invalid('vertices need finite bounded local coordinates')
+    if not isinstance(faces, list) or not 1 <= len(faces) <= 32768:
+        invalid('requires 1 to 32768 indexed faces')
+    if any(not isinstance(face, list) or not 3 <= len(face) <= 32 for face in faces):
+        invalid('faces need 3 to 32 corners')
+    if sum(len(face) for face in faces) > 131072:
+        invalid('exceeds the 131072 face-corner budget')
+    seen = set()
+    for face in faces:
+        if any(isinstance(index, bool) or not isinstance(index, int) or not 0 <= index < len(vertices) for index in face):
+            invalid('face index outside vertices')
+        key = frozenset(face)
+        if len(key) != len(face) or key in seen:
+            invalid('repeated face or face vertex')
+        seen.add(key)
+        origin = vertices[face[0]]
+        points = [[value - origin[axis] for axis, value in enumerate(vertices[index])] for index in face]
+        normal = [0.0, 0.0, 0.0]
+        for a, b in zip(points[1:-1], points[2:]):
+            normal[0] += a[1] * b[2] - a[2] * b[1]
+            normal[1] += a[2] * b[0] - a[0] * b[2]
+            normal[2] += a[0] * b[1] - a[1] * b[0]
+        scale_squared = max(sum(value * value for value in point) for point in points)
+        if math.hypot(*normal) <= scale_squared * 1e-12:
+            invalid('zero or unstable face area')
+    face_uvs = spec.get('faceUvs')
+    if face_uvs is not None and (not isinstance(face_uvs, list) or len(face_uvs) != len(faces) or
+            any(not isinstance(corners, list) or len(corners) != len(face) or
+                any(not isinstance(uv, list) or len(uv) != 2 or any(not number(v) for v in uv) for uv in corners)
+                for face, corners in zip(faces, face_uvs))):
+        invalid('faceUvs need one finite UV pair per face corner')
+    if 'smooth' in spec and not isinstance(spec['smooth'], bool):
+        invalid('smooth must be boolean')
+
+    mesh = bpy.data.meshes.new(name + '_mesh')
+    try:
+        mesh.from_pydata(vertices, [], faces)
+        mesh.update(calc_edges=True)
+        if mesh.validate(verbose=False, clean_customdata=False):
+            invalid('Blender refused the authored topology')
+        uv_layer = mesh.uv_layers.new(name='UVMap')
+        low = [min(point[axis] for point in vertices) for axis in range(3)]
+        extent = [max(point[axis] for point in vertices) - low[axis] for axis in range(3)]
+        axes = sorted(range(3), key=lambda axis: (-extent[axis], axis))[:2]
+        for index, polygon in enumerate(mesh.polygons):
+            polygon.use_smooth = spec.get('smooth', False)
+            for corner, loop in enumerate(polygon.loop_indices):
+                coordinate = face_uvs[index][corner] if face_uvs is not None else [
+                    (vertices[mesh.loops[loop].vertex_index][axis] - low[axis]) / (extent[axis] or 1) for axis in axes]
+                uv_layer.data[loop].uv = coordinate
+    except Exception:
+        bpy.data.meshes.remove(mesh)
+        raise
+    for selected in bpy.context.selected_objects:
+        selected.select_set(False)
+    obj = bpy.data.objects.new(name, mesh)
+    bpy.context.scene.collection.objects.link(obj)
+    bpy.context.view_layer.objects.active = obj
+    obj.select_set(True)
+    return obj

package/python/deepblend_scatter.py

@@ -0,0 +1,213 @@
+"""Bounded, deterministic placement of a prototype on static closed meshes.
+
+This is a runtime modeling primitive, not a case/recipe script. Only structured
+SceneSpec data enters it. Every emitted attachment vertex is checked against
+the actual target solid before the new mesh replaces the prototype.
+"""
+import bisect
+import json
+import math
+import random
+from array import array
+
+import bmesh
+import bpy
+from mathutils import Quaternion, Vector
+from mathutils.bvhtree import BVHTree
+
+from deepblend_util import ActionError
+
+MAX_POLYGONS = 500_000
+MAX_VERTICES = 1_000_000
+MAX_LOOPS = 2_000_000
+MAX_TARGET_POLYGONS = 131_072
+MAX_TARGET_TRIANGLES = 262_144
+RAY_DIRECTIONS = tuple(Vector(value).normalized() for value in
+                       ((1, .173, .287), (.219, 1, .131), (.157, .271, 1)))
+
+
+def _refuse(message):
+    raise ActionError('SCENE_SPEC_INVALID', 'surface_scatter: ' + message)
+
+
+def _finite(value):
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def _inside(target, point):
+    """Three independent parity rays; ambiguous/excessive crossings are refused."""
+    votes = 0
+    for direction in RAY_DIRECTIONS:
+        origin, hits = point.copy(), 0
+        for _ in range(256):
+            location, _, _, _ = target['bvh'].ray_cast(origin, direction, target['ray_length'])
+            if location is None:
+                break
+            hits += 1
+            origin = location + direction * target['epsilon'] * 4
+        else:
+            return False
+        votes += hits % 2
+    return votes >= 2
+
+
+def _target(entity_id, obj):
+    mesh = obj.data
+    bm = bmesh.new()
+    try:
+        bm.from_mesh(mesh)
+        if not bm.faces or any(not edge.is_manifold for edge in bm.edges) or abs(bm.calc_volume(signed=True)) <= 1e-18:
+            _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]
+    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()
+    triangles = [tuple(triangle.vertices) for triangle in mesh.loop_triangles]
+    diagonal = math.sqrt(sum((max(point[axis] for point in points) - min(point[axis] for point in points)) ** 2 for axis in range(3)))
+    epsilon = max(1e-6, max(abs(value) for point in points for value in point) * 4e-7, diagonal * 1e-7)
+    return {'id': entity_id, 'points': points, 'triangles': triangles,
+            'bvh': BVHTree.FromPolygons(points, triangles, all_triangles=True),
+            'epsilon': epsilon, 'ray_length': max(1.0, diagonal * 4)}
+
+
+def apply_surface_scatter(obj, targets, entry):
+    count = entry.get('count')
+    seed = entry.get('seed', 0)
+    anchors = entry.get('anchorVertexIndices')
+    scales = entry.get('scaleRange', [1.0, 1.0])
+    depth_mm = entry.get('embedDepthMm', 5.0)
+    bias = entry.get('upwardBias', 0.0)
+    if isinstance(count, bool) or not isinstance(count, int) or not 1 <= count <= 512:
+        _refuse('count must be an integer from 1 to 512')
+    if isinstance(seed, bool) or not isinstance(seed, int) or not 0 <= seed <= 2_147_483_647:
+        _refuse('seed must be an integer from 0 to 2147483647')
+    if not isinstance(targets, list) or not 1 <= len(targets) <= 8 or len({key for key, _ in targets}) != len(targets):
+        _refuse('select 1 to 8 distinct static target meshes')
+    if not isinstance(anchors, list) or not 1 <= len(anchors) <= 8 or any(
+            isinstance(index, bool) or not isinstance(index, int) or index < 0 for index in anchors) or len(set(anchors)) != len(anchors):
+        _refuse('anchorVertexIndices needs 1 to 8 distinct evaluated prototype vertex indices')
+    if not isinstance(scales, list) or len(scales) != 2 or any(not _finite(value) for value in scales) or not .05 <= scales[0] <= scales[1] <= 20:
+        _refuse('scaleRange must be an ordered positive range within 0.05 to 20')
+    if not _finite(depth_mm) or not 0 < depth_mm <= 100 or not _finite(bias) or not 0 <= bias <= 1:
+        _refuse('embedDepthMm must be within (0,100] and upwardBias within [0,1]')
+    source = obj.data
+    if not source.polygons or len(source.polygons) * count > MAX_POLYGONS or len(source.vertices) * count > MAX_VERTICES or len(source.loops) * count > MAX_LOOPS:
+        _refuse('prototype times count exceeds the vertex, polygon or UV-corner budget before allocation')
+    if any(index >= len(source.vertices) for index in anchors):
+        _refuse('attachment index exceeds the evaluated prototype vertex count')
+    used = {index for polygon in source.polygons for index in polygon.vertices}
+    if any(index not in used for index in anchors):
+        _refuse('attachment vertices must belong to actual prototype faces')
+    if sum(len(target.data.polygons) for _, target in targets) > MAX_TARGET_POLYGONS:
+        _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]
+    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
+    for target in target_records:
+        for triangle in target['triangles']:
+            a, b, c = (target['points'][index] for index in triangle)
+            normal = (b - a).cross(c - a)
+            area = normal.length * .5
+            if area <= 1e-14:
+                continue
+            normal.normalize()
+            total += area
+            weighted.append((target, a, b, c, normal))
+            areas.append(total)
+    if not weighted or not math.isfinite(total):
+        _refuse('targets have no measurable triangle surface')
+    prototype = [vertex.co.copy() for vertex in source.vertices]
+    if any(not all(math.isfinite(value) for value in point) for point in prototype):
+        _refuse('prototype has non-finite coordinates')
+    anchor = sum((prototype[index] for index in anchors), Vector()) / len(anchors)
+    relative = [point - anchor for point in prototype]
+    faces = [tuple(polygon.vertices) for polygon in source.polygons]
+    smooth = [polygon.use_smooth for polygon in source.polygons]
+    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()
+    try:
+        inverse = matrix.inverted()
+    except ValueError:
+        _refuse('prototype transform is singular')
+    linear = matrix.to_3x3()
+    axis = linear @ Vector((0, 0, 1))
+    if axis.length <= 1e-12:
+        _refuse('prototype Z axis is degenerate')
+    axis.normalize()
+    rng = random.Random(seed)
+    vertices, output_faces, placements = [], [], []
+    for _ in range(count * 16):
+        if len(placements) == count:
+            break
+        target, a, b, c, face_normal = weighted[min(len(weighted) - 1, bisect.bisect_right(areas, rng.random() * total))]
+        u, v = math.sqrt(rng.random()), rng.random()
+        surface = a * (1 - u) + b * (u * (1 - v)) + c * (u * v)
+        normal = face_normal.copy()
+        epsilon = target['epsilon']
+        if not _inside(target, surface - normal * epsilon):
+            if not _inside(target, surface + normal * epsilon):
+                continue
+            normal.negate()
+        _, _, _, chord = target['bvh'].ray_cast(surface - normal * epsilon, -normal, target['ray_length'])
+        if chord is None or not math.isfinite(chord):
+            continue
+        depth = min(depth_mm / 1000, (chord + epsilon) * .25)
+        if depth < epsilon * 8:
+            continue
+        point = surface - normal * depth
+        direction = normal * (1 - bias) + Vector((0, 0, 1)) * bias
+        if direction.length <= 1e-10:
+            direction = Vector((0, 0, 1))
+        direction.normalize()
+        scale = rng.uniform(*scales)
+        rotation = Quaternion(direction, rng.random() * math.tau).to_matrix() @ axis.rotation_difference(direction).to_matrix()
+        transform = rotation @ linear * scale
+        # Check the actual float32 round trip that will be stored in the mesh,
+        # not only an ideal surface point or the object's declared origin.
+        attachment = [matrix @ (inverse @ (point + transform @ relative[index])) for index in anchors]
+        distances = [target['bvh'].find_nearest(value)[3] for value in attachment]
+        if any(distance is None or distance < epsilon * 4 for distance in distances) or any(not _inside(target, value) for value in attachment):
+            continue
+        offset = len(vertices)
+        emitted = [inverse @ (point + transform @ value) for value in relative]
+        if any(not all(math.isfinite(value) for value in point) for point in emitted):
+            _refuse('placement produced non-finite coordinates')
+        vertices.extend(emitted)
+        output_faces.extend(tuple(index + offset for index in face) for face in faces)
+        placements.append({'index': len(placements), 'targetEntityId': target['id'],
+                           'anchorWorldMeters': list(point), 'embedDepthMm': depth * 1000, 'scale': scale})
+    if len(placements) != count:
+        _refuse('could place only %d/%d instances with all selected attachment vertices inside the actual targets; choose fitting anchors, scale or targets' % (len(placements), count))
+    mesh = bpy.data.meshes.new(source.name + '_surface_scatter')
+    try:
+        mesh.from_pydata(vertices, [], output_faces)
+        mesh.update()
+        if mesh.validate(verbose=False, clean_customdata=False):
+            _refuse('emitted geometry required a native repair')
+        for material in materials:
+            mesh.materials.append(material)
+        for index, polygon in enumerate(mesh.polygons):
+            prototype_index = index % len(faces)
+            polygon.use_smooth = smooth[prototype_index]
+            polygon.material_index = material_indices[prototype_index]
+        for name, coordinates in uv_maps:
+            layer = mesh.uv_layers.new(name=name)
+            layer.data.foreach_set('uv', array('f', (coordinate for _ in range(count) for uv in coordinates for coordinate in uv)))
+        obj.data = mesh
+        obj['deepblend_surface_scatter'] = json.dumps({'schemaVersion': 'deepblend.surface-scatter/v1',
+            'mode': 'static-closed-surface', 'count': count, 'seed': seed,
+            'prototypeVertexCount': len(prototype), 'prototypePolygonCount': len(faces),
+            'anchorVertexIndices': anchors, 'targetEntityIds': [key for key, _ in targets], 'placements': placements}, allow_nan=False)
+    except Exception:
+        if mesh.users == 0:
+            bpy.data.meshes.remove(mesh)
+        raise
+    if source.users == 0:
+        bpy.data.meshes.remove(source)

package/python/deepblend_scene.py

@@ -385,11 +385,14 @@ def create_generator(name, spec):
     elif shape == "handled_cup":
         from deepblend_vessel import create_handled_cup
         create_handled_cup(name, spec)
+    elif shape == "mesh":
+        from deepblend_mesh import create_mesh
+        create_mesh(name, spec)
     else:
         raise ActionError(
             "BLENDER_SCRIPT_ERROR",
             'unknown generator shape "%s"' % (shape,),
-            {"supported": ["cube", "rounded_box", "uv_sphere", "cylinder", "cone", "plane", "torus", "lathe", "curve", "handled_cup"]},
+            {"supported": ["cube", "rounded_box", "uv_sphere", "cylinder", "cone", "plane", "torus", "lathe", "curve", "handled_cup", "mesh"]},
         )
 
     obj = bpy.context.active_object
@@ -2105,7 +2108,7 @@ def build_scene(spec, options, guard):
                 for polygon in getattr(obj.data, "polygons", []):
                     polygon.material_index = 0
             generator = entity.get("generator", {})
-            if generator.get("bevel") or generator.get("shape") in ("uv_sphere", "cylinder", "cone", "torus", "lathe", "curve", "handled_cup"):
+            if (generator.get("bevel") and generator.get("shape") != "mesh") or generator.get("shape") in ("uv_sphere", "cylinder", "cone", "torus", "lathe", "curve", "handled_cup"):
                 _shade_smooth(obj)
 
         if entity.get("materialBindings"):
@@ -2128,7 +2131,7 @@ def build_scene(spec, options, guard):
             simulation_objects[entity_id] = meshes[0]
         entity_positions[entity_id] = [float(root.location[0]), float(root.location[1]), float(root.location[2])]
 
-    apply_model_modifiers(spec.get("entities") or [], entity_meshes)
+    apply_model_modifiers(spec.get("entities") or [], entity_meshes, spec.get('animationTracks') or [])
     scene['deepblend_requires_cycles'] = False
     for entry in spec.get('materials') or []:
         for surface in native_material_surfaces:
@@ -2173,7 +2176,18 @@ def build_scene(spec, options, guard):
     for camera in spec.get("cameras") or []:
         cameras[camera["id"]] = build_camera(camera, entity_positions)
     if cameras:
-        scene.camera = cameras[spec["cameras"][0]["id"]]
+        active_camera = (spec.get("project") or {}).get("activeCamera")
+        if active_camera is not None and active_camera not in cameras:
+            # Older accepted projects can contain a stale activeCamera reference.
+            # Preserve their first-camera fallback and make that limit explicit.
+            guard.note("SCENE_COMPILER_DECISION",
+                       'The declared active camera "%s" was not found; using first camera "%s"' %
+                       (active_camera, spec["cameras"][0]["id"]),
+                       {"requestedCameraId": active_camera, "cameraId": spec["cameras"][0]["id"]})
+            active_camera = None
+        # Camera arrays are canonically sorted after a patch. Adding a delivery
+        # camera must not replace the authored active camera in the saved file.
+        scene.camera = cameras[active_camera if active_camera is not None else spec["cameras"][0]["id"]]
 
     report_progress("build_animation", 75)
     actions = []

package/python/deepblend_views.py

@@ -447,8 +447,10 @@ def _visibility(scene, target, mask, tracked, index, parts):
     if silhouette == 0:
         return 0, 1.0, []
 
+    # Measured-mask selection must not change authored body membership: a
+    # fitted panel still belongs to this body when it is not measured separately.
     actors = [
-        candidate for candidate in (_tracked_objects(target, tracked, index))
+        candidate for candidate in (_tracked_objects(target, [*tracked, *parts], index))
         if candidate is not target and not candidate.hide_render
     ]
     if not actors: