Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

47.7 KB
Raw Blame
"""Render an exported 67js scene JSON in Blender Cycles OptiX with matched parity settings."""
import base64
import json
import math
import os
import re
import sys
import time

import bpy
import numpy
from mathutils import Matrix, Vector

sys.stdout.reconfigure(encoding="utf-8", errors="replace")

WATTS_PER_POINT_INTENSITY = 4.0 * math.pi
WATTS_PER_AREA_INTENSITY = math.pi
SUN_ANGULAR_DIAMETER = math.radians(1.0)
ENVIRONMENT_ROTATION_Z = -math.pi / 2.0
PART_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",
}

# Set by --soft-falloff. Blender 4 and later build a point or spot light with a radius as an oriented disk while Light.use_soft_falloff
# is on (the default) and as a sphere while it is off. Cook models the sphere, so the default here is off; None keeps the Blender default.
soft_falloff_setting = None
# Set by --light-mis off: lights stop being hit by BSDF rays and are sampled by next event estimation only (a diagnostic).
light_mis_enabled = True
# Set by --radiance-cap. Cook and the 67js runtime limit the texels of a sky map before they are interpolated (before-lookup, the default);
# the Blender world used to limit the interpolated value instead (after-lookup), which lets the texels beside a very bright spot add energy.
radiance_cap_before_lookup = True
# Set by --cycles-property name=value (repeatable): diagnostic overrides of scene.cycles properties, such as light_sampling_threshold=0.
cycles_property_assignments = []
Y_UP_TO_Z_UP = 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),
))
NUMPY_DTYPES = {
    "Float32Array": numpy.float32,
    "Uint32Array": numpy.uint32,
    "Uint16Array": numpy.uint16,
    "Uint8Array": numpy.uint8,
    "Uint8ClampedArray": numpy.uint8,
}
PEAK_MEMORY_PATTERN = re.compile(r"(?:Peak|Mem)[:\s]+([0-9.]+)\s*([KMGT]?)(?:i?B)?", re.IGNORECASE)


def read_flag_value(argument_list, flag_name, fallback_value):
    if flag_name not in argument_list:
        return fallback_value
    flag_index = argument_list.index(flag_name)
    if flag_index + 1 >= len(argument_list):
        raise ValueError(f"Flag {flag_name} requires a value.")
    return argument_list[flag_index + 1]


PIXEL_FILTER_TYPES = {"box": "BOX", "gaussian": "GAUSSIAN", "blackman-harris": "BLACKMAN_HARRIS"}
# Keep in step with GREY_DIFFUSE_MATERIAL in grey-diffuse-override.mjs: both renderers must shade the same thing.
GREY_DIFFUSE_ENTRY = {"color": [0.8, 0.8, 0.8], "metallic": 0.0, "roughness": 1.0, "specular": 0.0}
DEFAULT_DEPTH_SAMPLES = 64


SOFT_FALLOFF_VALUES = {"default": None, "on": True, "off": False}


def read_soft_falloff(argument_list):
    value = read_flag_value(argument_list, "--soft-falloff", "off")
    if value not in SOFT_FALLOFF_VALUES:
        raise ValueError(f"--soft-falloff must be default, on or off, got {value!r}.")
    return SOFT_FALLOFF_VALUES[value]


def read_radiance_cap_order(argument_list):
    value = read_flag_value(argument_list, "--radiance-cap", "before-lookup")
    if value not in ("before-lookup", "after-lookup"):
        raise ValueError(f"--radiance-cap must be before-lookup or after-lookup, got {value!r}.")
    return value == "before-lookup"


def parse_cli_arguments():
    if "--" not in sys.argv:
        raise ValueError("Pass script arguments after '--': <sceneJsonPath> <outputPrefix> [options].")
    argument_list = sys.argv[sys.argv.index("--") + 1:]
    if len(argument_list) < 2 or argument_list[0].startswith("--") or argument_list[1].startswith("--"):
        raise ValueError("Usage: blender -b --factory-startup --python bench/cycles-parity/render-cycles.py -- <sceneJsonPath> <outputPrefix> [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--keep-exr] [--part-ids] [--grey-diffuse] [--radiance-cap before-lookup|after-lookup] [--world-property name=value] [--soft-falloff default|on|off] [--z-depth] [--depth-samples 64] [--denoise none|oidn-gpu|oidn-cpu] [--f-stop 2.8 [--focus-distance m] [--aperture-blades 0|3..64] [--aperture-rotation degrees] [--sensor-width 36]]")
    return {
        "scene_json_path": os.path.abspath(argument_list[0]),
        "output_prefix": os.path.abspath(argument_list[1]),
        "samples": int(read_flag_value(argument_list, "--samples", "256")),
        "bounces": int(read_flag_value(argument_list, "--bounces", "8")),
        # Transparent Max Bounces on its own; absent means the same value as --bounces.
        "transparent_bounces": (
            int(read_flag_value(argument_list, "--transparent-bounces", "-1"))
            if "--transparent-bounces" in argument_list else None
        ),
        "seed": int(read_flag_value(argument_list, "--seed", "1")),
        "width": int(read_flag_value(argument_list, "--width", "960")),
        "height": int(read_flag_value(argument_list, "--height", "540")),
        "filter_type": read_flag_value(argument_list, "--filter-type", "box"),
        "filter_width": float(read_flag_value(argument_list, "--filter-width", "1.0")),
        "keep_exr": "--keep-exr" in argument_list,
        "part_ids": "--part-ids" in argument_list,
        "grey_diffuse": "--grey-diffuse" in argument_list,
        "z_depth": "--z-depth" in argument_list,
        "depth_samples": int(read_flag_value(argument_list, "--depth-samples", str(DEFAULT_DEPTH_SAMPLES))),
        "denoise": read_flag_value(argument_list, "--denoise", "none"),
        "f_stop": float(read_flag_value(argument_list, "--f-stop", "0")) if "--f-stop" in argument_list else None,
        "focus_distance": float(read_flag_value(argument_list, "--focus-distance", "0")) if "--focus-distance" in argument_list else None,
        "aperture_blades": int(read_flag_value(argument_list, "--aperture-blades", "0")),
        "aperture_rotation": float(read_flag_value(argument_list, "--aperture-rotation", "0")),
        "sensor_width": float(read_flag_value(argument_list, "--sensor-width", "36")),
        "soft_falloff": read_soft_falloff(argument_list),
        "light_mis": read_flag_value(argument_list, "--light-mis", "on") != "off",
        "radiance_cap_before_lookup": read_radiance_cap_order(argument_list),
    }


