deepcontrail-instance 0.1.0__py3-none-any.whl

deepcontrail/instance/__init__.py

@@ -0,0 +1,49 @@
+"""Instance segmentation of contrails: separate the contrails of a segmentation map.
+
+Mannstein-style line detection and region growing turn a binary or probability mask into
+one mask and one score per contrail. Torch-free; scikit-learn is needed only to train a
+``ScoreModel`` (the ``[scores]`` extra).
+"""
+
+from importlib.metadata import version
+
+from deepcontrail.instance.bundle import InstanceStep, load_instance_step, save_instance_step
+from deepcontrail.instance.config import InstancePipelineConfig, MannsteinConfig
+from deepcontrail.instance.io import (
+    instance_masks_from_annotators,
+    instance_masks_from_label_image,
+    to_coco_results,
+)
+from deepcontrail.instance.mannstein import detect_instances
+from deepcontrail.instance.pipeline import detect_instances_from_probabilities
+from deepcontrail.instance.refine import grow_instances, probability_weighted_scores
+from deepcontrail.instance.scoring import (
+    FEATURES,
+    ScoreModel,
+    instance_features,
+    match_quality,
+    training_data,
+)
+
+__version__ = version("deepcontrail-instance")
+
+__all__ = [
+    "FEATURES",
+    "InstancePipelineConfig",
+    "InstanceStep",
+    "MannsteinConfig",
+    "ScoreModel",
+    "__version__",
+    "detect_instances",
+    "detect_instances_from_probabilities",
+    "grow_instances",
+    "instance_features",
+    "instance_masks_from_annotators",
+    "instance_masks_from_label_image",
+    "load_instance_step",
+    "match_quality",
+    "probability_weighted_scores",
+    "save_instance_step",
+    "to_coco_results",
+    "training_data",
+]

deepcontrail/instance/_evaluation.py

