evomeme 0.1.9 → 0.1.10

package/dist/stage-blender/bake_materials.py

@@ -0,0 +1,102 @@
+"""Optional UV surface baking on an isolated runtime copy, after source capture."""
+import bpy
+import hashlib
+
+
+def bake_procedural_materials(scene, output, features, size, warnings):
+    original_engine = scene.render.engine
+    scene.render.engine = 'CYCLES'
+    scene.cycles.samples = 16
+    for obj in list(scene.objects):
+        if obj.type != 'MESH' or obj.hide_render or not obj.data.polygons:
+            continue
+        originals = [s.material for s in obj.material_slots]
+        if not any(m and features.get(m.name, {}).get('procedural') for m in originals):
+            continue
+        if any(m is None or features[m.name]['unsupported_nodes'] or features[m.name].get('unsupported_inputs') for m in originals):
+            warnings.append(obj.name + '：包含不支持的材质闭包，跳过自动表面烘焙。')
+            continue
+        # Bake each object's complete UV atlas so shared source materials do not
+        # accidentally pick up another object's coordinates or transforms.
+        obj.data = obj.data.copy()
+        obj.data.materials.clear()
+        working = [mat.copy() for mat in originals]
+        for mat in working:
+            obj.data.materials.append(mat)
+        bpy.ops.object.select_all(action='DESELECT')
+        obj.hide_set(False)
+        obj.select_set(True)
+        bpy.context.view_layer.objects.active = obj
+        if not obj.data.uv_layers:
+            bpy.ops.object.mode_set(mode='EDIT')
+            bpy.ops.mesh.select_all(action='SELECT')
+            bpy.ops.uv.smart_project(island_margin=.03)
+            bpy.ops.object.mode_set(mode='OBJECT')
+        obj.data.uv_layers.active = obj.data.uv_layers[0]
+        obj.data.uv_layers[0].active_render = True
+        key = hashlib.sha256(obj.name.encode()).hexdigest()[:12]
+        baked = {}
+        supported = True
+        for mat in working:
+            if not mat.use_nodes:
+                mat.use_nodes = True
+            out = next((n for n in mat.node_tree.nodes if n.type == 'OUTPUT_MATERIAL' and n.is_active_output), None)
+            if not out or not out.inputs['Surface'].is_linked or out.inputs['Surface'].links[0].from_node.type != 'BSDF_PRINCIPLED':
+                supported = False
+        if not supported:
+            warnings.append(obj.name + '：自动烘焙要求输出直接连接 Principled BSDF。')
+            continue
+        for channel, socket_name in [('base_color','Base Color'), ('roughness','Roughness'), ('metallic','Metallic'), ('normal','Normal')]:
+            image = bpy.data.images.new('Stage bake '+key+' '+channel, width=size, height=size, alpha=False)
+            image.colorspace_settings.name = 'sRGB' if channel == 'base_color' else 'Non-Color'
+            restore = []
+            for mat in working:
+                nodes, links = mat.node_tree.nodes, mat.node_tree.links
+                out = next(n for n in nodes if n.type == 'OUTPUT_MATERIAL' and n.is_active_output)
+                shader = out.inputs['Surface'].links[0].from_node
+                target = nodes.new('ShaderNodeTexImage')
+                target.image = image
+                nodes.active = target
+                emitter = None
+                if channel != 'normal':
+                    emitter = nodes.new('ShaderNodeEmission')
+                    socket = shader.inputs[socket_name]
+                    if socket.is_linked:
+                        links.new(socket.links[0].from_socket, emitter.inputs['Color'])
+                    else:
+                        value = socket.default_value
+                        emitter.inputs['Color'].default_value = tuple(value) if hasattr(value, '__len__') else (value,value,value,1)
+                    links.new(emitter.outputs[0], out.inputs['Surface'])
+                restore.append((mat, out, shader, target, emitter))
+            try:
+                bpy.ops.object.bake(type='NORMAL' if channel == 'normal' else 'EMIT', normal_space='TANGENT', margin=12, use_clear=True)
+                file = f'textures/{key}_{channel}.png'
+                image.filepath_raw = str(output/file)
+                image.file_format = 'PNG'
+                image.save()
+                baked[channel] = (image, file)
+            finally:
+                for mat, out, shader, target, emitter in restore:
+                    mat.node_tree.links.new(shader.outputs['BSDF'], out.inputs['Surface'])
+                    mat.node_tree.nodes.remove(target)
+                    if emitter:
+                        mat.node_tree.nodes.remove(emitter)
+        for source, mat in zip(originals, working):
+            mat.name = source.name + '::' + key
+            nodes, links = mat.node_tree.nodes, mat.node_tree.links
+            out = next(n for n in nodes if n.type == 'OUTPUT_MATERIAL' and n.is_active_output)
+            shader = out.inputs['Surface'].links[0].from_node
+            for channel, socket in [('base_color','Base Color'), ('roughness','Roughness'), ('metallic','Metallic'), ('normal','Normal')]:
+                image, file = baked[channel]
+                texture = nodes.new('ShaderNodeTexImage')
+                texture.image = image
+                if channel == 'normal':
+                    normal = nodes.new('ShaderNodeNormalMap')
+                    links.new(texture.outputs['Color'], normal.inputs['Color'])
+                    links.new(normal.outputs['Normal'], shader.inputs[socket])
+                else:
+                    links.new(texture.outputs['Color'], shader.inputs[socket])
+                features[source.name]['baked_channels'][obj.name+':'+channel] = file
+            features[source.name]['baked_objects'] = features[source.name].get('baked_objects', []) + [obj.name]
+            features[source.name].setdefault('runtime_materials', []).append({'object': obj.name, 'material_name': mat.name})
+    scene.render.engine = original_engine

