object-remove 0.1.0__py3-none-any.whl

object_remove/fillengines/patchmatch/solver.py

@@ -0,0 +1,152 @@
+"""PatchMatch inpainting solver, one scale level.
+
+Classic Barnes et al. PatchMatch (random init → propagation → random search)
+wrapped in an EM loop: search the nearest neighbour field, then reconstruct the
+hole by patch voting, repeat. All work is done in a *padded* coordinate frame so
+every patch window is fully in bounds and distance is a fixed size slice.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .patch_scorer import PatchScorer
+from .patch_search_index import PatchSearchIndex
+
+
+@dataclass
+class PatchMatchSolver:
+    radius: int = 3
+    pm_iters: int = 4       # propagation + random search sweeps per EM step
+    em_iters: int = 4       # search/reconstruct alternations
+    seed: int = 1234
+
+    def __post_init__(self):
+        self.scorer = PatchScorer(self.radius)
+
+    def solve_level(self, feat: np.ndarray, hole: np.ndarray,
+                    invalid: np.ndarray, progress=None, cancel=None) -> np.ndarray:
+        """Fill ``hole`` in the padded image ``feat``.
+
+        ``invalid`` marks pixels that must not be sourced from (all holes).
+        Returns a new padded image with hole pixels reconstructed.
+        """
+        r = self.radius
+        rng = np.random.default_rng(self.seed)
+        Hp, Wp = hole.shape
+        index = PatchSearchIndex(invalid, r)
+        if index.n_sources == 0:
+            return feat.copy()
+
+        targets = self._target_centers(hole, r)
+        nnf_c, nnf_d = self._init_nnf(feat, targets, index, rng)
+
+        current_estimate = feat.copy()
+        for em in range(self.em_iters):
+            if cancel is not None and cancel():
+                break
+            self._refresh(current_estimate, nnf_c, nnf_d, targets)
+            for it in range(self.pm_iters):
+                self._sweep(current_estimate, nnf_c, nnf_d, targets, index, rng,
+                           reverse=(it % 2 == 1))
+            current_estimate = self._vote(current_estimate, hole, nnf_c, nnf_d, targets)
+            if progress is not None:
+                progress((em + 1) / self.em_iters)
+        return current_estimate
+
+    def _target_centers(self, hole: np.ndarray, r: int) -> np.ndarray:
+        """Centers whose patch overlaps the hole (hole dilated by r), full window in bounds."""
+        Hp, Wp = hole.shape
+        dil = hole.copy()
+        for _ in range(r):
+            nxt = dil.copy()
+            nxt[1:, :] |= dil[:-1, :]
+            nxt[:-1, :] |= dil[1:, :]
+            nxt[:, 1:] |= dil[:, :-1]
+            nxt[:, :-1] |= dil[:, 1:]
+            dil = nxt
+        dil[:r, :] = False
+        dil[Hp - r:, :] = False
+        dil[:, :r] = False
+        dil[:, Wp - r:] = False
+        ys, xs = np.nonzero(dil)
+        return np.stack([ys, xs], axis=1).astype(np.int32)
+
+    def _init_nnf(self, feat, targets, index, rng):
+        Hp, Wp = feat.shape[:2]
+        coords = np.zeros((Hp, Wp, 2), dtype=np.int32)
+        coords[:, :, 0] = np.arange(Hp)[:, None]
+        coords[:, :, 1] = np.arange(Wp)[None, :]
+        dist = np.full((Hp, Wp), np.inf)
+        # known pixels with a fully valid window are zero cost identity seeds
+        dist[index.source_ok] = 0.0
+        samples = index.sample(rng, len(targets))
+        for i, (y, x) in enumerate(targets):
+            sy, sx = int(samples[i, 0]), int(samples[i, 1])
+            coords[y, x] = (sy, sx)
+            dist[y, x] = self.scorer.distance(feat, y, x, sy, sx)
+        return coords, dist
+
+    def _refresh(self, feat, coords, dist, targets):
+        for (y, x) in targets:
+            sy, sx = int(coords[y, x, 0]), int(coords[y, x, 1])
+            dist[y, x] = self.scorer.distance(feat, y, x, sy, sx)
+
+    def _sweep(self, feat, coords, dist, targets, index, rng, reverse):
+        order = targets[::-1] if reverse else targets
+        delta = -1 if reverse else 1
+        r = self.radius
+        Hp, Wp = feat.shape[:2]
+        for (y, x) in order:
+            best_d = dist[y, x]
+            best = (int(coords[y, x, 0]), int(coords[y, x, 1]))
+            # propagation from two causal neighbours
+            for (ny, nx) in ((y - delta, x), (y, x - delta)):
+                if 0 <= ny < Hp and 0 <= nx < Wp and np.isfinite(dist[ny, nx]):
+                    cand = (int(coords[ny, nx, 0]) + (y - ny),
+                            int(coords[ny, nx, 1]) + (x - nx))
+                    if index.is_source_ok(*cand):
+                        d = self.scorer.distance(feat, y, x, cand[0], cand[1])
+                        if d < best_d:
+                            best_d, best = d, cand
+            # random search, exponentially shrinking window
+            w = max(Hp, Wp)
+            while w >= 1:
+                cy = best[0] + int(rng.integers(-w, w + 1))
+                cx = best[1] + int(rng.integers(-w, w + 1))
+                if index.is_source_ok(cy, cx):
+                    d = self.scorer.distance(feat, y, x, cy, cx)
+                    if d < best_d:
+                        best_d, best = d, (cy, cx)
+                w //= 2
+            coords[y, x] = best
+            dist[y, x] = best_d
+
+    def _vote(self, feat, hole, coords, dist, targets):
+        r = self.radius
+        Hp, Wp, C = feat.shape
+        acc = np.zeros((Hp, Wp, C), dtype=np.float64)
+        wsum = np.zeros((Hp, Wp, 1), dtype=np.float64)
+        # Weight scale from the *nonzero* target distances only. Known pixel
+        # identity seeds sit at distance 0 and would otherwise pin the median to
+        # 0, collapsing every real match's weight to ~0 and freezing the fill.
+        target_dists = dist[targets[:, 0], targets[:, 1]]
+        nonzero_target_dists = target_dists[np.isfinite(target_dists) & (target_dists > 1e-9)]
+        weight_variance = (2.0 * (np.median(nonzero_target_dists) + 1e-6)
+                          if nonzero_target_dists.size else 1.0)
+        for (y, x) in targets:
+            d = dist[y, x]
+            if not np.isfinite(d):
+                continue
+            sy, sx = int(coords[y, x, 0]), int(coords[y, x, 1])
+            w = np.exp(-d / (weight_variance + 1e-9))
+            src = feat[sy - r:sy + r + 1, sx - r:sx + r + 1]
+            acc[y - r:y + r + 1, x - r:x + r + 1] += w * src
+            wsum[y - r:y + r + 1, x - r:x + r + 1] += w
+        out = feat.copy()
+        filled = (wsum[:, :, 0] > 0) & hole
+        recon = acc / np.maximum(wsum, 1e-9)
+        out[filled] = recon[filled]
+        return out

object_remove/fillengines/self_similar_shift.py

@@ -0,0 +1,368 @@
+"""Tier 2 — self similar rigid shift + seam carve.
+
+Pipeline:
+  1. ORB = FAST corners + 256 bit BRIEF descriptors + Hamming matching.
+  2. ``find_far_and_similar_points`` — a keypoint pair that is visually similar
+     but spatially far gives a candidate *rigid translation* (dx, dy) that copies
+     a self similar chunk of the image over the hole. Run twice (coarse/refine).
+  3. Score candidate offsets by border band SSD (continuity across the hole edge)
+     with a validity constraint, then copy the shifted block over the hole.
+  4. A dynamic programming seam carve (``compute_path``) cuts the copied block
+     in cleanly, computed once for x, then again for y by *transposing the
+     image and transposing back*, so the same 1D seam routine handles both axes.
+
+This is the cheap, good enough default path for homogeneous/repetitive texture
+(grass, sky, brick, wood). The final feather/blend is left to Stage E.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+from ..imageutil import as_float_rgb, rgb_to_gray
+from ..pyramid.image_pyramid import gaussian_blur
+
+
+# ==========================================================================
+# ORB: FAST corners + BRIEF descriptors + Hamming matching
+# ==========================================================================
+_FAST_CIRCLE = [(0, -3), (1, -3), (2, -2), (3, -1), (3, 0), (3, 1), (2, 2),
+                (1, 3), (0, 3), (-1, 3), (-2, 2), (-3, 1), (-3, 0), (-3, -1),
+                (-2, -2), (-1, -3)]
+
+
+@dataclass
+class BriefKeyPoint:
+    y: int
+    x: int
+    descriptor: np.ndarray  # (32,) uint8 packed = 256 bits
+
+
+def fast_corners(gray: np.ndarray, valid: np.ndarray, threshold: float = 0.06,
+                 n_contig: int = 9, border: int = 16) -> List[Tuple[int, int]]:
+    """FAST 9 corner detector over valid pixels only."""
+    H, W = gray.shape
+    pts: List[Tuple[int, int]] = []
+    circ = _FAST_CIRCLE
+    for y in range(border, H - border):
+        for x in range(border, W - border):
+            if not valid[y, x]:
+                continue
+            center_val = gray[y, x]
+            hi = center_val + threshold
+            lo = center_val - threshold
+            # quick reject on the 4 compass points
+            reject_count = 0
+            for dx, dy in (circ[0], circ[4], circ[8], circ[12]):
+                v = gray[y + dy, x + dx]
+                if v > hi or v < lo:
+                    reject_count += 1
+            if reject_count < 3:
+                continue
+            states = []
+            for dx, dy in circ:
+                v = gray[y + dy, x + dx]
+                states.append(1 if v > hi else (-1 if v < lo else 0))
+            if _has_contiguous(states, n_contig):
+                pts.append((y, x))
+    return pts
+
+
+def _has_contiguous(states: List[int], n: int) -> bool:
+    ext = states + states[:n - 1]
+    for sgn in (1, -1):
+        run = 0
+        for s in ext:
+            if s == sgn:
+                run += 1
+                if run >= n:
+                    return True
+            else:
+                run = 0
+    return False
+
+
+def _brief_pattern(patch: int = 15, n_bits: int = 256, seed: int = 42) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    return rng.integers(-patch, patch + 1, size=(n_bits, 4)).astype(np.int32)
+
+
+_BRIEF = _brief_pattern()
+
+
+def brief_descriptors(gray: np.ndarray, pts: List[Tuple[int, int]]) -> List[BriefKeyPoint]:
+    """256 bit BRIEF on a smoothed image, packed into 32 uint8 bytes."""
+    sm = gaussian_blur(gray)
+    H, W = sm.shape
+    out: List[BriefKeyPoint] = []
+    pat = _BRIEF
+    for (y, x) in pts:
+        bits = np.zeros(256, dtype=np.uint8)
+        for i in range(256):
+            ay = np.clip(y + pat[i, 1], 0, H - 1)
+            ax = np.clip(x + pat[i, 0], 0, W - 1)
+            by = np.clip(y + pat[i, 3], 0, H - 1)
+            bx = np.clip(x + pat[i, 2], 0, W - 1)
+            bits[i] = 1 if sm[ay, ax] < sm[by, bx] else 0
+        packed = np.packbits(bits)
+        out.append(BriefKeyPoint(y, x, packed))
+    return out
+
+
+def hamming(a: np.ndarray, b: np.ndarray) -> np.ndarray:
+    """Hamming distance between packed descriptor ``a`` (32,) and rows of ``b`` (N,32)."""
+    return np.bitwise_count(np.bitwise_xor(b, a[None, :])).sum(axis=1)
+
+
+# ==========================================================================
+# offset proposal
+# ==========================================================================
+def find_far_and_similar_points(kps: List[BriefKeyPoint], hole_bbox,
+                                min_offset: int, max_pairs: int = 40
+                                ) -> List[Tuple[int, int]]:
+    """Propose rigid (oy, ox) offsets from visually similar, spatially far pairs.
+
+    For keypoints near the hole, find the descriptor nearest keypoint that lies
+    at least ``min_offset`` away; the vector between them is a candidate shift.
+    """
+    if len(kps) < 2:
+        return []
+    y0, x0, y1, x1 = hole_bbox
+    cy, cx = (y0 + y1) / 2, (x0 + x1) / 2
+    db = np.stack([k.descriptor for k in kps])
+    coords = np.array([(k.y, k.x) for k in kps])
+    # anchors: keypoints closest to the hole (best boundary continuity)
+    d_to_hole = np.hypot(coords[:, 0] - cy, coords[:, 1] - cx)
+    anchor_idx = np.argsort(d_to_hole)[:max_pairs]
+    offsets: List[Tuple[int, int]] = []
+    for ai in anchor_idx:
+        dists = hamming(db[ai], db)
+        far = np.hypot(coords[:, 0] - coords[ai, 0],
+                       coords[:, 1] - coords[ai, 1]) >= min_offset
+        cand = np.where(far)[0]
+        if cand.size == 0:
+            continue
+        best = cand[np.argmin(dists[cand])]
+        oy = int(coords[best, 0] - coords[ai, 0])
+        ox = int(coords[best, 1] - coords[ai, 1])
+        offsets.append((oy, ox))
+    return offsets
+
+
+# ==========================================================================
+# DP seam carving (computePath) + transpose trick
+# ==========================================================================
+def compute_path(energy: np.ndarray) -> np.ndarray:
+    """Min cost vertical seam via DP. Returns one column index per row."""
+    h, w = energy.shape
+    cost = energy.astype(np.float64).copy()
+    back = np.zeros((h, w), dtype=np.int32)
+    for y in range(1, h):
+        for x in range(w):
+            xl = max(0, x - 1)
+            xr = min(w - 1, x + 1)
+            choices = cost[y - 1, xl:xr + 1]
+            k = int(np.argmin(choices))
+            back[y, x] = xl + k
+            cost[y, x] += choices[k]
+    seam = np.zeros(h, dtype=np.int32)
+    seam[-1] = int(np.argmin(cost[-1]))
+    for y in range(h - 2, -1, -1):
+        seam[y] = back[y + 1, seam[y + 1]]
+    return seam
+
+
+def transpose_texture(img: np.ndarray) -> np.ndarray:
+    if img.ndim == 3:
+        return np.transpose(img, (1, 0, 2))
+    return img.T
+
+
+# ==========================================================================
+# engine
+# ==========================================================================
+class SelfSimilarShiftEngine:
+    def __init__(self, margin: int = 8, fast_threshold: float = 0.06,
+                 brute_step: int = 6):
+        self.margin = margin
+        self.fast_threshold = fast_threshold
+        self.brute_step = brute_step
+        # border continuity SSD of the chosen offset; low => good self similarity.
+        # Read by the pipeline's AUTO tier gate. inf means no valid offset found.
+        self.last_border_score: float = float("inf")
+
+    def fill(self, image: np.ndarray, mask: np.ndarray,
+             progress=None, cancel=None) -> np.ndarray:
+        img = as_float_rgb(image).astype(np.float64)
+        hole = np.ascontiguousarray(mask > 0)
+        H, W = hole.shape
+        if not hole.any():
+            return img.copy()
+
+        ys, xs = np.nonzero(hole)
+        bbox = (int(ys.min()), int(xs.min()), int(ys.max()) + 1, int(xs.max()) + 1)
+        hole_span = max(bbox[3] - bbox[1], bbox[2] - bbox[0])
+
+        gray = rgb_to_gray(img.astype(np.float32))
+        valid = ~hole
+        if progress:
+            progress(0.1)
+
+        # ORB: corners + descriptors
+        corners = fast_corners(gray, valid, self.fast_threshold, border=16)
+        kps = brief_descriptors(gray, corners)
+        if progress:
+            progress(0.4)
+
+        # candidate offsets: coarse then refine pass
+        candidates: List[Tuple[int, int]] = []
+        candidates += find_far_and_similar_points(kps, bbox, min_offset=int(1.5 * hole_span))
+        candidates += find_far_and_similar_points(kps, bbox, min_offset=max(4, hole_span // 2))
+        candidates += self._brute_offsets(hole_span, H, W)
+        candidates = list({(int(o[0]), int(o[1])) for o in candidates if o != (0, 0)})
+
+        best, best_score = self._pick_offset(img, hole, bbox, candidates)
+        self.last_border_score = best_score
+        if best is None:
+            return img.copy()  # nothing valid; caller may fall back to another tier
+        if progress:
+            progress(0.7)
+
+        filled = self._composite_with_seam(img, hole, bbox, best)
+        if progress:
+            progress(1.0)
+        return filled
+
+    def _brute_offsets(self, hole_span, H, W) -> List[Tuple[int, int]]:
+        """A coarse grid of translations as a fallback when ORB is sparse."""
+        step = max(self.brute_step, hole_span // 2)
+        offs = []
+        rng = range(-max(hole_span + self.margin, 2 * step),
+                    max(hole_span + self.margin, 2 * step) + 1, step)
+        for oy in rng:
+            for ox in rng:
+                if abs(oy) + abs(ox) >= hole_span:
+                    offs.append((oy, ox))
+        return offs
+
+    def _pick_offset(self, img, hole, bbox, candidates):
+        H, W = hole.shape
+        y0, x0, y1, x1 = bbox
+        by0, bx0 = max(0, y0 - self.margin), max(0, x0 - self.margin)
+        by1, bx1 = min(H, y1 + self.margin), min(W, x1 + self.margin)
+        band = np.zeros((H, W), dtype=bool)
+        band[by0:by1, bx0:bx1] = True
+        band &= ~hole  # known context ring around the hole
+        band_idx = np.nonzero(band)
+        bys, bxs = band_idx
+        best_score = np.inf
+        best = None
+        for (oy, ox) in candidates:
+            sy = bys - oy
+            sx = bxs - ox
+            ok = (sy >= 0) & (sy < H) & (sx >= 0) & (sx < W)
+            if ok.mean() < 0.9:
+                continue
+            syo, sxo, byo, bxo = sy[ok], sx[ok], bys[ok], bxs[ok]
+            src_valid = ~hole[syo, sxo]
+            if src_valid.mean() < 0.9:
+                continue
+            d = img[byo, bxo] - img[syo, sxo]
+            score = float((d * d).sum(axis=1)[src_valid].mean())
+            if not self._hole_source_valid(hole, bbox, oy, ox):
+                continue
+            if score < best_score:
+                best_score = score
+                best = (oy, ox)
+        return best, best_score
+
+    @staticmethod
+    def _hole_source_valid(hole, bbox, oy, ox, min_frac=0.97):
+        H, W = hole.shape
+        ys, xs = np.nonzero(hole)
+        sy, sx = ys - oy, xs - ox
+        ok = (sy >= 0) & (sy < H) & (sx >= 0) & (sx < W)
+        if ok.mean() < min_frac:
+            return False
+        src_hole = np.ones(len(ys), dtype=bool)
+        src_hole[ok] = hole[sy[ok], sx[ok]]
+        return (~src_hole).mean() >= min_frac
+
+    def _composite_with_seam(self, img, hole, bbox, offset):
+        H, W = hole.shape
+        oy, ox = offset
+        out = img.copy()
+        copied = self._shift(img, oy, ox)
+
+        y0, x0, y1, x1 = bbox
+        ry0, rx0 = max(0, y0 - self.margin), max(0, x0 - self.margin)
+        ry1, rx1 = min(H, y1 + self.margin), min(W, x1 + self.margin)
+
+        # per pixel energy = colour difference between original and copied
+        diff = ((img - copied) ** 2).sum(axis=2)
+
+        use_copied = hole.copy()
+        region = np.zeros((H, W), dtype=bool)
+        region[ry0:ry1, rx0:rx1] = True
+
+        # x direction seams: trim left & right margins
+        use_copied |= self._side_seam(diff, hole, region, axis="left")
+        use_copied |= self._side_seam(diff, hole, region, axis="right")
+        # y direction via transpose
+        diff_t = transpose_texture(diff)
+        hole_t = transpose_texture(hole)
+        region_t = transpose_texture(region)
+        top = self._side_seam(diff_t, hole_t, region_t, axis="left")
+        bot = self._side_seam(diff_t, hole_t, region_t, axis="right")
+        use_copied |= transpose_texture(top)
+        use_copied |= transpose_texture(bot)
+
+        use_copied &= region  # never touch pixels outside the working region
+        use_copied |= hole
+        out[use_copied] = copied[use_copied]
+        return out
+
+    @staticmethod
+    def _shift(img, oy, ox):
+        """Shift image so that out[y,x] = img[y-oy, x-ox] (edge clamped)."""
+        H, W = img.shape[:2]
+        ys = np.clip(np.arange(H) - oy, 0, H - 1)
+        xs = np.clip(np.arange(W) - ox, 0, W - 1)
+        return img[np.ix_(ys, xs)]
+
+    def _side_seam(self, diff, hole, region, axis: str) -> np.ndarray:
+        """Find a min energy vertical seam in the left/right margin strip.
+
+        Returns a mask of pixels that should take the copied block, bounded by
+        the seam (between the hole edge and the region edge).
+        """
+        H, W = hole.shape
+        rys, rxs = np.nonzero(region)
+        if rys.size == 0:
+            return np.zeros((H, W), dtype=bool)
+        ry0, ry1 = rys.min(), rys.max() + 1
+        rx0, rx1 = rxs.min(), rxs.max() + 1
+        out = np.zeros((H, W), dtype=bool)
+        for y in range(ry0, ry1):
+            hx = np.nonzero(hole[y])[0]
+            if hx.size == 0:
+                continue
+            if axis == "left":
+                strip_x0, strip_x1 = rx0, hx.min()
+            else:
+                strip_x0, strip_x1 = hx.max() + 1, rx1
+            if strip_x1 <= strip_x0:
+                continue
+            strip = diff[ry0:ry1, strip_x0:strip_x1]
+            # cheap per row seam via cumulative min DP done once over the strip
+            seam = compute_path(strip)
+            yy = y - ry0
+            cut = strip_x0 + seam[yy]
+            if axis == "left":
+                out[y, cut:strip_x1] = True
+            else:
+                out[y, strip_x0:cut + 1] = True
+        return out

object_remove/imageutil.py

@@ -0,0 +1,59 @@
+"""Small shared image helpers: I/O and type conversions.
+
+Images inside the pipeline are ``float32`` arrays in ``[0, 1]`` with shape
+``(H, W, 3)`` for RGB. Masks are ``uint8`` / ``bool`` arrays of shape ``(H, W)``
+where nonzero means "inside the hole to be filled".
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def load_image(path: str) -> np.ndarray:
+    """Load an image as float32 RGB in [0, 1]."""
+    from PIL import Image
+
+    img = Image.open(path).convert("RGB")
+    return np.asarray(img, dtype=np.float32) / 255.0
+
+
+def save_image(path: str, image: np.ndarray) -> None:
+    """Save a float32 RGB [0, 1] image."""
+    from PIL import Image
+
+    arr = to_uint8(image)
+    Image.fromarray(arr, mode="RGB").save(path)
+
+
+def to_uint8(image: np.ndarray) -> np.ndarray:
+    return np.clip(image * 255.0 + 0.5, 0, 255).astype(np.uint8)
+
+
+def as_float_rgb(image: np.ndarray) -> np.ndarray:
+    """Normalise an arbitrary input array to float32 RGB in [0, 1]."""
+    arr = np.asarray(image)
+    if arr.dtype == np.uint8:
+        arr = arr.astype(np.float32) / 255.0
+    else:
+        arr = arr.astype(np.float32)
+    if arr.ndim == 2:
+        arr = np.repeat(arr[:, :, None], 3, axis=2)
+    if arr.shape[2] == 4:
+        arr = arr[:, :, :3]
+    return np.ascontiguousarray(arr)
+
+
+def rgb_to_gray(image: np.ndarray) -> np.ndarray:
+    """ITU-R 601-2 luma. Input float RGB, output float (H, W)."""
+    w = np.array([0.299, 0.587, 0.114], dtype=np.float32)
+    return image.reshape(-1, 3).dot(w).reshape(image.shape[:2])
+
+
+def clamp_rect(x: int, y: int, rect_w: int, rect_h: int, width: int, height: int):
+    """Clamp a rectangle to image bounds; return (x0, y0, x1, y1) exclusive."""
+    x0 = max(0, x)
+    y0 = max(0, y)
+    x1 = min(width, x + rect_w)
+    y1 = min(height, y + rect_h)
+    return x0, y0, x1, y1

object_remove/mask/__init__.py

@@ -0,0 +1,22 @@
+"""Stage A — mask acquisition & refinement.
+
+Selections are polygon/scanline based, with a raster mask as a *cached
+derivative*: :class:`PolygonSelection` is the primary representation (exact,
+resolution independent boolean ops), and a raster mask is generated on demand
+for consumption by the fill/render stages.
+"""
+
+from .polygon_selection import PolygonSelection
+from .brush_rasterizer import BrushRasterizer
+from .selection_enhancer import SelectionEnhancer
+from .connected_components import label_components, split_components
+from .auto_select import AutoSelectModel
+
+__all__ = [
+    "PolygonSelection",
+    "BrushRasterizer",
+    "SelectionEnhancer",
+    "label_components",
+    "split_components",
+    "AutoSelectModel",
+]

object_remove/mask/auto_select.py

@@ -0,0 +1,84 @@
+"""AI assisted auto select — the "tap to select" front end.
+
+A real deployment would back this with a quantised segmentation model (a
+generic one, or a person specific variant for portrait selection). This
+module defines the clean interface such a model would plug into and provides
+a **working, dependency free fallback**: a tap seeded flood fill over color
+similarity, so tap to select runs end to end without shipping any model
+weights.
+
+To wire a real model, subclass :class:`AutoSelectModel` and override
+:meth:`segment`.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Optional, Tuple
+
+import numpy as np
+
+from ..imageutil import as_float_rgb, rgb_to_gray
+
+
+class AutoSelectModel:
+    """Interface for tap/box to segmentation mask.
+
+    ``backend`` is informational; the base class runs the color flood fallback.
+    A real deployment would pass ``backend="deeplabv3_int8"`` (generic) or
+    ``backend="human_seg"`` (the person specific variant) and load quantised
+    weights in an override.
+    """
+
+    def __init__(self, backend: str = "color_flood_fallback"):
+        self.backend = backend
+
+    def segment(self, image: np.ndarray, seed: Tuple[int, int],
+                tolerance: float = 0.10, max_area_frac: float = 0.6) -> np.ndarray:
+        """Return a boolean object mask from a tap ``seed`` = (x, y).
+
+        Base implementation: region grow flood fill in color space, capped so a
+        runaway grow can't select the whole frame.
+        """
+        img = as_float_rgb(image)
+        return self._color_flood(img, seed, tolerance, max_area_frac)
+
+    def segment_box(self, image: np.ndarray, box: Tuple[int, int, int, int],
+                    tolerance: float = 0.12) -> np.ndarray:
+        """Segment the dominant object inside a box (x0, y0, x1, y1).
+
+        Seeds the flood from the box centre, a stand in for the model's
+        box prompt path.
+        """
+        x0, y0, x1, y1 = box
+        seed = ((x0 + x1) // 2, (y0 + y1) // 2)
+        return self.segment(image, seed, tolerance)
+
+    @staticmethod
+    def _color_flood(img: np.ndarray, seed: Tuple[int, int],
+                     tolerance: float, max_area_frac: float) -> np.ndarray:
+        h, w = img.shape[:2]
+        seed_x, seed_y = int(seed[0]), int(seed[1])
+        mask = np.zeros((h, w), dtype=bool)
+        if not (0 <= seed_x < w and 0 <= seed_y < h):
+            return mask
+        seed_color = img[seed_y, seed_x]
+        tolerance_sq_threshold = tolerance * tolerance * 3.0  # sum over 3 channels
+        max_pixels = int(max_area_frac * h * w)
+
+        visited = np.zeros((h, w), dtype=bool)
+        frontier = deque([(seed_x, seed_y)])
+        visited[seed_y, seed_x] = True
+        count = 0
+        while frontier and count < max_pixels:
+            x, y = frontier.popleft()
+            diff = img[y, x] - seed_color
+            if float(diff.dot(diff)) > tolerance_sq_threshold:
+                continue
+            mask[y, x] = True
+            count += 1
+            for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
+                if 0 <= nx < w and 0 <= ny < h and not visited[ny, nx]:
+                    visited[ny, nx] = True
+                    frontier.append((nx, ny))
+        return mask