def resolve_lens_options(options, camera_entry):
    """Depth-of-field settings from --f-stop and its companions, or None for a pinhole (the default).

    Without --focus-distance the focus is the eye-to-target distance, as in createCamera.
    """
    if options["f_stop"] is None:
        stray_flags = [name for name in ("--focus-distance", "--aperture-blades", "--aperture-rotation", "--sensor-width") if name in sys.argv]
        if stray_flags:
            raise ValueError(f"Option {stray_flags[0]} needs --f-stop: pass the f-stop that turns on depth of field, such as --f-stop 2.8.")
        return None
    if options["f_stop"] <= 0:
        raise ValueError(f"--f-stop must be above 0, got {options['f_stop']}.")
    if options["aperture_blades"] != 0 and not 3 <= options["aperture_blades"] <= 64:
        raise ValueError(f"--aperture-blades must be 0 (a round aperture) or from 3 to 64, got {options['aperture_blades']}.")
    focus_distance = options["focus_distance"]
    if focus_distance is None:
        focus_distance = math.dist(camera_entry["eye"], camera_entry["target"])
    return {
        "f_stop": options["f_stop"],
        "focus_distance": focus_distance,
        "aperture_blades": options["aperture_blades"],
        "aperture_rotation": options["aperture_rotation"],
        "sensor_width": options["sensor_width"],
    }


def decode_typed_array(encoded_entry):
    if encoded_entry is None:
        return None
    raw_bytes = base64.b64decode(encoded_entry["base64"])
    dtype = NUMPY_DTYPES[encoded_entry["type"]]
    return numpy.frombuffer(raw_bytes, dtype=dtype)


def convert_position_to_blender(position):
    return (position[0], -position[2], position[1])


def set_linear_rgba_socket(socket, rgb_color):
    socket.default_value = (rgb_color[0], rgb_color[1], rgb_color[2], 1.0)


def build_blender_mesh(mesh_name, geometry_entry):
    positions = decode_typed_array(geometry_entry["positions"]).reshape(-1, 3)
    normals = decode_typed_array(geometry_entry["normals"]).reshape(-1, 3)
    triangles = decode_typed_array(geometry_entry["indices"]).reshape(-1, 3)
    degenerate_mask = (triangles[:, 0] == triangles[:, 1]) | (triangles[:, 1] == triangles[:, 2]) | (triangles[:, 0] == triangles[:, 2])
    valid_triangles = triangles[~degenerate_mask]
    mesh = bpy.data.meshes.new(mesh_name)
    mesh.from_pydata(positions.tolist(), [], valid_triangles.tolist())
    mesh.validate()
    mesh.normals_split_custom_set_from_vertices(normals.tolist())
    uv_values = decode_typed_array(geometry_entry.get("uvs"))
    if uv_values is not None:
        uv_pairs = uv_values.reshape(-1, 2)
        uv_layer = mesh.uv_layers.new(name="UVMap")
        corner_uvs = uv_pairs[valid_triangles.reshape(-1)].copy()
        corner_uvs[:, 1] = 1.0 - corner_uvs[:, 1]
        uv_layer.data.foreach_set("uv", corner_uvs.reshape(-1))
    vertex_colors = decode_typed_array(geometry_entry.get("colors"))
    if vertex_colors is not None:
        color_attribute = mesh.color_attributes.new("Col", "FLOAT_COLOR", "POINT")
        rgb_values = vertex_colors.reshape(-1, 3)
        alpha_column = numpy.ones((len(rgb_values), 1), dtype=numpy.float32)
        rgba_values = numpy.concatenate([rgb_values, alpha_column], axis=1)
        color_attribute.data.foreach_set("color", rgba_values.reshape(-1))
    mesh.update()
    return mesh


def unpack_shared_image(image_name, texture_descriptor, image_entries, built_images):
    image_identifier = (texture_descriptor["image"]["imageId"], texture_descriptor.get("colorSpace", "srgb"))
    if image_identifier in built_images:
        return built_images[image_identifier]
    source_entry = image_entries[image_identifier[0]]
    raw_pixels = decode_typed_array(source_entry["data"])
    width = source_entry["width"]
    height = source_entry["height"]
    blender_image = bpy.data.images.new(image_name, width, height, alpha=True)
    if image_identifier[1] == "linear":
        # Set before the pixels: changing the colour space of an image that holds pixels reloads it and drops them.
        blender_image.colorspace_settings.name = "Non-Color"
    flipped_pixels = raw_pixels.reshape(height, width, 4)[::-1].astype(numpy.float32) / 255.0
    blender_image.pixels.foreach_set(flipped_pixels.reshape(-1))
    blender_image.pack()
    built_images[image_identifier] = blender_image
    return blender_image


def connect_base_color_texture(material, principled_node, material_entry, has_vertex_colors, image_entries, built_images):
    nodes = material.node_tree.nodes
    links = material.node_tree.links
    texture_node = nodes.new("ShaderNodeTexImage")
    texture_node.image = unpack_shared_image(f"{material.name}-map", material_entry["map"], image_entries, built_images)
    multiply_node = nodes.new("ShaderNodeMixRGB")
    multiply_node.blend_type = "MULTIPLY"
    multiply_node.inputs[0].default_value = 1.0
    set_linear_rgba_socket(multiply_node.inputs[2], material_entry["color"])
    links.new(texture_node.outputs["Color"], multiply_node.inputs[1])
    if has_vertex_colors:
        vertex_color_node = nodes.new("ShaderNodeVertexColor")
        vertex_color_node.layer_name = "Col"
        vertex_multiply_node = nodes.new("ShaderNodeMixRGB")
        vertex_multiply_node.blend_type = "MULTIPLY"
        vertex_multiply_node.inputs[0].default_value = 1.0
        links.new(multiply_node.outputs["Color"], vertex_multiply_node.inputs[1])
        links.new(vertex_color_node.outputs["Color"], vertex_multiply_node.inputs[2])
        links.new(vertex_multiply_node.outputs["Color"], principled_node.inputs["Base Color"])
    else:
        links.new(multiply_node.outputs["Color"], principled_node.inputs["Base Color"])
    if material_entry.get("alphaMode") == "mask":
        cutoff_node = nodes.new("ShaderNodeMath")
        cutoff_node.operation = "GREATER_THAN"
        cutoff_node.inputs[1].default_value = material_entry.get("alphaCutoff", 0.5)
        links.new(texture_node.outputs["Alpha"], cutoff_node.inputs[0])
        links.new(cutoff_node.outputs[0], principled_node.inputs["Alpha"])


