3D engine that AI agents drive
Add the Classroom scene bridge and its Cook against Cycles measurement, grey diffuse (#896)
Nguyen Xuan Anfbff50d1bc7b
diff --git a/bench/cycles-parity/classroom_bridge.py b/bench/cycles-parity/classroom_bridge.pynew file mode 100644index 00000000..f06706ed--- /dev/null+++ b/bench/cycles-parity/classroom_bridge.py@@ -0,0 +1,820 @@+"""Blender side of the Classroom parity bridge (#896).++Run inside Blender 5.3, on a copy of the Classroom demo scene (Christophe Seux, CC0), never with auto-run scripts:++ blender -b classroom.blend --disable-autoexec --python bench/cycles-parity/classroom_bridge.py -- export <outputDirectory> [options]+ blender -b classroom.blend --disable-autoexec --python bench/cycles-parity/classroom_bridge.py -- reference <outputPrefix> [options]++`export` writes the evaluated scene in the JSON scene format that render-cycles.py and trace-native.mjs read: one geometry per+mesh datablock (with the same modifier settings), one part per instance with its world matrix, the camera, the lights and the+world, with every material replaced by the grey diffuse one. It also writes <outputDirectory>/classroom-lens.json (the+depth-of-field flags) and <outputDirectory>/classroom-report.json (counts and everything dropped or approximated).++`reference` renders the original .blend in Cycles with the same drops and the same grey override, so the bridge itself+(lights, world, camera, geometry) can be compared with Cycles on the very scene it came from.++Both modes call prepare_scene first, so the two sides drop the same objects.+"""+import base64+import importlib.util+import json+import math+import os+import sys+import time++import bpy+import numpy+from mathutils import Euler, Matrix, Vector++sys.stdout.reconfigure(encoding="utf-8", errors="replace")++SCRIPT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))+REPOSITORY_ROOT = os.path.abspath(os.path.join(SCRIPT_DIRECTORY, "..", ".."))+BLENDER_TO_YUP = Matrix((+ (1.0, 0.0, 0.0, 0.0),+ (0.0, 0.0, 1.0, 0.0),+ (0.0, -1.0, 0.0, 0.0),+ (0.0, 0.0, 0.0, 1.0),+))+WATTS_PER_POINT_INTENSITY = 4.0 * math.pi+WATTS_PER_AREA_INTENSITY = math.pi+HDR_RADIANCE_LIMIT = 60000.0+HDR_WIDTH = 2048+HDR_HEIGHT = 1024+PROBE_HDR_WIDTH = 1024+PROBE_HDR_HEIGHT = 512+PROBE_VIEW_SIZE = 48+PROBE_SAMPLES = 8+BAKE_ROTATION_CANDIDATE_DEGREES = (0.0, 90.0, 180.0, 270.0)+UNSUPPORTED_OBJECT_TYPES = ("CURVES", "POINTCLOUD", "VOLUME", "GREASEPENCIL", "GPENCIL")+MESH_LIKE_OBJECT_TYPES = ("MESH", "CURVE", "SURFACE", "FONT", "META")+IGNORED_MODIFIER_PROPERTIES = {"rna_type", "persistent_uid", "name", "show_expanded", "is_active", "is_override_data", "use_pin_to_last", "execution_time"}+GREY_ALBEDO = 0.8+RAY_VISIBILITY_ATTRIBUTES = {+ "camera": "visible_camera", "diffuse": "visible_diffuse", "glossy": "visible_glossy",+ "transmission": "visible_transmission", "volumeScatter": "visible_volume_scatter", "shadow": "visible_shadow",+}+++def log(message):+ print(f"BRIDGE {message}", flush=True)+++def load_render_cycles_module():+ specification = importlib.util.spec_from_file_location("render_cycles", os.path.join(SCRIPT_DIRECTORY, "render-cycles.py"))+ module = importlib.util.module_from_spec(specification)+ specification.loader.exec_module(module)+ return module+++def read_option(argument_list, flag_name, fallback_value):+ if flag_name not in argument_list:+ return fallback_value+ return argument_list[argument_list.index(flag_name) + 1]+++def parse_arguments():+ if "--" not in sys.argv:+ raise ValueError("Pass the mode after '--': export <outputDirectory> | reference <outputPrefix>.")+ argument_list = sys.argv[sys.argv.index("--") + 1:]+ if len(argument_list) < 2 or argument_list[0] not in ("export", "reference"):+ raise ValueError("Usage: -- export <outputDirectory> [--width 960] [--height 540] [--keep-glass] | reference <outputPrefix> [--samples 1024] [--seed 1] [--pinhole] [--keep-glass]")+ return {+ "mode": argument_list[0],+ "output": os.path.abspath(argument_list[1]),+ "width": int(read_option(argument_list, "--width", "960")),+ "height": int(read_option(argument_list, "--height", "540")),+ "samples": int(read_option(argument_list, "--samples", "1024")),+ "seed": int(read_option(argument_list, "--seed", "1")),+ "keep_glass": "--keep-glass" in argument_list,+ "pinhole": "--pinhole" in argument_list,+ "bounces": int(read_option(argument_list, "--bounces", "8")),+ "variant": read_option(argument_list, "--variant", "baseline"),+ "z_depth": "--z-depth" in argument_list,+ }+++# ---- Visibility, modifiers, hair and glass: the same drops on both sides ----++def collect_instanced_object_names():+ names = set()+ for scene_object in bpy.data.objects:+ if scene_object.instance_type == "COLLECTION" and scene_object.instance_collection is not None:+ for source_object in scene_object.instance_collection.all_objects:+ names.add(source_object.name)+ return names+++def make_instanced_collections_visible_in_viewport(report):+ """Cycles draws a collection instance whatever the viewport flags of its source collection and objects say; the viewport+ evaluation the export reads does not, so those flags are cleared for everything that renders."""+ cleared_collections = 0+ cleared_objects = 0+ for scene_object in bpy.data.objects:+ if scene_object.instance_type != "COLLECTION" or scene_object.instance_collection is None:+ continue+ pending = [scene_object.instance_collection]+ while pending:+ collection = pending.pop()+ if collection.hide_viewport and not collection.hide_render:+ collection.hide_viewport = False+ cleared_collections += 1+ pending.extend(collection.children)+ for source_object in scene_object.instance_collection.all_objects:+ if not source_object.hide_render and source_object.hide_viewport:+ source_object.hide_viewport = False+ cleared_objects += 1+ report["instancedCollectionsMadeViewportVisible"] = cleared_collections+ report["instancedObjectsMadeViewportVisible"] = cleared_objects+++def make_render_collections_visible(layer_collection, visible_names):+ if layer_collection.exclude or layer_collection.collection.hide_render:+ return+ layer_collection.hide_viewport = False+ layer_collection.collection.hide_viewport = False+ for scene_object in layer_collection.collection.objects:+ if not scene_object.hide_render:+ visible_names.add(scene_object.name)+ for child_collection in layer_collection.children:+ make_render_collections_visible(child_collection, visible_names)+++def tag_material_node_trees(material):+ tags = set()+ if material is None or material.node_tree is None:+ return tags+ pending_trees = [material.node_tree]+ seen_tree_names = set()+ while pending_trees:+ node_tree = pending_trees.pop()+ if node_tree.name in seen_tree_names:+ continue+ seen_tree_names.add(node_tree.name)+ for node in node_tree.nodes:+ if node.type == "GROUP" and node.node_tree is not None:+ pending_trees.append(node.node_tree)+ elif node.type in ("BSDF_GLASS", "BSDF_REFRACTION"):+ tags.add("glass")+ elif node.type == "BSDF_TRANSPARENT":+ tags.add("transparent")+ elif node.type == "BSDF_PRINCIPLED":+ transmission_socket = node.inputs.get("Transmission Weight")+ if transmission_socket is not None and not transmission_socket.is_linked and transmission_socket.default_value >= 0.5:+ tags.add("glass")+ alpha_socket = node.inputs.get("Alpha")+ if alpha_socket is not None and (alpha_socket.is_linked or alpha_socket.default_value < 1.0):+ tags.add("alpha")+ return tags+++def tag_object_materials(scene_object):+ tags = set()+ for material_slot in scene_object.material_slots:+ tags |= tag_material_node_trees(material_slot.material)+ return tags+++def disable_particle_systems_and_sync_modifiers(report):+ for scene_object in bpy.data.objects:+ for modifier in scene_object.modifiers:+ if modifier.type == "PARTICLE_SYSTEM":+ settings = modifier.particle_system.settings+ instances_objects = settings.type == "EMITTER" and settings.render_type in ("OBJECT", "COLLECTION")+ if instances_objects:+ modifier.show_viewport = modifier.show_render+ report["particleInstanceSystemsKept"] += 1+ else:+ modifier.show_viewport = False+ modifier.show_render = False+ report["particleSystemsDropped"] += 1+ report["particleSystemsDroppedKinds"][f"{settings.type}/{settings.render_type}"] = report["particleSystemsDroppedKinds"].get(f"{settings.type}/{settings.render_type}", 0) + 1+ continue+ modifier.show_viewport = modifier.show_render+ if modifier.type in ("SUBSURF", "MULTIRES"):+ modifier.levels = modifier.render_levels+++def hide_object_everywhere(scene_object):+ scene_object.hide_render = True+ scene_object.hide_viewport = True+++def prepare_scene(scene, keep_glass):+ """Makes the viewport evaluation equal the render evaluation, then removes what the bench format cannot carry."""+ report = {+ "hiddenFromRender": 0,+ "hiddenFromRenderNames": [],+ "unsupportedObjects": {},+ "glassObjects": [],+ "cutoutObjectCount": 0,+ "particleInstanceSystemsKept": 0,+ "particleSystemsDropped": 0,+ "particleSystemsDroppedKinds": {},+ "extraSunsDropped": [],+ }+ make_instanced_collections_visible_in_viewport(report)+ instanced_names = collect_instanced_object_names()+ visible_names = set()+ make_render_collections_visible(scene.view_layers[0].layer_collection, visible_names)+ disable_particle_systems_and_sync_modifiers(report)+ for scene_object in list(scene.objects):+ if scene_object.name in instanced_names:+ continue+ if scene_object.name in visible_names:+ scene_object.hide_viewport = False+ try:+ scene_object.hide_set(False)+ except RuntimeError:+ pass+ else:+ scene_object.hide_viewport = True+ report["hiddenFromRender"] += 1+ report["hiddenFromRenderNames"].append(f"{scene_object.name} ({scene_object.type})")+ for scene_object in bpy.data.objects:+ if scene_object.type in UNSUPPORTED_OBJECT_TYPES and not scene_object.hide_render:+ report["unsupportedObjects"][scene_object.type] = report["unsupportedObjects"].get(scene_object.type, 0) + 1+ hide_object_everywhere(scene_object)+ continue+ if scene_object.type not in MESH_LIKE_OBJECT_TYPES or scene_object.hide_render:+ continue+ tags = tag_object_materials(scene_object)+ if "glass" in tags and not keep_glass:+ report["glassObjects"].append(scene_object.name)+ hide_object_everywhere(scene_object)+ elif tags & {"transparent", "alpha"}:+ report["cutoutObjectCount"] += 1+ sun_names = sorted(obj.name for obj in scene.objects if obj.type == "LIGHT" and obj.data.type == "SUN" and not obj.hide_render and obj.name in visible_names)+ for extra_sun_name in sun_names[1:]:+ report["extraSunsDropped"].append(extra_sun_name)+ hide_object_everywhere(bpy.data.objects[extra_sun_name])+ report["glassObjectCount"] = len(report["glassObjects"])+ report["glassObjectNamesSample"] = report["glassObjects"][:40]+ return report+++# ---- Coordinates, camera, lights ----++def to_yup(vector):+ return [float(vector[0]), float(vector[2]), float(-vector[1])]+++def column_major_yup_matrix(blender_matrix):+ matrix = BLENDER_TO_YUP @ blender_matrix+ return [float(matrix[row][column]) for column in range(4) for row in range(4)]+++def effective_horizontal_sensor_width(camera_data, width, height):+ fit = camera_data.sensor_fit+ if fit == "AUTO":+ fit = "HORIZONTAL" if width >= height else "VERTICAL"+ if fit == "HORIZONTAL":+ return camera_data.sensor_width+ return camera_data.sensor_height * width / height+++def vertical_fov_degrees(camera_data, width, height):+ horizontal_sensor_width = effective_horizontal_sensor_width(camera_data, width, height)+ half_tangent_x = horizontal_sensor_width / (2.0 * camera_data.lens)+ half_tangent_y = half_tangent_x * height / width+ return math.degrees(2.0 * math.atan(half_tangent_y))+++def build_camera_entries(scene, width, height, report):+ camera_object = scene.camera+ camera_data = camera_object.data+ if camera_data.type != "PERSP":+ raise ValueError(f"Camera type {camera_data.type} is not supported: the bench draws perspective cameras only.")+ world_matrix = camera_object.matrix_world+ eye = world_matrix.translation.copy()+ forward = (world_matrix.to_3x3() @ Vector((0.0, 0.0, -1.0))).normalized()+ camera_up = (world_matrix.to_3x3() @ Vector((0.0, 1.0, 0.0))).normalized()+ level_up = (Vector((0.0, 0.0, 1.0)) - forward * forward.z).normalized()+ roll_degrees = math.degrees(math.acos(max(-1.0, min(1.0, camera_up.dot(level_up)))))+ report["camera"] = {+ "name": camera_object.name,+ "lensMillimetres": camera_data.lens,+ "sensorWidth": camera_data.sensor_width,+ "sensorHeight": camera_data.sensor_height,+ "sensorFit": camera_data.sensor_fit,+ "shiftX": camera_data.shift_x,+ "shiftY": camera_data.shift_y,+ "rollDegrees": roll_degrees,+ "clipStart": camera_data.clip_start,+ "clipEnd": camera_data.clip_end,+ "dofEnabled": camera_data.dof.use_dof,+ "pixelAspect": scene.render.pixel_aspect_x / scene.render.pixel_aspect_y,+ "frame": scene.frame_current,+ }+ camera_entry = {+ "eye": to_yup(eye),+ "target": to_yup(eye + forward),+ "up": to_yup(level_up),+ "fov": vertical_fov_degrees(camera_data, width, height),+ "near": camera_data.clip_start,+ "far": max(camera_data.clip_end, 1000.0),+ }+ lens_entry = {"enabled": False}+ if camera_data.dof.use_dof:+ dof = camera_data.dof+ focus_distance = dof.focus_distance+ if dof.focus_object is not None:+ focus_distance = abs((dof.focus_object.matrix_world.translation - eye).dot(forward))+ lens_entry = {+ "enabled": True,+ "fStop": dof.aperture_fstop,+ "focusDistance": focus_distance,+ "apertureBlades": dof.aperture_blades,+ "apertureRotation": math.degrees(dof.aperture_rotation),+ "apertureRatio": dof.aperture_ratio,+ "sensorWidth": effective_horizontal_sensor_width(camera_data, width, height),+ }+ report["lens"] = lens_entry+ return camera_entry, lens_entry+++def light_color_with_exposure(light_data):+ exposure_scale = 2.0 ** getattr(light_data, "exposure", 0.0)+ return [float(channel) for channel in light_data.color], light_data.energy * exposure_scale+++def add_light_entry(environment, light_object, light_matrix, report):+ light_data = light_object.data+ color, energy = light_color_with_exposure(light_data)+ if energy <= 0.0:+ return+ position = to_yup(light_matrix.translation)+ emission_direction = to_yup((light_matrix.to_3x3() @ Vector((0.0, 0.0, -1.0))).normalized())+ if light_data.type == "SUN":+ toward_light = [-component for component in emission_direction]+ environment["keyColor"] = [channel * energy for channel in color]+ environment["lightDirection"] = toward_light+ environment["sunAngularRadius"] = light_data.angle / 2.0+ elif light_data.type == "POINT":+ environment["pointLights"].append({"position": position, "color": color, "intensity": energy / WATTS_PER_POINT_INTENSITY, "radius": light_data.shadow_soft_size})+ elif light_data.type == "SPOT":+ environment["spotLights"].append({+ "position": position,+ "color": color,+ "intensity": energy / WATTS_PER_POINT_INTENSITY,+ "radius": light_data.shadow_soft_size,+ "direction": emission_direction,+ "angle": light_data.spot_size / 2.0,+ "penumbra": light_data.spot_blend,+ })+ elif light_data.type == "AREA":+ scale = light_matrix.to_scale()+ local_up = to_yup((light_matrix.to_3x3() @ Vector((0.0, 1.0, 0.0))).normalized())+ shape = {"SQUARE": "rectangle", "RECTANGLE": "rectangle", "DISK": "disk", "ELLIPSE": "ellipse"}[light_data.shape]+ width_value = light_data.size * abs(scale.x)+ height_value = width_value if light_data.shape in ("SQUARE", "DISK") else light_data.size_y * abs(scale.y)+ entry = {+ "position": position,+ "color": color,+ "intensity": energy / WATTS_PER_AREA_INTENSITY,+ "width": width_value,+ "height": height_value,+ "direction": emission_direction,+ "up": [-component for component in local_up],+ "shape": shape,+ "spread": max(0.0001, min(math.pi, light_data.spread)),+ }+ environment["areaLights"].append(entry)+ if getattr(light_data, "normalize", True) is False:+ report["notes"].append(f"area light {light_object.name} has Normalize off, which the bench format cannot carry")+ report["lightCounts"][light_data.type] = report["lightCounts"].get(light_data.type, 0) + 1+++# ---- World ----++def describe_world(world):+ if world is None:+ return {"kind": "constant", "value": 0.0, "note": "no world"}+ if not world.use_nodes or world.node_tree is None:+ color = list(world.color)+ return {"kind": "constant", "value": color[0], "color": color, "grey": max(color) - min(color) < 1e-6}+ output_node = next((node for node in world.node_tree.nodes if node.type == "OUTPUT_WORLD" and node.is_active_output), None)+ if output_node is None or not output_node.inputs["Surface"].is_linked:+ return {"kind": "baked", "reason": "no linked world output"}+ background_node = output_node.inputs["Surface"].links[0].from_node+ if background_node.type != "BACKGROUND":+ return {"kind": "baked", "reason": f"output reads a {background_node.type} node"}+ color_socket = background_node.inputs["Color"]+ strength_socket = background_node.inputs["Strength"]+ if color_socket.is_linked or strength_socket.is_linked:+ linked_types = [socket.links[0].from_node.type for socket in (color_socket, strength_socket) if socket.is_linked]+ return {"kind": "baked", "reason": f"background inputs linked to {linked_types}"}+ color = [float(channel) * strength_socket.default_value for channel in color_socket.default_value[:3]]+ return {"kind": "constant", "value": color[0], "color": color, "grey": max(color) - min(color) < 1e-6}+++def create_probe_scene(name, world, width, height, samples, render_cycles):+ probe_scene = bpy.data.scenes.new(name)+ probe_scene.render.engine = "CYCLES"+ probe_scene.cycles.device = "CPU"+ probe_scene.cycles.samples = samples+ probe_scene.cycles.use_denoising = False+ probe_scene.cycles.use_adaptive_sampling = False+ probe_scene.render.film_transparent = False+ render_cycles.configure_linear_exr_output(probe_scene, width, height)+ probe_scene.world = world+ return probe_scene+++def add_probe_camera(probe_scene, camera_data, location, rotation_euler):+ camera_object = bpy.data.objects.new("probe-camera", camera_data)+ camera_object.location = location+ camera_object.rotation_mode = "XYZ"+ camera_object.rotation_euler = rotation_euler+ probe_scene.collection.objects.link(camera_object)+ probe_scene.camera = camera_object+ return camera_object+++def render_probe_scene_to_array(probe_scene, file_stem, render_cycles):+ exr_path = f"{file_stem}.exr"+ probe_scene.render.filepath = exr_path+ bpy.ops.render.render(write_still=True, scene=probe_scene.name)+ width = probe_scene.render.resolution_x+ height = probe_scene.render.resolution_y+ render_cycles.load_exr_into_npy(exr_path, f"{file_stem}.npy", width, height, False)+ return numpy.load(f"{file_stem}.npy")+++def render_world_to_hdr(world, hdr_path, width, height, rotation_euler, work_directory, render_cycles):+ probe_scene = create_probe_scene("hdr-bake", world, width, height, 4, render_cycles)+ camera_data = bpy.data.cameras.new("hdr-bake-camera")+ camera_data.type = "PANO"+ if hasattr(camera_data, "panorama_type"):+ camera_data.panorama_type = "EQUIRECTANGULAR"+ else:+ camera_data.cycles.panorama_type = "EQUIRECTANGULAR"+ for attribute_name, attribute_value in (("latitude_min", -math.pi / 2), ("latitude_max", math.pi / 2), ("longitude_min", -math.pi), ("longitude_max", math.pi)):+ if hasattr(camera_data, attribute_name):+ setattr(camera_data, attribute_name, attribute_value)+ add_probe_camera(probe_scene, camera_data, (0.0, 0.0, 0.0), rotation_euler)+ probe_scene.render.image_settings.file_format = "HDR"+ probe_scene.render.image_settings.color_mode = "RGB"+ probe_scene.render.filepath = hdr_path+ bpy.ops.render.render(write_still=True, scene=probe_scene.name)+++def probe_view_directions():+ directions = []+ for sign_x in (-1.0, 1.0):+ for sign_y in (-1.0, 1.0):+ for sign_z in (-1.0, 1.0):+ directions.append(Vector((sign_x, sign_y, sign_z * 0.6)).normalized())+ return directions+++def render_world_probe_views(world, label, work_directory, render_cycles):+ probe_scene = create_probe_scene(f"probe-{label}", world, PROBE_VIEW_SIZE, PROBE_VIEW_SIZE, PROBE_SAMPLES, render_cycles)+ camera_data = bpy.data.cameras.new(f"probe-camera-{label}")+ camera_data.angle = math.radians(60.0)+ views = []+ for view_index, direction in enumerate(probe_view_directions()):+ rotation = direction.to_track_quat("-Z", "Y").to_euler()+ camera_object = add_probe_camera(probe_scene, camera_data, (0.0, 0.0, 0.0), rotation)+ views.append(render_probe_scene_to_array(probe_scene, os.path.join(work_directory, f"probe-{label}-{view_index}"), render_cycles))+ probe_scene.collection.objects.unlink(camera_object)+ return views+++def probe_difference(reference_views, candidate_views):+ errors = [float(numpy.mean(numpy.abs(numpy.log1p(numpy.maximum(a, 0)) - numpy.log1p(numpy.maximum(b, 0))))) for a, b in zip(reference_views, candidate_views)]+ mean_ratio = float(numpy.mean([numpy.mean(b) for b in candidate_views]) / max(float(numpy.mean([numpy.mean(a) for a in reference_views])), 1e-12))+ return float(numpy.mean(errors)), mean_ratio+++def bake_world(world, work_directory, final_hdr_path, render_cycles, report):+ """Renders the world to an equirectangular .hdr, choosing the rotation about Z by probing the world from eight directions.++ The bench reads an .hdr through render-cycles.py's world nodes (an Environment Texture turned by -90 degrees about Z). Each+ candidate is rendered, put through those same nodes in a probe scene, and compared with the original world seen from the+ same directions, so the orientation is measured and not assumed."""+ original_views = render_world_probe_views(world, "original", work_directory, render_cycles)+ candidate_results = []+ for rotation_degrees in BAKE_ROTATION_CANDIDATE_DEGREES:+ candidate_path = os.path.join(work_directory, f"world-candidate-{int(rotation_degrees)}.hdr")+ euler = Euler((math.radians(90.0), 0.0, math.radians(rotation_degrees)), "XYZ")+ render_world_to_hdr(world, candidate_path, PROBE_HDR_WIDTH, PROBE_HDR_HEIGHT, euler, work_directory, render_cycles)+ hdr_scene = bpy.data.scenes.new(f"probe-hdr-{int(rotation_degrees)}")+ render_cycles.build_world_shader(hdr_scene, {"type": "hdri", "file": candidate_path, "intensity": 1.0, "radianceLimit": HDR_RADIANCE_LIMIT}, REPOSITORY_ROOT)+ candidate_views = render_world_probe_views(hdr_scene.world, f"hdr{int(rotation_degrees)}", work_directory, render_cycles)+ error, mean_ratio = probe_difference(original_views, candidate_views)+ candidate_results.append({"rotationDegrees": rotation_degrees, "meanLogError": error, "meanRatio": mean_ratio})+ log(f"world candidate {rotation_degrees} degrees: log error {error:.5f}, mean ratio {mean_ratio:.4f}")+ best = min(candidate_results, key=lambda entry: entry["meanLogError"])+ best_euler = Euler((math.radians(90.0), 0.0, math.radians(best["rotationDegrees"])), "XYZ")+ render_world_to_hdr(world, final_hdr_path, HDR_WIDTH, HDR_HEIGHT, best_euler, work_directory, render_cycles)+ report["worldBake"] = {"candidates": candidate_results, "chosenRotationDegrees": best["rotationDegrees"], "hdrWidth": HDR_WIDTH, "hdrHeight": HDR_HEIGHT, "radianceLimit": HDR_RADIANCE_LIMIT}+ return best+++# ---- Geometry ----++def modifier_signature(original_object):+ """A text key for the modifier stack; None when a modifier reads another object, so two copies could evaluate differently."""+ entries = []+ for modifier in original_object.modifiers:+ if not modifier.show_viewport:+ continue+ properties = []+ for property_description in modifier.bl_rna.properties:+ identifier = property_description.identifier+ if identifier in IGNORED_MODIFIER_PROPERTIES or property_description.type == "COLLECTION":+ continue+ value = getattr(modifier, identifier)+ if property_description.type == "POINTER":+ if isinstance(value, bpy.types.Object):+ return None+ properties.append((identifier, getattr(value, "name", None)))+ continue+ if hasattr(value, "__len__") and not isinstance(value, str):+ value = tuple(value)+ properties.append((identifier, value))+ entries.append((modifier.type, tuple(properties)))+ return repr(entries)+++def geometry_key(original_object):+ if original_object.type == "MESH":+ signature = modifier_signature(original_object)+ if signature is not None:+ return ("data", original_object.data.name, signature)+ return ("object", original_object.name)+++def mesh_to_arrays(evaluated_object):+ mesh = evaluated_object.to_mesh()+ try:+ mesh.calc_loop_triangles()+ triangle_count = len(mesh.loop_triangles)+ if triangle_count == 0:+ return None+ coordinates = numpy.empty(len(mesh.vertices) * 3, dtype=numpy.float32)+ mesh.vertices.foreach_get("co", coordinates)+ triangle_vertices = numpy.empty(triangle_count * 3, dtype=numpy.int32)+ mesh.loop_triangles.foreach_get("vertices", triangle_vertices)+ triangle_loops = numpy.empty(triangle_count * 3, dtype=numpy.int32)+ mesh.loop_triangles.foreach_get("loops", triangle_loops)+ corner_normals = numpy.empty(len(mesh.loops) * 3, dtype=numpy.float32)+ mesh.corner_normals.foreach_get("vector", corner_normals)+ positions = coordinates.reshape(-1, 3)[triangle_vertices]+ normals = corner_normals.reshape(-1, 3)[triangle_loops]+ stacked = numpy.concatenate([positions, normals], axis=1)+ unique_rows, inverse = numpy.unique(stacked, axis=0, return_inverse=True)+ return {+ "positions": numpy.ascontiguousarray(unique_rows[:, :3], dtype=numpy.float32),+ "normals": numpy.ascontiguousarray(unique_rows[:, 3:], dtype=numpy.float32),+ "indices": numpy.ascontiguousarray(inverse.reshape(-1), dtype=numpy.uint32),+ }+ finally:+ evaluated_object.to_mesh_clear()+++def encode_array(array):+ return {"type": {"float32": "Float32Array", "uint32": "Uint32Array"}[array.dtype.name], "base64": base64.b64encode(array.tobytes()).decode("ascii")}+++def collect_scene_content(scene, width, height, report, glass_names):+ depsgraph = bpy.context.evaluated_depsgraph_get()+ environment = {+ "world": True, "fillIntensity": 0, "ambientIntensity": 1, "fogDensity": 0,+ "lightDirection": [0.0, 1.0, 0.0], "keyColor": [0.0, 0.0, 0.0],+ "pointLights": [], "spotLights": [], "areaLights": [],+ }+ geometry_indices = {}+ geometries = []+ parts = []+ skipped = {"hiddenOriginal": 0, "showSelfFalse": 0, "emptyMesh": 0, "otherType": {}, "glassInstance": 0}+ triangle_total = 0+ negative_parts = 0+ ray_visibility_counts = {}+ empty_mesh_names = []+ for instance in depsgraph.object_instances:+ evaluated_object = instance.object+ original_object = evaluated_object.original+ if original_object.hide_render:+ skipped["hiddenOriginal"] += 1+ continue+ if hasattr(instance, "show_self") and not instance.show_self:+ skipped["showSelfFalse"] += 1+ continue+ if original_object.type == "LIGHT":+ add_light_entry(environment, evaluated_object, instance.matrix_world, report)+ continue+ if original_object.type not in MESH_LIKE_OBJECT_TYPES:+ skipped["otherType"][original_object.type] = skipped["otherType"].get(original_object.type, 0) + 1+ continue+ if original_object.name in glass_names:+ skipped["glassInstance"] += 1+ continue+ key = geometry_key(original_object)+ if key not in geometry_indices:+ arrays = mesh_to_arrays(evaluated_object)+ if arrays is None:+ geometry_indices[key] = None+ else:+ geometry_indices[key] = len(geometries)+ geometries.append(arrays)+ geometry_index = geometry_indices[key]+ if geometry_index is None:+ skipped["emptyMesh"] += 1+ empty_mesh_names.append(f"{original_object.name} ({original_object.type})")+ continue+ if instance.matrix_world.determinant() < 0.0:+ negative_parts += 1+ triangle_total += len(geometries[geometry_index]["indices"]) // 3+ name = original_object.name if instance.parent is None else f"{instance.parent.original.name}/{original_object.name}"+ part = {"name": name, "geometry": geometry_index, "matrix": column_major_yup_matrix(instance.matrix_world), "material": 0}+ hidden_rays = {kind: False for kind, attribute in RAY_VISIBILITY_ATTRIBUTES.items() if not getattr(original_object, attribute, True)}+ if hidden_rays:+ part["rayVisibility"] = hidden_rays+ for kind in hidden_rays:+ ray_visibility_counts[kind] = ray_visibility_counts.get(kind, 0) + 1+ parts.append(part)+ report["skipped"] = skipped+ report["partCount"] = len(parts)+ report["geometryCount"] = len(geometries)+ report["uniqueTriangleCount"] = sum(len(entry["indices"]) // 3 for entry in geometries)+ report["uniqueVertexCount"] = sum(len(entry["positions"]) for entry in geometries)+ report["instancedTriangleCount"] = triangle_total+ report["negativeDeterminantParts"] = negative_parts+ exported_names = {part["name"].split("/")[-1] for part in parts}+ report["emptyMeshObjects"] = empty_mesh_names[:40]+ report["renderableObjectsNotExported"] = [f"{obj.name} ({obj.type}, collections {[c.name for c in obj.users_collection][:2]})" for obj in bpy.data.objects if obj.type in MESH_LIKE_OBJECT_TYPES and not obj.hide_render and obj.name not in exported_names and obj.name not in glass_names][:60]+ report["partsWithHiddenRayKinds"] = ray_visibility_counts+ report["shadowCatcherOrHoldoutObjects"] = sum(1 for obj in bpy.data.objects if getattr(obj, "is_shadow_catcher", False) or getattr(obj, "is_holdout", False))+ return environment, geometries, parts+++def collect_inspection(scene):+ object_types = {}+ modifier_types = {}+ shared_data = {}+ for scene_object in bpy.data.objects:+ object_types[scene_object.type] = object_types.get(scene_object.type, 0) + 1+ for modifier in scene_object.modifiers:+ modifier_types[modifier.type] = modifier_types.get(modifier.type, 0) + 1+ if scene_object.type == "MESH":+ shared_data[scene_object.data.name] = shared_data.get(scene_object.data.name, 0) + 1+ node_types = {}+ for material in bpy.data.materials:+ for tag in tag_material_node_trees(material):+ node_types[tag] = node_types.get(tag, 0) + 1+ return {+ "blenderVersion": bpy.app.version_string,+ "objectTypes": object_types,+ "modifierTypes": modifier_types,+ "meshDatablocks": len(shared_data),+ "meshDatablocksUsedByMoreThanOneObject": sum(1 for count in shared_data.values() if count > 1),+ "materialCount": len(bpy.data.materials),+ "materialTags": node_types,+ "collectionInstanceEmpties": sum(1 for obj in bpy.data.objects if obj.instance_type == "COLLECTION"),+ "unitScale": scene.unit_settings.scale_length,+ "engine": scene.render.engine,+ "frame": scene.frame_current,+ "motionBlur": scene.render.use_motion_blur,+ "worldNodeTypes": sorted({node.type for node in scene.world.node_tree.nodes}) if scene.world and scene.world.use_nodes else None,+ }+++def grey_material_entry():+ return {"tag": "surface", "color": [GREY_ALBEDO] * 3, "metallic": 0, "roughness": 1, "specular": 0, "emission": 0}+++def run_export(options):+ started = time.perf_counter()+ scene = bpy.context.scene+ output_directory = options["output"]+ os.makedirs(output_directory, exist_ok=True)+ render_cycles = load_render_cycles_module()+ report = {"inspection": collect_inspection(scene), "lightCounts": {}, "notes": []}+ log("inspection " + json.dumps(report["inspection"]))+ report["raw"] = describe_lights_and_film(scene)+ report["prepare"] = prepare_scene(scene, options["keep_glass"])+ glass_names = set(report["prepare"].pop("glassObjects"))+ log("prepare " + json.dumps(report["prepare"]))+ camera_entry, lens_entry = build_camera_entries(scene, options["width"], options["height"], report)+ environment, geometries, parts = collect_scene_content(scene, options["width"], options["height"], report, glass_names)+ log("content " + json.dumps({key: report[key] for key in ("partCount", "geometryCount", "uniqueTriangleCount", "instancedTriangleCount", "negativeDeterminantParts", "skipped", "lightCounts")}))+ world_description = describe_world(scene.world)+ report["worldDescription"] = world_description+ if world_description["kind"] == "constant" and world_description.get("grey", True):+ world_entry = {"type": "constant", "value": world_description["value"]}+ else:+ relative_hdr_path = "artifacts/classroom/world.hdr"+ absolute_hdr_path = os.path.join(REPOSITORY_ROOT, relative_hdr_path)+ os.makedirs(os.path.dirname(absolute_hdr_path), exist_ok=True)+ work_directory = os.path.join(output_directory, "world-probes")+ os.makedirs(work_directory, exist_ok=True)+ bake_world(scene.world, work_directory, absolute_hdr_path, render_cycles, report)+ world_entry = {"type": "hdri", "file": relative_hdr_path, "intensity": 1.0, "radianceLimit": HDR_RADIANCE_LIMIT}+ description = {+ "id": "classroom",+ "camera": camera_entry,+ "environment": environment,+ "world": world_entry,+ "materials": [grey_material_entry()],+ "images": [],+ "parts": parts,+ "geometries": [{"positions": encode_array(entry["positions"]), "normals": encode_array(entry["normals"]), "indices": encode_array(entry["indices"])} for entry in geometries],+ }+ scene_path = os.path.join(output_directory, "classroom.json")+ with open(scene_path, "w", encoding="utf-8") as handle:+ json.dump(description, handle)+ with open(os.path.join(output_directory, "classroom-lens.json"), "w", encoding="utf-8") as handle:+ json.dump(lens_entry, handle, indent=2)+ report["sceneJsonBytes"] = os.path.getsize(scene_path)+ report["exportSeconds"] = round(time.perf_counter() - started, 2)+ report["environmentSummary"] = {key: (len(value) if isinstance(value, list) and key.endswith("Lights") else value) for key, value in environment.items() if key in ("keyColor", "lightDirection", "sunAngularRadius", "pointLights", "spotLights", "areaLights")}+ with open(os.path.join(output_directory, "classroom-report.json"), "w", encoding="utf-8") as handle:+ json.dump(report, handle, indent=2)+ log("done " + json.dumps({"sceneJsonBytes": report["sceneJsonBytes"], "exportSeconds": report["exportSeconds"], "environment": report["environmentSummary"], "world": world_entry["type"]}))+++def describe_lights_and_film(scene):+ """Raw light, world and film settings, so a brightness gap between the bridge and the original can be traced."""+ lights = []+ for light_object in bpy.data.objects:+ if light_object.type != "LIGHT":+ continue+ light_data = light_object.data+ lights.append({+ "name": light_object.name, "type": light_data.type, "energy": light_data.energy, "exposure": getattr(light_data, "exposure", None),+ "color": list(light_data.color), "radius": getattr(light_data, "shadow_soft_size", None), "hideRender": light_object.hide_render,+ "shape": getattr(light_data, "shape", None), "size": getattr(light_data, "size", None), "sizeY": getattr(light_data, "size_y", None),+ "scale": list(light_object.matrix_world.to_scale()), "library": light_data.library.filepath if light_data.library else None,+ "useShadow": getattr(light_data, "use_shadow", None), "normalize": getattr(light_data, "normalize", None),+ "cyclesSettings": {name: getattr(light_data.cycles, name, None) for name in ("is_portal", "max_bounces", "cast_shadow")} if hasattr(light_data, "cycles") else None,+ })+ world = scene.world+ world_raw = None+ if world is not None and world.use_nodes and world.node_tree is not None:+ world_raw = [{"type": node.type, "inputs": {socket.name: (list(socket.default_value) if hasattr(socket.default_value, "__len__") else socket.default_value) for socket in node.inputs if hasattr(socket, "default_value")}} for node in world.node_tree.nodes]+ return {+ "lights": lights, "worldNodes": world_raw,+ "filmExposure": scene.cycles.film_exposure, "viewExposure": scene.view_settings.exposure, "viewGamma": scene.view_settings.gamma,+ "viewTransform": scene.view_settings.view_transform, "lightTree": getattr(scene.cycles, "use_light_tree", None),+ "samplingThreshold": getattr(scene.cycles, "light_sampling_threshold", None), "maxBounces": scene.cycles.max_bounces,+ }+++def apply_reference_variant(scene, variant):+ """Experiments on the original scene: each removes one thing the bridge converts, to see which one the brightness depends on."""+ if variant == "film-reset":+ scene.cycles.film_exposure = 1.0+ scene.view_settings.exposure = 0.0+ scene.view_settings.gamma = 1.0+ elif variant == "no-world":+ scene.world = None+ elif variant in ("sun-only", "points-only", "areas-only", "spots-only"):+ keep = {"sun-only": "SUN", "points-only": "POINT", "areas-only": "AREA", "spots-only": "SPOT"}[variant]+ for light_object in bpy.data.objects:+ if light_object.type == "LIGHT" and light_object.data.type != keep:+ hide_object_everywhere(light_object)+ scene.world = None+++def run_reference(options):+ scene = bpy.context.scene+ render_cycles = load_render_cycles_module()+ prepare_report = prepare_scene(scene, options["keep_glass"])+ prepare_report.pop("glassObjects")+ log("prepare " + json.dumps(prepare_report))+ log("lights and film " + json.dumps(describe_lights_and_film(scene), default=str))+ apply_reference_variant(scene, options["variant"])+ render_options = {+ "samples": options["samples"], "seed": options["seed"], "bounces": options["bounces"], "transparent_bounces": None,+ "filter_type": "box", "filter_width": 1.0, "denoise": "none",+ }+ used_devices = render_cycles.configure_cycles_parity(scene, render_options)+ render_cycles.configure_linear_exr_output(scene, options["width"], options["height"])+ scene.render.use_motion_blur = False+ scene.render.film_transparent = False+ if options["pinhole"]:+ scene.camera.data.dof.use_dof = False+ render_cycles.apply_grey_diffuse_override(scene)+ exr_path = f"{options['output']}.exr"+ timing = render_cycles.execute_timed_cycles_render(scene, exr_path)+ render_cycles.load_exr_into_npy(exr_path, f"{options['output']}.npy", options["width"], options["height"], False)+ if options["z_depth"]:+ render_cycles.render_camera_z_depth(scene, options["output"], options["width"], options["height"], options["samples"])+ report = {"engine": "cycles-optix", "mode": "original-blend", "devices": used_devices, "samples": options["samples"], "seed": options["seed"], "pinhole": options["pinhole"], "renderCallSeconds": round(timing["render_call_seconds"], 3), "prepare": prepare_report}+ with open(f"{options['output']}.json", "w", encoding="utf-8") as handle:+ json.dump(report, handle, indent=2)+ log("reference done " + json.dumps({"renderCallSeconds": report["renderCallSeconds"]}))+++def main():+ options = parse_arguments()+ if options["mode"] == "export":+ run_export(options)+ else:+ run_reference(options)+++main()diff --git a/bench/cycles-parity/instanced-scene-in-batches.mjs b/bench/cycles-parity/instanced-scene-in-batches.mjsnew file mode 100644index 00000000..ef653944--- /dev/null+++ b/bench/cycles-parity/instanced-scene-in-batches.mjs@@ -0,0 +1,106 @@+// buildTraceScene({ instancing: true }) refuses more than MAX_TRACE_TRIANGLES (400,000) unique triangles, counted once per shared+// geometry. The native cycles kernel has no such limit (bench/cycles-parity/large-scene.mjs packs bigger scenes directly), and the+// Classroom scene holds 427,769 unique triangles. This builds the instanced scene in two batches that each fit under the cap and joins+// their instance and material lists, so the bench needs no change to src/.+import { MAX_TRACE_TRIANGLES } from '../../src/path-tracer-scene.js';+import { buildTraceSceneWithManyLights } from './trace-scene-many-lights.mjs';++function triangleCountOf(geometry) {+ return geometry.indices.length / 3;+}++function groupPartsByGeometry(parts) {+ const groups = new Map();+ for (const part of parts) {+ if (!groups.has(part.geometry)) {+ groups.set(part.geometry, []);+ }+ groups.get(part.geometry).push(part);+ }+ return groups;+}++function uniqueTriangleTotal(geometries) {+ let total = 0;+ for (const geometry of geometries) {+ total += triangleCountOf(geometry);+ }+ return total;+}++/**+ * Splits the geometries into one batch that fits the cap and, when the scene is over it, a second batch seeded with the biggest+ * shared geometries, so each batch still has shared geometry (a batch without any is flattened by buildTraceScene).+ */+export function splitGeometriesIntoBatches(groups) {+ const allGeometries = [...groups.keys()];+ if (uniqueTriangleTotal(allGeometries) <= MAX_TRACE_TRIANGLES) {+ return [allGeometries];+ }+ const sharedBySize = allGeometries+ .filter((geometry) => groups.get(geometry).length > 1)+ .sort((first, second) => triangleCountOf(second) - triangleCountOf(first));+ const secondBatch = new Set();+ let firstBatch = new Set(allGeometries);+ for (const geometry of sharedBySize) {+ if (uniqueTriangleTotal(firstBatch) <= MAX_TRACE_TRIANGLES && secondBatch.size > 0) {+ break;+ }+ secondBatch.add(geometry);+ firstBatch.delete(geometry);+ }+ if (uniqueTriangleTotal(firstBatch) > MAX_TRACE_TRIANGLES || uniqueTriangleTotal(secondBatch) > MAX_TRACE_TRIANGLES) {+ throw new RangeError('The scene needs more than two batches of instanced geometry; split it further in instanced-scene-in-batches.mjs.');+ }+ return [[...firstBatch], [...secondBatch]];+}++// FORMAT-v2 instance visibility bits: 1 camera, 2 diffuse, 4 glossy, 8 transmission, 16 shadow, 32 volume scatter.+const RAY_VISIBILITY_BITS = { camera: 1, diffuse: 2, glossy: 4, transmission: 8, shadow: 16, volumeScatter: 32 };+const ALL_RAY_KINDS = 63;++function visibilityFlagsFor(part) {+ let flags = ALL_RAY_KINDS;+ for (const [kind, isVisible] of Object.entries(part.rayVisibility ?? {})) {+ if (isVisible === false) {+ flags &= ~RAY_VISIBILITY_BITS[kind];+ }+ }+ return flags;+}++// Each instance of a batch scene is its part, in order; a part that hides from some ray kinds gets those bits cleared.+function applyRayVisibility(scene, batchParts) {+ scene.instances.forEach((instance, index) => {+ if (batchParts[index].rayVisibility) {+ instance.visibilityFlags = visibilityFlagsFor(batchParts[index]);+ }+ });+}++export function buildInstancedTraceSceneInBatches(parts, environment) {+ const groups = groupPartsByGeometry(parts);+ const batches = splitGeometriesIntoBatches(groups);+ const scenes = batches.map((geometries) => {+ const batchParts = geometries.flatMap((geometry) => groups.get(geometry));+ const scene = buildTraceSceneWithManyLights(batchParts, environment, { instancing: true });+ if (!scene.instances) {+ throw new RangeError('A batch of the instanced scene has no shared geometry and was flattened.');+ }+ applyRayVisibility(scene, batchParts);+ return scene;+ });+ const [firstScene, ...otherScenes] = scenes;+ const joined = { ...firstScene, instances: [...firstScene.instances], materials: [...firstScene.materials], traceMaterials: [...firstScene.traceMaterials] };+ for (const scene of otherScenes) {+ const partOffset = joined.materials.length;+ for (const instance of scene.instances) {+ joined.instances.push({ ...instance, materialIndex: instance.materialIndex + partOffset, objectId: instance.objectId + partOffset });+ }+ joined.materials.push(...scene.materials);+ joined.traceMaterials.push(...scene.traceMaterials);+ joined.surfaceOffset = Math.max(joined.surfaceOffset, scene.surfaceOffset);+ joined.farDistance = Math.max(joined.farDistance, scene.farDistance);+ }+ return { scene: joined, batchCount: batches.length, uniqueTrianglesPerBatch: batches.map(uniqueTriangleTotal) };+}diff --git a/bench/cycles-parity/render-cycles.py b/bench/cycles-parity/render-cycles.pyindex ef64f012..c4be1cb0 100644--- a/bench/cycles-parity/render-cycles.py+++ b/bench/cycles-parity/render-cycles.py@@ -18,6 +18,11 @@ WATTS_PER_AREA_INTENSITY = math.piSUN_ANGULAR_DIAMETER = math.radians(1.0)ENVIRONMENT_ROTATION_Z = -math.pi / 2.0PART_ID_STEPS = 64+# A part may carry rayVisibility: { shadow: false, ... } for the ray kinds it is hidden from (Cook reads the same field).+RAY_VISIBILITY_ATTRIBUTES = {+ "camera": "visible_camera", "diffuse": "visible_diffuse", "glossy": "visible_glossy",+ "transmission": "visible_transmission", "volumeScatter": "visible_volume_scatter", "shadow": "visible_shadow",+}Y_UP_TO_Z_UP = Matrix(((1.0, 0.0, 0.0, 0.0),(0.0, 0.0, -1.0, 0.0),@@ -338,6 +343,8 @@ def build_scene_objects(scene, description):column_major = part_entry["matrix"]local_matrix = Matrix([[column_major[column * 4 + row] for column in range(4)] for row in range(4)])mesh_object.matrix_world = Y_UP_TO_Z_UP @ local_matrix+ for ray_kind, is_visible in part_entry.get("rayVisibility", {}).items():+ setattr(mesh_object, RAY_VISIBILITY_ATTRIBUTES[ray_kind], is_visible)scene.collection.objects.link(mesh_object)@@ -430,7 +437,9 @@ def build_scene_lights(scene, environment_entry):sun_data = bpy.data.lights.new("Sun", "SUN")sun_data.energy = sun_strengthsun_data.color = [channel / sun_strength for channel in key_color]- sun_data.angle = SUN_ANGULAR_DIAMETER+ # A scene that sets sunAngularRadius (radians, as Cook reads it) gets that disc; the others keep the 1 degree default.+ sun_radius = environment_entry.get("sunAngularRadius")+ sun_data.angle = SUN_ANGULAR_DIAMETER if sun_radius is None else 2.0 * sun_radiussun_object = bpy.data.objects.new("Sun", sun_data)toward_light = Vector(convert_position_to_blender(environment_entry["lightDirection"])).normalized()sun_object.rotation_mode = "QUATERNION"diff --git a/bench/cycles-parity/run-classroom-parity.py b/bench/cycles-parity/run-classroom-parity.pynew file mode 100644index 00000000..feb0f5ce--- /dev/null+++ b/bench/cycles-parity/run-classroom-parity.py@@ -0,0 +1,460 @@+"""One-call driver for the Classroom parity row of #896: export, both renders, comparisons and a figure.++Run from the repository root on a machine with Blender 5.3 (Cycles OptiX), Node, the built render-native addon and a GPU:++ python3 bench/cycles-parity/run-classroom-parity.py [--data-directory <folder>] [--samples 1024] [--force stage,stage] [--keep-glass]++Stages, each skipped when its outputs already exist unless named in --force: export, cook, cycles, reference, compare.+The scene is the Blender "Classroom" demo file (Christophe Seux, CC0). It is downloaded once into --data-directory (default+~/cook-data/classroom), outside the repository, and opened only with auto-run scripts disabled. Outputs go to artifacts/classroom/+(ignored by Git); the summary is artifacts/classroom/summary.json and the figure artifacts/classroom/classroom-comparison.jpg.+"""+import glob+import json+import os+import shutil+import subprocess+import sys+import time+import traceback+import urllib.request+import zipfile++HERE = os.path.dirname(os.path.abspath(__file__))+REPOSITORY_ROOT = os.path.abspath(os.path.join(HERE, "..", ".."))+sys.path.insert(0, HERE)++CLASSROOM_URL = "https://download.blender.org/demo/test/classroom.zip"+OUTPUT_DIRECTORY = os.path.join(REPOSITORY_ROOT, "artifacts", "classroom")+SCENE_DIRECTORY = os.path.join(OUTPUT_DIRECTORY, "scene")+HOME_DIRECTORY = os.path.expanduser("~")+DEFAULT_DATA_DIRECTORY = os.path.join(HOME_DIRECTORY, "cook-data", "classroom")+BLENDER_SEARCH_PATTERNS = (+ os.path.join(HOME_DIRECTORY, "blender", "blender"),+ os.path.join(HOME_DIRECTORY, "*", "blender"),+ os.path.join(HOME_DIRECTORY, "*", "*", "blender"),+ os.path.join(os.sep + "opt", "*", "blender"),+ os.path.join(os.sep + "opt", "*", "*", "blender"),+)+WIDTH = 960+HEIGHT = 540+DEPTH_SAMPLES = 1024+++def parse_arguments():+ arguments = sys.argv[1:]++ def option(name, fallback):+ return arguments[arguments.index(name) + 1] if name in arguments else fallback++ return {+ "data_directory": option("--data-directory", DEFAULT_DATA_DIRECTORY),+ "samples": int(option("--samples", "1024")),+ "force": set(filter(None, option("--force", "").split(","))),+ "keep_glass": "--keep-glass" in arguments,+ }+++def log(message):+ line = f"[{time.strftime('%H:%M:%S')}] {message}"+ print(line, flush=True)+ with open(os.path.join(OUTPUT_DIRECTORY, "driver.log"), "a", encoding="utf-8") as handle:+ handle.write(line + "\n")+++def run_command(command, log_name, check=True):+ log_path = os.path.join(OUTPUT_DIRECTORY, f"{log_name}.log")+ started = time.perf_counter()+ with open(log_path, "w", encoding="utf-8") as handle:+ completed = subprocess.run(command, cwd=REPOSITORY_ROOT, stdout=handle, stderr=subprocess.STDOUT)+ seconds = time.perf_counter() - started+ log(f"{log_name}: exit {completed.returncode} in {seconds:.1f} s")+ if completed.returncode != 0:+ with open(log_path, encoding="utf-8", errors="replace") as handle:+ tail = handle.read().splitlines()[-25:]+ log(f"{log_name} tail:\n" + "\n".join(tail))+ if check:+ raise RuntimeError(f"{log_name} failed with exit code {completed.returncode}")+ return seconds+++def find_blender():+ found = shutil.which("blender")+ if found:+ return found+ for pattern in BLENDER_SEARCH_PATTERNS:+ for path in sorted(glob.glob(pattern)):+ if os.path.isfile(path) and os.access(path, os.X_OK):+ return path+ raise RuntimeError("Blender was not found on this machine.")+++def ensure_python_packages():+ """The packages come from `uv run --with numpy --with pillow --with flip-evaluator` (run-classroom-parity.sh)."""+ for module_name in ("numpy", "PIL", "flip_evaluator"):+ __import__(module_name)+++def ensure_classroom_file(data_directory):+ existing = glob.glob(os.path.join(data_directory, "**", "*.blend"), recursive=True)+ if existing:+ return existing[0]+ os.makedirs(data_directory, exist_ok=True)+ archive_path = os.path.join(data_directory, "classroom.zip")+ log(f"downloading {CLASSROOM_URL}")+ urllib.request.urlretrieve(CLASSROOM_URL, archive_path)+ with zipfile.ZipFile(archive_path) as archive:+ archive.extractall(data_directory)+ existing = glob.glob(os.path.join(data_directory, "**", "*.blend"), recursive=True)+ if not existing:+ raise RuntimeError("The Classroom archive holds no .blend file.")+ return existing[0]+++def blender_command(blender, blend_path, mode, output, extra):+ return [blender, "-b", "--disable-autoexec", blend_path, "--python", os.path.join(HERE, "classroom_bridge.py"), "--", mode, output, "--width", str(WIDTH), "--height", str(HEIGHT)] + extra+++def lens_flags_for(lens):+ if not lens.get("enabled"):+ return []+ return ["--f-stop", str(lens["fStop"]), "--focus-distance", str(lens["focusDistance"]), "--aperture-blades", str(lens["apertureBlades"]),+ "--aperture-rotation", str(lens["apertureRotation"]), "--sensor-width", str(lens["sensorWidth"])]+++def stage_wanted(stage, outputs, force):+ return stage in force or not all(os.path.exists(path) for path in outputs)+++def cook_command(scene_json, prefix, samples, seed, extra):+ return ["node", os.path.join(HERE, "trace-native.mjs"), scene_json, prefix, "--kernel", "cycles", "--samples", str(samples), "--bounces", "8", "--seed", str(seed),+ "--width", str(WIDTH), "--height", str(HEIGHT), "--grey-diffuse", "--instancing"] + extra+++def cycles_command(blender, scene_json, prefix, samples, seed, extra):+ return [blender, "-b", "--factory-startup", "--python", os.path.join(HERE, "render-cycles.py"), "--", scene_json, prefix, "--samples", str(samples), "--bounces", "8",+ "--seed", str(seed), "--width", str(WIDTH), "--height", str(HEIGHT), "--grey-diffuse"] + extra+++def tone_mapped_image(linear_rgb):+ import numpy+ import compare+ return (numpy.clip(compare.tone_map_like_67js(linear_rgb), 0.0, 1.0) * 255.0 + 0.5).astype(numpy.uint8)+++def write_side_by_side(cook_path, cycles_path, output_path):+ import numpy+ from PIL import Image+ cook = Image.fromarray(tone_mapped_image(numpy.load(cook_path))).resize((640, 360), Image.LANCZOS)+ cycles = Image.fromarray(tone_mapped_image(numpy.load(cycles_path))).resize((640, 360), Image.LANCZOS)+ canvas = Image.new("RGB", (1280, 360))+ canvas.paste(cook, (0, 0))+ canvas.paste(cycles, (640, 0))+ canvas.save(output_path, "JPEG", quality=80, optimize=True)+++def write_ratio_map(reference_path, candidate_path, output_path, block=12):+ import numpy+ from PIL import Image+ reference = numpy.load(reference_path).astype(numpy.float64).mean(axis=2)+ candidate = numpy.load(candidate_path).astype(numpy.float64).mean(axis=2)+ rows = reference.shape[0] // block+ columns = reference.shape[1] // block+ reference_blocks = reference[: rows * block, : columns * block].reshape(rows, block, columns, block).mean(axis=(1, 3))+ candidate_blocks = candidate[: rows * block, : columns * block].reshape(rows, block, columns, block).mean(axis=(1, 3))+ log_ratio = numpy.log2(numpy.maximum(candidate_blocks, 1e-6) / numpy.maximum(reference_blocks, 1e-6))+ scaled = numpy.clip(log_ratio / 0.25, -1.0, 1.0)+ image = numpy.zeros((rows, columns, 3), dtype=numpy.uint8)+ image[..., 0] = numpy.clip(128 + 127 * scaled, 0, 255)+ image[..., 2] = numpy.clip(128 - 127 * scaled, 0, 255)+ image[..., 1] = numpy.clip(128 - 127 * numpy.abs(scaled), 0, 255)+ Image.fromarray(image).resize((columns * 4, rows * 4), Image.NEAREST).save(output_path, "JPEG", quality=80)+ return {"blockMeanLog2RatioMin": float(log_ratio.min()), "blockMeanLog2RatioMax": float(log_ratio.max())}+++def select_image_summary(comparison):+ gates = comparison["parityGates"]+ tiles = comparison["tileGrid8x8"]+ return {+ "channelMeanRatio": gates["channelMeanRatioExact"], "channelMeanPass": gates["channelMeanPass"],+ "tilesWithin5Percent": f"{tiles['withinFivePercentCount']} of {tiles['eligibleTileCount']}", "tilePass": gates["tileGridPass"],+ "tileMinMax": [tiles["minRatio"], tiles["maxRatio"]], "darkTilesExcluded": tiles["excludedDarkTileCount"],+ "relMse": comparison["relMse"], "relMseTrimmed": comparison["relMseTrimmed"],+ "flipLdr": gates.get("flipLdrCandidateVsA"), "flipLdrSeedFloor": gates.get("flipLdrAVsB"), "flipLdrCeiling": gates.get("flipLdrCeiling"), "flipPass": gates.get("flipPass"),+ "seedFloorRelMse": comparison.get("seedAVsSeedB", {}).get("relMse"), "worstTiles": tiles["worstTiles"][:4],+ }+++def compare_images(reference_path, candidate_path, seed_path):+ import compare+ reference = compare.load_linear_rgb_image(reference_path)+ candidate = compare.load_linear_rgb_image(candidate_path)+ seed_comparison = None+ if seed_path and os.path.exists(seed_path):+ seed_comparison = compare.compare_image_pair(reference, compare.load_linear_rgb_image(seed_path), include_flip=True)+ comparison = compare.compare_image_pair(reference, candidate, include_flip=True, seed_ab_comparison=seed_comparison)+ summary = select_image_summary(comparison)+ summary["meanLuminance"] = float(reference.mean())+ return summary+++def compare_depths(cycles_depth_path, cook_depth_path, field_of_view):+ import numpy+ import compare_depth+ reference = numpy.load(cycles_depth_path)+ cook_z = compare_depth.ray_distance_to_z_depth(numpy.load(cook_depth_path), field_of_view)+ result = compare_depth.compare_depth_maps(reference, cook_z, 0.01)+ reference_hit = compare_depth.hit_mask_of(reference)+ candidate_hit = compare_depth.hit_mask_of(cook_z)+ agree = compare_depth.agreement_at(numpy.where(reference_hit, reference, 0.0), numpy.where(candidate_hit, cook_z, 0.0), reference_hit, candidate_hit, 0.01)+ disagree = ~agree+ grid = [[int(disagree[row * HEIGHT // 8:(row + 1) * HEIGHT // 8, column * WIDTH // 8:(column + 1) * WIDTH // 8].sum()) for column in range(8)] for row in range(8)]+ result["disagreeingPixelsPer8x8Tile"] = grid+ result["referenceMissShare"] = float((~reference_hit).mean())+ depth_error = numpy.abs(cook_z - reference) / numpy.maximum(reference, 1e-9)+ both = reference_hit & candidate_hit+ result["bothHitByRelativeError"] = {+ "above1Percent": int((both & (depth_error > 0.01)).sum()),+ "above5Percent": int((both & (depth_error > 0.05)).sum()),+ "above20Percent": int((both & (depth_error > 0.20)).sum()),+ }+ return result, disagree+++def write_depth_disagreement_image(disagree, cycles_depth_path, output_path):+ import numpy+ from PIL import Image+ depth = numpy.load(cycles_depth_path)+ shade = (numpy.clip(depth / max(float(depth.max()), 1e-6), 0, 1) * 160).astype(numpy.uint8)+ image = numpy.stack([shade, shade, shade], axis=2)+ image[disagree] = (255, 0, 0)+ Image.fromarray(image).save(output_path, "JPEG", quality=80)+++def read_json(path):+ with open(path, encoding="utf-8") as handle:+ return json.load(handle)+++def main():+ options = parse_arguments()+ os.makedirs(SCENE_DIRECTORY, exist_ok=True)+ summary = {"samples": options["samples"], "errors": {}}+ force = options["force"]+ samples = options["samples"]++ def guarded(stage, action):+ try:+ action()+ except Exception as error:+ summary["errors"][stage] = repr(error)+ log(f"STAGE {stage} FAILED: {error}\n{traceback.format_exc()[-1500:]}")++ log(f"driver start, samples {samples}, force {sorted(force)}")+ ensure_python_packages()+ blender = find_blender()+ summary["blender"] = blender+ blend_path = ensure_classroom_file(options["data_directory"])+ summary["blendBytes"] = os.path.getsize(blend_path)+ scene_json = os.path.join(SCENE_DIRECTORY, "classroom.json")+ report_path = os.path.join(SCENE_DIRECTORY, "classroom-report.json")++ def stage_export():+ if stage_wanted("export", [scene_json, report_path], force):+ extra = ["--keep-glass"] if options["keep_glass"] else []+ run_command(blender_command(blender, blend_path, "export", SCENE_DIRECTORY, extra), "export")++ guarded("export", stage_export)+ if os.path.exists(report_path):+ report = read_json(report_path)+ keys = ("partCount", "geometryCount", "uniqueTriangleCount", "uniqueVertexCount", "instancedTriangleCount", "negativeDeterminantParts", "skipped", "lightCounts", "environmentSummary", "worldDescription", "worldBake", "camera", "lens", "sceneJsonBytes", "exportSeconds", "notes", "raw", "emptyMeshObjects", "renderableObjectsNotExported", "partsWithHiddenRayKinds", "shadowCatcherOrHoldoutObjects")+ summary["export"] = {key: report.get(key) for key in keys}+ summary["inspection"] = report.get("inspection")+ summary["prepare"] = report.get("prepare")+ if not os.path.exists(scene_json):+ finish(summary)+ return+ lens = read_json(os.path.join(SCENE_DIRECTORY, "classroom-lens.json"))+ lens_flags = lens_flags_for(lens)+ summary["lens"] = lens+ variants = [("pinhole", [])]+ if lens.get("enabled"):+ variants.insert(0, ("dof", lens_flags))++ def stage_cook():+ for label, flags in variants:+ prefix = os.path.join(OUTPUT_DIRECTORY, f"cook-{label}")+ extra = list(flags) + (["--write-depth"] if label == "pinhole" else [])+ if stage_wanted("cook", [prefix + ".npy", prefix + ".json"], force):+ run_command(cook_command(scene_json, prefix, samples, 1, extra), f"cook-{label}")+ trace = read_json(prefix + ".json")+ summary.setdefault("cook", {})[label] = {key: trace.get(key) for key in ("triangleCount", "instanceCount", "samplingSeconds", "setupSeconds", "adapter", "thinLens", "cameraVerticalFovDegrees")}++ def stage_cycles():+ for label, flags in variants:+ for seed in (1, 2):+ prefix = os.path.join(OUTPUT_DIRECTORY, f"cycles-{label}-seed{seed}")+ with_depth = label == "pinhole" and seed == 1+ extra = list(flags) + (["--z-depth", "--depth-samples", str(DEPTH_SAMPLES)] if with_depth else [])+ if stage_wanted("cycles", [prefix + ".npy", prefix + ".json"], force):+ run_command(cycles_command(blender, scene_json, prefix, samples, seed, extra), f"cycles-{label}-seed{seed}")+ trace = read_json(os.path.join(OUTPUT_DIRECTORY, f"cycles-{label}-seed1.json"))+ summary.setdefault("cycles", {})[label] = {key: trace.get(key) for key in ("samplingSeconds", "setupSeconds", "devices", "blenderVersion", "thinLens", "cyclesPeakMemoryMegabytes", "depthError")}++ def stage_reference():+ prefix = os.path.join(OUTPUT_DIRECTORY, "blend-pinhole")+ if stage_wanted("reference", [prefix + ".npy"], force):+ extra = ["--pinhole", "--z-depth", "--samples", str(samples), "--seed", "1"] + (["--keep-glass"] if options["keep_glass"] else [])+ run_command(blender_command(blender, blend_path, "reference", prefix, extra), "blend-pinhole")++ guarded("cook", stage_cook)+ guarded("cycles", stage_cycles)+ guarded("reference", stage_reference)++ def stage_compare():+ comparisons = {}+ for label, flags in variants:+ cook_path = os.path.join(OUTPUT_DIRECTORY, f"cook-{label}.npy")+ cycles_path = os.path.join(OUTPUT_DIRECTORY, f"cycles-{label}-seed1.npy")+ seed_path = os.path.join(OUTPUT_DIRECTORY, f"cycles-{label}-seed2.npy")+ comparisons[f"cook-vs-cycles-{label}"] = compare_images(cycles_path, cook_path, seed_path)+ comparisons[f"cook-vs-cycles-{label}"]["ratioMap"] = write_ratio_map(cycles_path, cook_path, os.path.join(OUTPUT_DIRECTORY, f"ratio-map-{label}.jpg"))+ blend_npy = os.path.join(OUTPUT_DIRECTORY, "blend-pinhole.npy")+ if os.path.exists(blend_npy):+ seed_path = os.path.join(OUTPUT_DIRECTORY, "cycles-pinhole-seed2.npy")+ comparisons["bridge-cycles-vs-original-blend-pinhole"] = compare_images(blend_npy, os.path.join(OUTPUT_DIRECTORY, "cycles-pinhole-seed1.npy"), seed_path)+ comparisons["cook-vs-original-blend-pinhole"] = compare_images(blend_npy, os.path.join(OUTPUT_DIRECTORY, "cook-pinhole.npy"), seed_path)+ summary["images"] = comparisons+ fov = read_json(os.path.join(OUTPUT_DIRECTORY, "cook-pinhole.json"))["cameraVerticalFovDegrees"]+ cycles_depth = os.path.join(OUTPUT_DIRECTORY, "cycles-pinhole-seed1-depth.npy")+ depth_result, disagree = compare_depths(cycles_depth, os.path.join(OUTPUT_DIRECTORY, "cook-pinhole-depth.npy"), fov)+ summary["depth"] = depth_result+ blend_depth = os.path.join(OUTPUT_DIRECTORY, "blend-pinhole-depth.npy")+ if os.path.exists(blend_depth):+ import numpy+ import compare_depth+ geometry_check = compare_depth.compare_depth_maps(numpy.load(blend_depth), numpy.load(cycles_depth), 0.01)+ geometry_check["disagreeingPixelsPer8x8Tile"] = [[int((~compare_depth.agreement_at(numpy.load(blend_depth), numpy.load(cycles_depth), compare_depth.hit_mask_of(numpy.load(blend_depth)), compare_depth.hit_mask_of(numpy.load(cycles_depth)), 0.01))[row * HEIGHT // 8:(row + 1) * HEIGHT // 8, column * WIDTH // 8:(column + 1) * WIDTH // 8].sum()) for column in range(8)] for row in range(8)]+ summary["bridgeGeometryCheckDepthCyclesJsonVsOriginalBlend"] = geometry_check+ write_depth_disagreement_image(disagree, cycles_depth, os.path.join(OUTPUT_DIRECTORY, "depth-disagreement.jpg"))+ primary = variants[0][0]+ write_side_by_side(os.path.join(OUTPUT_DIRECTORY, f"cook-{primary}.npy"), os.path.join(OUTPUT_DIRECTORY, f"cycles-{primary}-seed1.npy"), os.path.join(OUTPUT_DIRECTORY, "classroom-comparison.jpg"))++ guarded("compare", stage_compare)+ guarded("diagnose", lambda: stage_diagnose(blender, blend_path, scene_json, options, summary))+ guarded("pointprobe", lambda: stage_point_probe(blender, scene_json, options, summary))+ finish(summary)+++POINT_PROBE_SAMPLES = 256+++def stage_point_probe(blender, scene_json, options, summary):+ """Cook against Cycles on the same exported scene, lit by one point light at a time and by all of them with radius 0.++ Both renderers read one JSON file, so a gap here is in how they treat a point light, not in the bridge."""+ scene = read_json(scene_json)+ environment = scene["environment"]+ points = environment["pointLights"]+ summary["pointLights"] = [{"index": index, "position": [round(value, 3) for value in light["position"]], "intensity": round(light["intensity"], 4), "radius": light["radius"], "color": [round(value, 3) for value in light["color"]]} for index, light in enumerate(points)]+ base = {"keyColor": [0, 0, 0], "areaLights": [], "spotLights": []}+ variants = {f"point{index}": {**base, "pointLights": [light]} for index, light in enumerate(points)}+ variants["all-radius0"] = {**base, "pointLights": [{**light, "radius": 0.0} for light in points]}+ results = {}+ for name, environment_changes in variants.items():+ variant_path = os.path.join(SCENE_DIRECTORY, f"classroom-probe-{name}.json")+ with open(variant_path, "w", encoding="utf-8") as handle:+ json.dump({**scene, "environment": {**environment, **environment_changes}}, handle)+ cook_prefix = os.path.join(OUTPUT_DIRECTORY, f"probe-cook-{name}")+ cycles_prefix = os.path.join(OUTPUT_DIRECTORY, f"probe-cycles-{name}")+ run_command(cook_command(variant_path, cook_prefix, POINT_PROBE_SAMPLES, 1, []), f"probe-cook-{name}", check=False)+ run_command(cycles_command(blender, variant_path, cycles_prefix, POINT_PROBE_SAMPLES, 1, []), f"probe-cycles-{name}", check=False)+ entry = {}+ for label, prefix in (("cook", cook_prefix), ("cycles", cycles_prefix)):+ if os.path.exists(prefix + ".npy"):+ entry[label] = channel_means(prefix + ".npy")[1]+ if len(entry) == 2:+ entry["cookOverCycles"] = round(entry["cook"] / max(entry["cycles"], 1e-12), 4)+ results[name] = entry+ summary["pointProbe"] = results+++DIAGNOSTIC_SAMPLES = 256+BLEND_VARIANTS = ("sun-only", "points-only", "areas-only", "spots-only")+LIGHT_SUBSETS = {+ "sun-only": {"pointLights": [], "areaLights": [], "spotLights": []},+ "points-only": {"keyColor": [0, 0, 0], "areaLights": [], "spotLights": []},+ "areas-only": {"keyColor": [0, 0, 0], "pointLights": [], "spotLights": []},+ "spots-only": {"keyColor": [0, 0, 0], "pointLights": [], "areaLights": []},+}+++def channel_means(npy_path):+ import numpy+ return [round(float(value), 5) for value in numpy.load(npy_path).reshape(-1, 3).mean(axis=0)]+++def stage_diagnose(blender, blend_path, scene_json, options, summary):+ """Mean radiance per light class on three scenes: the original blend, the bridge through Cycles, and the bridge through Cook.++ A pinhole camera at 256 samples; only the means are compared, so it finds which part of the scene the gap lives in."""+ scene = read_json(scene_json)+ table = {}+ for variant in BLEND_VARIANTS:+ prefix = os.path.join(OUTPUT_DIRECTORY, f"diag-blend-{variant}")+ if stage_wanted("diagnose", [prefix + ".npy"], options["force"]):+ extra = ["--pinhole", "--samples", str(DIAGNOSTIC_SAMPLES), "--seed", "1", "--variant", variant]+ run_command(blender_command(blender, blend_path, "reference", prefix, extra), f"diag-blend-{variant}", check=False)+ if os.path.exists(prefix + ".npy"):+ table.setdefault(variant, {})["blend"] = channel_means(prefix + ".npy")+ flipped_direction = [-component for component in scene["environment"]["lightDirection"]]+ subsets = {**LIGHT_SUBSETS, "sun-flipped": {**LIGHT_SUBSETS["sun-only"], "lightDirection": flipped_direction}}+ for name, environment_changes in subsets.items():+ subset_scene = {**scene, "environment": {**scene["environment"], **environment_changes}}+ subset_path = os.path.join(SCENE_DIRECTORY, f"classroom-{name}.json")+ with open(subset_path, "w", encoding="utf-8") as handle:+ json.dump(subset_scene, handle)+ cook_prefix = os.path.join(OUTPUT_DIRECTORY, f"diag-cook-{name}")+ cycles_prefix = os.path.join(OUTPUT_DIRECTORY, f"diag-cycles-{name}")+ if stage_wanted("diagnose", [cook_prefix + ".npy"], options["force"]):+ run_command(cook_command(subset_path, cook_prefix, DIAGNOSTIC_SAMPLES, 1, []), f"diag-cook-{name}", check=False)+ if stage_wanted("diagnose", [cycles_prefix + ".npy"], options["force"]):+ run_command(cycles_command(blender, subset_path, cycles_prefix, DIAGNOSTIC_SAMPLES, 1, []), f"diag-cycles-{name}", check=False)+ for label, prefix in (("cook", cook_prefix), ("cycles", cycles_prefix)):+ if os.path.exists(prefix + ".npy"):+ table.setdefault(name, {})[label] = channel_means(prefix + ".npy")+ summary["diagnose"] = table+ from PIL import Image+ import numpy+ for label, path in (("blend", "blend-pinhole"), ("cycles", "cycles-pinhole-seed1")):+ npy_path = os.path.join(OUTPUT_DIRECTORY, path + ".npy")+ if os.path.exists(npy_path):+ image = Image.fromarray(tone_mapped_image(numpy.load(npy_path))).resize((640, 360), Image.LANCZOS)+ image.save(os.path.join(OUTPUT_DIRECTORY, f"view-{label}-pinhole.jpg"), "JPEG", quality=75)+++def copy_small_outputs():+ """Copies the logs, JSON files and pictures (never the .npy dumps or the scene) into out/, the one folder a caller fetches."""+ small_directory = os.path.join(OUTPUT_DIRECTORY, "out")+ os.makedirs(small_directory, exist_ok=True)+ sources = glob.glob(os.path.join(OUTPUT_DIRECTORY, "*")) + glob.glob(os.path.join(SCENE_DIRECTORY, "classroom-*.json"))+ for source in sources:+ if os.path.isfile(source) and source.endswith((".json", ".log", ".jpg")) and os.path.getsize(source) < 3_000_000:+ shutil.copy(source, small_directory)+++def finish(summary):+ with open(os.path.join(OUTPUT_DIRECTORY, "summary.json"), "w", encoding="utf-8") as handle:+ json.dump(summary, handle, indent=2, default=str)+ copy_small_outputs()+ print("CLASSROOM_SUMMARY " + json.dumps(summary, default=str))+++if __name__ == "__main__":+ try:+ main()+ except Exception as error:+ os.makedirs(OUTPUT_DIRECTORY, exist_ok=True)+ log(f"DRIVER FAILED: {error}\n{traceback.format_exc()[-2000:]}")+ finish({"errors": {"driver": repr(error)}})+ raisediff --git a/bench/cycles-parity/run-classroom-parity.sh b/bench/cycles-parity/run-classroom-parity.shnew file mode 100644index 00000000..0496cab2--- /dev/null+++ b/bench/cycles-parity/run-classroom-parity.sh@@ -0,0 +1,12 @@+#!/usr/bin/env bash+# Runs the Classroom parity driver on the GPU machine from the repository root: build the addon, then the driver.+# Usage: bash bench/cycles-parity/run-classroom-parity.sh [driver options]+set -u+export PATH="$HOME/.local/bin:$PATH"+mkdir -p artifacts/classroom+(cd packages/render-native && node build.mjs) > artifacts/classroom/build.log 2>&1+tail -1 artifacts/classroom/build.log+if ! command -v uv > /dev/null; then+ curl -LsSf https://astral.sh/uv/install.sh | sh > artifacts/classroom/uv-install.log 2>&1+fi+uv run --no-project --with numpy --with pillow --with flip-evaluator python bench/cycles-parity/run-classroom-parity.py "$@" 2>&1 | tail -150diff --git a/bench/cycles-parity/scene-bridge.mjs b/bench/cycles-parity/scene-bridge.mjsindex 4aebeb59..3802cf52 100644--- a/bench/cycles-parity/scene-bridge.mjs+++ b/bench/cycles-parity/scene-bridge.mjs@@ -318,6 +318,7 @@ export async function reconstructTraceSceneSource(description, repositoryRootPatgeometry: decodedGeometries[partEntry.geometry],matrix: new Float32Array(partEntry.matrix),material: decodedMaterials[partEntry.material],+ ...(partEntry.rayVisibility ? { rayVisibility: partEntry.rayVisibility } : {}),}));const environmentMap = await rebuildEnvironmentMap(description.world, repositoryRootPath);const fullEnvironment = {diff --git a/bench/cycles-parity/trace-native.mjs b/bench/cycles-parity/trace-native.mjsindex c64e3461..5ddb09b8 100644--- a/bench/cycles-parity/trace-native.mjs+++ b/bench/cycles-parity/trace-native.mjs@@ -6,6 +6,7 @@ import { dirname, resolve } from 'node:path';import { createCamera } from '../../src/path-tracer.js';import * as packModule from '../../src/path-tracer-gpu-pack.js';import { buildTraceSceneWithManyLights } from './trace-scene-many-lights.mjs';+import { buildInstancedTraceSceneInBatches } from './instanced-scene-in-batches.mjs';import * as renderNative from '../../packages/render-native/index.mjs';import { writeFloat32Npy } from './npy.mjs';import { reconstructTraceSceneSource } from './scene-bridge.mjs';@@ -114,7 +115,7 @@ function parseLightSamplingOption(argumentList) {function parseTraceArguments(argumentList) {if (argumentList.length < 2 || argumentList[0].startsWith('--') || argumentList[1].startsWith('--')) {- throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration | --no-path-regeneration] [--env-compensation 0..1] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0] [--denoise none|wavelet|atrous] [--oidn-devices cpu,cuda,cpu-cli,cuda-cli] [--grey-diffuse] [--write-depth] [--f-stop 2.8 [--focus-distance m] [--aperture-blades 0|3..64] [--aperture-rotation degrees] [--sensor-width 36]]');+ throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration | --no-path-regeneration] [--env-compensation 0..1] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0] [--denoise none|wavelet|atrous] [--oidn-devices cpu,cuda,cpu-cli,cuda-cli] [--grey-diffuse] [--write-depth] [--instancing] [--f-stop 2.8 [--focus-distance m] [--aperture-blades 0|3..64] [--aperture-rotation degrees] [--sensor-width 36]]');}return {sceneJsonPath: resolve(argumentList[0]),@@ -151,6 +152,7 @@ function parseTraceArguments(argumentList) {maxSeconds: parseNumberOption(argumentList, '--max-seconds', 1800, 1),greyDiffuse: argumentList.includes('--grey-diffuse'),writeDepth: argumentList.includes('--write-depth'),+ instancing: argumentList.includes('--instancing'),lens: parseLensOptions(argumentList),};}@@ -316,7 +318,11 @@ async function runCli() {const totalStarted = performance.now();const buildStarted = performance.now();const traceSource = await reconstructTraceSceneSource(description);- const traceScene = buildTraceSceneWithManyLights(traceSource.parts, traceSource.environment);+ if (options.instancing && options.kernel !== 'cycles') {+ throw new RangeError('Option --instancing needs --kernel cycles: the legacy kernel packs flattened scenes only.');+ }+ const instancedBatches = options.instancing ? buildInstancedTraceSceneInBatches(traceSource.parts, traceSource.environment) : null;+ const traceScene = instancedBatches ? instancedBatches.scene : buildTraceSceneWithManyLights(traceSource.parts, traceSource.environment);// render-cycles.py takes the lens from the flags only, so a lens set in the scene file is dropped here to keep the two sides comparable.const { fStop: ignoredSceneFStop, ...sceneCameraWithoutLens } = traceSource.camera;const camera = createCamera({ ...sceneCameraWithoutLens, ...options.lens }, options.width, options.height);@@ -408,6 +414,9 @@ async function runCli() {denoiseNonFinitePixelsReplaced: wavelet ? wavelet.replacedPixels : 0,oidnTrial,triangleCount: nativeInput.triangleCount,+ instanceCount: nativeInput.instanceCount ?? null,+ instancing: options.instancing,+ instanceBatches: instancedBatches ? instancedBatches.uniqueTrianglesPerBatch : null,adapter: traced.adapter,backend: traced.backend,features: traced.features,diff --git a/bench/cycles-parity/trace-scene-many-lights.mjs b/bench/cycles-parity/trace-scene-many-lights.mjsindex 624473e7..ae9e1bf8 100644--- a/bench/cycles-parity/trace-scene-many-lights.mjs+++ b/bench/cycles-parity/trace-scene-many-lights.mjs@@ -26,22 +26,23 @@ function unlinkedLights(lights) {return lights.map(light => ({ ...light, bit: UNLINKED_LIGHT_BIT }));}-export function buildTraceSceneWithManyLights(parts, environment) {+// `options.instancing` keeps copies of one geometry as instances (a scene packed with buildNativeInputV2 for the cycles kernel).+export function buildTraceSceneWithManyLights(parts, environment, options = {}) {const analyticLights = listAnalyticLights(environment);if (analyticLights.length <= MAX_TRACE_LIGHTS) {- return applyCookOnlyFields(buildTraceScene(parts, environment), parts, environment);+ return applyCookOnlyFields(buildTraceScene(parts, environment, options), parts, environment);}const points = [];const spots = [];const areas = [];for (let start = 0; start < analyticLights.length; start += MAX_TRACE_LIGHTS) {const chunk = analyticLights.slice(start, start + MAX_TRACE_LIGHTS);- const chunkLights = buildTraceScene(parts, chunkEnvironment(environment, chunk)).lights;+ const chunkLights = buildTraceScene(parts, chunkEnvironment(environment, chunk), options).lights;points.push(...unlinkedLights(chunkLights.points));spots.push(...unlinkedLights(chunkLights.spots));areas.push(...unlinkedLights(chunkLights.areas));}- const traceScene = buildTraceScene(parts, { ...environment, pointLights: [], spotLights: [], areaLights: [] });+ const traceScene = buildTraceScene(parts, { ...environment, pointLights: [], spotLights: [], areaLights: [] }, options);traceScene.lights = { sun: traceScene.lights.sun, points, spots, areas };return applyCookOnlyFields(traceScene, parts, environment);}diff --git a/docs/cook-classroom-comparison.jpg b/docs/cook-classroom-comparison.jpgnew file mode 100644index 00000000..f45557feBinary files /dev/null and b/docs/cook-classroom-comparison.jpg differdiff --git a/docs/cycles-parity.md b/docs/cycles-parity.mdindex e9b55ecd..c5668333 100644--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@ -1001,6 +1001,94 @@ NODE_OPTIONS=--max-old-space-size=16384 node bench/cycles-parity/large-sequence-Not measured: sizes above 4,000,000 triangles (nothing failed at 4M, so the largest working size is not known), more than one run per cell, two sessions alive at once, and peak host memory.+## Classroom scene against Cycles, every material grey diffuse (#896, slice C1b)++The last Done-when item of #896 asks for the Blender "Classroom" demo scene (Christophe Seux, CC0, from blender.org's demo files) with every material overridden to grey diffuse to pass the image-match checks against Cycles, and a depth pass that matches Cycles on 99.9 percent of pixels. This slice is the bridge, the harness and the first full measurement. The depth gate passes. The image gates do not pass, and the cause is pinned to one thing, point lights with a radius (below). Only `bench/`, `tests/` and this guide change; the `.blend` and everything derived from it stay outside the repository.++Picture (Cook left, Cycles right, 1024 samples, depth of field on, grey diffuse): `docs/cook-classroom-comparison.jpg`.++### The bridge++[`classroom_bridge.py`](../bench/cycles-parity/classroom_bridge.py) runs inside Blender 5.3 on the opened scene, with auto-run scripts disabled (`blender -b --disable-autoexec classroom.blend --python ... -- export <dir>`). `export` writes the evaluated scene in the JSON format the other parity benches read: one geometry per mesh datablock and modifier stack (so linked copies share it), one part per instance with its world matrix, the camera, the lights, the world and one grey material (base 0.8, roughness 1, as the harness defines). `render-cycles.py` builds the Cycles side from that same JSON, so both renderers see exactly the same scene. `reference` renders the original `.blend` in Cycles with the same drops and the same override, to measure the bridge itself.++[`run-classroom-parity.py`](../bench/cycles-parity/run-classroom-parity.py) (started by `run-classroom-parity.sh`) does everything in one call: download once, export, Cook and Cycles renders, comparisons, depth, a figure and the diagnostic experiments. Small changes elsewhere in `bench/`: `trace-native.mjs --instancing` keeps shared geometry as instances (through `instanced-scene-in-batches.mjs`, below), parts may carry `rayVisibility` (read by `render-cycles.py` and by Cook's instance visibility bits), and `render-cycles.py` reads `environment.sunAngularRadius` as Cook does.++`buildTraceScene` refuses an instanced scene with more than 400,000 unique triangles, counted once per shared geometry, and the Classroom holds 427,769. The kernel has no such limit. `instanced-scene-in-batches.mjs` builds the scene in two batches that each fit and joins their instance lists, so `src/` is untouched (tests: `tests/cycles-parity-instanced-batches.test.js`, `tests/cycles-parity-instancing-option.test.js`).++### Counts `[measured]`++| | |+| --- | --- |+| Instances (parts) | 886 |+| Distinct geometries | 231 |+| Unique triangles | 427,769 (271,605 vertices) |+| Triangles counting every instance | 1,229,429 |+| Mirrored instances (negative determinant) | 26 |+| Lights | 1 sun (angular radius 0.0150 rad, strength 1), 7 point, 2 area, 0 spot |+| World | constant black (strength 0) |+| Camera | 25 mm on a 32 mm sensor, 960 x 540, vertical field of view 39.60 degrees, no roll, no shift |+| Depth of field | f/2.083 (aperture radius 6.0 mm), 6 blades, focus 7.959 m |++### Dropped or approximated, the same on both sides unless noted++- Glass: 2 objects (`glass`, `Box309.002`) are removed from both renders. As opaque grey they would seal the windows.+- Particle system: 1 halo emitter is switched off in both.+- Four objects with a transparent or alpha-cutout material render opaque under the override, in both (no object is dropped for it).+- Five spot lights exist in the file but belong to hidden objects; neither the original nor the bridge renders them.+- 22 instances evaluate to no triangles through `Object.to_mesh` and are not exported: `porte`, `porte.001`, `focus`, eight `venitianBlind*`, six `Circle.002`, four suitcase wheels (`kolesa01_k*`) and `Plane.013`. The original renders at least some of them (the exporter also lists `beamWithHole`, `ceilingWithHole`, `volumeLightMask` and `DustParticules` as not exported). This is a gap between the bridge and the original file, not between Cook and Cycles `[inferred: these objects get their shape from modifiers (lattice, hook, armature) or nodes that the evaluated-mesh read does not return]`.+- Ray visibility is exported: 13 parts hidden from shadow rays and 1 from camera rays. Without it the sun was blocked in the bridge (sun-only mean radiance 0.0001 against 0.0388 with it). Shadow catchers and holdouts (10 objects) are counted and not handled.+- Lights keep shadows on in the bridge even where the file turns them off (`exterior_fillLight`), and per-light bounce limits are not carried.+- The JSON camera's far clip is 1000 (the file has 100), because Cook ignores it; the original-file renders use 100.+- Depth of field has no anamorphic ratio (it is 1 here), so nothing was dropped for the lens.++### Gates, Cook against Cycles on the same exported scene `[measured]`++960 x 540, 1024 spp, seed 1 for both (Cycles seed 2 for the noise floor), 8 bounces, box filter, Blender 5.3.0 OptiX and Cook on one RTX 4090. Colour with the scene's depth of field on both sides; depth with the aperture closed on both sides (Cook's depth is ray distance, converted to Z by `compare_depth.py`, which assumes no lens), at 1024 samples on both (at the 64 Cycles samples of the earlier rows the silhouette pixels of this scene are noisy and the same comparison scored 99.57 percent).++| Gate | Result | Pass |+| --- | --- | --- |+| Mean ratio per channel within 2 % | 1.123 / 1.129 / 1.138 | fail |+| 8 x 8 tiles within 5 % | 2 of 64 (min 1.003, max 2.914) | fail |+| FLIP LDR against the seed floor + 0.02 | 0.183 (floor 0.115, ceiling 0.135) | fail |+| relMSE (reported) | 0.334 against a Cycles seed-to-seed floor of 0.066 | n/a |+| Depth agreement at 1 % on 99.9 % of pixels | 99.939 % (316 of 518,400 pixels disagree) | pass |+| Depth at 0.1 % / 0.5 % | 98.97 % / 99.86 % | reported |++The pinhole colour comparison gives the same numbers (1.124 / 1.129 / 1.138, 2 of 64 tiles, relMSE 0.336), so depth of field is not what fails the colour gates. The room is dark and noisy (mean radiance 0.17, a small window and a few lamps), so the Cycles noise floor itself is high.++Depth: every one of the 316 disagreeing pixels sits next to a silhouette (none in the interior of a surface; away from silhouettes the agreement is 100 percent and the 99th percentile of the relative error is 0.10 percent). They gather in the right-hand tiles of rows 1 to 4 (107, 119, 45 and 10 pixels in the last column), where the venetian blinds' thin slats are, and a handful are scattered along the floor. 311 are both-hit pixels over 1 percent, 68 over 5 and 17 over 20 percent (a slat edge against what is behind it); 2 are hit only by Cycles and 3 only by Cook. 1,637 pixels are background in both (the window openings), so the miss handling is exercised by a rendered scene for the first time.++### Why the colour gates fail (measured gap, inferred cause)++Same JSON, one light class at a time (pinhole, 256 spp, mean of the green channel; Cook over Cycles):++| Lights | Cook / Cycles |+| --- | --- |+| sun only | 1.0015 (0.03884 / 0.03878) |+| 2 area lights only | 0.9985 (0.08935 / 0.08948) |+| 7 point lights, radius as in the file (0.08 to 0.18) | 1.41 (0.0770 / 0.0545, all channels) |+| the same 7 point lights, radius 0 | 1.0023 (0.05596 / 0.05583) |+| one point light at a time | 1.09 (radius 0.08), 1.50 to 2.09 (the six lamps of radius 0.18) |++The sun and the area lights agree to 0.2 percent, and the point lights agree to 0.2 percent too once their radius is 0. With a radius, Cook is 1.5 to 2.1 times brighter than Cycles on each of the six 0.18 m lamps, which sit at 2.31 m under a ceiling fixture (inferred: inside or against geometry). Everything above comes from a single pair of renders per row, so the second decimal of the small values is noise. The suspect is how the `cycles` kernel samples and shadows a sphere light whose sphere overlaps or touches geometry (light sampling in `packages/render-native`, point lights with `radius` in `src/cycles/`, against Cycles' sphere light sampling); I did not read or change kernel code, so the function is not named. That is for an issue: "point light with radius overlapping geometry is up to 2x brighter than Cycles", with this scene or a reduced one (a 0.18 m sphere light inside an open shade) as the reproduction. With the radius set to 0 on both sides the full gates would very likely come close to passing, but that full-resolution run was not made, so it is not claimed.++### The bridge against the original file `[measured]`++The bridge is not exact. Cycles on the exported JSON has a mean radiance of 0.17 against 0.668 for Cycles on the original `.blend` with the same drops and override (ratio 0.24 to 0.27), and the depth passes of the two agree on 91.2 percent of pixels, with the disagreement in the central tiles (rows 1 to 4, columns 2 and 3: the blackboard wall). Sun-only is 0.0388 against 0.376. The likely causes are the 22 unexported instances and lights whose file settings the format cannot carry (shadows off on `exterior_fillLight`, per-light bounce limits), but the experiments to separate them were not run, so the cause is open. This does not affect the Cook against Cycles comparison above, which reads one file on both sides; it means the scene Cook was tested on is a faithful reading of the Classroom only in its camera, the 886 instances it exports, the sun and the world.++### Commands++On a machine with Blender 5.3, Node, `uv` and the built `packages/render-native` addon (a GPU):++```sh+(cd packages/render-native && node build.mjs)+bash bench/cycles-parity/run-classroom-parity.sh [--samples 1024] [--force export,cook,cycles,reference,diagnose]+```++Output goes to `artifacts/classroom/` (ignored by Git): `summary.json`, `classroom-comparison.jpg`, the logs, and in `out/` the small files. The scene is read from `~/cook-data/classroom` and downloaded from `https://download.blender.org/demo/test/classroom.zip` on the first run.++Not covered: the 22 unexported instances and the bridge gap above; the point light difference (to be filed); a full-resolution run with point-light radius 0 on both sides; 4096 samples.+## Reproducible CommandsRun from the repository root in PowerShell. Set `$env:BLENDER_BIN` if Blender 5.3 is installed outside `C:\Program Files\Blender Foundation\Blender 5.3\blender.exe`, and pass an untracked `<out-dir>` (such as `artifacts/cycles-parity`) so binary `.exr` and `.npy` files stay out of Git:diff --git a/tests/cycles-parity-instanced-batches.test.js b/tests/cycles-parity-instanced-batches.test.jsnew file mode 100644index 00000000..32fa4736--- /dev/null+++ b/tests/cycles-parity-instanced-batches.test.js@@ -0,0 +1,32 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { MAX_TRACE_TRIANGLES } from '../src/path-tracer-scene.js';+import { splitGeometriesIntoBatches } from '../bench/cycles-parity/instanced-scene-in-batches.mjs';++function geometryWithTriangles(triangleCount) {+ return { indices: new Uint32Array(triangleCount * 3) };+}++function groupsFor(entries) {+ return new Map(entries.map(([geometry, useCount]) => [geometry, Array.from({ length: useCount }, () => ({ geometry }))]));+}++test('a scene under the cap stays in one batch', () => {+ const groups = groupsFor([[geometryWithTriangles(1000), 3], [geometryWithTriangles(500), 1]]);+ assert.equal(splitGeometriesIntoBatches(groups).length, 1);+});++test('a scene over the cap splits into two batches that each fit and each hold a shared geometry', () => {+ const big = geometryWithTriangles(300000);+ const shared = geometryWithTriangles(60000);+ const single = geometryWithTriangles(67769);+ const groups = groupsFor([[big, 2], [shared, 4], [single, 1]]);+ const batches = splitGeometriesIntoBatches(groups);+ assert.equal(batches.length, 2);+ for (const batch of batches) {+ const total = batch.reduce((sum, geometry) => sum + geometry.indices.length / 3, 0);+ assert.ok(total <= MAX_TRACE_TRIANGLES);+ assert.ok(batch.some((geometry) => groups.get(geometry).length > 1));+ }+ assert.equal(batches.flat().length, 3);+});diff --git a/tests/cycles-parity-instancing-option.test.js b/tests/cycles-parity-instancing-option.test.jsnew file mode 100644index 00000000..df3d4c6e--- /dev/null+++ b/tests/cycles-parity-instancing-option.test.js@@ -0,0 +1,28 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { buildTraceSceneWithManyLights } from '../bench/cycles-parity/trace-scene-many-lights.mjs';++const SHARED_TRIANGLE = {+ positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),+ indices: new Uint32Array([0, 1, 2]),+};++function translationMatrix(x) {+ return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]);+}++function buildParts() {+ return [0, 2, 4].map((x, index) => ({ name: `copy-${index}`, geometry: SHARED_TRIANGLE, matrix: translationMatrix(x), material: { color: [0.8, 0.8, 0.8] } }));+}++const ENVIRONMENT = { keyColor: [1, 1, 1], lightDirection: [0, 1, 0], pointLights: [], spotLights: [], areaLights: [] };++test('the many-lights wrapper keeps shared geometry as instances when asked, and flattens it otherwise', () => {+ const instanced = buildTraceSceneWithManyLights(buildParts(), ENVIRONMENT, { instancing: true });+ assert.equal(instanced.instances.length, 3);+ assert.equal(new Set(instanced.instances.map((instance) => instance.geometry)).size, 1);+ const flattened = buildTraceSceneWithManyLights(buildParts(), ENVIRONMENT);+ assert.equal(flattened.instances, undefined);+ assert.equal(flattened.indices.length, 9);+});