package/dist/stage-blender/export_scene.py

@@ -0,0 +1,275 @@
+"""Export a saved source in an isolated Blender process. Never overwrites input.
+
+Arguments after --: a JSON request written by the local scene export service.
+The host validates every artifact before atomically promoting the package.
+"""
+import bpy
+import hashlib
+import json
+import math
+import struct
+import sys
+sys.dont_write_bytecode = True
+import uuid
+from pathlib import Path
+from mathutils import Vector
+
+
+def write_json(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding='utf-8')
+
+
+def xyz(v):
+    return [float(v[0]), float(v[2]), float(-v[1])]
+
+
+def connected_nodes(tree):
+    visited = set()
+    found = []
+    def walk(node, current_tree):
+        key = (current_tree.as_pointer(), node.as_pointer())
+        if key in visited:
+            return
+        visited.add(key)
+        found.append(node)
+        if node.type == 'GROUP' and node.node_tree:
+            for output in node.node_tree.nodes:
+                if output.type == 'GROUP_OUTPUT':
+                    walk(output, node.node_tree)
+        for socket in node.inputs:
+            for link in socket.links:
+                walk(link.from_node, current_tree)
+    for node in tree.nodes:
+        if node.type in {'OUTPUT_MATERIAL', 'OUTPUT_WORLD'} and getattr(node, 'is_active_output', True):
+            walk(node, tree)
+    return found
+
+
+def choose_device():
+    try:
+        prefs = bpy.context.preferences.addons['cycles'].preferences
+        for backend in ['OPTIX', 'CUDA', 'HIP', 'METAL', 'ONEAPI']:
+            try:
+                prefs.compute_device_type = backend
+                prefs.get_devices()
+                if any(d.type == backend for d in prefs.devices):
+                    for d in prefs.devices:
+                        d.use = d.type == backend
+                    return 'GPU'
+            except Exception:
+                continue
+    except Exception:
+        pass
+    return 'CPU'
+
+
+def make_camera(scene, name, position, target):
+    camera = bpy.data.objects.new(name, bpy.data.cameras.new(name))
+    scene.collection.objects.link(camera)
+    camera.location = position
+    camera.rotation_euler = (Vector(target) - camera.location).to_track_quat('-Z', 'Y').to_euler()
+    camera.data.lens = 38
+    camera.data.clip_end = max(1000, (Vector(target) - camera.location).length * 10)
+    return camera
+
+
+def main(request):
+    output = Path(request['output_dir']).resolve()
+    source = Path(bpy.data.filepath).resolve()
+    if not source.is_file() or source.suffix.lower() != '.blend':
+        raise RuntimeError('Save the Blender source .blend before exporting a scene package')
+    if source == output / 'source/scene.blend':
+        raise RuntimeError('Source and output must differ')
+    scene = bpy.data.scenes.get(request.get('scene_name')) if request.get('scene_name') else bpy.context.scene
+    if scene is None:
+        raise RuntimeError('Requested Blender scene does not exist')
+    if abs(scene.unit_settings.scale_length - 1.0) > 1e-6:
+        raise RuntimeError('Scene export requires metre-scale coordinates (unit scale 1); convert a source copy first')
+    if scene.render.engine not in {'CYCLES', 'BLENDER_EEVEE_NEXT'}:
+        raise RuntimeError('Scene preview supports Cycles and Eevee source scenes')
+    if bpy.data.libraries:
+        raise RuntimeError('Linked libraries must be made local in an export copy before packaging')
+    bpy.context.window.scene = scene
+    warnings = []
+    # Pack images/fonts/sounds and reject unsupported external dependencies instead
+    # of creating a package that happens to work only on the author's machine.
+    bpy.ops.file.pack_all()
+    remaining = [str(p) for p in bpy.utils.blend_paths(absolute=True, packed=False) if p]
+    if remaining:
+        raise RuntimeError('Unpacked external dependencies (sequences/caches/volumes): ' + ', '.join(remaining[:8]))
+    for folder in ['source', 'preview', 'runtime', 'textures']:
+        (output / folder).mkdir(parents=True, exist_ok=True)
+    render_objects = [o for o in scene.objects if not o.hide_render]
+    geometry = [o for o in render_objects if o.type in {'MESH', 'CURVE', 'SURFACE', 'FONT', 'META'}]
+    if not geometry:
+        raise RuntimeError('Scene contains no renderable geometry')
+    bounds = [o.matrix_world @ Vector(corner) for o in geometry for corner in o.bound_box]
+    low = Vector(tuple(min(p[i] for p in bounds) for i in range(3)))
+    high = Vector(tuple(max(p[i] for p in bounds) for i in range(3)))
+    center = (low + high) / 2
+    radius = max((high-low).length / 2, 1)
+    camera_names = request.get('camera_names') or []
+    cameras = []
+    if camera_names:
+        for name in camera_names:
+            obj = scene.objects.get(name)
+            if not obj or obj.type != 'CAMERA':
+                raise RuntimeError('Camera does not exist: ' + name)
+            cameras.append(obj)
+    else:
+        reference = scene.camera or next((o for o in render_objects if o.type == 'CAMERA'), None)
+        if reference is None:
+            reference = make_camera(scene, 'Stage Reference', center + Vector((1.25, -1.8, 1.05))*radius, center)
+            warnings.append('源场景没有相机；参考机位根据模型边界生成。')
+        cameras = [reference, make_camera(scene, 'Stage Overview', center + Vector((.65, -.85, 2.4))*radius, center)]
+    if len(cameras) > 6 or any(c.data.type != 'PERSP' for c in cameras):
+        raise RuntimeError('Select between 1 and 6 perspective cameras')
+    scene.camera = cameras[0]
+    render_settings = {'engine': scene.render.engine, 'frame': scene.frame_current, 'samples': scene.cycles.samples,
+        'view_transform': scene.view_settings.view_transform, 'look': scene.view_settings.look,
+        'exposure': scene.view_settings.exposure, 'gamma': scene.view_settings.gamma,
+        'resolution': [scene.render.resolution_x, scene.render.resolution_y],
+        'preview_quality': request.get('quality', 'preview')}
+    width = request.get('width', 960)
+    aspect = scene.render.resolution_x * scene.render.pixel_aspect_x / (scene.render.resolution_y * scene.render.pixel_aspect_y)
+    if aspect < .25 or aspect > 4:
+        raise RuntimeError('Source camera aspect is outside supported range 0.25..4')
+    scene.render.resolution_x = width
+    scene.render.resolution_y = max(1, round(width/aspect))
+    scene.render.resolution_percentage = 100
+    scene.render.pixel_aspect_x = aspect * scene.render.resolution_y / width
+    scene.render.pixel_aspect_y = 1
+    if scene.render.use_border:
+        warnings.append('参考图使用完整画幅，未使用源场景的渲染边框。')
+    scene.render.use_border = False
+    scene.render.use_crop_to_border = False
+    ids = set()
+    nodes = []
+    materials = {}
+    volumes = []
+    for obj in scene.objects:
+        stable_id = obj.get('evomeme_node_id') or str(uuid.uuid5(uuid.NAMESPACE_URL, request['asset_id']+'/'+obj.name))
+        if stable_id in ids:
+            raise RuntimeError('Duplicate evomeme_node_id: '+stable_id)
+        ids.add(stable_id)
+        obj['evomeme_node_id'] = stable_id
+        nodes.append({'id': stable_id, 'name': obj.name, 'type': obj.type, 'parent': obj.parent.name if obj.parent else None,
+            'renderable': not obj.hide_render})
+        if obj.hide_render:
+            continue
+        if obj.type == 'VOLUME':
+            volumes.append({'object': obj.name, 'type': 'VOLUME'})
+        if any(m.type == 'NODES' for m in obj.modifiers):
+            warnings.append(obj.name + '：几何节点按导出时的求值结果交付，需复核实例与动画。')
+        for slot in obj.material_slots:
+            mat = slot.material
+            if not mat:
+                continue
+            if mat.name not in materials:
+                linked = connected_nodes(mat.node_tree) if mat.use_nodes else []
+                types = sorted(set(n.bl_idname for n in linked))
+                unsupported = [t for t in types if t.startswith('ShaderNodeBsdf') and t != 'ShaderNodeBsdfPrincipled']
+                unsupported += [t for t in types if t in {'ShaderNodeMixShader', 'ShaderNodeAddShader', 'ShaderNodeScript', 'ShaderNodeShaderToRGB'} or t.startswith('ShaderNodeVolume')]
+                simple_nodes = {'ShaderNodeOutputMaterial', 'ShaderNodeBsdfPrincipled', 'ShaderNodeTexImage',
+                    'ShaderNodeUVMap', 'ShaderNodeNormalMap', 'ShaderNodeSeparateColor', 'ShaderNodeSeparateRGB',
+                    'ShaderNodeRGB', 'ShaderNodeValue'}
+                composed = [t for t in types if t not in simple_nodes and t not in unsupported]
+                # Four-channel baking cannot resolve procedural opacity,
+                # emission, transmission, displacement, or custom closures.
+                unbaked_inputs = []
+                if composed:
+                    for node in linked:
+                        if node.type == 'BSDF_PRINCIPLED':
+                            unbaked_inputs += [s.name for s in node.inputs if s.is_linked and s.name not in {'Base Color','Roughness','Metallic','Normal'}]
+                        if node.type == 'OUTPUT_MATERIAL' and node.inputs['Displacement'].is_linked:
+                            unbaked_inputs.append('Displacement')
+                materials[mat.name] = {'id': str(uuid.uuid5(uuid.NAMESPACE_URL, request['asset_id']+'/material/'+mat.name)),
+                    'name': mat.name, 'node_types': types, 'procedural': bool(composed),
+                    'unsupported_nodes': unsupported, 'unsupported_inputs': sorted(set(unbaked_inputs)), 'objects': [], 'baked_channels': {}}
+                if any('Volume' in t for t in types):
+                    volumes.append({'object': obj.name, 'material': mat.name, 'type': 'SHADER_VOLUME'})
+            materials[mat.name]['objects'].append(obj.name)
+    world_nodes = connected_nodes(scene.world.node_tree) if scene.world and scene.world.use_nodes else []
+    if any('Volume' in n.bl_idname for n in world_nodes):
+        volumes.append({'object': 'World', 'type': 'WORLD_VOLUME'})
+    lights = []
+    for obj in render_objects:
+        if obj.type != 'LIGHT':
+            continue
+        position, rotation, _ = obj.matrix_world.decompose()
+        lights.append({'name': obj.name, 'type': obj.data.type, 'position': list(position), 'rotation_xyz_rad': list(rotation.to_euler('XYZ')),
+            'energy': obj.data.energy, 'color_linear': list(obj.data.color), 'shadow_enabled': getattr(obj.data, 'use_shadow', True),
+            'spot_size': getattr(obj.data, 'spot_size', math.pi/2), 'size': getattr(obj.data, 'size', 0)})
+    # Source reference remains authored and editable. Runtime-only conversion is
+    # performed after this snapshot/reference stage.
+    scene.cycles.device = choose_device()
+    bpy.ops.wm.save_as_mainfile(filepath=str(output/'source/scene.blend'), copy=True)
+    if request.get('quality') != 'final':
+        scene.cycles.samples = 32
+        scene.cycles.use_denoising = True
+    scene.render.image_settings.file_format = 'PNG'
+    scene.render.image_settings.color_mode = 'RGBA'
+    for index, camera in enumerate(cameras):
+        scene.camera = camera
+        camera_id = 'reference' if index == 0 else 'overview' if index == 1 else 'inspection_'+str(index)
+        scene.render.filepath = str(output/f'preview/blender_{camera_id}.png')
+        bpy.ops.render.render(write_still=True, scene=scene.name)
+    scene.camera = cameras[0]
+    if request.get('bake_materials'):
+        from bake_materials import bake_procedural_materials
+        bake_procedural_materials(scene, output, materials, request.get('texture_size', 1024), warnings)
+    # Exclude hidden helpers from runtime geometry, but leave source unchanged.
+    for obj in scene.objects:
+        volume_only = bool(obj.material_slots) and all(s.material and s.material.use_nodes and
+            any(n.type == 'OUTPUT_MATERIAL' and n.inputs['Volume'].is_linked and not n.inputs['Surface'].is_linked for n in s.material.node_tree.nodes)
+            for s in obj.material_slots)
+        obj.select_set(not obj.hide_render and not volume_only and obj.type != 'VOLUME')
+    for camera in cameras:
+        camera.hide_render = False
+        camera.select_set(True)
+    bpy.ops.export_scene.gltf(filepath=str(output/'model.glb'), export_format='GLB', use_selection=True,
+        use_active_scene=True, export_yup=True, export_apply=True, export_cameras=True, export_lights=False, export_extras=True)
+    model = (output/'model.glb').read_bytes()
+    gltf = json.loads(model[20:20+struct.unpack_from('<I', model, 12)[0]])
+    camera_defs = []
+    # Matrix world is used to handle parented cameras; glTF projection is the
+    # exported, actual vertical FOV rather than a guessed sensor conversion.
+    for index, camera in enumerate(cameras):
+        node = next((n for n in gltf.get('nodes', []) if n.get('name') == camera.name and 'camera' in n), None)
+        if node is None:
+            raise RuntimeError('Exported camera missing: '+camera.name)
+        projection = gltf['cameras'][node['camera']]['perspective']
+        pos, rot, scale = camera.matrix_world.decompose()
+        if max(abs(s-1) for s in scale) > .0001 or abs(camera.data.shift_x)+abs(camera.data.shift_y) > .0001:
+            raise RuntimeError('Scaled or shifted cameras require conversion to a perspective export camera')
+        from mathutils import Matrix
+        q = (Matrix.Rotation(-math.pi/2, 4, 'X') @ camera.matrix_world).to_quaternion()
+        direction = rot @ Vector((0,0,-1))
+        camera_id = 'reference' if index == 0 else 'overview' if index == 1 else 'inspection_'+str(index)
+        camera_defs.append({'id': camera_id, 'label': camera.name, 'position': xyz(pos), 'quaternion_xyzw': [q.x,q.y,q.z,q.w],
+            'look_at': xyz(pos+direction*radius), 'vertical_fov_rad': projection['yfov'], 'aspect_ratio': aspect,
+            'near': projection['znear'], 'far': projection.get('zfar', camera.data.clip_end),
+            'reference_render': f'preview/blender_{camera_id}.png'})
+    world_color = list(scene.world.color) if scene.world else [.1,.1,.1]
+    features = {'schema': 'evomeme.source_scene_features.v1', 'nodes': nodes, 'materials': list(materials.values()), 'volumes': volumes,
+        'world': {'environment_texture': any(n.bl_idname == 'ShaderNodeTexEnvironment' for n in world_nodes), 'color': world_color},
+        'rendering': render_settings, 'export_warnings': warnings}
+    contract = {'schema': 'evomeme.scene_contract.v1', 'asset_id': request['asset_id'], 'contract_revision': 1,
+        'source_of_truth': {'authoring_and_cycles_appearance': 'source/scene.blend', 'authoring_scene': scene.name,
+            'reference_camera': 'reference', 'reference_render': 'preview/blender_reference.png'},
+        'coordinates': {'blender_to_gltf': '[x,y,z] -> [x,z,-y]', 'conversion_already_baked': True, 'metres_per_unit': 1,
+            'up_axis': '+y', 'forward_axis': '-z', 'pivot': 'origin', 'scale_hint_metres': None,
+            'root_transform': {'position': [0,0,0], 'quaternion_xyzw': [0,0,0,1], 'scale': [1,1,1]}},
+        'cameras': camera_defs, 'blender_lights': lights, 'source_features': features,
+        'contents': {'mesh_count': len(gltf.get('meshes', [])), 'node_count': len(gltf.get('nodes', [])),
+            'material_count': len(gltf.get('materials', [])), 'camera_count': len(gltf.get('cameras', [])),
+            'skin_count': len(gltf.get('skins', [])), 'animations': len(gltf.get('animations', []))}}
+    write_json(output/'export-manifest.json', contract)
+    print('EVOMEME_SCENE_EXPORT '+json.dumps({'ok': True, 'asset_id': request['asset_id'], 'cameras': len(camera_defs)}, ensure_ascii=True), flush=True)
+
+
+if __name__ == '__main__':
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    request_file = Path(sys.argv[sys.argv.index('--')+1])
+    main(json.loads(request_file.read_text(encoding='utf-8')))