def connect_vertex_colors(material, principled_node, material_entry):
    nodes = material.node_tree.nodes
    links = material.node_tree.links
    vertex_color_node = nodes.new("ShaderNodeVertexColor")
    vertex_color_node.layer_name = "Col"
    multiply_node = nodes.new("ShaderNodeMixRGB")
    multiply_node.blend_type = "MULTIPLY"
    multiply_node.inputs[0].default_value = 1.0
    set_linear_rgba_socket(multiply_node.inputs[2], material_entry["color"])
    links.new(vertex_color_node.outputs["Color"], multiply_node.inputs[1])
    links.new(multiply_node.outputs["Color"], principled_node.inputs["Base Color"])


def connect_emissive_map(material, principled_node, material_entry, emission_color, image_entries, built_images):
    nodes = material.node_tree.nodes
    links = material.node_tree.links
    texture_node = nodes.new("ShaderNodeTexImage")
    texture_node.image = unpack_shared_image(f"{material.name}-emissive", material_entry["emissiveMap"], image_entries, built_images)
    multiply_node = nodes.new("ShaderNodeMixRGB")
    multiply_node.blend_type = "MULTIPLY"
    multiply_node.inputs[0].default_value = 1.0
    set_linear_rgba_socket(multiply_node.inputs[2], emission_color)
    links.new(texture_node.outputs["Color"], multiply_node.inputs[1])
    links.new(multiply_node.outputs["Color"], principled_node.inputs["Emission Color"])


def configure_anisotropy(principled_node, material_entry):
    strength = material_entry.get("anisotropy", 0.0)
    if strength <= 0.0:
        return
    alpha = material_entry.get("roughness", 0.5) ** 2
    alpha_tangent = alpha + (1.0 - alpha) * (strength ** 2)
    principled_node.inputs["Anisotropic"].default_value = min((1.0 - alpha / alpha_tangent) / 0.9, 1.0)
    principled_node.inputs["Roughness"].default_value = (alpha * alpha_tangent) ** 0.25
    principled_node.inputs["Anisotropic Rotation"].default_value = material_entry.get("anisotropyRotation", 0.0) / (2.0 * math.pi)
    node_tree = principled_node.id_data
    tangent_node = node_tree.nodes.new("ShaderNodeTangent")
    tangent_node.direction_type = "UV_MAP"
    tangent_node.uv_map = "UVMap"
    node_tree.links.new(tangent_node.outputs["Tangent"], principled_node.inputs["Tangent"])


def configure_thin_film(principled_node, material_entry):
    if material_entry.get("iridescence", 0.0) <= 0.0:
        return
    principled_node.inputs["Thin Film Thickness"].default_value = material_entry.get("iridescenceThickness", 400.0)
    principled_node.inputs["Thin Film IOR"].default_value = material_entry.get("iridescenceIor", 1.3)


def configure_subsurface(principled_node, material_entry):
    subsurface_block = material_entry.get("subsurface")
    if not subsurface_block or subsurface_block.get("weight", 0.0) <= 0.0:
        return
    principled_node.subsurface_method = "RANDOM_WALK"
    principled_node.inputs["Subsurface Weight"].default_value = subsurface_block["weight"]
    principled_node.inputs["Subsurface Radius"].default_value = subsurface_block.get("radius", [1.0, 0.2, 0.1])
    principled_node.inputs["Subsurface Scale"].default_value = subsurface_block.get("scale", 0.05)


def configure_principled_layers(material, principled_node, material_entry):
    principled_node.inputs["Coat Weight"].default_value = material_entry.get("clearcoat", 0.0)
    principled_node.inputs["Coat Roughness"].default_value = material_entry.get("clearcoatRoughness", 0.0)
    default_transmission = principled_node.inputs["Transmission Weight"].default_value
    principled_node.inputs["Transmission Weight"].default_value = material_entry.get("transmission", default_transmission)
    default_ior = principled_node.inputs["IOR"].default_value
    principled_node.inputs["IOR"].default_value = material_entry.get("ior", default_ior)
    sheen_color = material_entry.get("sheenColor", [0.0, 0.0, 0.0])
    if any(sheen_color):
        principled_node.inputs["Sheen Weight"].default_value = 1.0
        set_linear_rgba_socket(principled_node.inputs["Sheen Tint"], sheen_color)
        principled_node.inputs["Sheen Roughness"].default_value = material_entry.get("sheenRoughness", 0.0)
    principled_node.inputs["Specular IOR Level"].default_value = 0.5 * material_entry.get("specular", 1.0)
    set_linear_rgba_socket(principled_node.inputs["Specular Tint"], material_entry.get("specularColor", [1.0, 1.0, 1.0]))
    configure_anisotropy(principled_node, material_entry)
    configure_thin_film(principled_node, material_entry)
    configure_subsurface(principled_node, material_entry)
    attenuation_distance = material_entry.get("attenuationDistance")
    if attenuation_distance:
        absorption_node = material.node_tree.nodes.new("ShaderNodeVolumeAbsorption")
        attenuation_color = material_entry.get("attenuationColor", [1.0, 1.0, 1.0])
        set_linear_rgba_socket(absorption_node.inputs["Color"], attenuation_color)
        mean_log_color = sum(math.log(max(channel, 0.001)) for channel in attenuation_color) / 3.0
        absorption_node.inputs["Density"].default_value = -mean_log_color / attenuation_distance
        output_node = material.node_tree.nodes["Material Output"]
        material.node_tree.links.new(absorption_node.outputs["Volume"], output_node.inputs["Volume"])


