@funpixel/tools 0.0.0-stage → 0.1.1

package/bench/handlers/scene.py

@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Scene primitives every handler shares.
+
+Importing, bounds and argument clamping live here rather than in each verb
+because the alternative is four handlers that drift: one sniffs formats
+differently, one forgets to reset the scene, one clamps a size and one does not.
+Verb-specific logic stays in the verb; anything two verbs both need belongs
+here.
+"""
+import json
+import os
+import struct
+
+import bpy
+from mathutils import Vector
+
+# Render engines in the order we want them. The name changes with Blender: 4.2-4.5
+# call EEVEE `BLENDER_EEVEE_NEXT` (and register nothing else headless on 4.5.3, see
+# render.py), 5.x calls it `BLENDER_EEVEE` again and has no `_NEXT`. A hard-coded
+# name broke `funtools model --local` on Blender 5; the engine is picked from what
+# this bpy offers instead. Workbench and Cycles are the last resorts.
+RENDER_ENGINES = ("BLENDER_EEVEE_NEXT", "BLENDER_EEVEE", "BLENDER_WORKBENCH", "CYCLES")
+
+
+def render_engine():
+    """The first of RENDER_ENGINES this Blender registers."""
+    offered = {i.identifier for i in bpy.types.RenderSettings.bl_rna.properties["engine"].enum_items}
+    for name in RENDER_ENGINES:
+        if name in offered:
+            return name
+    raise RuntimeError(f"no known render engine in this Blender (it offers: {', '.join(sorted(offered))})")
+
+
+# Extension -> importer. The Rust side already constrained `format` to this set
+# (or to "" for sniffing), so this table never sees an arbitrary string.
+#
+# `blend` OPENS rather than imports, because it IS a scene rather than an
+# interchange file. It earns its place for one reason, measured repeatedly this
+# session: **the interchange formats normalise a rig on the way through.** glTF
+# drops `use_deform`, drops vertices belonging to no face, and drops actions
+# that drive nothing; FBX drops those actions too and doubles a bone count. A
+# `.blend` hands a handler the scene exactly as authored, which is what an
+# incident fixture must do to reproduce an incident.
+_IMPORTERS = {
+    "glb": lambda p: bpy.ops.import_scene.gltf(filepath=p),
+    "gltf": lambda p: bpy.ops.import_scene.gltf(filepath=p),
+    # `use_image_search=False`: FBX names textures by path, and the search walks
+    # the directories around that path looking for a file of the same name.
+    "fbx": lambda p: bpy.ops.import_scene.fbx(filepath=p, use_image_search=False),
+    "obj": lambda p: bpy.ops.wm.obj_import(filepath=p),
+    "blend": lambda p: bpy.ops.wm.open_mainfile(filepath=p),
+}
+
+# A `.blend` already IS the scene, so opening one must not be preceded by the
+# empty-scene reset that every other importer needs.
+_OPENS_SCENE = {"blend"}
+
+# glTF and GLB share a magic; the JSON form is plain text.
+_MAGIC = ((b"glTF", "glb"), (b"Kaydara", "fbx"), (b"BLENDER", "blend"))
+
+
+def sniff(path):
+    """Guess the importer from the first bytes, when no format was given."""
+    with open(path, "rb") as fh:
+        head = fh.read(32)
+    for magic, fmt in _MAGIC:
+        if head.startswith(magic):
+            return fmt
+    stripped = head.lstrip()
+    if stripped.startswith(b"{"):
+        return "gltf"
+    if stripped.startswith((b"#", b"v ", b"o ", b"mtllib")):
+        return "obj"
+    raise ValueError("could not identify the model format from its first bytes")
+
+
+# How many images the last import referenced by path and had dropped. Read by
+# the verbs that report it; see `_drop_external_images`.
+EXTERNAL_IMAGES_DROPPED = 0
+
+
+def _refuse_external_gltf_uris(path, fmt):
+    """Refuse a glTF whose buffers or images point outside the file.
+
+    The service's intake (`src/intake`) already refused these before a spawn;
+    this is the backstop for anything that reaches the entrypoint another way.
+    The importer resolves a `uri` against the file's directory, so
+    `/proc/self/environ` or `../../.env` would be READ and its bytes written
+    into the model a verb hands back.
+    """
+    if fmt not in ("glb", "gltf"):
+        return
+    with open(path, "rb") as fh:
+        raw = fh.read()
+    if raw[:4] == b"glTF":
+        (length,) = struct.unpack_from("<I", raw, 12)
+        raw = raw[20 : 20 + length]
+    doc = json.loads(raw.decode("utf-8-sig"))
+    for key in ("buffers", "images"):
+        for i, item in enumerate(doc.get(key) or []):
+            uri = item.get("uri")
+            if uri is not None and not uri.startswith("data:"):
+                raise ValueError(
+                    "%s %d points outside the file; the bench never opens anything "
+                    "the upload does not contain" % (key[:-1], i)
+                )
+
+
+def _drop_bone_shapes():
+    """Remove the objects bones are DRAWN with, which the glTF importer makes.
+
+    Blender's importer gives every bone a custom shape (an `Icosphere` mesh
+    object) so the rig reads in the viewport. It is furniture, not the model, and
+    every verb that saw it was wrong: `inspect` counted a second mesh, and the
+    retexture views rendered it as a sphere the size of the rig in front of the
+    body, so the repaint reached only the head and arms.
+    """
+    shapes = set()
+    for arm in (o for o in bpy.data.objects if o.type == "ARMATURE"):
+        for pb in arm.pose.bones:
+            if pb.custom_shape is not None:
+                shapes.add(pb.custom_shape.name)
+                pb.custom_shape = None
+    for name in shapes:
+        obj = bpy.data.objects.get(name)
+        if obj is not None:
+            bpy.data.objects.remove(obj, do_unlink=True)
+    return len(shapes)
+
+
+def _drop_external_images():
+    """Remove every image the file named by path instead of carrying.
+
+    FBX names its textures by path (an artist's `C:\\textures\\skin.png`, or
+    `/etc/…`), and Blender loads a path lazily: the pixels are read when the
+    exporter or the renderer first asks, and would then ride out inside the
+    model we return. Nothing the caller sent can be at that path on our host, so
+    the reference could never resolve to THEIR texture — only to one of ours.
+    Dropped, never refused: artist FBX files carry dead texture paths routinely.
+    """
+    global EXTERNAL_IMAGES_DROPPED
+    dropped = 0
+    for img in list(bpy.data.images):
+        if img.source in {"FILE", "SEQUENCE", "MOVIE", "TILED"} and img.packed_file is None:
+            bpy.data.images.remove(img)
+            dropped += 1
+    EXTERNAL_IMAGES_DROPPED = dropped
+    return dropped
+
+
+def import_model(path, fmt):
+    """Reset to an EMPTY scene, then import.
+
+    The reset is not optional: Blender's default scene ships a cube, a camera
+    and a lamp, and every one of them would be counted as part of the model, lit
+    it, or framed the render. `use_empty=True` is the difference between
+    measuring the asset and measuring the asset plus Blender's furniture.
+    """
+    fmt = fmt or sniff(path)
+    importer = _IMPORTERS.get(fmt)
+    if importer is None:
+        raise ValueError("unsupported format %r" % fmt)
+    _refuse_external_gltf_uris(path, fmt)
+    # Opening a .blend REPLACES the scene, so resetting first would be wasted
+    # work — and `read_factory_settings` after it would throw the file away.
+    if fmt not in _OPENS_SCENE:
+        bpy.ops.wm.read_factory_settings(use_empty=True)
+    importer(path)
+    _drop_external_images()
+    _drop_bone_shapes()
+    return fmt
+
+
+def import_into_current(path, fmt):
+    """Import ALONGSIDE what is already loaded — no scene reset.
+
+    Separate from [`import_model`] on purpose, and named so the difference is
+    impossible to miss at a call site. `fit_rig` needs two models in one scene
+    (a donor rig and a target mesh); every other verb needs a clean scene and
+    would be silently wrong if a stray import survived.
+
+    Making the reset a flag on one function would put the dangerous case one
+    typo away from the safe one.
+    """
+    fmt = fmt or sniff(path)
+    importer = _IMPORTERS.get(fmt)
+    if importer is None:
+        raise ValueError("unsupported format %r" % fmt)
+    _refuse_external_gltf_uris(path, fmt)
+    importer(path)
+    _drop_external_images()
+    _drop_bone_shapes()
+    return fmt
+
+
+def mesh_objects():
+    return [o for o in bpy.data.objects if o.type == "MESH"]
+
+
+def armature_object():
+    return next((o for o in bpy.data.objects if o.type == "ARMATURE"), None)
+
+
+def world_bounds(objects):
+    """Axis-aligned bounds over every object's world-space corners.
+
+    For a SKINNED mesh this is the rest pose. That is the right answer for both
+    callers — `inspect` describes the asset as stored, and the turntable proves
+    the asset rather than one frame of an animation — but it is worth knowing
+    that a posed character can exceed this box.
+    """
+    pts = []
+    for o in objects:
+        pts.extend(o.matrix_world @ Vector(c) for c in o.bound_box)
+    if not pts:
+        return None
+    return {
+        "min": [min(p.x for p in pts), min(p.y for p in pts), min(p.z for p in pts)],
+        "max": [max(p.x for p in pts), max(p.y for p in pts), max(p.z for p in pts)],
+    }
+
+
+def export_glb(out_path, selected_only=False, optimise_animation=False, extras=False):
+    """Write the scene as a GLB, with the flags the Harness scripts settled on.
+
+    `export_animations` + `export_animation_mode='ACTIONS'` + `export_skins`:
+    all three scripts that ship a rigged character use exactly this set, because
+    the default drops either the clips or the binding and the result loads
+    without error while standing still.
+
+    `export_yup=True` because glTF is Y-up and Blender is Z-up. Omitting it
+    exports a character lying on its back — which imports cleanly, renders, and
+    is wrong.
+
+    `optimise_animation` is OPT-IN, and only `author_clips` asks for it. It
+    belongs to the verb that AUTHORED the clips, where the 1.5 GB incident
+    happened; a repair verb that silently re-optimised someone else's animation
+    would be changing data it was not asked to touch. Turning it on globally
+    would make every verb a little bit lossy for free.
+    """
+    kwargs = {
+        "filepath": out_path,
+        "export_format": "GLB",
+        "export_animations": True,
+        "export_animation_mode": "ACTIONS",
+        "export_skins": True,
+        "export_apply": False,
+        "export_yup": True,
+    }
+    if selected_only:
+        kwargs["use_selection"] = True
+    if extras:
+        # Custom properties as glTF `extras`: how a built level tells the game
+        # which node is a marker or a collider (build_level). Off elsewhere, so a
+        # repair verb never starts shipping an asset's stray properties.
+        kwargs["export_extras"] = True
+    if optimise_animation:
+        # `export_def_bones=False` keeps a non-deform control bone that we posed
+        # (a jaw, on some rigs) from being dropped along with the rig's unused
+        # controls. The optimiser then removes the flat curves of everything we
+        # did NOT pose, which is where the size goes.
+        kwargs["export_def_bones"] = False
+        kwargs["export_optimize_animation_size"] = True
+        kwargs["export_optimize_animation_keep_anim_armature"] = False
+
+    bpy.ops.export_scene.gltf(**kwargs)
+    if not os.path.exists(out_path):
+        raise RuntimeError("the exporter reported success but wrote no file")
+    return out_path
+
+
+def clamp_int(value, default, low, high):
+    """Clamp an optional integer argument.
+
+    `None` and `0` both mean "use the default": JSON may omit the key, and proto3
+    cannot distinguish an unset `uint32` from a zero one, so a caller that omits
+    a frame count must not get zero frames.
+    """
+    if value is None:
+        return default
+    try:
+        n = int(value)
+    except (TypeError, ValueError):
+        return default
+    if n == 0:
+        return default
+    return max(low, min(high, n))
+
+
+def triangles(obj):
+    """Triangles in a mesh as a renderer draws it: an n-gon is n - 2."""
+    return sum(len(p.vertices) - 2 for p in obj.data.polygons)
+
+
+def is_skinned(obj):
+    """Bound to an armature: a modifier AND vertex groups. Either alone moves nothing."""
+    return any(m.type == "ARMATURE" for m in obj.modifiers) and bool(obj.vertex_groups)
+
+
+def select_only(objects, active):
+    """Make `objects` the whole selection and `active` the active object.
+
+    The object operators (`transform_apply`, `join`, the vertex-group ones) act
+    on the selection, and a stray selected object from the import would be
+    changed along with the ones meant.
+    """
+    for o in bpy.context.view_layer.objects:
+        o.select_set(False)
+    for o in objects:
+        o.select_set(True)
+    bpy.context.view_layer.objects.active = active

package/bench/handlers/sheet.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Pictures as arrays: write a PNG, lay several on one sheet, draw the
+lettered grid a vision pass marks cells on.
+
+The grid is what makes a model's marks exact: a cell name like "C7" (column
+letter, row number, from the top-left) is something a vision model can say
+reliably, and the bench knows to the pixel which part of which view it
+means. The labels are drawn with a tiny built-in bitmap font, so no font
+file and no text renderer is needed.
+"""
+import bpy
+import numpy as np
+
+# 3x5 glyphs, one row per string, '#' = ink.
+_GLYPHS = {
+    "A": ("###", "#.#", "###", "#.#", "#.#"), "B": ("##.", "#.#", "##.", "#.#", "##."),
+    "C": ("###", "#..", "#..", "#..", "###"), "D": ("##.", "#.#", "#.#", "#.#", "##."),
+    "E": ("###", "#..", "##.", "#..", "###"), "F": ("###", "#..", "##.", "#..", "#.."),
+    "G": ("###", "#..", "#.#", "#.#", "###"), "H": ("#.#", "#.#", "###", "#.#", "#.#"),
+    "I": ("###", ".#.", ".#.", ".#.", "###"), "J": ("..#", "..#", "..#", "#.#", "###"),
+    "K": ("#.#", "#.#", "##.", "#.#", "#.#"), "L": ("#..", "#..", "#..", "#..", "###"),
+    "M": ("#.#", "###", "###", "#.#", "#.#"), "N": ("##.", "#.#", "#.#", "#.#", "#.#"),
+    "O": ("###", "#.#", "#.#", "#.#", "###"), "P": ("###", "#.#", "###", "#..", "#.."),
+    "0": ("###", "#.#", "#.#", "#.#", "###"), "1": (".#.", "##.", ".#.", ".#.", "###"),
+    "2": ("###", "..#", "###", "#..", "###"), "3": ("###", "..#", "###", "..#", "###"),
+    "4": ("#.#", "#.#", "###", "..#", "..#"), "5": ("###", "#..", "###", "..#", "###"),
+    "6": ("###", "#..", "###", "#.#", "###"), "7": ("###", "..#", "..#", "..#", "..#"),
+    "8": ("###", "#.#", "###", "#.#", "###"), "9": ("###", "#.#", "###", "..#", "###"),
+}
+COLUMNS = "ABCDEFGHIJKLMNOP"
+
+
+def cell_name(col, row):
+    return "%s%d" % (COLUMNS[col], row + 1)
+
+
+def write_png(rgb, path, alpha=None):
+    """`rgb` (H, W, 3), rows top-down, values as stored (sRGB / 255). `alpha` (H, W) in 0–1
+    writes an RGBA PNG (the `fidelity` renders: the model on nothing)."""
+    h, w = rgb.shape[:2]
+    img = bpy.data.images.new("out", w, h, alpha=alpha is not None)
+    px = np.ones((h, w, 4), dtype=np.float32)
+    px[..., :3] = np.clip(rgb[::-1], 0.0, 1.0)
+    if alpha is not None:
+        px[..., 3] = np.clip(alpha[::-1], 0.0, 1.0)
+        img.alpha_mode = "STRAIGHT"
+    img.pixels.foreach_set(px.ravel())
+    img.filepath_raw = path
+    img.file_format = "PNG"
+    img.save()
+    bpy.data.images.remove(img)
+
+
+def read_png(path, size):
+    """A PNG as (size, size, 3) rows top-down, scaled to `size`."""
+    img = bpy.data.images.load(path)
+    if img.size[0] == 0:
+        raise ValueError("an image could not be read")
+    img.scale(size, size)
+    px = np.empty(size * size * 4, dtype=np.float32)
+    img.pixels.foreach_get(px)
+    bpy.data.images.remove(img)
+    return px.reshape(size, size, 4)[::-1, :, :3].copy()
+
+
+def _text(rgb, x, y, text, scale):
+    for i, ch in enumerate(text):
+        g = _GLYPHS[ch]
+        for gy, line in enumerate(g):
+            for gx, c in enumerate(line):
+                if c == "#":
+                    x0 = x + (i * 4 + gx) * scale
+                    y0 = y + gy * scale
+                    rgb[y0:y0 + scale, x0:x0 + scale] = 1.0
+
+
+def grid(rgb, cells):
+    """The picture with a `cells`×`cells` grid and a label in every cell."""
+    out = rgb.copy()
+    size = out.shape[0]
+    step = size / cells
+    scale = max(1, int(step // 24))
+    for i in range(1, cells):
+        p = int(round(i * step))
+        out[:, p] = out[:, p] * 0.3
+        out[p, :] = out[p, :] * 0.3
+    for row in range(cells):
+        for col in range(cells):
+            name = cell_name(col, row)
+            x, y = int(col * step) + 2, int(row * step) + 2
+            w, h = (len(name) * 4 + 1) * scale, 7 * scale
+            out[y:y + h, x:x + w] = out[y:y + h, x:x + w] * 0.25
+            _text(out, x + scale, y + scale, name, scale)
+    return out
+
+
+def contact(pictures, columns=4):
+    """Pictures of one size side by side, `columns` across."""
+    size = pictures[0].shape[0]
+    cols = min(len(pictures), columns)
+    rows = (len(pictures) + cols - 1) // cols
+    out = np.full((rows * size, cols * size, 3), 0.18, dtype=np.float32)
+    for i, p in enumerate(pictures):
+        r, c = divmod(i, cols)
+        out[r * size:(r + 1) * size, c * size:(c + 1) * size] = p
+    return out
+
+
+def cell_mask(cells, grid_cells, size):
+    """A (size*size,) bool mask of the named cells."""
+    mask = np.zeros((size, size), dtype=bool)
+    step = size / grid_cells
+    for name in cells:
+        col = COLUMNS.index(name[0])
+        row = int(name[1:]) - 1
+        mask[int(round(row * step)):int(round((row + 1) * step)),
+             int(round(col * step)):int(round((col + 1) * step))] = True
+    return mask.ravel()

package/bench/handlers/texels.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Material slots, their base-colour pictures, and the texels behind them.
+
+`apply_skin` and `apply_texture` both work per (object, material slot): find
+the image that feeds the slot's base colour (or note a flat colour), learn
+where on the surface each texel lies (`raster` in UV space), change pixels,
+and write a NEW image into the same slot. No slot, material or UV is added —
+one material stays one material, an outline stays an outline.
+
+Pixel values are read and written as Blender holds them for the image — for
+the 8-bit sRGB textures a GLB carries that is the stored value / 255 — so a
+texel that is not changed comes back exactly as it went in.
+"""
+import bpy
+import numpy as np
+
+from . import raster
+
+MAX_EDGE = 4096
+
+
+def _bsdf(mat):
+    if mat is None or not mat.use_nodes:
+        return None
+    return next((n for n in mat.node_tree.nodes if n.type == "BSDF_PRINCIPLED"), None)
+
+
+def base_image_node(mat):
+    """The image node feeding the Principled BSDF's Base Color, or None."""
+    bsdf = _bsdf(mat)
+    if bsdf is None:
+        return None
+    sock = bsdf.inputs.get("Base Color")
+    if sock is None or not sock.is_linked:
+        return None
+    node = sock.links[0].from_node
+    for _ in range(3):  # through the importer's colour-factor mix
+        if node.type == "TEX_IMAGE":
+            return node
+        linked = [i for i in node.inputs if i.is_linked]
+        if not linked:
+            return None
+        node = linked[0].links[0].from_node
+    return None
+
+
+class Slot:
+    """One material slot of one object: its triangles and its base colour."""
+
+    def __init__(self, model, obj_index, slot_index, mat):
+        self.mat = mat
+        self.name = mat.name if mat else "(no material)"
+        self.tris = np.nonzero((model.owner == obj_index) & (model.slot == slot_index))[0]
+        self.node = base_image_node(mat)
+        img = self.node.image if self.node is not None else None
+        self.image = img if img is not None and img.size[0] > 0 else None
+        self.pixels = None
+        if self.image is not None:
+            w, h = self.image.size
+            if w * h > MAX_EDGE * MAX_EDGE:
+                raise ValueError("material %r has a texture over %d px" % (self.name, MAX_EDGE))
+            px = np.empty(w * h * 4, dtype=np.float32)
+            self.image.pixels.foreach_get(px)
+            self.pixels = px.reshape(h, w, 4)
+        bsdf = _bsdf(mat)
+        c = bsdf.inputs["Base Color"].default_value if bsdf is not None else (0.8, 0.8, 0.8, 1.0)
+        self.flat = np.array(c[:3], dtype=np.float32)
+
+    def sample(self, uv):
+        """Base colour at UVs (N, 2): the texture's pixel, or the flat colour."""
+        if self.pixels is None:
+            return np.broadcast_to(self.flat, (len(uv), 3)).copy()
+        h, w = self.pixels.shape[:2]
+        u = np.nan_to_num(uv[:, 0]) % 1.0
+        v = np.nan_to_num(uv[:, 1]) % 1.0
+        x = np.clip((u * w).astype(np.int64), 0, w - 1)
+        y = np.clip((v * h).astype(np.int64), 0, h - 1)
+        return self.pixels[y, x, :3]
+
+
+def slots(model):
+    out = []
+    for oi, obj in enumerate(model.objects):
+        mats = list(obj.data.materials) or [None]
+        for si, mat in enumerate(mats):
+            s = Slot(model, oi, si, mat)
+            if len(s.tris):
+                out.append(s)
+    return out
+
+
+def texel_points(model, slot):
+    """Every texel of `slot`'s image that its triangles cover: flat pixel
+    index, surface point (N, 3) and face normal (N, 3)."""
+    h, w = slot.pixels.shape[:2]
+    uv = model.uv[slot.tris]
+    if np.isnan(uv).any():
+        raise ValueError("material %r is textured but its mesh has no UVs" % slot.name)
+    # UV v runs up, image rows here run up too (Blender stores bottom row first).
+    xy = np.stack([uv[..., 0] % 1.0 * w, uv[..., 1] % 1.0 * h], axis=-1)
+    _, tri, bary = raster.rasterize(xy, np.zeros(xy.shape[:2]), w, h, want_bary=True)
+    flat = np.nonzero(tri >= 0)[0]
+    t = slot.tris[tri[flat]]
+    corners = model.pos[model.tris[t]]
+    b = bary[flat][:, :, None]
+    points = (corners * b).sum(axis=1)
+    return flat, points, model.normal[t]
+
+
+def replace_image(slot, rgb, suffix):
+    """Write `rgb` (H, W, 3) as a new packed image in the slot's texture node."""
+    h, w = rgb.shape[:2]
+    old = slot.image
+    img = bpy.data.images.new("%s_%s" % (old.name, suffix), w, h, alpha=True)
+    img.colorspace_settings.name = old.colorspace_settings.name
+    px = np.concatenate([rgb, slot.pixels[..., 3:4]], axis=-1).astype(np.float32)
+    img.pixels.foreach_set(px.ravel())
+    img.file_format = "PNG"
+    img.pack()
+    slot.node.image = img
+    # A model that draws its emission from the base colour's own picture (a
+    # generated mesh often does, so it reads unlit) would keep glowing in its
+    # OLD colours over the new ones: every node reading that picture follows.
+    if slot.mat is not None and slot.mat.node_tree is not None:
+        for node in slot.mat.node_tree.nodes:
+            if node.type == "TEX_IMAGE" and node.image == old:
+                node.image = img
+    return img
+
+
+def fill_unseen(rgb, known, rounds=48):
+    """Grow known texels into unknown ones, one ring per round: what no view
+    saw takes its neighbours' colour instead of a hole."""
+    rgb = rgb.copy()
+    known = known.copy()
+    for _ in range(rounds):
+        if known.all():
+            break
+        acc = np.zeros_like(rgb)
+        cnt = np.zeros(known.shape, dtype=np.float32)
+        for dy, dx in ((0, 1), (0, -1), (1, 0), (-1, 0)):
+            k = np.roll(known, (dy, dx), axis=(0, 1))
+            acc += np.roll(rgb, (dy, dx), axis=(0, 1)) * k[..., None]
+            cnt += k
+        grow = (~known) & (cnt > 0)
+        rgb[grow] = acc[grow] / cnt[grow][:, None]
+        known = known | grow
+    if not known.all() and known.any():
+        rgb[~known] = rgb[known].mean(axis=0)
+    return rgb
+
+
+def shade_view(model, cam, size, slots_by_tri, zbuf, tri, bary, lit=True):
+    """What a view shows: base colour under a soft headlight (`lit=False`: the base colour
+    alone, flat, as a Workbench FLAT render shows it), on the key colour.
+    Returns (rgb (S, S, 3) rows top-down, coverage share)."""
+    from .views import KEY
+    out = np.broadcast_to(KEY, (size * size, 3)).copy()
+    hit = np.nonzero(tri >= 0)[0]
+    t = tri[hit]
+    uv = (model.uv[t] * bary[hit][:, :, None]).sum(axis=1)
+    colour = np.zeros((len(hit), 3), dtype=np.float32)
+    for s in set(slots_by_tri[t]):
+        m = slots_by_tri[t] == s
+        colour[m] = s.sample(uv[m])
+    facing = np.clip(-(model.normal[t] @ np.array(cam["forward"])), 0.0, 1.0)
+    out[hit] = colour * (0.6 + 0.4 * facing)[:, None] if lit else colour
+    return out.reshape(size, size, 3), len(hit) / float(size * size)
+
+
+def slot_lookup(model, all_slots):
+    """An object array mapping each triangle to its Slot."""
+    lookup = np.empty(len(model.tris), dtype=object)
+    for s in all_slots:
+        lookup[s.tris] = s
+    return lookup