@@ -0,0 +1,392 @@
+"""Building blocks of the instance evaluation and tuning scripts.
+
+Private module (leading underscore): it serves the repository scripts in ``scripts/`` and is
+not part of the public API, so it may change between releases.
+
+Annotator samples, scene lists and splits, loading predictions, running the detection in
+parallel, and scoring it per annotator sample (pooled COCO mAP over IoU 0.25-0.75, see
+``deepcontrail.instance.metrics``). The scripts in ``scripts/`` are thin command-line
+wrappers around these functions.
+
+Only ``instance_masks/<split>/<id>.npy`` is read from a dataset. Parallel runs use the default
+multiprocessing start method, so they also work where ``fork`` is unavailable (Windows) or
+unsafe (macOS).
+"""
+
+from __future__ import annotations
+
+import multiprocessing
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from deepcontrail.core.readers import (
+    binarize_mask,
+    extract_all_annotator_instances,
+    extract_annotator_instances,
+    load_instance_masks,
+    load_mask,
+)
+from deepcontrail.instance.labels import annotator_masks_from_instances
+from deepcontrail.instance.mannstein import detect_instances
+from deepcontrail.instance.pipeline import detect_instances_from_probabilities
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from deepcontrail.instance.config import InstancePipelineConfig, MannsteinConfig
+    from deepcontrail.instance.scoring import ScoreModel
+
+Detections = tuple[list[np.ndarray], list[float]]
+
+
+def default_workers() -> int:
+    """Return a safe default number of worker processes: at most 8, at most the CPU count."""
+    return max(1, min(8, os.cpu_count() or 1))
+
+
+@dataclass(frozen=True)
+class Sample:
+    """One annotator on one scene: their semantic mask and their instances (GT)."""
+
+    stem: str
+    slot: int
+    annotator_mask: np.ndarray
+    gt: list[np.ndarray]
+
+
+def build_samples(instance_masks: np.ndarray, stem: str = "") -> list[Sample]:
+    """Build every annotator sample of one scene, including empty ones.
+
+    Parameters
+    ----------
+    instance_masks
+        ``(N, H, W, A)`` instance masks; 1 = pixel of instance n for annotator a, -1 =
+        annotator a did not draw instance n (never part of the GT). ``A`` may be 1.
+    stem
+        Scene id, kept on each sample for reporting.
+
+    Returns
+    -------
+    list[Sample]
+        One sample per annotator. Its mask is the union of the annotator's contrails. A sample
+        with an empty GT is skipped by the scorer.
+    """
+    masks = annotator_masks_from_instances(instance_masks)
+    return [
+        Sample(stem, slot, masks[..., slot], extract_annotator_instances(instance_masks, slot))
+        for slot in range(instance_masks.shape[-1])
+    ]
+
+
+def list_scenes(root: str | Path, split: str) -> list[str]:
+    """Return the sorted scene ids of ``<root>/instance_masks/<split>/``.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the folder does not exist.
+    """
+    folder = Path(root) / "instance_masks" / split
+    if not folder.is_dir():
+        raise FileNotFoundError(f"directory not found: {folder}")
+    return sorted(p.stem for p in folder.glob("*.npy"))
+
+
+def split_scenes(
+    stems: Sequence[str],
+    seed: int,
+    n_search: int | None = None,
+    n_holdout: int | None = None,
+) -> tuple[list[str], list[str]]:
+    """Split scene ids into disjoint search and holdout sets, reproducibly.
+
+    The ids are shuffled with ``seed``; the first ``n_search`` form the search set and the next
+    ``n_holdout`` the holdout. By default the search set is half of the scenes and the holdout
+    is the rest.
+
+    Raises
+    ------
+    ValueError
+        If either set would be empty, or if more scenes are asked for than exist.
+    """
+    n = len(stems)
+    n_search = n // 2 if n_search is None else n_search
+    n_holdout = n - n_search if n_holdout is None else n_holdout
+    if n_search <= 0 or n_holdout <= 0:
+        raise ValueError(
+            f"{n} scenes give {n_search} search and {n_holdout} holdout scenes; both must be "
+            "at least 1 (the holdout is what the results are judged on)"
+        )
+    if n_search + n_holdout > n:
+        raise ValueError(f"need {n_search} + {n_holdout} scenes, found {n}")
+    shuffled = [stems[int(i)] for i in np.random.default_rng(seed).permutation(n)]
+    return shuffled[:n_search], shuffled[n_search : n_search + n_holdout]
+
+
+def select_annotator_samples(
+    root: str | Path, n_samples: int, n_holdout: int, seed: int, split: str = "train"
+) -> tuple[list[Sample], list[Sample]]:
+    """Pick non-empty annotator samples for a search and a holdout, scene by scene.
+
+    Scenes are shuffled with ``seed`` and walked in order; each scene's non-empty annotator
+    samples go to the search set until it holds at least ``n_samples``, then to the holdout
+    until it holds at least ``n_holdout``. A scene is never split.
+
+    Raises
+    ------
+    ValueError
+        If the split has too few non-empty annotator samples.
+    """
+    root = Path(root)
+    stems = list_scenes(root, split)
+    order = np.random.default_rng(seed).permutation(len(stems))
+    search: list[Sample] = []
+    holdout: list[Sample] = []
+    for i in order:
+        if len(holdout) >= n_holdout:
+            break
+        raw = load_instance_masks(root / "instance_masks" / split / f"{stems[i]}.npy")
+        scene = [s for s in build_samples(raw, stems[i]) if s.gt]
+        (search if len(search) < n_samples else holdout).extend(scene)
+    if len(search) < n_samples or len(holdout) < n_holdout:
+        raise ValueError(
+            f"need {n_samples} + {n_holdout} non-empty annotator samples, found "
+            f"{len(search)} + {len(holdout)}"
+        )
+    return search, holdout
+
+
+def load_prediction(path: str | Path) -> np.ndarray:
+    """Load one scene's semantic prediction as a float32 map in ``[0, 1]``.
+
+    Parameters
+    ----------
+    path
+        A ``.npy`` file with probabilities of shape ``(H, W)``, or a ``.png`` grayscale
+        mask where any non-zero pixel is foreground (returned as 0.0/1.0).
+
+    Raises
+    ------
+    ValueError
+        If the suffix is neither ``.npy`` nor ``.png``, if a ``.npy`` array is not 2-D, holds
+        non-finite values, or has values outside ``[0, 1]`` (tolerance 1e-3).
+    """
+    path = Path(path)
+    suffix = path.suffix.lower()
+    if suffix == ".png":
+        return binarize_mask(load_mask(path)).astype(np.float32)
+    if suffix == ".npy":
+        probs = np.load(path)
+        if probs.ndim != 2:
+            raise ValueError(f"prediction {path} must be a 2-D (H, W) array, got {probs.shape}")
+        if not np.all(np.isfinite(probs)):
+            raise ValueError(f"prediction {path} has non-finite values (NaN or inf)")
+        if np.any(probs < -1e-3) or np.any(probs > 1.0 + 1e-3):
+            raise ValueError(f"prediction {path} has values outside [0, 1] (tolerance 1e-3)")
+        return probs.astype(np.float32)
+    raise ValueError(f"unsupported prediction suffix {suffix!r}; expected .npy or .png")
+
+
+def prediction_path(pred_dir: str | Path, stem: str) -> Path:
+    """Return ``<stem>.npy`` if present, else ``<stem>.png`` in ``pred_dir``."""
+    npy = Path(pred_dir) / f"{stem}.npy"
+    return npy if npy.exists() else Path(pred_dir) / f"{stem}.png"
+
+
+def load_predictions(
+    pred_dir: str | Path, root: str | Path, stems: Sequence[str], split: str
+) -> tuple[list[np.ndarray], list[list[list[np.ndarray]]]]:
+    """Load the predictions of ``stems`` and their GT contrails per annotator.
+
+    Raises
+    ------
+    FileNotFoundError
+        If a scene has no prediction file, or no instance masks in ``split``.
+    ValueError
+        If a prediction is not the size of its masks.
+    """
+    instance_dir = Path(root) / "instance_masks" / split
+    missing = [s for s in stems if not prediction_path(pred_dir, s).exists()]
+    if missing:
+        raise FileNotFoundError(
+            f"{len(missing)} of {len(stems)} scenes have no prediction in {pred_dir}: "
+            + ", ".join(missing[:5])
+        )
+    no_gt = [s for s in stems if not (instance_dir / f"{s}.npy").exists()]
+    if no_gt:
+        raise FileNotFoundError(
+            f"{len(no_gt)} scenes have no instance masks in {instance_dir}: " + ", ".join(no_gt[:5])
+        )
+    probs, gts = [], []
+    for stem in stems:
+        prob = load_prediction(prediction_path(pred_dir, stem))
+        raw = load_instance_masks(instance_dir / f"{stem}.npy")
+        check_size(prob, raw.shape[1:3], stem)
+        probs.append(prob)
+        gts.append(extract_all_annotator_instances(raw))
+    return probs, gts
+
+
+def check_size(prediction: np.ndarray, mask_shape: tuple[int, ...], stem: str) -> None:
+    """Raise if a prediction is not on the pixel grid of its masks.
+
+    Raises
+    ------
+    ValueError
+        If the shapes differ.
+    """
+    if tuple(prediction.shape) != tuple(mask_shape):
+        h, w = prediction.shape
+        mh, mw = mask_shape
+        raise ValueError(
+            f"prediction of {stem} is {h}x{w} but its masks are {mh}x{mw}; predictions must be "
+            "on the pixel grid of the masks"
+        )
+
+
+_WORKER: dict[str, Any] = {}
+
+
+def _init_worker(state: dict[str, Any]) -> None:
+    _WORKER.clear()
+    _WORKER.update(state)
+
+
+def _detect_probabilities(probs: np.ndarray) -> Detections:
+    return detect_instances_from_probabilities(
+        probs, _WORKER["config"], score_model=_WORKER.get("score_model")
+    )
+
+
+def _detect_mask(mask: np.ndarray) -> Detections:
+    return detect_instances(mask, _WORKER["config"])
+
+
+def _run_parallel(
+    fn: Callable[[np.ndarray], Detections],
+    items: Sequence[np.ndarray],
+    state: dict[str, Any],
+    workers: int,
+) -> list[Detections]:
+    """Apply ``fn`` to every item, in a process pool when ``workers > 1``.
+
+    ``state`` (small: configs) reaches each worker once through the pool initializer; the
+    items are sent with the tasks.
+    """
+    if workers <= 1 or len(items) <= 1:
+        _init_worker(state)
+        return [fn(item) for item in items]
+    with multiprocessing.Pool(workers, initializer=_init_worker, initargs=(state,)) as pool:
+        return pool.map(fn, items, chunksize=4)
+
+
+def detect_all(
+    probs: Sequence[np.ndarray],
+    config: InstancePipelineConfig,
+    workers: int,
+    score_model: ScoreModel | None = None,
+) -> list[Detections]:
+    """Run ``detect_instances_from_probabilities`` on every map (optionally re-scored)."""
+    state = {"config": config, "score_model": score_model}
+    return _run_parallel(_detect_probabilities, probs, state, workers)
+
+
+def detect_all_masks(
+    masks: Sequence[np.ndarray], config: MannsteinConfig, workers: int
+) -> list[Detections]:
+    """Run plain Mannstein (``detect_instances``) on every binary mask."""
+    return _run_parallel(_detect_mask, masks, {"config": config}, workers)
+
+
+def evaluate_annotator_masks(
+    samples: Sequence[Sample],
+    config: MannsteinConfig,
+    workers: int,
+    per_threshold: bool = False,
+    match_iou: float = 0.5,
+) -> dict[str, Any]:
+    """Run plain Mannstein on each sample's own annotator mask and score it (pooled mAP).
+
+    Returns
+    -------
+    dict[str, Any]
+        The result of ``evaluate_annotator_samples`` plus ``mean_pred_instances``.
+    """
+    from deepcontrail.instance.metrics import evaluate_annotator_samples
+
+    out = detect_all_masks([s.annotator_mask for s in samples], config, workers)
+    preds = [o[0] for o in out]
+    result = evaluate_annotator_samples(
+        preds,
+        [s.gt for s in samples],
+        [o[1] for o in out],
+        match_iou=match_iou,
+        per_threshold=per_threshold,
+    )
+    result["mean_pred_instances"] = float(np.mean([len(p) for p in preds])) if preds else 0.0
+    return result
+
+
+def evaluate_pipeline(
+    probs: Sequence[np.ndarray],
+    gts: Sequence[Sequence[Sequence[np.ndarray]]],
+    config: InstancePipelineConfig,
+    workers: int,
+    match_iou: float = 0.5,
+    per_threshold: bool = False,
+    consensus: Sequence[Sequence[np.ndarray]] | None = None,
+    score_model: ScoreModel | None = None,
+) -> dict[str, Any]:
+    """Run the pipeline on every map and score it (pooled mAP).
+
+    Parameters
+    ----------
+    probs
+        Probability maps, one per scene.
+    gts
+        ``gts[i][a]`` holds the GT masks annotator ``a`` drew on scene ``i``.
+    config
+        Pipeline configuration.
+    workers
+        Worker processes (1 runs in-process).
+    match_iou
+        IoU threshold of the reference P/R/F1 matching.
+    per_threshold
+        Also return the AP at each IoU threshold.
+    consensus
+        If given, ``consensus[i]`` holds the consensus instances of scene ``i`` and each scene
+        is scored once against them instead of once per annotator.
+    score_model
+        Optional learned scores.
+
+    Returns
+    -------
+    dict[str, Any]
+        ``evaluate_annotator_samples`` result (``map``, reference ``f1`` ...) plus
+        ``mean_pred_instances`` per scene. Annotators who drew nothing are skipped.
+    """
+    from deepcontrail.instance.metrics import evaluate_annotator_samples
+
+    detections = detect_all(probs, config, workers, score_model)
+    if consensus is not None:
+        preds = [d[0] for d in detections]
+        scores = [d[1] for d in detections]
+        targets = [list(c) for c in consensus]
+    else:
+        preds, scores, targets = [], [], []
+        for (masks, scene_scores), scene_gt in zip(detections, gts, strict=True):
+            for slot_gt in scene_gt:
+                preds.append(masks)
+                scores.append(scene_scores)
+                targets.append(list(slot_gt))
+    result = evaluate_annotator_samples(
+        preds, targets, scores, match_iou=match_iou, per_threshold=per_threshold
+    )
+    result["mean_pred_instances"] = (
+        float(np.mean([len(d[0]) for d in detections])) if detections else 0.0
+    )
+    return result

