deepcontrail-instance 0.1.0__py3-none-any.whl

deepcontrail/instance/mannstein.py

@@ -0,0 +1,114 @@
+"""Top-level Mannstein-style instance-segmentation pipeline.
+
+Public entry point that threads the private line-filter, segmentation, scoring and
+deduplication modules together into ``detect_instances`` (binary mask in; masks and scores
+out). Probability maps go through ``detect_instances_from_probabilities``.
+
+The detection criteria follow Mannstein, Meyer & Wendling (1999), "Operational detection of
+contrails from NOAA-AVHRR data", Int. J. Remote Sensing 20(8), 1641-1660,
+doi:10.1080/014311699212650.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from deepcontrail.instance._growing import grow_regions
+from deepcontrail.instance._lines import detect_line_pixels
+from deepcontrail.instance._overlap import remove_duplicates
+from deepcontrail.instance._shape import candidate_score
+from deepcontrail.instance.config import MannsteinConfig
+
+
+def _run_pipeline(
+    semantic_mask: np.ndarray,
+    config: MannsteinConfig,
+) -> tuple[list[tuple[np.ndarray, np.ndarray]], list[float]]:
+    """Optionally line-filter, then segment, score and deduplicate into ``(contrails, scores)``."""
+    if config.line_filter:
+        mask = detect_line_pixels(
+            semantic_mask.astype(np.float32),
+            config.num_kernels,
+            config.kernel_size,
+            config.sigma1,
+            config.sigma_delta,
+            config.response_threshold,
+        )
+    else:
+        mask = semantic_mask > 0
+
+    candidates = grow_regions(
+        mask,
+        config.min_pixels,
+        config.min_length,
+        config.min_r_score,
+        config.lookback,
+        config.alignment_threshold,
+        config.fit_avg_size if config.filter_avg_size is None else config.filter_avg_size,
+    )
+    survivors = remove_duplicates(candidates, config.iou_threshold)
+    return survivors, [
+        candidate_score(rows, cols, config.score_saturation, config.fit_avg_size)
+        for rows, cols in survivors
+    ]
+
+
+def _masks_from_contrails(
+    contrails: list[tuple[np.ndarray, np.ndarray]],
+    h: int,
+    w: int,
+) -> list[np.ndarray]:
+    masks: list[np.ndarray] = []
+    for rows, cols in contrails:
+        mask = np.zeros((h, w), dtype=bool)
+        mask[rows, cols] = True
+        masks.append(mask)
+    return masks
+
+
+def _check_binary_mask(mask: np.ndarray) -> np.ndarray:
+    """Return ``mask`` as an array after checking it is a 2-D, finite, binary mask."""
+    mask = np.asarray(mask)
+    if mask.ndim != 2:
+        raise ValueError(f"mask must be a 2-D (H, W) array, got shape {mask.shape}")
+    if mask.dtype != bool and not np.all(np.isfinite(mask)):
+        raise ValueError("mask must be finite (no NaN or inf)")
+    if mask.dtype != bool and not np.isin(mask, (0, 1)).all():
+        raise ValueError(
+            "mask must be binary (0/1 or bool); for a probability map use "
+            "detect_instances_from_probabilities"
+        )
+    return mask
+
+
+def detect_instances(
+    semantic_mask: np.ndarray, config: MannsteinConfig | None = None
+) -> tuple[list[np.ndarray], list[float]]:
+    """Split a binary contrail mask into separate contrails with plain Mannstein.
+
+    Parameters
+    ----------
+    semantic_mask
+        Binary 2D array ``(H, W)``: bool, or numbers in ``{0, 1}``.
+    config
+        Algorithm configuration. Defaults to ``MannsteinConfig()``.
+
+    Returns
+    -------
+    tuple[list[np.ndarray], list[float]]
+        Boolean instance masks ``(H, W)`` and their quality scores in ``[0, 1]``, aligned
+        one-to-one; both empty when no contrail is found. Contrails may share pixels where
+        they cross.
+
+    Raises
+    ------
+    ValueError
+        If ``semantic_mask`` is not 2-D, not finite or not binary (a probability map belongs
+        to ``detect_instances_from_probabilities``).
+    """
+    mask = _check_binary_mask(semantic_mask)
+    if config is None:
+        config = MannsteinConfig()
+    h, w = mask.shape
+    contrails, scores = _run_pipeline(mask, config)
+    return _masks_from_contrails(contrails, h, w), scores

deepcontrail/instance/metrics.py

@@ -0,0 +1,232 @@
+"""Instance metrics across independent annotators: COCO mAP, precision, recall and F1.
+
+The mAP needs the ``[map]`` extra (pycocotools); torch is never needed.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any, cast
+
+import numpy as np
+
+DEFAULT_IOU_THRESHOLDS = (0.25, 0.35, 0.45, 0.55, 0.65, 0.75)
+COCO_MAX_DETECTIONS = 100
+"""Detections per sample kept by the COCO mAP (pycocotools default; extra ones are dropped)."""
+
+
+def match_instances(
+    pred_masks: list[np.ndarray],
+    gt_masks: list[np.ndarray],
+    iou_threshold: float = 0.5,
+) -> tuple[int, int, int]:
+    """Greedy one-to-one IoU matching of predicted and ground-truth masks.
+
+    Parameters
+    ----------
+    pred_masks
+        Predicted boolean instance masks, each ``(H, W)``.
+    gt_masks
+        Ground-truth boolean instance masks, each ``(H, W)``.
+    iou_threshold
+        Minimum IoU for a pred/GT pair to count as a match.
+
+    Returns
+    -------
+    tuple[int, int, int]
+        ``(tp, fp, fn)``. Every pred and GT is matched at most once, always
+        taking the highest-IoU available pair first. Unmatched preds are false
+        positives and unmatched GT are false negatives. Empty inputs are valid.
+    """
+    n_pred = len(pred_masks)
+    n_gt = len(gt_masks)
+    if n_pred == 0 and n_gt == 0:
+        return 0, 0, 0
+
+    matched_pred = [False] * n_pred
+    matched_gt = [False] * n_gt
+    pairs: list[tuple[float, int, int]] = []
+    for i, pred in enumerate(pred_masks):
+        for j, gt in enumerate(gt_masks):
+            intersection = np.logical_and(pred, gt).sum()
+            union = np.logical_or(pred, gt).sum()
+            iou = float(intersection / union) if union else 0.0
+            if iou >= iou_threshold:
+                pairs.append((iou, i, j))
+
+    pairs.sort(key=lambda pair: pair[0], reverse=True)
+    tp = 0
+    for _iou, i, j in pairs:
+        if not matched_pred[i] and not matched_gt[j]:
+            matched_pred[i] = True
+            matched_gt[j] = True
+            tp += 1
+
+    return tp, n_pred - tp, n_gt - tp
+
+
+def evaluate_annotator_samples(
+    pred_masks: list[list[np.ndarray]],
+    gt_masks: list[list[np.ndarray]],
+    pred_scores: list[list[float]] | None = None,
+    iou_thresholds: tuple[float, ...] | list[float] = DEFAULT_IOU_THRESHOLDS,
+    match_iou: float = 0.5,
+    per_threshold: bool = True,
+    include_empty: bool = False,
+) -> dict[str, Any]:
+    """Score instance predictions per annotator sample (pooled COCO segmentation mAP).
+
+    One sample is one annotator on one scene. Samples whose ground truth is empty are
+    skipped (the official protocol) unless ``include_empty``. All remaining samples are
+    pooled into a single COCO segmentation mAP computation (one image per sample, single
+    class), averaged over ``iou_thresholds``. Precision, recall and F1 from one-to-one
+    matching at ``match_iou``, pooled over the same samples, are returned as a reference.
+
+    With ``include_empty``, every sample is kept and every detection on an empty sample is a
+    false detection, as in real use where most scenes have no contrail.
+
+    The computation is the standard COCO segmentation AP of pycocotools (101 recall points, at
+    most 100 detections per sample, area "all", with a warning when a sample has more); torch is
+    not needed. Every sample is registered
+    with COCO, so ``include_empty`` counts the detections on empty samples (torchmetrics'
+    ``MeanAveragePrecision`` drops them).
+
+    Parameters
+    ----------
+    pred_masks
+        ``pred_masks[i]`` is the list of predicted boolean ``(H, W)`` masks for sample ``i``.
+    gt_masks
+        ``gt_masks[i]`` is the list of GT boolean masks of sample ``i`` (one annotator).
+    pred_scores
+        Confidence per predicted mask, aligned with ``pred_masks``; ``None`` = 1.0 for all.
+    iou_thresholds
+        IoU thresholds averaged by the mAP. Defaults to 0.25, 0.35, ..., 0.75.
+    match_iou
+        IoU threshold of the reference one-to-one matching.
+    per_threshold
+        Also return the AP at each threshold.
+    include_empty
+        Keep samples with an empty ground truth and count their detections as false.
+
+    Returns
+    -------
+    dict[str, Any]
+        ``map``, ``ap_per_threshold`` (when requested), ``precision``, ``recall``, ``f1``,
+        ``tp``, ``fp``, ``fn``, ``n_samples`` and ``n_skipped_empty``.
+
+    Raises
+    ------
+    ValueError
+        If ``pred_masks``, ``gt_masks`` (and ``pred_scores``) have different lengths.
+    """
+    if len(pred_masks) != len(gt_masks) or (
+        pred_scores is not None and len(pred_scores) != len(pred_masks)
+    ):
+        raise ValueError("pred_masks, gt_masks and pred_scores must have one entry per samples")
+    keep = [i for i, gt in enumerate(gt_masks) if gt or include_empty]
+    preds = [pred_masks[i] for i in keep]
+    gts = [gt_masks[i] for i in keep]
+    scores = None if pred_scores is None else [pred_scores[i] for i in keep]
+
+    tp = fp = fn = 0
+    for p, g in zip(preds, gts, strict=True):
+        a, b, c = match_instances(p, g, match_iou)
+        tp, fp, fn = tp + a, fp + b, fn + c
+    precision = tp / (tp + fp) if tp + fp else 0.0
+    recall = tp / (tp + fn) if tp + fn else 0.0
+    crowded = sum(len(p) > COCO_MAX_DETECTIONS for p in preds)
+    if crowded:
+        warnings.warn(
+            f"{crowded} sample(s) have more than {COCO_MAX_DETECTIONS} detections; the COCO mAP "
+            f"keeps only the {COCO_MAX_DETECTIONS} detections with the highest scores per sample",
+            UserWarning,
+            stacklevel=2,
+        )
+    pooled, ap = _coco_ap_all_samples(preds, gts, scores, list(iou_thresholds))
+    result: dict[str, Any] = {
+        "map": pooled,
+        "precision": precision,
+        "recall": recall,
+        "f1": 2 * precision * recall / (precision + recall) if precision + recall else 0.0,
+        "tp": tp,
+        "fp": fp,
+        "fn": fn,
+        "n_samples": len(keep),
+        "n_skipped_empty": len(gt_masks) - len(keep),
+    }
+    if per_threshold:
+        result["ap_per_threshold"] = dict(zip(iou_thresholds, ap.tolist(), strict=True))
+    return result
+
+
+def _coco_ap_all_samples(
+    preds: list[list[np.ndarray]],
+    gts: list[list[np.ndarray]],
+    scores: list[list[float]] | None,
+    thresholds: list[float],
+) -> tuple[float, np.ndarray]:
+    """Pooled mAP and AP per threshold, every sample registered in COCO (empty GT included).
+
+    Standard COCO segmentation AP (pycocotools defaults: 101 recall points, 100 detections,
+    area "all"), with ``thresholds`` as IoU thresholds. Zeros when there is nothing to score.
+    """
+    import contextlib
+    import io
+
+    try:
+        import pycocotools.mask as mask_utils
+        from pycocotools.coco import COCO
+        from pycocotools.cocoeval import COCOeval
+    except ImportError as err:
+        raise ImportError(
+            "the COCO mAP needs pycocotools: pip install 'deepcontrail-instance[map]'"
+        ) from err
+
+    images: list[dict[str, Any]] = []
+    gt_anns: list[dict[str, Any]] = []
+    dt_anns: list[dict[str, Any]] = []
+    for image_id, (p, g) in enumerate(zip(preds, gts, strict=True)):
+        h, w = (g or p)[0].shape if (g or p) else (1, 1)
+        images.append({"id": image_id, "height": h, "width": w})
+        for m in g:
+            rle = mask_utils.encode(np.asfortranarray(m.astype(np.uint8)))
+            gt_anns.append(
+                {"id": len(gt_anns) + 1, "image_id": image_id, "category_id": 0,
+                 "segmentation": rle, "area": float(mask_utils.area(rle)), "iscrowd": 0}
+            )  # fmt: skip
+        for k, m in enumerate(p):
+            rle = mask_utils.encode(np.asfortranarray(m.astype(np.uint8)))
+            score = 1.0 if scores is None else float(scores[image_id][k])
+            dt_anns.append(
+                {"id": len(dt_anns) + 1, "image_id": image_id, "category_id": 0,
+                 "segmentation": rle, "area": float(mask_utils.area(rle)), "score": score}
+            )  # fmt: skip
+    if not gt_anns:
+        return 0.0, np.zeros(len(thresholds))
+    categories = [{"id": 0, "name": "0"}]
+    coco_gt, coco_dt = COCO(), COCO()
+    # In-memory datasets (the pycocotools stubs mark ``dataset`` read-only).
+    cast("Any", coco_gt).dataset = {
+        "images": images,
+        "annotations": gt_anns,
+        "categories": categories,
+    }
+    cast("Any", coco_dt).dataset = {
+        "images": images,
+        "annotations": dt_anns,
+        "categories": categories,
+    }
+    with contextlib.redirect_stdout(io.StringIO()):
+        coco_gt.createIndex()
+        coco_dt.createIndex()
+        coco_eval = COCOeval(coco_gt, coco_dt, iouType="segm")
+        coco_eval.params.iouThrs = np.array(thresholds, dtype=np.float64)
+        coco_eval.evaluate()
+        coco_eval.accumulate()
+    precision = coco_eval.eval["precision"][:, :, 0, 0, -1]
+
+    def summary(values: np.ndarray) -> float:
+        valid = values[values > -1]
+        return max(float(np.mean(valid)), 0.0) if valid.size else 0.0
+
+    return summary(precision), np.array([summary(row) for row in precision])