def build_blender_material(material_name, material_entry, has_vertex_colors, image_entries, built_images):
    material = bpy.data.materials.new(material_name)
    principled_node = material.node_tree.nodes["Principled BSDF"]
    set_linear_rgba_socket(principled_node.inputs["Base Color"], material_entry["color"])
    principled_node.inputs["Metallic"].default_value = material_entry.get("metallic", 0.0)
    principled_node.inputs["Roughness"].default_value = material_entry.get("roughness", 0.5)
    if material_entry.get("tag") == "liquid":
        principled_node.inputs["Transmission Weight"].default_value = 1.0
        principled_node.inputs["IOR"].default_value = material_entry["liquid"]["ior"]
    configure_principled_layers(material, principled_node, material_entry)
    if material_entry.get("alphaMode") == "blend" and 0.0 <= material_entry.get("opacity", 1.0) < 1.0:
        principled_node.inputs["Alpha"].default_value = material_entry["opacity"]
    if material_entry.get("emission", 0.0) > 0.0:
        emission_color = material_entry.get("emissiveColor", material_entry["color"])
        set_linear_rgba_socket(principled_node.inputs["Emission Color"], emission_color)
        principled_node.inputs["Emission Strength"].default_value = material_entry["emission"]
        if "emissiveMap" in material_entry:
            connect_emissive_map(material, principled_node, material_entry, emission_color, image_entries, built_images)
    if "map" in material_entry:
        connect_base_color_texture(material, principled_node, material_entry, has_vertex_colors, image_entries, built_images)
    elif has_vertex_colors:
        connect_vertex_colors(material, principled_node, material_entry)
    return material


def build_scene_objects(scene, description):
    built_meshes = {}
    built_materials = {}
    built_images = {}
    image_entries = description.get("images", [])
    for part_entry in description["parts"]:
        geometry_index = part_entry["geometry"]
        geometry_entry = description["geometries"][geometry_index]
        has_vertex_colors = geometry_entry.get("colors") is not None
        if geometry_index not in built_meshes:
            mesh = build_blender_mesh(f"geometry-{geometry_index}", geometry_entry)
            mesh.materials.append(None)
            built_meshes[geometry_index] = mesh
        material_key = (part_entry["material"], has_vertex_colors)
        if material_key not in built_materials:
            material_entry = description["materials"][part_entry["material"]]
            material_name = f"material-{part_entry['material']}"
            built_materials[material_key] = build_blender_material(material_name, material_entry, has_vertex_colors, image_entries, built_images)
        mesh_object = bpy.data.objects.new(part_entry["name"], built_meshes[geometry_index])
        mesh_object.material_slots[0].link = "OBJECT"
        mesh_object.material_slots[0].material = built_materials[material_key]
        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)


def limit_image_radiance(image, radiance_limit):
    channel_count = image.channels
    pixels = numpy.empty(image.size[0] * image.size[1] * channel_count, dtype=numpy.float32)
    image.pixels.foreach_get(pixels)
    colors = pixels.reshape(-1, channel_count)
    colors[:, :3] = numpy.minimum(colors[:, :3], radiance_limit)
    image.pixels.foreach_set(colors.reshape(-1))
    image.update()


def build_world_shader(scene, world_description, repository_root):
    world = bpy.data.worlds.new("World")
    scene.world = world
    nodes = world.node_tree.nodes
    links = world.node_tree.links
    background_node = nodes["Background"]
    if world_description["type"] == "constant":
        constant_value = world_description["value"]
        background_node.inputs[0].default_value = (constant_value, constant_value, constant_value, 1.0)
        background_node.inputs[1].default_value = 1.0
        return
    if world_description["type"] == "hdri":
        coordinate_node = nodes.new("ShaderNodeTexCoord")
        mapping_node = nodes.new("ShaderNodeMapping")
        mapping_node.inputs["Rotation"].default_value = (0.0, 0.0, ENVIRONMENT_ROTATION_Z)
        environment_node = nodes.new("ShaderNodeTexEnvironment")
        environment_node.image = bpy.data.images.load(os.path.join(repository_root, world_description["file"]))
        if radiance_cap_before_lookup:
            limit_image_radiance(environment_node.image, world_description["radianceLimit"])
        links.new(coordinate_node.outputs["Generated"], mapping_node.inputs["Vector"])
        links.new(mapping_node.outputs["Vector"], environment_node.inputs["Vector"])
        cap_node = nodes.new("ShaderNodeVectorMath")
        cap_node.operation = "MINIMUM"
        radiance_limit = world_description["radianceLimit"]
        cap_node.inputs[1].default_value = (radiance_limit, radiance_limit, radiance_limit)
        links.new(environment_node.outputs["Color"], cap_node.inputs[0])
        links.new(cap_node.outputs["Vector"], background_node.inputs[0])
        background_node.inputs[1].default_value = world_description["intensity"]
        return
    raise ValueError(f"Unsupported world description type '{world_description['type']}'.")


def attach_light_receivers(light_object, receiver_names):
    if receiver_names is None:
        return
    receiver_collection = bpy.data.collections.new(f"{light_object.name}-receivers")
    for object_name in receiver_names:
        receiver_collection.objects.link(bpy.data.objects[object_name])
    light_object.light_linking.receiver_collection = receiver_collection


def apply_soft_falloff_setting(light_data):
    if soft_falloff_setting is not None:
        light_data.use_soft_falloff = soft_falloff_setting
    if not light_mis_enabled:
        light_data.cycles.use_multiple_importance_sampling = False