deepcontrail/instance/_growing.py

@@ -0,0 +1,236 @@
+"""Direction-following region growing that splits a binary mask into contrail regions.
+
+Private module (leading underscore); not exported from ``deepcontrail.instance``.
+
+Seeds walk the mask in row-major order. From each seed not already claimed by an earlier
+region, a breadth-first flood grows along 8-connected neighbours that stay aligned with the
+region's local direction, until the region ends. Each region is then tested for minimum size
+and linearity (:func:`deepcontrail.instance._shape.is_long_and_straight`). A pixel may belong
+to more than one region where contrails cross; only seeds are skipped once claimed.
+
+The mask is padded by one background pixel on every side and worked on as flat indices, so the
+eight neighbours are constant offsets with no bounds check. Region membership is an int32
+"owner stamp" per pixel, and the local alignment direction is kept as exact integer running
+sums over the trailing ``lookback`` window, updated in constant time as the region grows.
+
+This is the region-growing step of the Mannstein-style method (Mannstein, Meyer & Wendling,
+1999, Int. J. Remote Sensing 20(8), 1641-1660, doi:10.1080/014311699212650).
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+import numpy as np
+
+from deepcontrail.instance._shape import is_long_and_straight
+
+# 8-neighbour directions examined in this exact order for every dequeued pixel: (dr, dc).
+_OFFSETS = ((-1, -1), (-1, 0), (-1, 1), (0, -1), (0, 1), (1, -1), (1, 0), (1, 1))
+
+
+class _Region:
+    """A growing region: its accepted pixels and a running alignment-window fit.
+
+    Pixels are stored as flat indices into the padded mask. The alignment window keeps exact
+    integer running sums (n, Σr, Σc, Σr², Σc², Σrc) over the last ``lookback`` accepted pixels,
+    so the local least-squares direction is recomputed in constant time when the region grows.
+    """
+
+    __slots__ = (
+        "branch",
+        "dirty",
+        "flat",
+        "intercept",
+        "lookback",
+        "size",
+        "slope",
+        "sum_c",
+        "sum_c2",
+        "sum_r",
+        "sum_r2",
+        "sum_rc",
+        "width",
+        "window",
+        "window_n",
+    )
+
+    def __init__(self, flat0: int, row0: int, col0: int, lookback: int, width: int) -> None:
+        self.flat = [flat0]
+        self.size = 1
+        self.sum_r = row0
+        self.sum_c = col0
+        self.sum_r2 = row0 * row0
+        self.sum_c2 = col0 * col0
+        self.sum_rc = row0 * col0
+        self.window = deque((flat0,))
+        self.window_n = 1
+        self.branch = 0
+        self.slope = 0.0
+        self.intercept = 0.0
+        self.dirty = True
+        self.lookback = lookback
+        self.width = width
+
+    def add(self, flat: int, row: int, col: int) -> None:
+        """Accept a pixel and fold it into the running alignment window."""
+        self.flat.append(flat)
+        self.size += 1
+        self.window.append(flat)
+        self.sum_r += row
+        self.sum_c += col
+        self.sum_r2 += row * row
+        self.sum_c2 += col * col
+        self.sum_rc += row * col
+        self.window_n += 1
+        if self.window_n > self.lookback:
+            oldest = self.window.popleft()
+            oldest_r = oldest // self.width - 1
+            oldest_c = oldest % self.width - 1
+            self.sum_r -= oldest_r
+            self.sum_c -= oldest_c
+            self.sum_r2 -= oldest_r * oldest_r
+            self.sum_c2 -= oldest_c * oldest_c
+            self.sum_rc -= oldest_r * oldest_c
+            self.window_n -= 1
+        self.dirty = True
+
+    def refresh_fit(self) -> None:
+        """Recompute the cached local direction from the running window sums.
+
+        Branch 0 fits rows on columns (columns vary more), branch 1 fits columns on rows. With
+        no spread in the regressor the slope is ``0.0`` and the intercept is the regressand mean.
+        """
+        n = self.window_n
+        var_c = n * self.sum_c2 - self.sum_c * self.sum_c
+        var_r = n * self.sum_r2 - self.sum_r * self.sum_r
+        fit_rows_on_cols = var_c > var_r if var_c != var_r else self._tie_prefers_cols()
+        if fit_rows_on_cols:
+            self.branch = 0
+            slope = (n * self.sum_rc - self.sum_r * self.sum_c) / var_c
+            self.slope = slope
+            self.intercept = (self.sum_r - slope * self.sum_c) / n
+        else:
+            self.branch = 1
+            if var_r == 0:
+                self.slope = 0.0
+                self.intercept = self.sum_c / n
+            else:
+                slope = (n * self.sum_rc - self.sum_r * self.sum_c) / var_r
+                self.slope = slope
+                self.intercept = (self.sum_c - slope * self.sum_r) / n
+        self.dirty = False
+
+    def _tie_prefers_cols(self) -> bool:
+        """Break an exact spread tie between the two axes.
+
+        When the window's row and column spreads are exactly equal, either axis fits equally
+        well. The choice follows the float comparison ``std(cols) > std(rows)`` over the window,
+        so that results stay identical to the published v0.1.0 instance step and the score model
+        trained on its output. Exact ties are rare, so this costs nothing measurable.
+        """
+        window = np.asarray(self.window, dtype=np.int64)
+        rows = (window // self.width - 1).astype(float)
+        cols = (window % self.width - 1).astype(float)
+        return bool(np.std(cols) > np.std(rows))
+
+    def accepts(self, row: int, col: int, threshold: float) -> bool:
+        """Whether a candidate pixel continues the region's local direction.
+
+        Fewer than five accumulated pixels are always accepted (bootstrap). Otherwise the cached
+        local direction predicts the candidate's coordinate along the more-variant axis and it is
+        accepted when the deviation is within ``threshold``.
+        """
+        if self.size < 5:
+            return True
+        if self.dirty:
+            self.refresh_fit()
+        if self.branch == 0:
+            return abs(self.slope * col + self.intercept - row) < threshold
+        return abs(self.slope * row + self.intercept - col) < threshold
+
+    def coords(self) -> tuple[np.ndarray, np.ndarray]:
+        """(rows, cols) arrays of the accepted pixels in acceptance order."""
+        flat = np.asarray(self.flat, dtype=np.int64)
+        return flat // self.width - 1, flat % self.width - 1
+
+
+def grow_regions(
+    binary_mask: np.ndarray,
+    min_pixels: int,
+    min_length: float,
+    min_r_score: float,
+    lookback: int,
+    alignment_threshold: float,
+    avg_size: int,
+) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Grow aligned regions out of a binary mask and keep the straight, long ones.
+
+    Parameters
+    ----------
+    binary_mask
+        2D boolean or ``{0, 1}`` array of shape ``(H, W)``.
+    min_pixels
+        Minimum pixel count to keep a region.
+    min_length
+        Minimum region length for the linearity check.
+    min_r_score
+        Straightness threshold, squared before the comparison.
+    lookback
+        Trailing window used for the local alignment regression.
+    alignment_threshold
+        Maximum allowed deviation for a neighbour to join a growing region.
+    avg_size
+        Endpoint averaging window for the length check.
+
+    Returns
+    -------
+    list[tuple[np.ndarray, np.ndarray]]
+        ``(rows, cols)`` coordinate arrays of the kept regions, in seed order and pixels in
+        acceptance order.
+    """
+    h, w = binary_mask.shape
+    padded = np.zeros((h + 2, w + 2), dtype=bool)
+    padded[1:-1, 1:-1] = binary_mask
+    mask = padded.ravel()
+    width = w + 2
+    stamp = np.zeros(mask.size, dtype=np.int32)
+    # (flat offset, dr, dc) per neighbour, in the required examination order.
+    neighbors = tuple((dr * width + dc, dr, dc) for dr, dc in _OFFSETS)
+
+    contrails: list[tuple[np.ndarray, np.ndarray]] = []
+    region_num = 0
+    for seed in np.nonzero(mask)[0]:
+        seed = int(seed)
+        if stamp[seed] != 0:
+            continue
+        region_num += 1
+        region = _Region(seed, seed // width - 1, seed % width - 1, lookback, width)
+        stamp[seed] = region_num
+        queue: deque[int] = deque((seed,))
+
+        while queue:
+            cur = int(queue.popleft())
+            cur_r = cur // width - 1
+            cur_c = cur % width - 1
+            for offset, d_r, d_c in neighbors:
+                flat = cur + offset
+                if not mask[flat]:
+                    continue
+                if stamp[flat] == region_num:
+                    continue
+                n_r = cur_r + d_r
+                n_c = cur_c + d_c
+                if not region.accepts(n_r, n_c, alignment_threshold):
+                    continue
+                stamp[flat] = region_num
+                region.add(flat, n_r, n_c)
+                queue.append(flat)
+
+        if region.size < min_pixels:
+            continue
+        rows_arr, cols_arr = region.coords()
+        if is_long_and_straight(rows_arr, cols_arr, min_r_score, min_length, avg_size):
+            contrails.append((rows_arr, cols_arr))
+
+    return contrails