texture3d 0.2.0__py3-none-any.whl

texture3d/mapping/atlas.py

@@ -0,0 +1,246 @@
+"""Stage 6: pack the patch rectangles into one square texture, copy the
+(levelled) pixels, write the per-corner texture coordinates, sharpen."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Sequence, Tuple
+
+import numpy as np
+
+from texture3d.mapping import imageops
+from texture3d.mapping.patches import PatchSet
+from texture3d.mapping.types import NO_ID, PatchTooLarge, Rect, View
+
+
+def compute_texture_size(rects: Sequence[Rect], multiple: int) -> int:
+    """The square that would hold the rectangles at a 0.9 fill, at least the
+    largest side, rounded up to a power of two or a multiple."""
+    area = sum(r.area for r in rects)
+    max_side = max([max(r.width, r.height) for r in rects] + [0])
+    scaled = int(np.ceil(np.float32(area) * np.float32(1.0 / 0.9)))
+    side = max(int(np.ceil(np.sqrt(np.float32(scaled)))), max_side)
+    if multiple > 0:
+        return ((side + multiple - 1) // multiple) * multiple
+    size = 1
+    while size < side:
+        size *= 2
+    return size
+
+
+class MaxRectsBinPack:
+    """MaxRects bin packing with the bottom-left rule, rotation allowed.
+
+    Every step places, of all remaining rectangles, the one whose best
+    position is lowest (then leftmost).
+    """
+
+    def __init__(self, width: int, height: int):
+        self.width = width
+        self.height = height
+        self.free = np.array([[0, 0, width, height]], dtype=np.int64)
+
+    def insert(self, sizes: np.ndarray) -> Tuple[List[Tuple[Rect, int]], np.ndarray]:
+        """Places as many of the (N, 2) ``sizes`` as fit. Returns the placed
+        rectangles with their input index, and the indices left unplaced."""
+        remaining = np.arange(len(sizes))
+        placed: List[Tuple[Rect, int]] = []
+        big = np.int64(1) << np.int64(62)
+        while len(remaining):
+            w = sizes[remaining, 0][:, None]
+            h = sizes[remaining, 1][:, None]
+            fx, fy, fw, fh = (self.free[:, i][None, :] for i in range(4))
+            fr = np.arange(len(self.free), dtype=np.int64)[None, :]
+            # Candidate keys order (top, x, free rect, orientation).
+            fit0 = (fw >= w) & (fh >= h)
+            fit1 = (fw >= h) & (fh >= w)
+            key0 = np.where(fit0, ((fy + h) << 39) | (fx << 25) | (fr << 1), big)
+            key1 = np.where(fit1, ((fy + w) << 39) | (fx << 25) | (fr << 1) | 1, big)
+            best = np.minimum(key0.min(axis=1), key1.min(axis=1))
+            feasible = best < big
+            if not feasible.any():
+                break
+            top = best >> 39
+            x = (best >> 25) & ((1 << 14) - 1)
+            top = np.where(feasible, top, big)
+            x = np.where(feasible, x, big)
+            u = int(np.lexsort((x, top))[0])
+            k = int(best[u])
+            free_index = (k >> 1) & ((1 << 24) - 1)
+            rotated = bool(k & 1)
+            fxu, fyu = int(self.free[free_index, 0]), int(self.free[free_index, 1])
+            pw, ph = int(sizes[remaining[u], 0]), int(sizes[remaining[u], 1])
+            node = Rect(fxu, fyu, ph if rotated else pw, pw if rotated else ph)
+            self._place(node)
+            placed.append((node, int(remaining[u])))
+            remaining = np.delete(remaining, u)
+        return placed, remaining
+
+    def _place(self, node: Rect) -> None:
+        fx, fy, fw, fh = (self.free[:, i] for i in range(4))
+        ux, uy, uw, uh = node.x, node.y, node.width, node.height
+        hit = ~((ux >= fx + fw) | (ux + uw <= fx) | (uy >= fy + fh) | (uy + uh <= fy))
+        pieces = []
+        for i in np.flatnonzero(hit):
+            x, y, w, h = self.free[i]
+            if ux < x + w and ux + uw > x:
+                if y < uy < y + h:
+                    pieces.append((x, y, w, uy - y))
+                if uy + uh < y + h:
+                    pieces.append((x, uy + uh, w, y + h - (uy + uh)))
+            if uy < y + h and uy + uh > y:
+                if x < ux < x + w:
+                    pieces.append((x, y, ux - x, h))
+                if ux + uw < x + w:
+                    pieces.append((ux + uw, y, x + w - (ux + uw), h))
+        kept = self.free[~hit]
+        if pieces:
+            kept = np.concatenate([kept, np.array(pieces, dtype=np.int64).reshape(-1, 4)])
+        self.free = kept
+        self._prune()
+
+    def _prune(self) -> None:
+        """Drop free rectangles contained in another; of two identical ones
+        the earlier goes."""
+        n = len(self.free)
+        if n < 2:
+            return
+        x, y, w, h = (self.free[:, i] for i in range(4))
+        contained = (
+            (x[:, None] >= x[None, :])
+            & (y[:, None] >= y[None, :])
+            & (x[:, None] + w[:, None] <= x[None, :] + w[None, :])
+            & (y[:, None] + h[:, None] <= y[None, :] + h[None, :])
+        )
+        identical = contained & contained.T
+        np.fill_diagonal(contained, False)
+        earlier = np.arange(n)[None, :] < np.arange(n)[:, None]
+        contained &= ~(identical & earlier)
+        self.free = self.free[~contained.any(axis=1)]
+
+
+def shelf_pack(sizes: np.ndarray, width: int, height: int) -> Tuple[List[Tuple[Rect, int]], np.ndarray]:
+    """Next-fit decreasing-height shelf packing, rotation allowed: every
+    rectangle is laid so it is wider than tall, sorted by height, and placed
+    left to right on shelves stacked from the top. O(N log N), for the tens of
+    thousands of tiny patches a dense mesh seen by many views produces, where
+    MaxRects is quadratic. Returns the placed rectangles with their input
+    index, and the indices left unplaced."""
+    n = len(sizes)
+    if n == 0:
+        return [], np.zeros(0, dtype=np.int64)
+    w = sizes[:, 0].astype(np.int64)
+    h = sizes[:, 1].astype(np.int64)
+    rotated = h > w
+    pw = np.where(rotated, h, w)
+    ph = np.where(rotated, w, h)
+    order = np.lexsort((np.arange(n), -pw, -ph))
+    placed: List[Tuple[Rect, int]] = []
+    unplaced: List[int] = []
+    y = 0
+    i = 0
+    while i < n:
+        shelf_h = int(ph[order[i]])
+        if y + shelf_h > height:
+            unplaced.extend(order[i:].tolist())
+            break
+        # Take rectangles while they fit on this shelf's width; those wider
+        # than the texture can never be placed.
+        widths = pw[order[i:]]
+        x_end = np.cumsum(widths)
+        fits = x_end <= width
+        take = int(np.argmin(fits)) if not fits.all() else len(widths)
+        if take == 0:
+            unplaced.append(int(order[i]))
+            i += 1
+            continue
+        xs = x_end[:take] - widths[:take]
+        for k in range(take):
+            idx = int(order[i + k])
+            placed.append((Rect(int(xs[k]), y, int(pw[idx]), int(ph[idx])), idx))
+        y += shelf_h
+        i += take
+    return placed, np.array(unplaced, dtype=np.int64)
+
+
+def pack_rects(sizes: np.ndarray, size: int, exact_limit: int) -> Tuple[List[Tuple[Rect, int]], np.ndarray]:
+    """MaxRects up to ``exact_limit`` rectangles, the shelf packer beyond it
+    (0 = always MaxRects)."""
+    if exact_limit <= 0 or len(sizes) <= exact_limit:
+        return MaxRectsBinPack(size, size).insert(sizes)
+    return shelf_pack(sizes, size, size)
+
+
+@dataclass
+class AtlasOutput:
+    pixels: np.ndarray  # (S, S, 3) BGR8
+    size: int
+    face_texcoords: np.ndarray  # (F, 3, 2)
+    #: Where each textured patch landed in the atlas.
+    patch_rects: List[Rect] = field(default_factory=list)
+
+
+def generate(
+    patch_set: PatchSet,
+    images: List[np.ndarray],
+    views: List[View],
+    texture_size_multiple: int = 0,
+    max_texture_size: int = 8192,
+    empty_color_bgr: Tuple[int, int, int] = (39, 127, 255),
+    sharpness_weight: float = 0.5,
+    exact_packing_limit: int = 4000,
+) -> AtlasOutput:
+    """Packs, copies, and writes the final texture coordinates. Raises
+    ``PatchTooLarge`` when a patch does not fit the largest texture allowed.
+    Up to ``exact_packing_limit`` patches are packed with MaxRects; more
+    take the shelf packer (see ``shelf_pack``)."""
+    patches = patch_set.patches
+    for patch in patches:
+        if max_texture_size > 0 and (patch.rect.width > max_texture_size or patch.rect.height > max_texture_size):
+            raise PatchTooLarge(f"patch {patch.rect.width}x{patch.rect.height} exceeds {max_texture_size}")
+    sizes = np.array([[p.rect.width, p.rect.height] for p in patches], dtype=np.int64)
+    texture_size = compute_texture_size([p.rect for p in patches], texture_size_multiple)
+    if max_texture_size > 0:
+        texture_size = min(texture_size, max_texture_size)
+    while True:
+        placed, remaining = pack_rects(sizes, texture_size, exact_packing_limit)
+        if len(remaining) == 0 or texture_size == max_texture_size:
+            if len(remaining):
+                r = patches[int(remaining[0])].rect
+                raise PatchTooLarge(f"patch {r.width}x{r.height} does not fit a {texture_size} texture")
+            break
+        texture_size *= 2
+        if max_texture_size > 0:
+            texture_size = min(texture_size, max_texture_size)
+
+    atlas = np.empty((texture_size, texture_size, 3), dtype=np.uint8)
+    atlas[:] = np.array(empty_color_bgr, dtype=np.uint8)
+    texcoords = patch_set.face_texcoords.copy()
+    patch_rects: List[Rect] = []
+    for rect, p in placed:
+        patch = patches[p]
+        rotated = rect.width != patch.rect.width
+        if patch.label != NO_ID:
+            patch_rects.append(rect)
+            view = views[patch.label]
+            source = images[patch.label]
+            r0 = max(0, -patch.rect.y)
+            r1 = min(patch.rect.height, view.height - patch.rect.y)
+            c0 = max(0, -patch.rect.x)
+            c1 = min(patch.rect.width, view.width - patch.rect.x)
+            if r1 > r0 and c1 > c0:
+                block = source[patch.rect.y + r0 : patch.rect.y + r1, patch.rect.x + c0 : patch.rect.x + c1]
+                if rotated:
+                    # A rotated placement is the transpose of the patch.
+                    atlas[rect.y + c0 : rect.y + c1, rect.x + r0 : rect.x + r1] = block.transpose(1, 0, 2)
+                else:
+                    atlas[rect.y + r0 : rect.y + r1, rect.x + c0 : rect.x + c1] = block
+        t = texcoords[patch.faces]
+        if rotated:
+            texcoords[patch.faces] = np.stack([t[..., 1] + rect.x, t[..., 0] + rect.y], axis=-1)
+        else:
+            texcoords[patch.faces] = t + np.array([rect.x, rect.y], dtype=np.float32)
+
+    if sharpness_weight > 0:
+        atlas = imageops.sharpen(atlas, 1.5, sharpness_weight)
+    return AtlasOutput(pixels=atlas, size=texture_size, face_texcoords=texcoords, patch_rects=patch_rects)

texture3d/mapping/imageops.py

@@ -0,0 +1,80 @@
+"""The image arithmetic the stages share."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import cv2
+import numpy as np
+
+from texture3d.mapping.types import View
+
+
+def gray_normalized(view: View) -> np.ndarray:
+    """Grey in 0...1: ``0.114 B + 0.587 G + 0.299 R`` over normalised bytes."""
+    bgr = view.bgr.astype(np.float32) * np.float32(1.0 / 255.0)
+    return bgr[..., 0] * np.float32(0.114) + bgr[..., 1] * np.float32(0.587) + bgr[..., 2] * np.float32(0.299)
+
+
+def gradient_magnitude_blurred(gray: np.ndarray) -> np.ndarray:
+    """Sobel 3x3 gradient magnitude at scale 1/8, then a 15x15 Gaussian blur."""
+    gx = cv2.Sobel(gray, cv2.CV_32F, 1, 0, ksize=3, scale=1.0 / 8.0, borderType=cv2.BORDER_REFLECT_101)
+    gy = cv2.Sobel(gray, cv2.CV_32F, 0, 1, ksize=3, scale=1.0 / 8.0, borderType=cv2.BORDER_REFLECT_101)
+    magnitude = cv2.magnitude(gx, gy)
+    return cv2.GaussianBlur(magnitude, (15, 15), 0, borderType=cv2.BORDER_REFLECT_101)
+
+
+def invalid_region_mask(view: View) -> Optional[np.ndarray]:
+    """Black regions reached by flood fill from eight border seeds.
+
+    Those regions are the padding left by lens undistortion and must not
+    texture anything. None when no seed is black.
+    """
+    gray = cv2.cvtColor(view.bgr, cv2.COLOR_BGR2GRAY)
+    h, w = gray.shape
+    seeds = [(0, 0), (0, h // 2), (0, h - 1), (w // 2, h - 1), (w - 1, h - 1), (w - 1, h // 2), (w - 1, 0), (w // 2, 0)]
+    if not any(gray[y, x] == 0 for x, y in seeds):
+        return None
+    filled = np.zeros((h + 2, w + 2), dtype=np.uint8)
+    flags = 8 | cv2.FLOODFILL_MASK_ONLY | (255 << 8)
+    for x, y in seeds:
+        if gray[y, x] == 0 and filled[y + 1, x + 1] == 0:
+            cv2.floodFill(gray.copy(), filled, (x, y), 255, 0, 3, flags)
+    mask = np.full((h, w), 255, dtype=np.uint8)
+    mask[filled[1:-1, 1:-1] != 0] = 0
+    return mask
+
+
+def sample_linear(image: np.ndarray, pts: np.ndarray) -> np.ndarray:
+    """Bilinear sample between the four pixels around ``floor(pt)``.
+
+    Integer coordinates are pixel centres; pixels outside the image
+    contribute nothing. ``image`` is (H, W, 3) of any numeric type; the
+    result is float32.
+    """
+    h, w = image.shape[:2]
+    pts = np.asarray(pts, dtype=np.float32)
+    gx = np.floor(pts[:, 0]).astype(np.int64)
+    gy = np.floor(pts[:, 1]).astype(np.int64)
+    dx = pts[:, 0] - gx.astype(np.float32)
+    dy = pts[:, 1] - gy.astype(np.float32)
+    result = np.zeros((len(pts), 3), dtype=np.float32)
+    for i, wy in ((0, 1 - dy), (1, dy)):
+        y = gy + i
+        y_ok = (y >= 0) & (y < h)
+        for j, wx in ((0, 1 - dx), (1, dx)):
+            x = gx + j
+            ok = y_ok & (x >= 0) & (x < w)
+            weight = (wx * wy)[ok]
+            result[ok] += image[y[ok], x[ok]].astype(np.float32) * weight[:, None]
+    return result
+
+
+def gaussian_blur_bgr8(image: np.ndarray, sigma: float) -> np.ndarray:
+    return cv2.GaussianBlur(image, (0, 0), sigma)
+
+
+def sharpen(image: np.ndarray, sigma: float, weight: float) -> np.ndarray:
+    """Unsharp mask: ``img (1 + w) - blur(img) w``."""
+    blurred = gaussian_blur_bgr8(image, sigma)
+    return cv2.addWeighted(image, 1.0 + weight, blurred, -weight, 0.0)

texture3d/mapping/labeling.py

@@ -0,0 +1,298 @@
+"""Stage 3: one view per face.
+
+The face graph (faces adjacent across an edge, both seen by at least one view)
+is an MRF whose labels are the views plus "none". A face's data cost for a
+view falls with the view's quality, normalised by the 95th percentile of all
+qualities so a few very sharp faces do not flatten the rest; the Potts
+smoothness term makes neighbours prefer the same view, which is what grows
+the patches. Solved by synchronous loopy belief propagation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, List, Optional, Tuple
+
+import numpy as np
+
+from texture3d.mapping.topology import Topology
+from texture3d.mapping.types import NO_ID, FaceViews, Mesh, View
+
+MAX_ENERGY = np.float32(1000)
+
+
+@dataclass
+class Outcome:
+    #: Per face: view index, or NO_ID for no view.
+    labels: np.ndarray
+    #: The 95th-percentile quality the data costs were normalised by.
+    norm_quality: float
+    energy: float
+    iterations: int
+    #: Face pairs across an edge where exactly one side has no view, in face
+    #: order, then pairs whose labels differ, in the graph's edge order. The
+    #: seam leveling walks these.
+    seam_edges: np.ndarray
+    #: The face graph's undirected edges, smaller face first, in face order.
+    graph_edges: np.ndarray
+    #: Faces no view rasterised that took a neighbour's view (see ``fill_unseen``).
+    filled: Optional[np.ndarray] = None
+
+
+def approximate_permille(values: np.ndarray, permille: float = 0.95) -> float:
+    """Approximate ``permille`` of ``values`` with a 1000-bin histogram.
+
+    Zero when every quality is zero: the data costs then read every view as
+    as good as the best and the smoothness term decides.
+    """
+    v = np.asarray(values, dtype=np.float32)
+    v = v[np.isfinite(v)]
+    if len(v) == 0:
+        return 0.0
+    max_quality = float(v.max())
+    if max_quality <= 0:
+        return 0.0
+    bins = 1000
+    bin_interval = np.float32(bins) / np.float32(max_quality)
+    i = (v * bin_interval).astype(np.int64)
+    freq = np.bincount(i[(i >= 0) & (i < bins)], minlength=bins)
+    total = int(freq.sum())
+    num = 0
+    upper = 0.0
+    for b in range(bins):
+        if num / total > permille:
+            return upper
+        num += int(freq[b])
+        upper = float((np.float32(b) * np.float32(max_quality)) / np.float32(bins - 1))
+    return max_quality
+
+
+class BeliefPropagation:
+    """The flattened MRF and its synchronous sweeps.
+
+    Labels per node in the order they were set; messages per directed edge
+    with one entry per label of the receiving node.
+    """
+
+    def __init__(
+        self,
+        label_offset: np.ndarray,
+        labels_flat: np.ndarray,
+        costs_flat: np.ndarray,
+        edge_from: np.ndarray,
+        edge_to: np.ndarray,
+    ):
+        self.label_offset = label_offset
+        self.labels_flat = labels_flat
+        self.costs_flat = costs_flat.astype(np.float32)
+        self.edge_from = edge_from
+        self.edge_to = edge_to
+        node_count = len(label_offset) - 1
+        n_labels = np.diff(label_offset)
+        self.node_of_label = np.repeat(np.arange(node_count), n_labels)
+
+        edge_count = len(edge_from)
+        per_edge = n_labels[edge_to]
+        self.msg_offset = np.zeros(edge_count + 1, dtype=np.int64)
+        np.cumsum(per_edge, out=self.msg_offset[1:])
+        total = int(self.msg_offset[-1])
+        self.slot_edge = np.repeat(np.arange(edge_count), per_edge)
+        slot_j = np.arange(total) - self.msg_offset[self.slot_edge]
+        # Message slot -> the (node, label) it speaks about.
+        self.s_idx = label_offset[edge_to[self.slot_edge]] + slot_j
+        # A message on edge e (n1 -> n2) for n2's label j takes the minimum over
+        # n1's labels k of n1's belief without n2's message plus the Potts term.
+        # That belief lives in the slots of the reverse edge (its messages are
+        # indexed by n1's labels), so the matching label's slot is found once.
+        label_max = int(labels_flat.max()) + 1 if len(labels_flat) else 1
+        node_key = self.node_of_label * label_max + labels_flat
+        n1 = edge_from[self.slot_edge]
+        label_j = labels_flat[self.s_idx]
+        query = n1 * label_max + label_j
+        pos = np.searchsorted(node_key, query)
+        pos_c = np.minimum(pos, len(node_key) - 1)
+        found = (node_key[pos_c] == query) & (label_j != 0)
+        k = pos_c - label_offset[n1]
+        self.match = np.where(found, self.msg_offset[self.slot_edge ^ 1] + k, -1)
+        self.reverse_of_slot = self.slot_edge ^ 1
+        self.old = np.zeros(total, dtype=np.float32)
+        self.new = np.zeros(total, dtype=np.float32)
+        self.label, self.data_cost = self._first_min(self.costs_flat)
+
+    def _first_min(self, energy: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """Per node the first label of least energy, as (label, cost)."""
+        node_min = np.minimum.reduceat(energy, self.label_offset[:-1])
+        candidates = np.flatnonzero(energy == node_min[self.node_of_label])
+        _, first = np.unique(self.node_of_label[candidates], return_index=True)
+        chosen = candidates[first]
+        return self.labels_flat[chosen], self.costs_flat[chosen]
+
+    def compute_energy(self) -> float:
+        lf = self.label[self.edge_from]
+        lt = self.label[self.edge_to]
+        agree = (lf == lt) & (lf != 0)
+        return float(self.data_cost.sum(dtype=np.float64)) + float(MAX_ENERGY) * float((~agree).sum())
+
+    def sweep(self) -> None:
+        total_labels = len(self.labels_flat)
+        incoming = np.bincount(self.s_idx, weights=self.old, minlength=total_labels).astype(np.float32)
+        belief = self.costs_flat[self.s_idx] + incoming[self.s_idx] - self.old
+        segment_min = np.minimum.reduceat(belief, self.msg_offset[:-1])
+        floor = segment_min[self.reverse_of_slot] + MAX_ENERGY
+        matched = np.where(self.match >= 0, belief[np.maximum(self.match, 0)], np.float32(np.inf))
+        np.minimum(floor, matched, out=self.new)
+        # Normalise each edge's messages to a minimum of zero.
+        edge_min = np.minimum.reduceat(self.new, self.msg_offset[:-1])
+        self.new -= edge_min[self.slot_edge]
+        self.old, self.new = self.new, self.old
+        incoming = np.bincount(self.s_idx, weights=self.old, minlength=total_labels).astype(np.float32)
+        self.label, self.data_cost = self._first_min(self.costs_flat + incoming)
+
+    def optimize(self, log: Optional[Callable[[str], None]] = None) -> Tuple[float, int]:
+        """Sweep until the energy stops falling, tolerating a few increases,
+        at most 100 sweeps."""
+        energy = self.compute_energy()
+        i = 0
+        increases = 0
+        total_increases = 0
+        while True:
+            last = energy
+            self.sweep()
+            energy = self.compute_energy()
+            diff = last - energy
+            i += 1
+            if log:
+                log(f"  sweep {i}: energy {energy:.0f}")
+            if i > 100 or diff == 0:
+                break
+            if diff < 0:
+                total_increases += 1
+                increases += 1
+                if increases > 3:
+                    break
+            else:
+                if total_increases > 5:
+                    break
+                increases = 0
+        return energy, i
+
+
+def fill_unseen(
+    mesh: Mesh, topology: Topology, labels: np.ndarray, views: List[View], passes: int = 3
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Give a face no view rasterised the view of a textured neighbour.
+
+    On a dense mesh a face smaller than a pixel in every keyframe is never
+    scored. It takes the view of the first edge neighbour that has one,
+    provided its three vertices project in front of that view's camera and
+    inside its image. Repeated ``passes`` times so small clusters fill from
+    their rim. Without this such faces land in the empty patch and speckle
+    the surface with the empty colour. Returns the new labels and the mask
+    of faces that were filled.
+    """
+    labels = labels.copy()
+    filled = np.zeros(len(labels), dtype=bool)
+    ff = topology.face_faces
+    for _ in range(passes):
+        unlabelled = labels == NO_ID
+        neighbour_label = np.where(ff != NO_ID, labels[np.maximum(ff, 0)], NO_ID)
+        has = neighbour_label != NO_ID
+        candidates = np.flatnonzero(unlabelled & has.any(axis=1))
+        if len(candidates) == 0:
+            break
+        chosen = neighbour_label[candidates, np.argmax(has[candidates], axis=1)]
+        changed = False
+        for v in np.unique(chosen):
+            faces = candidates[chosen == v]
+            view = views[int(v)]
+            cam = view.camera.to_camera(mesh.positions[mesh.faces[faces].ravel()])
+            z = cam[:, 2]
+            safe = cam.copy()
+            safe[z <= 0, 2] = 1.0
+            px = view.camera.to_image(safe)
+            ok = (z > 0) & (px[:, 0] >= 0) & (px[:, 1] >= 0) & (px[:, 0] <= view.width - 1) & (px[:, 1] <= view.height - 1)
+            accept = faces[ok.reshape(-1, 3).all(axis=1)]
+            if len(accept):
+                labels[accept] = v
+                filled[accept] = True
+                changed = True
+        if not changed:
+            break
+    return labels, filled
+
+
+def assign(
+    mesh: Mesh,
+    topology: Topology,
+    face_views: FaceViews,
+    data_smoothness_ratio: float = 0.1,
+    log: Optional[Callable[[str], None]] = None,
+    views: Optional[List[View]] = None,
+    fill: bool = False,
+) -> Outcome:
+    face_count = mesh.face_count
+    ff = topology.face_faces
+    f_idx = np.broadcast_to(np.arange(face_count)[:, None], ff.shape)
+    has = (ff != NO_ID) & (f_idx < ff)
+    visible = face_views.visible
+    vis_f = visible[f_idx]
+    vis_g = visible[np.where(ff != NO_ID, ff, 0)]
+    graph_mask = has & vis_f & vis_g
+    seam_mask = has & (vis_f != vis_g)
+    graph_edges = np.stack([f_idx[graph_mask], ff[graph_mask]], axis=-1)
+    seam_first = np.stack([f_idx[seam_mask], ff[seam_mask]], axis=-1)
+
+    norm_quality = approximate_permille(face_views.quality)
+    max_energy = np.float32(data_smoothness_ratio) * MAX_ENERGY
+
+    # Labels per node: 0 ("no view") first, then the face's views plus one.
+    counts = face_views.counts
+    n_labels = counts + 1
+    label_offset = np.zeros(face_count + 1, dtype=np.int64)
+    np.cumsum(n_labels, out=label_offset[1:])
+    total = int(label_offset[-1])
+    labels_flat = np.zeros(total, dtype=np.int64)
+    costs_flat = np.full(total, max_energy, dtype=np.float32)
+    is_view = np.ones(total, dtype=bool)
+    is_view[label_offset[:-1]] = False
+    labels_flat[is_view] = face_views.view + 1
+    q = face_views.quality
+    if norm_quality > 0:
+        normalized = np.where(q >= norm_quality, np.float32(1), q / np.float32(norm_quality))
+    else:
+        normalized = np.ones_like(q)
+    costs_flat[is_view] = (np.float32(1) - normalized) * max_energy
+
+    edge_from = np.stack([graph_edges[:, 0], graph_edges[:, 1]], axis=-1).ravel()
+    edge_to = np.stack([graph_edges[:, 1], graph_edges[:, 0]], axis=-1).ravel()
+    inference = BeliefPropagation(label_offset, labels_flat, costs_flat, edge_from, edge_to)
+    energy, iterations = inference.optimize(log)
+
+    labels = np.where(inference.label > 0, inference.label - 1, NO_ID)
+    filled = np.zeros(face_count, dtype=bool)
+    if fill and views is not None:
+        labels, filled = fill_unseen(mesh, topology, labels, views)
+        if log and filled.any():
+            log(f"  {int(filled.sum())} unseen faces took a neighbour's view")
+        # Filled faces count as seen for the seams, which are then recomputed
+        # over every edge: the same two blocks as below, in the same order.
+        seen = visible | filled
+        seen_f = seen[f_idx]
+        seen_g = seen[np.where(ff != NO_ID, ff, 0)]
+        seam_mask = has & (seen_f != seen_g)
+        seam_first = np.stack([f_idx[seam_mask], ff[seam_mask]], axis=-1)
+        both = has & seen_f & seen_g
+        differ = both & (labels[f_idx] != labels[np.where(ff != NO_ID, ff, 0)])
+        seam_second = np.stack([f_idx[differ], ff[differ]], axis=-1)
+    else:
+        seam_second = graph_edges[labels[graph_edges[:, 0]] != labels[graph_edges[:, 1]]]
+    seam_edges = np.concatenate([seam_first, seam_second]) if len(seam_first) or len(seam_second) else np.zeros((0, 2), np.int64)
+    return Outcome(
+        labels=labels,
+        norm_quality=norm_quality,
+        energy=energy,
+        iterations=iterations,
+        seam_edges=seam_edges,
+        graph_edges=graph_edges,
+        filled=filled,
+    )