object-remove 0.2.0__tar.gz → 0.2.2__tar.gz

{object_remove-0.2.0 → object_remove-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: object-remove
-Version: 0.2.0
+Version: 0.2.2
 Summary: From-scratch reference implementation of a tiered on-device object-removal pipeline, CPU and GPU
 Author: shalaga44
 License-Expression: MIT
@@ -31,6 +31,8 @@ Dynamic: license-file
 
 # object_remove
 
+[![PyPI](https://img.shields.io/pypi/v/object-remove.svg)](https://pypi.org/project/object-remove/)
+
 A from scratch implementation of an on device object removal pipeline (see
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full design): a
 polygon/scanline mask layer, **four fill engines** of increasing

{object_remove-0.2.0 → object_remove-0.2.2}/README.md

@@ -1,5 +1,7 @@
 # object_remove
 
+[![PyPI](https://img.shields.io/pypi/v/object-remove.svg)](https://pypi.org/project/object-remove/)
+
 A from scratch implementation of an on device object removal pipeline (see
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full design): a
 polygon/scanline mask layer, **four fill engines** of increasing

{object_remove-0.2.0 → object_remove-0.2.2}/object_remove/__init__.py

@@ -15,7 +15,7 @@ Public entry point::
 import importlib
 from typing import Any
 
-__version__ = "0.1.0"
+__version__ = "0.2.2"
 
 # Lazy attribute map: name maps to (submodule, attribute). Loaded on first access so
 # importing any subpackage never eagerly drags in the whole tree.

{object_remove-0.2.0 → object_remove-0.2.2}/object_remove/cv/orb.py

@@ -31,12 +31,15 @@ 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.
 
-    The per pixel Python loop scales with total image area, not hole size,
-    so it dominates on large photos. The 4 point compass quick reject (which
-    only needs to prune candidates, not decide corners) is vectorised over
-    the whole interior at once via shifted slices; the expensive full 16
-    point contiguous arc test then runs only on the much smaller surviving
-    candidate set, with identical semantics to the scalar version.
+    Both the 4 point compass quick reject and the full 16 point contiguous
+    arc test are vectorised over the whole interior at once via shifted
+    slices, rather than looping per candidate pixel in Python -- a Python
+    loop there would scale with total image area (not hole size), dominating
+    runtime on large photos. The arc test still needs a loop to walk the 16
+    (+n_contig-1 wrap-around) circle taps and accumulate the longest same
+    sign run, but that loop is a fixed ~24 iterations regardless of image
+    size, with each iteration a single vectorised array op over every
+    interior pixel at once -- identical semantics to the scalar version.
     """
     H, W = gray.shape
     circ = _FAST_CIRCLE
@@ -57,35 +60,26 @@ def fast_corners(gray: np.ndarray, valid: np.ndarray, threshold: float = 0.06,
         reject += (v > hi) | (v < lo)
 
     cand = (reject >= 3) & valid[iy0:iy1, ix0:ix1]
-    cys, cxs = np.nonzero(cand)
-
-    pts: List[Tuple[int, int]] = []
-    for cy, cx in zip(cys, cxs):
-        y, x = int(cy) + iy0, int(cx) + ix0
-        center_val = gray[y, x]
-        chi = center_val + threshold
-        clo = center_val - threshold
-        states = []
-        for dx, dy in circ:
-            v = gray[y + dy, x + dx]
-            states.append(1 if v > chi else (-1 if v < clo 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]
+    if not cand.any():
+        return []
+
+    states = np.empty((len(circ),) + center.shape, dtype=np.int8)
+    for i, (dx, dy) in enumerate(circ):
+        v = shifted(dx, dy)
+        states[i] = np.where(v > hi, 1, np.where(v < lo, -1, 0))
+
+    # circular wrap-around, same as `states + states[:n_contig - 1]` in the
+    # scalar version's per-point list
+    ext = np.concatenate([states, states[:n_contig - 1]], axis=0)
+    found = np.zeros(center.shape, dtype=bool)
     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
+        run = np.zeros(center.shape, dtype=np.int32)
+        for i in range(ext.shape[0]):
+            run = np.where(ext[i] == sgn, run + 1, 0)
+            found |= run >= n_contig
+
+    cys, cxs = np.nonzero(cand & found)
+    return [(int(cy) + iy0, int(cx) + ix0) for cy, cx in zip(cys, cxs)]
 
 
 def _brief_pattern(patch: int = 15, n_bits: int = 256, seed: int = 42) -> np.ndarray:
@@ -97,26 +91,28 @@ _BRIEF = _brief_pattern()
 
 
 def brief_descriptors(gray: np.ndarray, pts: List[Tuple[int, int]]) -> List[Keypoint]:
-    """256 bit BRIEF on a smoothed image, packed into 32 uint8 bytes."""
+    """256 bit BRIEF on a smoothed image, packed into 32 uint8 bytes.
+
+    Bit computation is vectorised across all points *and* all 256 pattern
+    taps at once (one (N, 256) gather + compare + packbits), instead of a
+    per point Python loop each doing its own small array ops -- per call
+    overhead there dominates runtime for images with many keypoints.
+    """
+    if not pts:
+        return []
     sm = gaussian_blur(gray)
     H, W = sm.shape
-    out: List[Keypoint] = []
     pat = _BRIEF
-    # Per point bit computation is vectorised across all 256 pattern taps at
-    # once: the equivalent scalar per bit loop spends almost all its time in
-    # per element np.clip() call overhead (measured ~19x slower than a single
-    # array clip of the same size), which dominates runtime for images with
-    # many keypoints.
+    pys = np.asarray([p[0] for p in pts], dtype=np.int64)[:, None]
+    pxs = np.asarray([p[1] for p in pts], dtype=np.int64)[:, None]
     pax, pay, pbx, pby = pat[:, 0], pat[:, 1], pat[:, 2], pat[:, 3]
-    for (y, x) in pts:
-        ay = np.clip(y + pay, 0, H - 1)
-        ax = np.clip(x + pax, 0, W - 1)
-        by = np.clip(y + pby, 0, H - 1)
-        bx = np.clip(x + pbx, 0, W - 1)
-        bits = (sm[ay, ax] < sm[by, bx]).astype(np.uint8)
-        packed = np.packbits(bits)
-        out.append(Keypoint(y, x, packed))
-    return out
+    ay = np.clip(pys + pay[None, :], 0, H - 1)
+    ax = np.clip(pxs + pax[None, :], 0, W - 1)
+    by = np.clip(pys + pby[None, :], 0, H - 1)
+    bx = np.clip(pxs + pbx[None, :], 0, W - 1)
+    bits = (sm[ay, ax] < sm[by, bx]).astype(np.uint8)  # (N, 256)
+    packed = np.packbits(bits, axis=1)  # (N, 32)
+    return [Keypoint(y, x, packed[i]) for i, (y, x) in enumerate(pts)]
 
 
 def hamming(a: np.ndarray, b: np.ndarray) -> np.ndarray:

{object_remove-0.2.0 → object_remove-0.2.2}/object_remove/effects/perspective_correction.py

@@ -99,6 +99,25 @@ def _bilinear_sample(image: np.ndarray, xs: np.ndarray, ys: np.ndarray) -> np.nd
     return out
 
 
+def bilinear_resize(image: np.ndarray, out_shape: Tuple[int, int]) -> np.ndarray:
+    """Plain bilinear resize to ``out_shape`` (oh, ow) -- pixel-center mapping
+    with clamped borders, not a homography warp. Shared by callers that need
+    an arbitrary-scale resize (e.g. the selection enhancer's pyramid blur)
+    without duplicating the bilinear-sample math."""
+    ih, iw = image.shape[:2]
+    oh, ow = out_shape
+    yy, xx = np.mgrid[0:oh, 0:ow]
+    src_x = np.clip((xx.astype(np.float64) + 0.5) * (iw / ow) - 0.5, 0.0, iw - 1)
+    src_y = np.clip((yy.astype(np.float64) + 0.5) * (ih / oh) - 0.5, 0.0, ih - 1)
+    img = image.astype(np.float64)
+    squeeze = img.ndim == 2
+    if squeeze:
+        img = img[:, :, None]
+    sampled = _bilinear_sample(img, src_x.ravel(), src_y.ravel())
+    sampled = sampled.reshape(oh, ow, -1)
+    return sampled[:, :, 0] if squeeze else sampled
+
+
 def map_image(image: np.ndarray, H: np.ndarray, out_shape: Tuple[int, int]) -> np.ndarray:
     """Warp ``image`` through ``H`` (src -> dst) into an image of
     ``out_shape``, via inverse mapping + bilinear sampling."""

{object_remove-0.2.0 → object_remove-0.2.2}/object_remove/fillengines/primary/patch_grid_solver_gpu.py

@@ -52,6 +52,37 @@ def _gather_windows(field: torch.Tensor, centers: torch.Tensor, r: int) -> torch
     return field[ys, xs]
 
 
+def _local_src_mask(source_coords: torch.Tensor, base_mask: torch.Tensor,
+                    layer_centers: torch.Tensor, margin0: int, cap: int) -> torch.Tensor:
+    """Restrict `base_mask` (already reuse-filtered) to a spatial window
+    around this layer's own centres, doubling the window until it actually
+    contains a candidate (or giving up at `cap` and returning `base_mask`
+    unrestricted). Nearby sources are always at least as good a match as far
+    ones for real photos, so this changes only which near-tied candidate wins
+    - not whether a good one is found.
+
+    Without this, every layer's (T, S) search scans every valid pixel in the
+    whole image (`_best_sources_batch` below), which is fine for a small hole
+    but is the dominant cost for a thick one: a hole this solver treats as
+    ``H`` boundary-distance layers deep (see `_hole_layers`) does that full
+    scan ``H`` times, and a hole a few hundred pixels thick (e.g. a wide,
+    mostly-flat padding bar) turns into a multi-minute solve on a search that
+    only ever needed its own neighbourhood."""
+    cy0 = int(layer_centers[:, 0].min())
+    cy1 = int(layer_centers[:, 0].max())
+    cx0 = int(layer_centers[:, 1].min())
+    cx1 = int(layer_centers[:, 1].max())
+    margin = margin0
+    while margin < cap:
+        spatial = ((source_coords[:, 0] >= cy0 - margin) & (source_coords[:, 0] <= cy1 + margin) &
+                  (source_coords[:, 1] >= cx0 - margin) & (source_coords[:, 1] <= cx1 + margin))
+        combined = base_mask & spatial
+        if combined.any():
+            return combined
+        margin *= 2
+    return base_mask
+
+
 def _best_sources_batch(working: torch.Tensor, known: torch.Tensor,
                         target_centers: torch.Tensor, source_coords: torch.Tensor,
                         src_mask: torch.Tensor, r: int):
@@ -136,6 +167,8 @@ class TorchPrimaryFillEngineImpl:
         records: List[PatchCopyRecord] = []
         total = max(1, len(centers_np))
         processed = 0
+        local_margin0 = max(4 * r, 16)
+        local_cap = max(H, W)
 
         for layer_id in np.unique(center_layers):
             if cancel is not None and cancel():
@@ -144,6 +177,8 @@ class TorchPrimaryFillEngineImpl:
             layer_centers = centers[idx]
 
             src_mask = reuse_count < self.max_reuse
+            src_mask = _local_src_mask(source_coords, src_mask, layer_centers,
+                                       local_margin0, local_cap)
             best_idx, best_dist = _best_sources_batch(
                 working, known, layer_centers, source_coords, src_mask, r)
 

{object_remove-0.2.0 → object_remove-0.2.2}/object_remove/fillengines/primary/quad_tree_index.py

@@ -85,8 +85,10 @@ class QuadTreeIndex:
                 yield from self._iter_points(c)
 
     def all_points(self) -> np.ndarray:
-        idx = list(self._iter_points(self.root))
-        return self.coords[idx] if idx else np.empty((0, 2), dtype=np.int64)
+        # every index gets inserted into exactly one leaf at construction
+        # time (see __init__/_insert), so the full point set is always just
+        # self.coords -- no need to walk the tree to reconstruct it.
+        return self.coords
 
     def query_range(self, y0: int, x0: int, y1: int, x1: int) -> np.ndarray:
         """Points whose centre lies in ``[y0,y1) x [x0,x1)``, pruning whole
@@ -122,8 +124,15 @@ class QuadTreeIndex:
                                    ) -> Optional[Tuple[int, int]]:
         coords = self.all_points()
         if used and len(coords):
-            reuse_count = np.array([used.get((int(y), int(x)), 0) for y, x in coords])
-            coords = coords[reuse_count < max_reuse]
+            # linearise (y, x) -> y*W+x so the per-point dict.get in a Python
+            # loop becomes one vectorised membership test against just the
+            # (typically far smaller) set of sources that are actually
+            # over-used, rather than looping over every candidate in Python.
+            W = self.root.x1
+            overused = [k[0] * W + k[1] for k, v in used.items() if v >= max_reuse]
+            if overused:
+                coord_idx = coords[:, 0] * W + coords[:, 1]
+                coords = coords[~np.isin(coord_idx, overused)]
         return _best_match(image, ty, tx, coords, radius, target_valid)
 
 

{object_remove-0.2.0 → object_remove-0.2.2}/object_remove/fillengines/self_similar_shift.py

@@ -72,18 +72,27 @@ def _similar_far_offsets(kps: List[Keypoint], hole_bbox,
 # DP seam carving + transpose trick
 # ==========================================================================
 def min_cost_seam(energy: np.ndarray) -> np.ndarray:
-    """Min cost vertical seam via DP. Returns one column index per row."""
+    """Min cost vertical seam via DP. Returns one column index per row.
+
+    Row y only depends on row y-1, so the DP itself must stay a sequential
+    Python loop over rows; but within a row, each column's 3 way choice
+    (up-left/up/up-right) is independent of its neighbours' choices and is
+    vectorised across the whole row at once (edges padded with +inf so they
+    naturally fall back to the 2 candidate case), instead of an inner
+    per-column Python loop -- same argmin tie-breaking (favours the
+    lower-index candidate) as the scalar version.
+    """
     h, w = energy.shape
     cost = energy.astype(np.float64).copy()
     back = np.zeros((h, w), dtype=np.int32)
+    xs = np.arange(w)
     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]
+        prev = cost[y - 1]
+        padded = np.concatenate(([np.inf], prev, [np.inf]))
+        choices = np.stack([padded[0:w], padded[1:w + 1], padded[2:w + 2]])  # (3, w)
+        k = np.argmin(choices, axis=0)
+        back[y] = np.clip(xs + (k - 1), 0, w - 1)
+        cost[y] += choices[k, xs]
     seam = np.zeros(h, dtype=np.int32)
     seam[-1] = int(np.argmin(cost[-1]))
     for y in range(h - 2, -1, -1):
@@ -267,6 +276,12 @@ class SelfSimilarShiftEngine:
         ry0, ry1 = rys.min(), rys.max() + 1
         rx0, rx1 = rxs.min(), rxs.max() + 1
         out = np.zeros((H, W), dtype=bool)
+        # The DP always spans the same fixed row range (ry0:ry1); only the
+        # column bounds change with each row's hole extent. Rows sharing the
+        # same (strip_x0, strip_x1) -- typical for straight-ish hole edges --
+        # would otherwise resolve the identical DP from scratch once per row
+        # just to read off a single seam[yy] value, so cache by those bounds.
+        seam_cache: dict = {}
         for y in range(ry0, ry1):
             hx = np.nonzero(hole[y])[0]
             if hx.size == 0:
@@ -277,9 +292,12 @@ class SelfSimilarShiftEngine:
                 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 = min_cost_seam(strip)
+            key = (strip_x0, strip_x1)
+            seam = seam_cache.get(key)
+            if seam is None:
+                strip = diff[ry0:ry1, strip_x0:strip_x1]
+                seam = min_cost_seam(strip)
+                seam_cache[key] = seam
             yy = y - ry0
             cut = strip_x0 + seam[yy]
             if axis == "left":

object_remove-0.2.2/object_remove/mask/connected_components.py

@@ -0,0 +1,142 @@
+"""Connected component labelling.
+
+Labelling is a from scratch run-length union find (no
+``scipy.ndimage.label``): each row is decomposed into contiguous True runs,
+union-find operates over runs rather than individual pixels (a filled region
+has orders of magnitude fewer runs than pixels), and the final label write
+back is one vectorized numpy slice assignment per run. The per region
+*extraction* step is fanned out across a bounded thread pool so splitting a
+selection into its components stays fast on large masks.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+
+class _UnionFind:
+    __slots__ = ("parent",)
+
+    def __init__(self, n: int):
+        self.parent = list(range(n))
+
+    def find(self, x: int) -> int:
+        root = x
+        while self.parent[root] != root:
+            root = self.parent[root]
+        while self.parent[x] != root:
+            self.parent[x], x = root, self.parent[x]
+        return root
+
+    def union(self, a: int, b: int) -> None:
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.parent[max(ra, rb)] = min(ra, rb)
+
+
+def _row_runs(mask: np.ndarray) -> List[List[Tuple[int, int]]]:
+    """Per-row list of inclusive ``(start, end)`` True-run spans."""
+    h = mask.shape[0]
+    runs: List[List[Tuple[int, int]]] = []
+    for y in range(h):
+        row = mask[y]
+        if not row.any():
+            runs.append([])
+            continue
+        idx = np.flatnonzero(np.diff(np.concatenate(([0], row.view(np.int8), [0]))))
+        runs.append([(int(a), int(b) - 1) for a, b in zip(idx[0::2], idx[1::2])])
+    return runs
+
+
+def _label_dense(mask: np.ndarray, connectivity: int) -> Tuple[np.ndarray, int]:
+    """Run-based labelling over an already-cropped-to-content array."""
+    h, w = mask.shape
+    labels = np.zeros((h, w), dtype=np.int32)
+    row_runs = _row_runs(mask)
+
+    run_id: List[List[int]] = []
+    next_id = 0
+    for runs in row_runs:
+        run_id.append(list(range(next_id, next_id + len(runs))))
+        next_id += len(runs)
+    if next_id == 0:
+        return labels, 0
+    uf = _UnionFind(next_id)
+
+    diag = connectivity == 8
+    for y in range(1, h):
+        prev_runs, cur_runs = row_runs[y - 1], row_runs[y]
+        if not prev_runs or not cur_runs:
+            continue
+        i = j = 0
+        while i < len(prev_runs) and j < len(cur_runs):
+            p0, p1 = prev_runs[i]
+            c0, c1 = cur_runs[j]
+            touches = (p0 <= c1 + 1 and c0 <= p1 + 1) if diag else (p0 <= c1 and c0 <= p1)
+            if touches:
+                uf.union(run_id[y - 1][i], run_id[y][j])
+            if p1 < c1:
+                i += 1
+            else:
+                j += 1
+
+    remap: Dict[int, int] = {}
+    count = 0
+    for y, runs in enumerate(row_runs):
+        for j, (x0, x1) in enumerate(runs):
+            root = uf.find(run_id[y][j])
+            lab = remap.get(root)
+            if lab is None:
+                count += 1
+                lab = count
+                remap[root] = lab
+            labels[y, x0:x1 + 1] = lab
+    return labels, count
+
+
+def label_components(mask: np.ndarray, connectivity: int = 8) -> Tuple[np.ndarray, int]:
+    """Run-length union find labelling. Returns (labels, count).
+
+    ``labels`` is int32, 0 = background, 1..count = components. Cropped to
+    the mask's bounding box internally (a selection is usually a small
+    region of a much larger canvas) before labelling, then placed back.
+    """
+    mask = np.ascontiguousarray(mask > 0)
+    h, w = mask.shape
+    labels = np.zeros((h, w), dtype=np.int32)
+    if not mask.any():
+        return labels, 0
+    row_any = np.flatnonzero(mask.any(axis=1))
+    col_any = np.flatnonzero(mask.any(axis=0))
+    y0, y1 = int(row_any[0]), int(row_any[-1])
+    x0, x1 = int(col_any[0]), int(col_any[-1])
+    sub_labels, count = _label_dense(mask[y0:y1 + 1, x0:x1 + 1], connectivity)
+    labels[y0:y1 + 1, x0:x1 + 1] = sub_labels
+    return labels, count
+
+
+def split_components(mask: np.ndarray, max_selections: int = 0,
+                     min_area: int = 1, workers: int = 4) -> List[np.ndarray]:
+    """Split a mask into per component boolean masks.
+
+    Extraction is fanned across a bounded worker pool. ``max_selections`` (>0)
+    keeps only the largest N components; ``min_area`` drops specks.
+    """
+    labels, n = label_components(mask)
+    if n == 0:
+        return []
+
+    def extract(lab: int) -> np.ndarray:
+        return labels == lab
+
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as ex:
+        comps = list(ex.map(extract, range(1, n + 1)))
+
+    comps = [c for c in comps if int(c.sum()) >= min_area]
+    comps.sort(key=lambda c: int(c.sum()), reverse=True)
+    if max_selections and max_selections > 0:
+        comps = comps[:max_selections]
+    return comps

object_remove-0.2.2/object_remove/mask/scanline_selection.py

@@ -0,0 +1,123 @@
+"""Scanline/run-length selection model.
+
+A selection is a list of rows, each holding a sorted list of
+non-overlapping, non-adjacent inclusive ``(start, end)`` column spans.
+``add_region`` inserts a span via binary search and absorbs any spans that
+overlap or touch it. This is the data structure ``SelectionEnhancer.
+process_selection`` uses for the 15%-85% object-separation overlap gate.
+"""
+
+from __future__ import annotations
+
+import bisect
+from typing import List, Tuple
+
+import numpy as np
+
+Span = Tuple[int, int]
+
+
+class ScanlineSelection:
+    """Run-length selection over a fixed ``(height, width)`` canvas."""
+
+    def __init__(self, height: int, width: int):
+        self.height = height
+        self.width = width
+        self.rows: List[List[Span]] = [[] for _ in range(height)]
+
+    def add_region(self, row: int, x0: int, x1: int) -> None:
+        """Insert inclusive span ``[x0, x1]`` into ``row``, merging with any
+        overlapping or adjacent existing spans."""
+        if row < 0 or row >= self.height or x1 < x0:
+            return
+        x0 = max(0, x0)
+        x1 = min(self.width - 1, x1)
+        if x1 < x0:
+            return
+        spans = self.rows[row]
+        starts = [s[0] for s in spans]
+        idx = bisect.bisect_left(starts, x0)
+        j = idx
+        while j > 0 and spans[j - 1][1] >= x0 - 1:
+            j -= 1
+        k = idx
+        while k < len(spans) and spans[k][0] <= x1 + 1:
+            k += 1
+        new_start, new_end = x0, x1
+        if j < k:
+            new_start = min(new_start, spans[j][0])
+            new_end = max(new_end, spans[k - 1][1])
+        spans[j:k] = [(new_start, new_end)]
+
+    @classmethod
+    def from_mask(cls, mask: np.ndarray) -> "ScanlineSelection":
+        h, w = mask.shape
+        sel = cls(h, w)
+        mask = mask > 0
+        for y in range(h):
+            row = mask[y]
+            if not row.any():
+                continue
+            idx = np.flatnonzero(np.diff(np.concatenate(([0], row.view(np.int8), [0]))))
+            spans = [(int(a), int(b) - 1) for a, b in zip(idx[0::2], idx[1::2])]
+            sel.rows[y] = spans
+        return sel
+
+    def to_mask(self) -> np.ndarray:
+        mask = np.zeros((self.height, self.width), dtype=bool)
+        for y, spans in enumerate(self.rows):
+            for x0, x1 in spans:
+                mask[y, x0:x1 + 1] = True
+        return mask
+
+    def intersect(self, other: "ScanlineSelection") -> "ScanlineSelection":
+        """Per-row interval intersection."""
+        out = ScanlineSelection(self.height, self.width)
+        for y in range(min(self.height, other.height)):
+            a, b = self.rows[y], other.rows[y]
+            i = j = 0
+            result: List[Span] = []
+            while i < len(a) and j < len(b):
+                lo = max(a[i][0], b[j][0])
+                hi = min(a[i][1], b[j][1])
+                if lo <= hi:
+                    result.append((lo, hi))
+                if a[i][1] < b[j][1]:
+                    i += 1
+                else:
+                    j += 1
+            out.rows[y] = result
+        return out
+
+    def difference(self, other: "ScanlineSelection") -> "ScanlineSelection":
+        """Per-row interval subtraction: ``self`` minus ``other``."""
+        out = ScanlineSelection(self.height, self.width)
+        for y in range(self.height):
+            a = self.rows[y]
+            b = other.rows[y] if y < other.height else []
+            result: List[Span] = []
+            for x0, x1 in a:
+                cur = x0
+                for bx0, bx1 in b:
+                    if bx1 < cur or bx0 > x1:
+                        continue
+                    if bx0 > cur:
+                        result.append((cur, min(bx0 - 1, x1)))
+                    cur = max(cur, bx1 + 1)
+                    if cur > x1:
+                        break
+                if cur <= x1:
+                    result.append((cur, x1))
+            out.rows[y] = result
+        return out
+
+    def total_length(self) -> int:
+        return sum(x1 - x0 + 1 for spans in self.rows for x0, x1 in spans)
+
+    def row_overlap_ratio(self, other: "ScanlineSelection") -> float:
+        """Percentage of ``self``'s covered columns also covered by
+        ``other`` (used by the 15%-85% object-separation gate)."""
+        total = self.total_length()
+        if total == 0:
+            return 0.0
+        return self.intersect(other).total_length() / total * 100.0