ftw-fbp 0.1.0__py3-none-any.whl

fbp/__init__.py

@@ -0,0 +1,35 @@
+"""Field boundary prediction post-processing algorithms."""
+
+from fbp.methods import (
+    FTW_2E,
+    BoundaryVote,
+    ClosedComponents,
+    Components,
+    ExtentBoundaryThreshold,
+    FTPWatershed,
+    GaussianMixture,
+    IterativeWatershed,
+    Method,
+    OrientedWatershed,
+    StochasticWatershed,
+    UltrametricContours,
+    ftp_pipeline,
+)
+from fbp.windowed import run_windowed
+
+__all__ = [
+    "FTW_2E",
+    "BoundaryVote",
+    "ClosedComponents",
+    "Components",
+    "ExtentBoundaryThreshold",
+    "FTPWatershed",
+    "GaussianMixture",
+    "IterativeWatershed",
+    "Method",
+    "OrientedWatershed",
+    "StochasticWatershed",
+    "UltrametricContours",
+    "ftp_pipeline",
+    "run_windowed",
+]

fbp/core/__init__.py

@@ -0,0 +1 @@
+"""Shared geometry primitives every post-processing method is built from."""

fbp/core/fast_morph.py

@@ -0,0 +1,169 @@
+"""Integer versions of the two scikit-image calls that dominate BoundaryVote's runtime.
+
+On 5,120 x 5,120 production windows, ``h_maxima`` and ``watershed`` take 92% of
+BoundaryVote's time. When the surface is on the 1/255 grid of the uint8 probability
+rasters, both can run on integer levels.
+
+``h_maxima_itk`` uses ITK grayscale reconstruction by dilation. It gives the same
+result as scikit-image, checked on 5k and 9k windows, and runs about 10x faster on one
+thread. ``watershed_bucket`` floods with a bucket queue in O(N) under scikit-image's
+rules. Marker pixels of equal cost leave the queue in scan order rather than heap
+order, so the lines move only at exact ties (99.99% of pixels agree).
+
+Both reject surfaces that are not on the 1/255 grid. ``quantize_prob`` rounds a float
+softmax onto it, which is what storing it as uint8 does. ``Method(fast=True)`` does
+both.
+"""
+
+import numpy as np
+
+try:
+    import SimpleITK as sitk  # noqa: N813  (the package's own conventional alias)
+    from numba import njit
+except ImportError as e:
+    raise ImportError(
+        "fast=True needs the fast backend: pip install 'ftw-fbp[fast]'"
+    ) from e
+from skimage.morphology._util import _offsets_to_raveled_neighbors
+
+LEVELS = 255.0
+
+
+def quantize_prob(prob: np.ndarray) -> np.ndarray:
+    """Softmax rounded to 1/255 steps per class, as the uint8 production rasters do."""
+    return (np.rint(prob.astype(np.float32) * LEVELS) / LEVELS).astype(np.float32)
+
+
+def _to_levels(x: np.ndarray, name: str) -> np.ndarray:
+    u = np.rint(x * LEVELS)
+    if np.abs(x * LEVELS - u).max() > 0.25:  # fp16 error is ~0.06 levels
+        raise ValueError(
+            f"{name} is not on the 1/255 grid; quantize it with quantize_prob"
+        )
+    return u.astype(np.uint8)
+
+
+def h_maxima_itk(image: np.ndarray, h: float, footprint: None = None) -> np.ndarray:
+    """``skimage.morphology.h_maxima`` for a [0, 1] surface on the 1/255 grid."""
+    if footprint is not None:
+        raise ValueError("only the default (full) footprint is supported")
+    img = _to_levels(image, "h_maxima input")
+    h_lv = int(np.ceil(h * LEVELS - 1e-9))  # residue >= h  <=>  levels >= ceil(h*255)
+    if h_lv > int(img.max()) - int(img.min()):
+        return np.zeros(img.shape, np.uint8)
+    marker = np.clip(img.astype(np.int16) - h_lv, 0, 255).astype(np.uint8)
+    f = sitk.ReconstructionByDilationImageFilter()
+    f.SetFullyConnected(True)
+    # GetArrayFromImage (a copy): a view of the temporary result can be freed under us.
+    rec = sitk.GetArrayFromImage(
+        f.Execute(sitk.GetImageFromArray(marker), sitk.GetImageFromArray(img))
+    )
+    return ((img.astype(np.int16) - rec) >= h_lv).astype(np.uint8)
+
+
+@njit(cache=True)
+def _bucket_kernel(img, locs, structure, mask, output):  # noqa: ANN001, ANN202, PLR0912, PLR0915
+    cap = max(1024, 4 * locs.shape[0])
+    ix = np.empty(cap, np.int64)
+    sr = np.empty(cap, np.int64)
+    nx = np.full(cap, -1, np.int64)
+    head = np.full(256, -1, np.int64)
+    tail = np.full(256, -1, np.int64)
+    n = 0
+    for k in range(locs.shape[0]):
+        v = img[locs[k]]
+        ix[n] = locs[k]
+        sr[n] = locs[k]
+        nx[n] = -1
+        if head[v] < 0:
+            head[v] = n
+        else:
+            nx[tail[v]] = n
+        tail[v] = n
+        n += 1
+    cur = 0
+    while cur < 256:
+        e = head[cur]
+        if e < 0:
+            cur += 1
+            continue
+        head[cur] = nx[e]
+        if head[cur] < 0:
+            tail[cur] = -1
+        ei, es = ix[e], sr[e]
+        if output[ei] and ei != es:
+            continue
+        lab = output[es]
+        diff = False
+        if not mask[ei]:
+            diff = True
+        else:
+            for q in range(structure.shape[0]):
+                nb = structure[q] + ei
+                if mask[nb]:
+                    nl = output[nb]
+                    if nl != 0 and nl != lab:  # noqa: PLR1714  (numba: keep it scalar)
+                        mask[ei] = False
+                        diff = True
+                        break
+        if not diff:
+            output[ei] = lab
+        for q in range(structure.shape[0]):
+            nb = structure[q] + ei
+            if not mask[nb] or output[nb]:
+                continue
+            v = img[nb]
+            if v < cur:  # noqa: PLR1730  skimage: cost >= the popping pixel's cost
+                v = cur
+            if n == cap:
+                cap *= 2
+                a = np.empty(cap, np.int64)
+                a[:n] = ix[:n]
+                ix = a
+                a = np.empty(cap, np.int64)
+                a[:n] = sr[:n]
+                sr = a
+                a = np.full(cap, -1, np.int64)
+                a[:n] = nx[:n]
+                nx = a
+            ix[n] = nb
+            sr[n] = es
+            nx[n] = -1
+            if head[v] < 0:
+                head[v] = n
+            else:
+                nx[tail[v]] = n
+            tail[v] = n
+            n += 1
+
+
+def watershed_bucket(
+    image: np.ndarray,
+    markers: np.ndarray | None = None,
+    mask: np.ndarray | None = None,
+    watershed_line: bool = True,
+    connectivity: int = 1,
+) -> np.ndarray:
+    """Skimage's ``watershed(image, markers, mask=mask, watershed_line=True)``.
+
+    For ``image = -surface`` with ``surface`` on the 1/255 grid.
+    """
+    if not watershed_line or connectivity != 1:
+        raise ValueError("only watershed_line=True, connectivity=1 is implemented")
+    if markers is None or mask is None:
+        raise ValueError("markers and mask are required")
+    lv = _to_levels(image + 1.0, "watershed input")  # -(1 - pb) + 1 = pb
+    img = np.pad(lv, 1)
+    msk = np.pad(mask.astype(bool), 1).ravel()
+    out = np.pad(markers.astype(np.int32), 1)
+    st = _offsets_to_raveled_neighbors(
+        img.shape, np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]], bool), center=(1, 1)
+    )
+    _bucket_kernel(
+        img.ravel(),
+        np.flatnonzero(out).astype(np.int64),
+        st.astype(np.int64),
+        msk,
+        out.ravel(),
+    )
+    return out[1:-1, 1:-1].copy()