def add_spot_light(scene, light_index, spot_entry):
    light_data = bpy.data.lights.new(f"Spot-{light_index}", "SPOT")
    light_data.energy = spot_entry["intensity"] * WATTS_PER_POINT_INTENSITY
    light_data.color = spot_entry["color"]
    light_data.shadow_soft_size = spot_entry["radius"]
    apply_soft_falloff_setting(light_data)
    light_data.spot_size = 2.0 * spot_entry["angle"]
    light_data.spot_blend = spot_entry["penumbra"]
    spot_object = bpy.data.objects.new(f"Spot-{light_index}", light_data)
    spot_object.location = convert_position_to_blender(spot_entry["position"])
    spot_object.rotation_mode = "QUATERNION"
    aim_direction = Vector(convert_position_to_blender(spot_entry["direction"])).normalized()
    spot_object.rotation_quaternion = aim_direction.to_track_quat("-Z", "Y")
    scene.collection.objects.link(spot_object)
    attach_light_receivers(spot_object, spot_entry.get("affects"))


def add_area_light(scene, light_index, area_entry):
    light_data = bpy.data.lights.new(f"Area-{light_index}", "AREA")
    light_data.energy = area_entry["intensity"] * WATTS_PER_AREA_INTENSITY
    light_data.color = area_entry["color"]
    shape_name = area_entry.get("shape", "rectangle")
    light_data.shape = {"rectangle": "RECTANGLE", "disk": "DISK", "ellipse": "ELLIPSE"}[shape_name]
    light_data.size = area_entry["width"]
    if shape_name != "disk":
        light_data.size_y = area_entry["height"]
    if "spread" in area_entry:
        light_data.spread = area_entry["spread"]
    area_object = bpy.data.objects.new(f"Area-{light_index}", light_data)
    area_object.location = convert_position_to_blender(area_entry["position"])
    normal_vector = Vector(convert_position_to_blender(area_entry["direction"])).normalized()
    up_vector = Vector(convert_position_to_blender(area_entry.get("up", [0.0, 1.0, 0.0]))).normalized()
    width_axis = up_vector.cross(normal_vector)
    if width_axis.length < 1e-3:
        width_axis = Vector((1.0, 0.0, 0.0))
    width_axis.normalize()
    height_axis = width_axis.cross(normal_vector)
    rotation_matrix = Matrix((width_axis, height_axis, -normal_vector)).transposed()
    area_object.rotation_mode = "QUATERNION"
    area_object.rotation_quaternion = rotation_matrix.to_quaternion()
    scene.collection.objects.link(area_object)
    attach_light_receivers(area_object, area_entry.get("affects"))


def build_scene_lights(scene, environment_entry):
    key_color = environment_entry["keyColor"]
    if max(key_color) > 0.0:
        sun_strength = max(key_color)
        sun_data = bpy.data.lights.new("Sun", "SUN")
        sun_data.energy = sun_strength
        sun_data.color = [channel / sun_strength for channel in key_color]
        # 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_radius
        sun_object = bpy.data.objects.new("Sun", sun_data)
        toward_light = Vector(convert_position_to_blender(environment_entry["lightDirection"])).normalized()
        sun_object.rotation_mode = "QUATERNION"
        sun_object.rotation_quaternion = toward_light.to_track_quat("Z", "Y")
        scene.collection.objects.link(sun_object)
        attach_light_receivers(sun_object, environment_entry.get("keyAffects"))
    for light_index, point_entry in enumerate(environment_entry.get("pointLights", [])):
        point_data = bpy.data.lights.new(f"Point-{light_index}", "POINT")
        point_data.energy = point_entry["intensity"] * WATTS_PER_POINT_INTENSITY
        point_data.color = point_entry["color"]
        point_data.shadow_soft_size = point_entry["radius"]
        apply_soft_falloff_setting(point_data)
        point_object = bpy.data.objects.new(f"Point-{light_index}", point_data)
        point_object.location = convert_position_to_blender(point_entry["position"])
        scene.collection.objects.link(point_object)
        attach_light_receivers(point_object, point_entry.get("affects"))
    for light_index, spot_entry in enumerate(environment_entry.get("spotLights", [])):
        add_spot_light(scene, light_index, spot_entry)
    for light_index, area_entry in enumerate(environment_entry.get("areaLights", [])):
        add_area_light(scene, light_index, area_entry)


def configure_depth_of_field(camera_data, lens_options, aspect):
    """Thin-lens depth of field, matching createCamera in src/path-tracer.js (the same flags go to trace-native.mjs).

    The sensor is sensor-width / aspect tall, so the focal length Cycles derives from the vertical field of view is the one
    the native side computes; the aperture radius is then focal length / (2 * f-stop) in metres.
    """
    camera_data.sensor_height = lens_options["sensor_width"] / aspect
    camera_data.dof.use_dof = True
    camera_data.dof.aperture_fstop = lens_options["f_stop"]
    camera_data.dof.focus_distance = lens_options["focus_distance"]
    if lens_options["aperture_blades"] > 0:
        camera_data.dof.aperture_blades = lens_options["aperture_blades"]
        camera_data.dof.aperture_rotation = math.radians(lens_options["aperture_rotation"])


def build_camera_object(scene, camera_entry, lens_options=None, aspect=16.0 / 9.0):
    camera_data = bpy.data.cameras.new("Camera")
    camera_data.sensor_fit = "VERTICAL"
    if lens_options is not None:
        configure_depth_of_field(camera_data, lens_options, aspect)
    camera_data.angle_y = math.radians(camera_entry["fov"])
    camera_data.clip_start = camera_entry["near"]
    camera_data.clip_end = camera_entry["far"]
    camera_object = bpy.data.objects.new("Camera", camera_data)
    eye_vector = Vector(convert_position_to_blender(camera_entry["eye"]))
    target_vector = Vector(convert_position_to_blender(camera_entry["target"]))
    camera_object.location = eye_vector
    camera_object.rotation_mode = "QUATERNION"
    camera_object.rotation_quaternion = (target_vector - eye_vector).to_track_quat("-Z", "Y")
    scene.collection.objects.link(camera_object)
    scene.camera = camera_object


def configure_linear_exr_output(scene, width, height):
    scene.render.resolution_x = width
    scene.render.resolution_y = height
    scene.render.resolution_percentage = 100
    scene.render.image_settings.file_format = "OPEN_EXR"
    scene.render.image_settings.color_depth = "32"
    scene.render.image_settings.color_mode = "RGB"
    scene.render.image_settings.exr_codec = "ZIP"
    scene.view_settings.view_transform = "Raw"
    scene.view_settings.look = "None"