package/dist/stage-blender/preview_camera.py

@@ -0,0 +1,90 @@
+"""Read-only, persistent Cycles camera preview worker. Never saves the .blend."""
+import bpy
+import json
+import math
+import sys
+import time
+from mathutils import Matrix, Quaternion, Vector
+
+
+def emit(value):
+    print('EVOMEME_PREVIEW ' + json.dumps(value, ensure_ascii=True), flush=True)
+
+
+device = 'CPU'
+try:
+    prefs = bpy.context.preferences.addons['cycles'].preferences
+    for backend in ['OPTIX', 'CUDA', 'HIP', 'METAL', 'ONEAPI']:
+        try:
+            prefs.compute_device_type = backend
+            prefs.get_devices()
+            if any(d.type == backend for d in prefs.devices):
+                for d in prefs.devices:
+                    d.use = d.type == backend
+                device = backend
+                break
+        except Exception:
+            continue
+except Exception:
+    pass
+
+# glTF has Y up; Blender has Z up. Local camera axes are shared (-Z, +Y).
+gltf_to_blender = Matrix.Rotation(math.pi / 2, 4, 'X')
+camera_data = bpy.data.cameras.new('EvoMeme comparison preview')
+camera_obj = bpy.data.objects.new('EvoMeme comparison preview', camera_data)
+linked_scene = None
+
+for line in sys.stdin:
+    try:
+        job = json.loads(line)
+        started = time.monotonic()
+        scene = bpy.data.scenes.get(job['scene'])
+        if scene is None:
+            raise ValueError('The contracted Blender scene does not exist')
+        if scene.render.engine not in {'CYCLES', 'BLENDER_EEVEE_NEXT'}:
+            raise ValueError('Native comparison requires a Cycles or Eevee source scene')
+        if linked_scene != scene:
+            scene.collection.objects.link(camera_obj)
+            linked_scene = scene
+        c = job['camera']
+        x, y, z, w = c['quaternion']
+        camera_obj.matrix_world = gltf_to_blender @ Matrix.LocRotScale(
+            Vector(c['position']), Quaternion((w, x, y, z)), Vector((1, 1, 1)))
+        camera_data.type = 'PERSP'
+        camera_data.sensor_fit = 'VERTICAL'
+        camera_data.sensor_height = 24
+        camera_data.lens = 24 / (2 * math.tan(math.radians(c['fov']) / 2))
+        camera_data.clip_start = c['near']
+        camera_data.clip_end = c['far']
+        camera_data.shift_x = camera_data.shift_y = 0
+        camera_data.dof.use_dof = False
+        scene.camera = camera_obj
+        scene.render.resolution_x = job['width']
+        scene.render.resolution_y = job['height']
+        scene.render.resolution_percentage = 100
+        # Preserve the exact camera aspect despite integer image dimensions.
+        scene.render.pixel_aspect_x = c['aspect'] * job['height'] / job['width']
+        scene.render.pixel_aspect_y = 1
+        scene.render.use_border = False
+        scene.render.use_crop_to_border = False
+        scene.render.use_persistent_data = True
+        scene.cycles.device = 'GPU' if device != 'CPU' else 'CPU'
+        scene.cycles.samples = 32
+        scene.cycles.use_denoising = True
+        scene.render.image_settings.file_format = 'PNG'
+        scene.render.image_settings.color_mode = 'RGBA'
+        scene.render.filepath = job['output']
+        bpy.context.view_layer.update()
+        bpy.ops.render.render(write_still=True, scene=scene.name)
+        projection = camera_obj.calc_matrix_camera(bpy.context.evaluated_depsgraph_get(),
+            x=job['width'], y=job['height'], scale_x=scene.render.pixel_aspect_x,
+            scale_y=scene.render.pixel_aspect_y)
+        emit({'id': job['id'], 'ok': True, 'seconds': round(time.monotonic() - started, 2),
+              'engine': scene.render.engine, 'device': device, 'samples': 32,
+              'width': job['width'], 'height': job['height'], 'blender': bpy.app.version_string,
+              'camera_matrix_blender': [list(row) for row in camera_obj.matrix_world],
+              'projection': [list(row) for row in projection],
+              'view_transform': scene.view_settings.view_transform,
+              'look': scene.view_settings.look})
+    except Exception as error:
+        emit({'id': locals().get('job', {}).get('id'), 'ok': False, 'error': str(error)})