fbp/core/merge.py

@@ -0,0 +1,119 @@
+"""Union-find line merging and RAG-based hierarchical region merging."""
+
+import numpy as np
+from scipy.ndimage import label as ndi_label
+from skimage import graph
+
+from fbp.core.regions import lines_from_labels, neighbours4, relabel_dense
+
+
+class UnionFind:
+    """Disjoint-set over labels 0..n, path-compressed, lower label wins."""
+
+    def __init__(self, n: int) -> None:
+        """Start with every label its own group."""
+        self.parent = np.arange(n + 1)
+
+    def find(self, a: int) -> int:
+        """Group representative of ``a``."""
+        while self.parent[a] != a:
+            self.parent[a] = self.parent[self.parent[a]]
+            a = self.parent[a]
+        return a
+
+    def union(self, a: int, b: int) -> None:
+        """Merge the groups of ``a`` and ``b``."""
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.parent[max(ra, rb)] = min(ra, rb)
+
+
+def weight_boundary(g: graph.RAG, src: int, dst: int, n: int) -> dict[str, int | float]:
+    """Count-weighted mean boundary probability after merging src into dst."""
+    default = {"weight": 0.0, "count": 0}
+    cs, cd = g[src].get(n, default)["count"], g[dst].get(n, default)["count"]
+    ws, wd = g[src].get(n, default)["weight"], g[dst].get(n, default)["weight"]
+    count = cs + cd
+    return {"count": count, "weight": (cs * ws + cd * wd) / count}
+
+
+def merge_boundary(_g: graph.RAG, _src: int, _dst: int) -> None:
+    """No-op merge callback: ``weight_boundary`` carries all the state we keep."""
+
+
+def merge_by_lines(
+    inst: np.ndarray,
+    r: np.ndarray,
+    c: np.ndarray,
+    pairs: np.ndarray,
+    keep: np.ndarray,
+    uniq: np.ndarray,
+) -> np.ndarray:
+    """Union unsupported line pairs and fill the junctions that fully merged.
+
+    ``keep`` is a boolean per entry of ``uniq`` (the sorted, unique
+    ``a * base + b`` pair keys of ``pairs``): the union-find merges every pair
+    whose key is *not* kept, then a line pixel is filled only when every
+    region it touches ended up in the same merged group, so a kept split
+    always stays a gap and two parcels are never adjacent.
+    """
+    valid = pairs[:, 0] > 0
+    base = int(inst.max()) + 1
+    uf = UnionFind(int(inst.max()))
+    for k, k_ok in zip(uniq, keep, strict=True):
+        if not k_ok:
+            uf.union(int(k // base), int(k % base))
+    lut = np.array([uf.find(i) for i in range(int(inst.max()) + 1)], dtype=np.int32)
+    merged = lut[inst]
+    p = np.pad(inst, 1)
+    nbm = lut[neighbours4(p, r, c)]
+    mx = nbm.max(axis=1)
+    cand = np.where(
+        valid & (mx > 0) & ((nbm == mx[:, None]) | (nbm == 0)).all(axis=1), mx, 0
+    )
+    cand_img = np.zeros_like(merged)
+    cand_img[r, c] = cand
+    q = np.pad(cand_img, 1)
+    nbc = neighbours4(q, r, c)
+    conflict = ((nbc != 0) & (nbc != cand[:, None])).any(axis=1)
+    keep_px = (cand > 0) & ~conflict
+    merged[r[keep_px], c[keep_px]] = cand[keep_px]
+    dense, _ = ndi_label(merged > 0)
+    return dense.astype(np.int32, copy=False)
+
+
+def merge_hierarchy(
+    over: np.ndarray,
+    edge_surface: np.ndarray,
+    fg: np.ndarray,
+    level: float,
+    weights: dict[tuple[int, int], tuple[float, int]] | None = None,
+) -> np.ndarray:
+    """RAG-boundary hierarchical merge shared by ``ucm`` and ``owt``.
+
+    Builds ``rag_boundary(over, edge_surface)`` with the background node
+    dropped, optionally overrides specific edge weights (owt's oriented
+    signal), then greedily merges below ``level`` and relabels densely.
+    """
+    if over.max() <= 1:
+        return over.astype(np.int32, copy=False)
+    rag = graph.rag_boundary(over, edge_surface.astype(np.float64), connectivity=1)
+    if 0 in rag:
+        rag.remove_node(0)  # background is not a region to merge into
+    if weights:
+        for (a, b), (w, n_px) in weights.items():
+            if rag.has_edge(a, b):
+                rag[a][b]["weight"] = w
+                rag[a][b]["count"] = n_px
+    merged = graph.merge_hierarchical(
+        over,
+        rag,
+        thresh=level,
+        rag_copy=False,
+        in_place_merge=True,
+        merge_func=merge_boundary,
+        weight_func=weight_boundary,
+    ).astype(np.int32, copy=False)
+    merged[~fg] = 0
+    merged[fg] += 1  # merge_hierarchical may hand out label 0
+    return relabel_dense(lines_from_labels(merged, fg))

fbp/core/postprocess.py

@@ -0,0 +1,121 @@
+"""Foreground rules and the fixed-order cleanup steps applied after a split."""
+
+import numpy as np
+from scipy.ndimage import binary_dilation
+from scipy.ndimage import label as ndi_label
+from skimage.filters import threshold_otsu
+
+
+def foreground(seg: np.ndarray, prob: np.ndarray, rule: str | float) -> np.ndarray:
+    """Foreground mask for a ``Method.foreground`` rule.
+
+    A number keeps pixels whose field probability is above it.
+    """
+    if isinstance(rule, int | float):
+        return prob[1] > rule
+    if rule == "argmax":
+        return seg == 1
+    if rule == "not_background":
+        return seg != 0
+    if rule == "otsu":
+        pf = prob[1]
+        if float(pf.max() - pf.min()) < 1e-3:
+            return seg == 1
+        return pf > threshold_otsu(pf)
+    raise ValueError(f"unknown foreground rule {rule!r}")
+
+
+def drop_low_field(inst: np.ndarray, pf: np.ndarray, min_mean: float) -> np.ndarray:
+    """Drop parcels whose mean field probability is under ``min_mean``."""
+    labels = inst.ravel()
+    total = np.bincount(labels, weights=pf.ravel().astype(np.float64))
+    mean = total / np.maximum(np.bincount(labels), 1)
+    return np.where(mean[inst] >= min_mean, inst, 0).astype(np.int32, copy=False)
+
+
+def drop_small(inst: np.ndarray, min_area: int) -> np.ndarray:
+    """Remove parcels below ``min_area`` pixels and relabel."""
+    if min_area <= 0:
+        return inst
+    ids, counts = np.unique(inst[inst > 0], return_counts=True)
+    small = ids[counts < min_area]
+    if not len(small):
+        return inst
+    out = inst.copy()
+    out[np.isin(out, small)] = 0
+    dense, _ = ndi_label(out > 0)
+    return dense.astype(np.int32, copy=False)
+
+
+def fill_holes(inst: np.ndarray, max_area: int) -> np.ndarray:
+    """Assign background holes inside a parcel to that parcel.
+
+    ``max_area < 0`` fills every hole; otherwise only holes under ``max_area``
+    pixels. A hole is a background component that touches exactly one parcel and
+    not the image border, so the gap at a kept split is never filled.
+    """
+    if max_area == 0:
+        return inst
+    bg, n = ndi_label(inst == 0)
+    if n == 0:
+        return inst
+    border = set(np.unique(np.concatenate([bg[0], bg[-1], bg[:, 0], bg[:, -1]])))
+    out = inst.copy()
+    p = np.pad(inst, 1)
+    for i, size in zip(*np.unique(bg[bg > 0], return_counts=True), strict=True):
+        if i in border or (max_area > 0 and size >= max_area):
+            continue
+        m = bg == i
+        r, c = np.nonzero(m)
+        nb = np.concatenate(
+            [p[r, c + 1], p[r + 2, c + 1], p[r + 1, c], p[r + 1, c + 2]]
+        )
+        owners = np.unique(nb[nb > 0])
+        if len(owners) == 1:
+            out[m] = owners[0]
+    return out
+
+
+def merge_small(inst: np.ndarray, min_area: int) -> np.ndarray:
+    """Merge small parcels into their longest-shared-border neighbour.
+
+    ``min_area`` px, instead of deleting them. Parcels are separated by a
+    one-pixel gap, so the neighbourhood is taken two pixels out and the gap
+    between the pair is filled; otherwise the merged parcel would fall apart
+    again when labels are rebuilt. A parcel with no neighbour within that
+    distance is left alone.
+    """
+    if min_area <= 0:
+        return inst
+    ids, counts = np.unique(inst[inst > 0], return_counts=True)
+    order = [i for _, i in sorted(zip(counts, ids, strict=True)) if _ < min_area]
+    if not order:
+        return inst
+    out = inst.copy()
+    cross = np.ones((5, 5), dtype=bool)
+    for i in order:
+        m = out == i
+        if not m.any():
+            continue
+        near = binary_dilation(m, structure=cross) & ~m
+        vals, freq = np.unique(out[near & (out > 0)], return_counts=True)
+        if not len(vals):
+            continue
+        best = int(vals[freq.argmax()])
+        # bridge the gap so the pair stays one connected parcel
+        gap = (
+            binary_dilation(m, structure=np.ones((3, 3), dtype=bool))
+            & binary_dilation(out == best, structure=np.ones((3, 3), dtype=bool))
+            & (out == 0)
+        )
+        out[gap] = best
+        out[m] = best
+    dense, _ = ndi_label(out > 0)
+    return dense.astype(np.int32, copy=False)
+
+
+def apply_post_steps(
+    inst: np.ndarray, min_area: int, hole_area: int, merge_area: int
+) -> np.ndarray:
+    """Post-steps in a fixed order: fill holes, merge slivers, drop what is left."""
+    return drop_small(merge_small(fill_holes(inst, hole_area), merge_area), min_area)

fbp/core/regions.py

@@ -0,0 +1,150 @@
+"""Watershed regions, connected components, and the label bookkeeping they share."""
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.ndimage import label as ndi_label
+from skimage.morphology import h_maxima, h_minima, local_maxima, local_minima
+from skimage.segmentation import watershed
+
+
+@dataclass(frozen=True)
+class Regions:
+    """One watershed's output plus the marker bookkeeping around it."""
+
+    labels: np.ndarray  # int32, 0 outside fg and on lines (when lines=True)
+    lines: np.ndarray  # bool, watershed lines inside fg
+    markers: np.ndarray  # int32 marker image
+    n_markers: int
+    fallback: bool  # True when no marker was found and labels = components(fg)
+
+
+def components(fg: np.ndarray) -> np.ndarray:
+    """Connected components of the foreground."""
+    out, _ = ndi_label(fg)
+    return out.astype(np.int32, copy=False)
+
+
+def relabel_dense(lab: np.ndarray) -> np.ndarray:
+    """Labels remapped to a dense 0..n range, preserving background."""
+    _, dense = np.unique(lab, return_inverse=True)
+    dense = dense.reshape(lab.shape).astype(np.int32, copy=False)
+    if lab.min() != 0:
+        dense += 1
+    return dense
+
+
+def lines_from_labels(lab: np.ndarray, fg: np.ndarray) -> np.ndarray:
+    """1-px lines between different labels so adjacent regions never touch."""
+    p = np.pad(lab, 1)
+    c = p[1:-1, 1:-1]
+    diff = ((p[:-2, 1:-1] != c) & (p[:-2, 1:-1] > 0)) | (
+        (p[1:-1, :-2] != c) & (p[1:-1, :-2] > 0)
+    )
+    out = lab.copy()
+    out[diff & fg & (c > 0)] = 0
+    return out
+
+
+def neighbours4(padded: np.ndarray, r: np.ndarray, c: np.ndarray) -> np.ndarray:
+    """Values at the 4-neighbourhood of ``(r, c)`` in a 1-padded image."""
+    return np.stack(
+        [
+            padded[r, c + 1],
+            padded[r + 2, c + 1],
+            padded[r + 1, c],
+            padded[r + 1, c + 2],
+        ],
+        axis=1,
+    )
+
+
+def pairs_at_lines(
+    inst: np.ndarray, lines: np.ndarray
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Per line pixel: (rows, cols, (n_px, 2) sorted label pairs).
+
+    The pair is the two largest distinct positive neighbour labels; pixels
+    touching < 2 labels get (0, 0).
+    """
+    p = np.pad(inst, 1)
+    r, c = np.nonzero(lines)
+    nb = neighbours4(p, r, c)
+    nb.sort(axis=1)
+    first = nb[:, :1]
+    distinct = np.concatenate(
+        [first, np.where(nb[:, 1:] != nb[:, :-1], nb[:, 1:], 0)], axis=1
+    )
+    distinct.sort(axis=1)
+    top2 = distinct[:, -2:]  # two largest distinct (0 if fewer than two)
+    top2[top2[:, 0] == 0] = 0
+    return r, c, top2
+
+
+def _morphology(backend: str) -> tuple:
+    """The h-maxima and watershed functions for ``backend``."""
+    if backend == "skimage":
+        return h_maxima, watershed
+    if backend == "fast":
+        from fbp.core.fast_morph import h_maxima_itk, watershed_bucket  # noqa: PLC0415  (optional [fast] extra)
+
+        return h_maxima_itk, watershed_bucket
+    raise ValueError(backend)
+
+
+def watershed_regions(  # noqa: PLR0913  (keyword-only flags)
+    surface: np.ndarray,
+    fg: np.ndarray,
+    h: float,
+    *,
+    lines: bool = True,
+    mode: str = "max",
+    backend: str = "skimage",
+) -> Regions:
+    """Watershed inside ``fg``, seeded at ``surface``'s own extrema.
+
+    ``backend="fast"`` runs the h-maxima and the watershed on integer levels
+    (``fbp.core.fast_morph``). It applies to ``mode="max"`` only and needs the
+    surface on the 1/255 grid.
+
+    ``mode="max"`` (every other caller) seeds on maxima: ``h > 0`` seeds
+    ``h``-maxima at least ``h`` deep, ``h == 0`` seeds every regional maximum,
+    and outside ``fg`` is masked to 0 for the seed search (harmless for the
+    non-negative distance/probability surfaces every ``max`` caller uses,
+    since 0 is already their own floor).
+
+    ``mode="min"`` (owt only) seeds on minima instead, matching
+    ``skimage.morphology.h_minima``/``local_minima`` directly. It masks
+    outside ``fg`` by *substituting* ``surface.max() + 1`` there rather than
+    multiplying by ``fg``: h_maxima/h_minima's floating-point tolerance scales
+    with each pixel's own magnitude, so zeroing every masked-out pixel would
+    change the in-``fg`` pixels' tolerance too when negated into a maxima
+    search, and does occasionally flip which of two nearly-tied real pixels
+    counts as the seed on real patches (see the owt port report).
+
+    Falls back to plain connected components of ``fg`` when no marker
+    survives.
+    """
+    z = np.zeros(fg.shape, dtype=np.int32)
+    if not fg.any():
+        return Regions(z, np.zeros(fg.shape, dtype=bool), z, 0, True)
+    if mode == "max":
+        hmax, ws = _morphology(backend)
+        seed = surface * fg
+        peaks = (hmax(seed, h=h) & fg) if h > 0 else (local_maxima(seed) & fg)
+        flood_surface = -surface
+    elif mode == "min":
+        ws = watershed
+        seed = np.where(fg, surface, surface.max() + 1.0).astype(surface.dtype)
+        peaks = (h_minima(seed, h=h) & fg) if h > 0 else (local_minima(seed) & fg)
+        flood_surface = surface
+    else:
+        raise ValueError(mode)
+    markers, n = ndi_label(peaks)
+    markers = markers.astype(np.int32, copy=False)
+    if n == 0:
+        return Regions(components(fg), np.zeros(fg.shape, dtype=bool), markers, 0, True)
+    labels = ws(flood_surface, markers=markers, mask=fg, watershed_line=lines)
+    labels = labels.astype(np.int32, copy=False)
+    line_mask = (fg & (labels == 0)) if lines else np.zeros(fg.shape, dtype=bool)
+    return Regions(labels, line_mask, markers, int(n), False)

fbp/core/surfaces.py

@@ -0,0 +1,36 @@
+"""The scalar surfaces a split rule seeds its watershed on."""
+
+import numpy as np
+from scipy.ndimage import convolve, distance_transform_edt
+
+N_ORIENT = 8
+LINE_PX = 5  # length of the oriented averaging line, in pixels
+
+
+def boundary_distance(seg: np.ndarray) -> np.ndarray:
+    """EDT of (seg != boundary), the FTP pipeline's watershed surface."""
+    return distance_transform_edt(seg != 2).astype(np.float32, copy=False)
+
+
+def boundary_prob(prob: np.ndarray) -> np.ndarray:
+    """1 - p_boundary, high away from a predicted boundary."""
+    return (1.0 - prob[2]).astype(np.float32, copy=False)
+
+
+def line_kernel(theta: float, length: int) -> np.ndarray:
+    """Normalised line of ``length`` px through the kernel centre at ``theta``."""
+    k = np.zeros((length, length), dtype=np.float32)
+    c = length // 2
+    for t in np.linspace(-c, c, 4 * length + 1):
+        r = int(round(c - t * np.sin(theta)))
+        q = int(round(c + t * np.cos(theta)))
+        k[r, q] = 1.0
+    return k / k.sum()
+
+
+def oriented_signal(pb: np.ndarray, length: int = LINE_PX) -> np.ndarray:
+    """``(N_ORIENT, H, W)`` mean boundary probability along a line per orientation."""
+    thetas = np.arange(N_ORIENT) * np.pi / N_ORIENT
+    return np.stack(
+        [convolve(pb, line_kernel(t, length), mode="nearest") for t in thetas]
+    )

fbp/methods/__init__.py

@@ -0,0 +1,41 @@
+"""Methods that turn (background, field, boundary) predictions into field instances."""
+
+from fbp.methods.base import Method
+from fbp.methods.boundaryvote import BoundaryVote
+from fbp.methods.components import ClosedComponents, Components
+from fbp.methods.ftp import FTPWatershed, ftp_pipeline
+from fbp.methods.gmm import GaussianMixture
+from fbp.methods.iterh import IterativeWatershed
+from fbp.methods.owt import OrientedWatershed
+from fbp.methods.swst import StochasticWatershed
+from fbp.methods.thresholds import ExtentBoundaryThreshold
+from fbp.methods.ucm import UltrametricContours
+
+# The setting used for the FTW Global Data 2nd Edition, on 2.5 m probabilities.
+FTW_2E = BoundaryVote(
+    foreground="not_background",
+    surface="boundary_probability",
+    seed_depth=0.01,
+    min_line_support=0.5,
+    min_mean_field_probability=0.25,
+    refill_field_probability=0.10,
+    refill_min_uncovered=0.02,
+    min_area_m2=900,
+    fast=True,
+)
+
+__all__ = [
+    "FTW_2E",
+    "BoundaryVote",
+    "ClosedComponents",
+    "Components",
+    "ExtentBoundaryThreshold",
+    "FTPWatershed",
+    "GaussianMixture",
+    "IterativeWatershed",
+    "Method",
+    "OrientedWatershed",
+    "StochasticWatershed",
+    "UltrametricContours",
+    "ftp_pipeline",
+]