deepcontrail/instance/pipeline.py

@@ -0,0 +1,90 @@
+"""Instance detection from a semantic probability map.
+
+Threshold, split with Mannstein, grow into moderate-probability pixels, then score
+(optionally with a learned :class:`deepcontrail.instance.scoring.ScoreModel`).
+See :class:`deepcontrail.instance.config.InstancePipelineConfig`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from deepcontrail.instance.config import InstancePipelineConfig
+from deepcontrail.instance.mannstein import detect_instances
+from deepcontrail.instance.refine import grow_instances, probability_weighted_scores
+from deepcontrail.instance.scoring import scene_features
+
+if TYPE_CHECKING:
+    from deepcontrail.instance.scoring import ScoreModel
+
+_TOLERANCE = 1e-3
+
+
+def detect_instances_from_probabilities(
+    probs: np.ndarray,
+    config: InstancePipelineConfig | None = None,
+    score_model: ScoreModel | None = None,
+) -> tuple[list[np.ndarray], list[float]]:
+    """Detect contrail instances in a semantic probability map.
+
+    Parameters
+    ----------
+    probs
+        Probability map ``(H, W)`` with values in ``[0, 1]``, e.g. the sigmoid output of a
+        semantic segmentation model.
+    config
+        Pipeline settings. Defaults to ``InstancePipelineConfig()``.
+    score_model
+        Optional learned scores: replaces each contrail's score by the model's prediction.
+        It must have been trained on detections made with the same ``config``.
+
+    Returns
+    -------
+    tuple[list[np.ndarray], list[float]]
+        Boolean instance masks ``(H, W)`` and their scores in ``[0, 1]``, aligned one-to-one.
+        Instances may share pixels where contrails cross.
+
+    Raises
+    ------
+    ValueError
+        If ``probs`` is not 2-D, not finite or outside ``[0, 1]``, or if ``score_model`` was
+        trained with another pipeline config or on scenes of another size.
+    """
+    if config is None:
+        config = InstancePipelineConfig()
+    if score_model is not None and score_model.pipeline_config != config:
+        raise ValueError("the score model was trained with another pipeline config")
+    probs = np.asarray(probs, dtype=np.float32)
+    if probs.ndim != 2:
+        raise ValueError(f"probabilities must be a 2-D (H, W) array, got shape {probs.shape}")
+    if not np.all(np.isfinite(probs)):
+        raise ValueError("probabilities must be finite (no NaN or inf)")
+    if probs.size and (probs.min() < -_TOLERANCE or probs.max() > 1.0 + _TOLERANCE):
+        raise ValueError("probabilities must lie in [0, 1]")
+    scene_shape = score_model.trained_on.get("scene_shape") if score_model is not None else None
+    if scene_shape is not None and tuple(scene_shape) != probs.shape:
+        raise ValueError(
+            f"the score model was trained on {tuple(scene_shape)} scenes, got {probs.shape}: "
+            "its features are in pixels, so retrain it for this scene size"
+        )
+
+    binary = (probs > config.semantic_threshold).astype(np.uint8)
+    if not binary.any():
+        return [], []
+
+    masks, scores = detect_instances(binary, config.mannstein)
+    masks = grow_instances(
+        masks,
+        probs,
+        scores,
+        threshold=config.grow_threshold,
+        steps=config.grow_steps,
+        connectivity=config.grow_connectivity,
+    )
+    if config.probability_scores:
+        scores = probability_weighted_scores(masks, probs, scores)
+    if score_model is not None:
+        scores = [float(v) for v in score_model.predict(scene_features(masks, probs, scores))]
+    return masks, scores

deepcontrail/instance/refine.py

@@ -0,0 +1,119 @@
+"""Refinement of detected instances using the semantic probability map.
+
+Annotators draw contrails wider than a semantic mask thresholded at 0.5: the model is
+trained on agreement-weighted soft labels, so contrail edges where only some annotators
+agree fall below 0.5. Growing each instance into neighbouring pixels of moderate
+probability brings its shape closer to an annotated contrail.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.ndimage import binary_dilation
+
+_STRUCTURES = {
+    4: np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]], dtype=bool),
+    8: np.ones((3, 3), dtype=bool),
+}
+
+
+def grow_instances(
+    masks: list[np.ndarray],
+    probs: np.ndarray,
+    scores: list[float],
+    threshold: float,
+    steps: int,
+    connectivity: int = 4,
+) -> list[np.ndarray]:
+    """Grow instances into neighbouring pixels whose probability exceeds ``threshold``.
+
+    Each step adds, to every instance, its neighbours (4- or 8-connected) with
+    ``probs > threshold`` that belong to no instance yet. A pixel reached by several
+    instances in the same step goes to the highest-scoring one (the first one on ties),
+    so every newly grown pixel belongs to exactly one instance. Pixels an instance
+    already had are always kept, and pixels of other instances are never taken.
+
+    Parameters
+    ----------
+    masks
+        Boolean instance masks, each ``(H, W)``.
+    probs
+        Semantic probability map ``(H, W)`` in ``[0, 1]``.
+    scores
+        One score per instance, used to settle contested pixels.
+    threshold
+        Growth only enters pixels with ``probs > threshold``.
+    steps
+        Number of growth steps (0 returns copies of the input).
+    connectivity
+        4 or 8.
+
+    Returns
+    -------
+    list[np.ndarray]
+        Grown boolean masks, aligned with ``masks``.
+
+    Raises
+    ------
+    ValueError
+        If ``connectivity`` is not 4 or 8, ``steps`` is negative, or ``scores`` does
+        not have one entry per mask.
+    """
+    if connectivity not in _STRUCTURES:
+        raise ValueError(f"connectivity must be 4 or 8, got {connectivity}")
+    if steps < 0:
+        raise ValueError(f"steps must be >= 0, got {steps}")
+    if len(scores) != len(masks):
+        raise ValueError(f"need one of scores per mask, got {len(scores)} for {len(masks)}")
+    grown = [m.astype(bool).copy() for m in masks]
+    if not grown or steps == 0:
+        return grown
+
+    structure = _STRUCTURES[connectivity]
+    allowed = probs > threshold
+    owned = np.any(np.stack(grown), axis=0)
+    order = sorted(range(len(grown)), key=lambda i: -scores[i])
+    for _ in range(steps):
+        claimed = np.zeros_like(owned)
+        additions = []
+        for i in order:
+            dilated = np.asarray(binary_dilation(grown[i], structure), dtype=bool)
+            new = dilated & allowed & ~owned & ~claimed
+            claimed |= new
+            additions.append((i, new))
+        if not claimed.any():
+            break
+        for i, new in additions:
+            grown[i] |= new
+        owned |= claimed
+    return grown
+
+
+def probability_weighted_scores(
+    masks: list[np.ndarray], probs: np.ndarray, scores: list[float]
+) -> list[float]:
+    """Multiply each instance score by the mean probability over the instance.
+
+    The semantic probability reflects how many annotators would mark a pixel, so it
+    ranks instances by expected agreement. Empty masks score 0.
+
+    Parameters
+    ----------
+    masks
+        Boolean instance masks, each ``(H, W)``.
+    probs
+        Semantic probability map ``(H, W)`` in ``[0, 1]``.
+    scores
+        Base score per instance (e.g. the Mannstein quality score).
+
+    Returns
+    -------
+    list[float]
+        Weighted scores, aligned with ``masks``.
+    """
+    weighted = []
+    for mask, score in zip(masks, scores, strict=True):
+        # A 0/1 int mask indexes ``probs`` by position rather than selecting its True pixels.
+        bool_mask = np.asarray(mask, dtype=bool)
+        weighted.append(float(score * probs[bool_mask].mean()) if bool_mask.any() else 0.0)
+    return weighted