def configure_cycles_denoising(scene, mode):
    """Off by default. "oidn-gpu" and "oidn-cpu" run Cycles' own Open Image Denoise with albedo and normal passes.

    Blender's default denoiser for final renders is Open Image Denoise (the other choice is OptiX), with the
    albedo and normal passes, the accurate prefilter and, when a GPU renders, GPU denoising. This sets those
    values explicitly so the comparison does not depend on a default.
    """
    if mode == "none":
        scene.cycles.use_denoising = False
        return
    if mode not in ("oidn-gpu", "oidn-cpu"):
        raise ValueError(f"--denoise must be none, oidn-gpu or oidn-cpu, got {mode!r}.")
    scene.cycles.use_denoising = True
    scene.cycles.denoiser = "OPENIMAGEDENOISE"
    scene.cycles.denoising_input_passes = "RGB_ALBEDO_NORMAL"
    scene.cycles.denoising_prefilter = "ACCURATE"
    scene.cycles.denoising_use_gpu = mode == "oidn-gpu"


def configure_cycles_parity(scene, options):
    scene.render.engine = "CYCLES"
    preferences = bpy.context.preferences.addons["cycles"].preferences
    preferences.compute_device_type = "OPTIX"
    preferences.get_devices()
    used_devices = []
    for device in preferences.devices:
        device.use = device.type == "OPTIX"
        if device.use:
            used_devices.append(device.name)
    if not used_devices:
        raise RuntimeError("No OptiX GPU device was found in Blender Cycles preferences.")
    scene.cycles.device = "GPU"
    scene.cycles.samples = options["samples"]
    scene.cycles.seed = options["seed"]
    configure_cycles_denoising(scene, options["denoise"])
    scene.cycles.use_adaptive_sampling = False
    scene.cycles.pixel_filter_type = PIXEL_FILTER_TYPES[options["filter_type"]]
    scene.cycles.filter_width = options["filter_width"]
    scene.cycles.sample_clamp_direct = 0.0
    scene.cycles.sample_clamp_indirect = 0.0
    scene.cycles.caustics_reflective = True
    scene.cycles.caustics_refractive = True
    bounces = options["bounces"]
    scene.cycles.max_bounces = bounces
    scene.cycles.diffuse_bounces = bounces
    scene.cycles.glossy_bounces = bounces
    scene.cycles.transmission_bounces = bounces
    scene.cycles.volume_bounces = bounces
    transparent_bounces = options["transparent_bounces"]
    scene.cycles.transparent_max_bounces = bounces if transparent_bounces is None else transparent_bounces
    for property_assignment in cycles_property_assignments:
        apply_cycles_property(scene, property_assignment)
    return used_devices


# One --cycles-property name=value, applied after every setting above so that the override is what renders.
def apply_cycles_property(scene, property_assignment):
    if "=" not in property_assignment:
        raise ValueError(f"--cycles-property takes name=value, got {property_assignment!r}.")
    property_name, property_text = property_assignment.split("=", 1)
    if not hasattr(scene.cycles, property_name):
        raise ValueError(f"--cycles-property names a scene.cycles property, and {property_name!r} is not one.")
    current_value = getattr(scene.cycles, property_name)
    try:
        property_value = json.loads(property_text)
    except json.JSONDecodeError:
        raise ValueError(f"--cycles-property {property_name} takes a JSON value such as 0, 0.5, true or \"NAME\", got {property_text!r}.")
    if isinstance(current_value, bool) != isinstance(property_value, bool):
        raise ValueError(f"--cycles-property {property_name} is {'a boolean' if isinstance(current_value, bool) else 'not a boolean'}, got {property_text!r}.")
    if isinstance(current_value, int) and not isinstance(property_value, int):
        raise ValueError(f"--cycles-property {property_name} is a whole number, got {property_text!r}.")
    if isinstance(current_value, str) != isinstance(property_value, str):
        raise ValueError(f"--cycles-property {property_name} is {'a name in quotes' if isinstance(current_value, str) else 'a number'}, got {property_text!r}.")
    setattr(scene.cycles, property_name, type(current_value)(property_value))


# One --world-property name=value (a diagnostic): sets a property of the world's Cycles settings, such as sampling_method="NONE"
# (the sky is then found by BSDF sampling only) or sample_map_resolution=4096. Blender versions keep these on world.cycles or on world.
def apply_world_property(world, property_assignment):
    if "=" not in property_assignment:
        raise ValueError(f"--world-property takes name=value, got {property_assignment!r}.")
    property_name, property_text = property_assignment.split("=", 1)
    try:
        property_value = json.loads(property_text)
    except json.JSONDecodeError:
        raise ValueError(f"--world-property {property_name} takes a JSON value such as 0, 0.5, true or \"NAME\", got {property_text!r}.")
    for owner in (world.cycles, world):
        if hasattr(owner, property_name):
            setattr(owner, property_name, property_value)
            print("WORLD_PROPERTY " + json.dumps({"name": property_name, "value": property_value, "readBack": str(getattr(owner, property_name))}))
            return
    sampling_names = [name for name in dir(world.cycles) + dir(world) if "sampl" in name or "resolution" in name]
    raise ValueError(f"--world-property {property_name!r} is on neither world.cycles nor world; names that mention sampling: {sampling_names}")


def parse_megabytes_from_stats(stats_text):
    matches = PEAK_MEMORY_PATTERN.findall(stats_text)
    if not matches:
        return None
    scale_by_unit = {"K": 1.0 / 1024.0, "M": 1.0, "": 1.0, "G": 1024.0, "T": 1024.0 * 1024.0}
    values = [float(number_text) * scale_by_unit.get(unit_text.upper(), 1.0) for number_text, unit_text in matches]
    return max(values)