package/dist/stage-blender/repair_mesh.py

@@ -0,0 +1,112 @@
+"""
+Minimal Blender repair for evomeme canonical packages.
+
+Runs inside Blender or a bpy wheel:
+
+  blender --background --factory-startup --python repair_mesh.py -- \\
+    --src /abs/model.glb --dest /abs/out.glb [--ground] [--report /abs/report.json]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _bpy():
+    try:
+        import bpy  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError(
+            "repair_mesh.py must run inside Blender or an env with the bpy wheel"
+        ) from exc
+    return bpy
+
+
+def repair(src: Path, dest: Path, *, ground: bool) -> dict:
+    bpy = _bpy()
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+
+    # Clear default cube if present
+    for obj in list(bpy.data.objects):
+        bpy.data.objects.remove(obj, do_unlink=True)
+
+    ext = src.suffix.lower()
+    if ext in {".glb", ".gltf"}:
+        bpy.ops.import_scene.gltf(filepath=str(src))
+    elif ext == ".fbx":
+        bpy.ops.import_scene.fbx(filepath=str(src))
+    elif ext == ".obj":
+        bpy.ops.wm.obj_import(filepath=str(src))
+    else:
+        raise RuntimeError(f"unsupported source suffix: {ext}")
+
+    imported = [obj for obj in bpy.context.scene.objects if obj.type in {"MESH", "ARMATURE", "EMPTY"}]
+    if not imported:
+        raise RuntimeError("Blender imported no objects")
+
+    # Join meshes for a stable single root when grounding
+    meshes = [obj for obj in imported if obj.type == "MESH"]
+    if ground and meshes:
+        bpy.ops.object.select_all(action="DESELECT")
+        for obj in meshes:
+            obj.select_set(True)
+        bpy.context.view_layer.objects.active = meshes[0]
+        if len(meshes) > 1:
+            bpy.ops.object.join()
+        active = bpy.context.view_layer.objects.active
+        bpy.ops.object.origin_set(type="ORIGIN_GEOMETRY", center="BOUNDS")
+        # Put lowest point on Z=0 (Blender Z-up); glTF export converts to Y-up.
+        min_z = min((active.matrix_world @ v.co).z for v in active.data.vertices) if active.data.vertices else 0.0
+        active.location.z -= min_z
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    bpy.ops.export_scene.gltf(
+        filepath=str(dest),
+        export_format="GLB",
+        use_selection=False,
+    )
+
+    return {
+        "ok": True,
+        "src": str(src),
+        "dest": str(dest),
+        "ground": ground,
+        "object_count": len(imported),
+        "mesh_count": len(meshes),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--src", required=True)
+    parser.add_argument("--dest", required=True)
+    parser.add_argument("--ground", action="store_true")
+    parser.add_argument("--report", default="")
+    # Blender passes everything after `--`; also tolerate stray blender args.
+    args, _unknown = parser.parse_known_args(argv)
+
+    src = Path(args.src).expanduser().resolve()
+    dest = Path(args.dest).expanduser().resolve()
+    if not src.is_file():
+        raise SystemExit(f"source missing: {src}")
+
+    report = repair(src, dest, ground=bool(args.ground))
+    text = json.dumps(report, ensure_ascii=False, indent=2)
+    if args.report:
+        report_path = Path(args.report).expanduser().resolve()
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(text + "\n", encoding="utf-8")
+    print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    # When launched via `blender --python this.py -- ...`, argv includes blender noise.
+    argv = sys.argv
+    if "--" in argv:
+        argv = argv[argv.index("--") + 1 :]
+    else:
+        argv = argv[1:]
+    raise SystemExit(main(argv))