def load_exr_into_npy(exr_path, npy_path, width, height, keep_exr):
    loaded_image = bpy.data.images.load(exr_path)
    rgba_pixels = numpy.empty(width * height * 4, dtype=numpy.float32)
    loaded_image.pixels.foreach_get(rgba_pixels)
    linear_rgb = rgba_pixels.reshape(height, width, 4)[::-1, :, :3].copy()
    numpy.save(npy_path, linear_rgb)
    bpy.data.images.remove(loaded_image)
    if not keep_exr:
        os.remove(exr_path)


def render_part_identifier_map(scene, output_prefix, width, height):
    mesh_objects = sorted([item for item in scene.objects if item.type == "MESH"], key=lambda item: item.name)
    part_names = [item.name for item in mesh_objects]
    for part_index, mesh_object in enumerate(mesh_objects, start=1):
        part_material = bpy.data.materials.new(f"part-id-{part_index}")
        part_material.diffuse_color = (part_index / PART_ID_STEPS, 0.0, 0.0, 1.0)
        mesh_object.material_slots[0].material = part_material
    scene.render.engine = "BLENDER_WORKBENCH"
    scene.display.shading.light = "FLAT"
    scene.display.shading.color_type = "MATERIAL"
    scene.display.render_aa = "OFF"
    scene.view_settings.view_transform = "Raw"
    scene.world.color = (0.0, 0.0, 0.0)
    temporary_exr = f"{output_prefix}-part-levels.exr"
    temporary_npy = f"{output_prefix}-part-levels.npy"
    scene.render.filepath = temporary_exr
    bpy.ops.render.render(write_still=True)
    load_exr_into_npy(temporary_exr, temporary_npy, width, height, False)
    red_levels = numpy.load(temporary_npy)[:, :, 0]
    os.remove(temporary_npy)
    part_indices = numpy.rint(red_levels * PART_ID_STEPS).astype(numpy.int16)
    numpy.save(f"{output_prefix}-parts.npy", part_indices)
    with open(f"{output_prefix}-parts.json", "w", encoding="utf-8") as handle:
        json.dump(part_names, handle, indent=2)
    print("PART_IDS " + json.dumps({"parts": part_names, "outputPrefix": output_prefix}))


def apply_grey_diffuse_override(scene):
    """Shades every object with one grey diffuse material, as the view layer's material override does."""
    grey_material = build_blender_material("grey-diffuse-override", GREY_DIFFUSE_ENTRY, False, [], {})
    scene.view_layers[0].material_override = grey_material


def build_camera_z_depth_material():
    """An emission material whose colour is the camera Z depth: the distance along the view axis, not along the ray."""
    material = bpy.data.materials.new("camera-z-depth")
    node_tree = material.node_tree
    node_tree.nodes.clear()
    camera_data_node = node_tree.nodes.new("ShaderNodeCameraData")
    emission_node = node_tree.nodes.new("ShaderNodeEmission")
    emission_node.inputs["Strength"].default_value = 1.0
    output_node = node_tree.nodes.new("ShaderNodeOutputMaterial")
    node_tree.links.new(camera_data_node.outputs["View Z Depth"], emission_node.inputs["Color"])
    node_tree.links.new(emission_node.outputs["Emission"], output_node.inputs["Surface"])
    return material


def render_camera_z_depth(scene, output_prefix, width, height, depth_samples):
    """Renders the camera Z depth through Cycles into <prefix>-depth.npy (rows from the top, 0 where nothing is hit).

    A real Z pass needs a multilayer EXR or compositor nodes; the Camera Data node's View Z Depth is the same
    quantity (Cycles' pass is camera_z_depth too) and goes through the single-layer path used for the colour image.
    The world is switched off so a miss reads 0, which is also what Cook writes.
    """
    scene.view_layers[0].material_override = build_camera_z_depth_material()
    scene.world.node_tree.nodes["Background"].inputs[1].default_value = 0.0
    scene.cycles.samples = depth_samples
    depth_exr_path = f"{output_prefix}-depth.exr"
    depth_npy_path = f"{output_prefix}-depth.npy"
    scene.render.filepath = depth_exr_path
    bpy.ops.render.render(write_still=True)
    load_exr_into_npy(depth_exr_path, depth_npy_path, width, height, False)
    z_depth = numpy.load(depth_npy_path)[:, :, 0].copy()
    numpy.save(depth_npy_path, z_depth)
    return depth_npy_path


def execute_timed_cycles_render(scene, exr_path):
    scene.render.filepath = exr_path
    stats_events = []
    render_started = time.perf_counter()

    def record_stats(*callback_arguments):
        elapsed = time.perf_counter() - render_started
        joined_text = " ".join(str(item) for item in callback_arguments if item is not None)
        stats_events.append((elapsed, joined_text))

    bpy.app.handlers.render_stats.append(record_stats)
    try:
        bpy.ops.render.render(write_still=True)
    finally:
        bpy.app.handlers.render_stats.remove(record_stats)
    render_call_seconds = time.perf_counter() - render_started
    first_sample_seconds = None
    last_sample_seconds = None
    peak_stats_megabytes = 0.0
    for event_seconds, stats_text in stats_events:
        parsed_peak = parse_megabytes_from_stats(stats_text)
        if parsed_peak is not None:
            peak_stats_megabytes = max(peak_stats_megabytes, parsed_peak)
        if "Rendering " in stats_text or "Sample " in stats_text:
            if first_sample_seconds is None:
                first_sample_seconds = event_seconds
            last_sample_seconds = event_seconds
    if first_sample_seconds is None:
        cycles_sync_seconds = render_call_seconds
        sampling_seconds = 0.0
    else:
        cycles_sync_seconds = first_sample_seconds
        end_seconds = last_sample_seconds if last_sample_seconds is not None and last_sample_seconds > first_sample_seconds else render_call_seconds
        sampling_seconds = max(0.0, end_seconds - first_sample_seconds)
    return {
        "render_call_seconds": render_call_seconds,
        "cycles_sync_seconds": cycles_sync_seconds,
        "sampling_seconds": sampling_seconds,
        "after_last_sample_seconds": max(0.0, render_call_seconds - (last_sample_seconds or render_call_seconds)),
        "peak_stats_megabytes": peak_stats_megabytes,
        "stats_event_count": len(stats_events),
        "last_stats_text": stats_events[-1][1] if stats_events else "",
    }


def lower_process_priority():
    if os.name != "nt":
        return
    import ctypes
    below_normal_priority_class = 0x00004000
    process_handle = ctypes.windll.kernel32.GetCurrentProcess()
    ctypes.windll.kernel32.SetPriorityClass(process_handle, below_normal_priority_class)


def main():
    lower_process_priority()
    options = parse_cli_arguments()
    os.makedirs(os.path.dirname(options["output_prefix"]), exist_ok=True)
    with open(options["scene_json_path"], encoding="utf-8") as handle:
        description = json.load(handle)
    repository_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
    build_started = time.perf_counter()
    bpy.ops.wm.read_factory_settings(use_empty=True)
    scene = bpy.context.scene
    global soft_falloff_setting
    soft_falloff_setting = options["soft_falloff"]
    global light_mis_enabled
    light_mis_enabled = options["light_mis"]
    global radiance_cap_before_lookup
    radiance_cap_before_lookup = options["radiance_cap_before_lookup"]
    global cycles_property_assignments
    cycles_property_assignments = []
    for index, token in enumerate(sys.argv):
        if token != "--cycles-property":
            continue
        if index + 1 >= len(sys.argv):
            raise ValueError("--cycles-property takes name=value after it.")
        cycles_property_assignments.append(sys.argv[index + 1])
    build_scene_objects(scene, description)
    build_world_shader(scene, description["world"], repository_root)
    for index, token in enumerate(sys.argv):
        if token != "--world-property":
            continue
        if index + 1 >= len(sys.argv):
            raise ValueError("--world-property takes name=value after it.")
        apply_world_property(scene.world, sys.argv[index + 1])
    build_scene_lights(scene, description["environment"])
    lens_options = resolve_lens_options(options, description["camera"])
    build_camera_object(scene, description["camera"], lens_options, options["width"] / options["height"])
    configure_linear_exr_output(scene, options["width"], options["height"])
    if options["part_ids"]:
        render_part_identifier_map(scene, options["output_prefix"], options["width"], options["height"])
        return
    used_devices = configure_cycles_parity(scene, options)
    if options["grey_diffuse"]:
        apply_grey_diffuse_override(scene)
    scene_build_seconds = time.perf_counter() - build_started
    exr_path = f"{options['output_prefix']}.exr"
    npy_path = f"{options['output_prefix']}.npy"
    timing = execute_timed_cycles_render(scene, exr_path)
    load_exr_into_npy(exr_path, npy_path, options["width"], options["height"], options["keep_exr"])
    setup_seconds = scene_build_seconds + timing["cycles_sync_seconds"]
    total_trace_seconds = scene_build_seconds + timing["render_call_seconds"]
    report_samples = scene.cycles.samples
    depth_npy_path = None
    depth_error = None
    if options["z_depth"]:
        try:
            depth_npy_path = render_camera_z_depth(scene, options["output_prefix"], options["width"], options["height"], options["depth_samples"])
        except Exception as error:  # the colour image is already on disk; keep its report even when the depth pass fails
            depth_error = repr(error)
            print("DEPTH_PASS_FAILED " + depth_error)
    report = {
        "greyDiffuse": options["grey_diffuse"],
        "thinLens": None if lens_options is None else {
            **lens_options,
            "blenderLensMillimetres": scene.camera.data.lens,
            "blenderApertureRadius": scene.camera.data.lens / 1000.0 / (2.0 * lens_options["f_stop"]),
        },
        "depthNpyPath": depth_npy_path,
        "depthError": depth_error,
        "depthSamples": options["depth_samples"] if options["z_depth"] else None,
        "engine": "cycles-optix",
        "blenderVersion": bpy.app.version_string,
        "devices": used_devices,
        "sceneId": description["id"],
        "npyPath": npy_path,
        "exrPath": exr_path if options["keep_exr"] else None,
        "width": options["width"],
        "height": options["height"],
        "samples": report_samples,
        "seed": scene.cycles.seed,
        "bounces": scene.cycles.max_bounces,
        "diffuseBounces": scene.cycles.diffuse_bounces,
        "glossyBounces": scene.cycles.glossy_bounces,
        "transmissionBounces": scene.cycles.transmission_bounces,
        "volumeBounces": scene.cycles.volume_bounces,
        "transparentMaxBounces": scene.cycles.transparent_max_bounces,
        "useDenoising": scene.cycles.use_denoising,
        "useAdaptiveSampling": scene.cycles.use_adaptive_sampling,
        "pixelFilterType": scene.cycles.pixel_filter_type,
        "filterWidth": scene.cycles.filter_width,
        "sampleClampDirect": scene.cycles.sample_clamp_direct,
        "sampleClampIndirect": scene.cycles.sample_clamp_indirect,
        "causticsReflective": scene.cycles.caustics_reflective,
        "causticsRefractive": scene.cycles.caustics_refractive,
        "useLightTree": getattr(scene.cycles, "use_light_tree", None),
        "viewTransform": scene.view_settings.view_transform,
        "look": scene.view_settings.look,
        "sceneBuildSeconds": round(scene_build_seconds, 6),
        "cyclesSyncSeconds": round(timing["cycles_sync_seconds"], 6),
        "setupSeconds": round(setup_seconds, 6),
        "samplingSeconds": round(timing["sampling_seconds"], 6),
        "secondsAfterLastSample": round(timing["after_last_sample_seconds"], 6),
        "denoiseMode": options["denoise"],
        "denoiser": scene.cycles.denoiser if scene.cycles.use_denoising else None,
        "renderCallSeconds": round(timing["render_call_seconds"], 6),
        "totalTraceSeconds": round(total_trace_seconds, 6),
        "cyclesPeakMemoryMegabytes": round(timing["peak_stats_megabytes"], 2),
        "statsEventCount": timing["stats_event_count"],
        "lastStatsText": timing["last_stats_text"],
    }
    with open(f"{options['output_prefix']}.json", "w", encoding="utf-8") as handle:
        json.dump(report, handle, indent=2)
    print("CYCLES_TRACE " + json.dumps(report))


if __name__ == "__main__":
    main()