deepcontrail-instance 0.1.0__py3-none-any.whl

deepcontrail/instance/config.py

@@ -0,0 +1,237 @@
+"""Pydantic configuration model for Mannstein instance detection.
+
+Serializable via ``model_dump()``. Uses only pydantic + pyyaml — no torch,
+scipy, or numpy at module level.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+FORMAT_VERSION = 1
+"""Version of the instance config file layout (``format_version`` in the YAML files)."""
+
+_SECTIONS = ("format_version", "mannstein", "pipeline")
+
+
+def _read_sections(path: str | Path) -> dict[str, Any]:
+    """Read an instance config YAML and check its top-level keys and format version."""
+    with Path(path).open() as f:
+        raw = yaml.safe_load(f) or {}
+    unknown = sorted(set(raw) - set(_SECTIONS))
+    if unknown:
+        raise ValueError(f"{path}: unknown section(s) {unknown}; expected {list(_SECTIONS)}")
+    version = raw.get("format_version", FORMAT_VERSION)
+    if version != FORMAT_VERSION:
+        raise ValueError(f"{path}: format_version {version!r} is not supported ({FORMAT_VERSION})")
+    return raw
+
+
+class MannsteinConfig(BaseModel):
+    """Settings of the Mannstein step that splits a binary contrail mask into contrails.
+
+    The defaults are the tuned settings of the default pipeline (``InstancePipelineConfig()``),
+    chosen for one contrail per annotator-drawn contrail (pooled mAP over IoU 0.25-0.75).
+
+    Parameters
+    ----------
+    line_filter
+        Keep only mask pixels where an oriented line kernel responds above
+        ``response_threshold`` before splitting. Off by default: at the tuned settings it keeps
+        every pixel of the mask and takes most of the run time.
+    num_kernels
+        Number of oriented line kernels (line filter only).
+    kernel_size
+        Kernel size in pixels, odd (line filter only).
+    sigma1
+        Inner Gaussian sigma in pixels (line filter only).
+    sigma_delta
+        Outer minus inner Gaussian sigma, in pixels (line filter only).
+    response_threshold
+        Minimum kernel response (line filter only).
+    min_pixels
+        Minimum contrail size in pixels.
+    min_length
+        Minimum contrail length in pixels.
+    min_r_score
+        Minimum straightness, squared before the comparison: a contrail is kept when its
+        straightness ((λ1 - λ2) / (λ1 + λ2))², from the eigenvalues of its pixel-coordinate
+        covariance, exceeds ``min_r_score²``. The measure does not depend on the direction.
+    lookback
+        Number of most recent pixels of a growing contrail used to fit its local direction.
+    alignment_threshold
+        A neighbouring pixel joins a growing contrail when it lies within this many pixels of
+        the contrail's local direction.
+    fit_avg_size
+        Pixels averaged at each end of a contrail when measuring its length, for the
+        length/straightness filter and the minimum size of a scored contrail.
+    filter_avg_size
+        Overrides ``fit_avg_size`` for the length/straightness filter only. ``None`` reuses
+        ``fit_avg_size``.
+    iou_threshold
+        Two candidates overlapping more than this IoU are duplicates; the first found is kept.
+    score_saturation
+        Pixel count at which the size part of the score, tanh(n_pixels / score_saturation),
+        approaches 1.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    line_filter: bool = False
+    num_kernels: Annotated[int, Field(gt=0)] = 24
+    kernel_size: Annotated[int, Field(gt=0)] = 25
+    sigma1: Annotated[float, Field(gt=0.0)] = 3.38996845929638
+    sigma_delta: Annotated[float, Field(gt=0.0)] = 0.7008195042725893
+    response_threshold: Annotated[float, Field(ge=0.0)] = 0.00012714987768293402
+    min_pixels: Annotated[int, Field(gt=0)] = 5
+    min_length: Annotated[float, Field(gt=0.0)] = 4.173422506229322
+    min_r_score: Annotated[float, Field(ge=0.0, le=1.0)] = 0.07830797096507566
+    lookback: Annotated[int, Field(gt=0)] = 53
+    alignment_threshold: Annotated[float, Field(gt=0.0)] = 2.4559123612088265
+    fit_avg_size: Annotated[int, Field(gt=0)] = 2
+    filter_avg_size: Annotated[int, Field(gt=0)] | None = 2
+    iou_threshold: Annotated[float, Field(ge=0.0, le=1.0)] = 0.29602142259052816
+    score_saturation: Annotated[float, Field(gt=0.0)] = 26.486876651437136
+
+    @model_validator(mode="after")
+    def _validate_kernel_size(self) -> MannsteinConfig:
+        """Ensure kernel_size is odd."""
+        if self.kernel_size % 2 == 0:
+            raise ValueError(f"kernel_size must be odd, got {self.kernel_size}")
+        return self
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> MannsteinConfig:
+        """Build a ``MannsteinConfig`` from a plain dictionary."""
+        return cls.model_validate(d)
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> MannsteinConfig:
+        """Load a ``MannsteinConfig`` from the ``mannstein:`` section of a YAML file.
+
+        Fields missing from the section keep their defaults; unknown fields are an error.
+
+        Raises
+        ------
+        ValueError
+            If the file has no ``mannstein:`` section, unknown sections or fields, or another
+            ``format_version``.
+        """
+        sections = _read_sections(path)
+        if "mannstein" not in sections:
+            raise ValueError(f"{path} has no mannstein: section")
+        return cls.model_validate({**cls().model_dump(), **sections["mannstein"]})
+
+
+# Mannstein settings of the consensus preset: tuned with scripts/optimize_mannstein.py on each
+# annotator's own mask (train), then chosen on validation predictions for the consensus target
+# (see configs/instance_pipeline_consensus.yaml).
+_CONSENSUS_MANNSTEIN = MannsteinConfig(
+    num_kernels=27,
+    kernel_size=15,
+    sigma1=1.6281154034079715,
+    sigma_delta=0.6895797586480001,
+    response_threshold=0.00012114447935536606,
+    min_pixels=10,
+    min_length=3.6267323822860877,
+    min_r_score=0.05470144383145452,
+    lookback=53,
+    alignment_threshold=2.663708517028666,
+    fit_avg_size=3,
+    filter_avg_size=2,
+    iou_threshold=0.41435493420805575,
+    score_saturation=18.325171813375093,
+)
+
+
+class InstancePipelineConfig(BaseModel):
+    """Configuration of the probability-map instance pipeline.
+
+    The pipeline thresholds a semantic probability map, splits the binary mask into
+    contrails with Mannstein, grows each contrail into neighbouring pixels of moderate
+    probability, and scores it. The defaults are the tuned pipeline, and their Mannstein part
+    is ``MannsteinConfig()``.
+
+    Parameters
+    ----------
+    semantic_threshold
+        Pixels with probability above this value form the binary mask given to Mannstein.
+    grow_threshold
+        Growth enters neighbouring pixels with probability above this value.
+    grow_steps
+        Number of one-pixel growth steps (0 disables growth).
+    grow_connectivity
+        Neighbourhood used for growth: 4 or 8.
+    probability_scores
+        Multiply each Mannstein score by the contrail's mean probability.
+    mannstein
+        Settings of the Mannstein splitting step.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    semantic_threshold: Annotated[float, Field(gt=0.0, lt=1.0)] = 0.46466753022859164
+    grow_threshold: Annotated[float, Field(ge=0.0, lt=1.0)] = 0.3711273368123679
+    grow_steps: Annotated[int, Field(ge=0)] = 1
+    grow_connectivity: Literal[4, 8] = 8
+    probability_scores: bool = True
+    mannstein: MannsteinConfig = MannsteinConfig()
+
+    @classmethod
+    def consensus(cls) -> InstancePipelineConfig:
+        """Return the settings for contrails agreed by most annotators.
+
+        Same as ``configs/instance_pipeline_consensus.yaml``.
+
+        No growth: growth widens contrails toward how single annotators draw them, which helps
+        when each annotator is the ground truth (the defaults) but not for the consensus.
+        """
+        return cls(
+            semantic_threshold=0.5,
+            grow_threshold=0.4,
+            grow_steps=0,
+            grow_connectivity=8,
+            probability_scores=True,
+            mannstein=_CONSENSUS_MANNSTEIN,
+        )
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> InstancePipelineConfig:
+        """Build an ``InstancePipelineConfig`` from a plain dictionary."""
+        return cls.model_validate(d)
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> InstancePipelineConfig:
+        """Load from a YAML file with ``pipeline:`` and ``mannstein:`` sections.
+
+        Either section may be missing or partial: what is missing is taken from the preset
+        ``InstancePipelineConfig()``, so ``mannstein: {num_kernels: 24}`` changes only
+        ``num_kernels``. Unknown sections or fields are an error, so a typo is never silently
+        replaced by a default.
+
+        Raises
+        ------
+        ValueError
+            On unknown sections or fields, invalid values, or another ``format_version``.
+        """
+        sections = _read_sections(path)
+        preset = cls().model_dump()
+        mannstein = {**preset.pop("mannstein"), **sections.get("mannstein", {})}
+        return cls.model_validate(
+            {**preset, **sections.get("pipeline", {}), "mannstein": mannstein}
+        )
+
+    def to_yaml(self, path: str | Path) -> None:
+        """Write ``format_version`` and the ``mannstein:`` and ``pipeline:`` sections."""
+        data = self.model_dump()
+        mannstein = data.pop("mannstein")
+        with Path(path).open("w") as f:
+            yaml.safe_dump(
+                {"format_version": FORMAT_VERSION, "mannstein": mannstein, "pipeline": data},
+                f,
+                sort_keys=False,
+            )

deepcontrail/instance/io.py

@@ -0,0 +1,139 @@
+"""Instance masks from your own annotations, and detected contrails as COCO results.
+
+The instance tools read only ``instance_masks/<split>/<id>.npy``: an ``(N, H, W, A)`` int8 array
+where 1 marks a pixel of contrail n drawn by annotator a, 0 a pixel it does not cover, and -1
+that annotator a drew no contrail n (``A = 1`` for a single annotator). The two builders below
+write that array from a label image or from per-annotator masks. COCO polygons can be turned
+into masks first with ``pycocotools`` (``COCO.annToMask``).
+
+``to_coco_results`` saves detections as COCO result entries with RLE masks: overlapping
+contrails stay separate, and the format is read by standard COCO tools.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def instance_masks_from_label_image(labels: np.ndarray) -> np.ndarray:
+    """Build single-annotator instance masks from a label image.
+
+    Parameters
+    ----------
+    labels
+        Integer ``(H, W)`` image: 0 is background, every other value one contrail (values need
+        not be consecutive). Contrails cannot overlap in a label image.
+
+    Returns
+    -------
+    np.ndarray
+        ``(N, H, W, 1)`` int8, contrails in increasing label order.
+    """
+    labels = np.asarray(labels)
+    if labels.ndim != 2:
+        raise ValueError(f"labels must be a 2-D (H, W) image, got shape {labels.shape}")
+    ids = [v for v in np.unique(labels) if v != 0]
+    raw = np.zeros((len(ids), *labels.shape, 1), dtype=np.int8)
+    for n, value in enumerate(ids):
+        raw[n, :, :, 0] = labels == value
+    return raw
+
+
+def instance_masks_from_annotators(
+    contrails: Sequence[Sequence[np.ndarray]], shape: tuple[int, int] | None = None
+) -> np.ndarray:
+    """Build instance masks from the contrails each annotator drew.
+
+    Parameters
+    ----------
+    contrails
+        ``contrails[a]`` holds the boolean ``(H, W)`` masks of annotator ``a``'s contrails;
+        an annotator may have drawn none. Contrail n of one annotator and contrail n of another
+        are unrelated.
+    shape
+        Image size, required only when nobody drew anything.
+
+    Returns
+    -------
+    np.ndarray
+        ``(N, H, W, A)`` int8 with N the most contrails any annotator drew; -1 where annotator
+        a drew fewer than n + 1 contrails.
+
+    Raises
+    ------
+    ValueError
+        If masks have different shapes, or no mask and no ``shape`` is given.
+    """
+    masks = [np.asarray(m, dtype=bool) for drawn in contrails for m in drawn]
+    shapes = {m.shape for m in masks} | ({tuple(shape)} if shape is not None else set())
+    if len(shapes) != 1:
+        raise ValueError(
+            f"all masks must have one shape (pass shape= when nobody drew), got {sorted(shapes)}"
+        )
+    (h, w) = shapes.pop()
+    n = max((len(drawn) for drawn in contrails), default=0)
+    raw = np.full((n, h, w, len(contrails)), -1, dtype=np.int8)
+    for a, drawn in enumerate(contrails):
+        for k, mask in enumerate(drawn):
+            raw[k, :, :, a] = np.asarray(mask, dtype=bool)
+    return raw
+
+
+def to_coco_results(
+    masks: Sequence[np.ndarray],
+    scores: Sequence[float],
+    image_id: int | str,
+    category_id: int = 1,
+) -> list[dict[str, Any]]:
+    """Turn one scene's detections into COCO result entries with RLE masks.
+
+    Parameters
+    ----------
+    masks
+        Boolean ``(H, W)`` contrail masks, e.g. from ``detect_instances_from_probabilities``.
+    scores
+        One score per mask.
+    image_id
+        Identifier of the scene, copied into every entry.
+    category_id
+        COCO category of a contrail.
+
+    Returns
+    -------
+    list[dict]
+        ``{"image_id", "category_id", "segmentation": {"size", "counts"}, "score"}`` per
+        contrail, ready for ``json.dump`` (RLE counts as text).
+
+    Raises
+    ------
+    ValueError
+        If ``scores`` does not have one entry per mask.
+    """
+    try:
+        import pycocotools.mask as mask_utils
+    except ImportError as err:
+        raise ImportError(
+            "to_coco_results needs pycocotools: pip install 'deepcontrail-instance[map]'"
+        ) from err
+
+    if len(scores) != len(masks):
+        raise ValueError(f"need one score per mask, got {len(scores)} for {len(masks)}")
+    results = []
+    for mask, score in zip(masks, scores, strict=True):
+        rle = mask_utils.encode(np.asfortranarray(np.asarray(mask, dtype=np.uint8)))
+        counts = rle["counts"]
+        counts = counts.decode() if isinstance(counts, bytes) else counts
+        results.append(
+            {
+                "image_id": image_id,
+                "category_id": category_id,
+                "segmentation": {"size": list(rle["size"]), "counts": counts},
+                "score": float(score),
+            }
+        )
+    return results

deepcontrail/instance/labels.py

@@ -0,0 +1,211 @@
+"""Labels derived from instance masks: each annotator's mask, agreement, consensus contrails.
+
+The instance task needs only ``instance_masks``: each annotator's mask, the agreement map and
+the consensus mask are derived from it (``*_from_instances``), for any number of annotators,
+one included. On OpenContrails they equal the stored ``annotator_masks``, ``probability_masks``
+and ``semantic_masks`` exactly. The consensus contrails (:func:`build_consensus_instances`) are
+the instance-level counterpart of the consensus mask.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from deepcontrail.core.readers import extract_all_annotator_instances
+
+
+def partition_gt_instances_by_semantic(
+    all_gt: list[list[list[np.ndarray]]],
+    semantic_masks: list[np.ndarray],
+    min_overlap_fraction: float = 0.5,
+    tolerance_px: int = 1,
+) -> tuple[list[list[list[np.ndarray]]], list[list[list[np.ndarray]]]]:
+    """Split ground-truth instances into those lying mostly on the semantic mask and the rest.
+
+    The first step of :func:`build_consensus_instances`. Always pass the ground-truth
+    semantic mask, never a prediction.
+
+    Parameters
+    ----------
+    all_gt
+        ``all_gt[scene][slot]`` is the list of boolean ``(H, W)`` instance masks of one
+        annotator slot. Slots are split independently.
+    semantic_masks
+        One boolean ``(H, W)`` ground-truth semantic mask per scene, in the order of ``all_gt``.
+    min_overlap_fraction
+        An instance is kept when at least this fraction of its pixels lies inside the mask
+        (within ``tolerance_px``); kept instances stay whole. With 0.5, a contrail that only
+        crosses or touches a consensus contrail is set aside.
+    tolerance_px
+        Pixels within this many 4-connected steps of the mask count as inside, so the same
+        contrail drawn 1 px off by an annotator is kept. 0 means strictly inside.
+
+    Returns
+    -------
+    tuple[list[list[list[np.ndarray]]], list[list[list[np.ndarray]]]]
+        ``(kept, dropped)``, both with the scene and slot structure of ``all_gt``.
+
+    Raises
+    ------
+    ValueError
+        If the number of scenes differs between the two inputs, or
+        ``min_overlap_fraction`` is not in ``(0, 1]``, or ``tolerance_px`` is negative.
+    """
+    if len(all_gt) != len(semantic_masks):
+        raise ValueError(
+            f"need one semantic mask per scene, got {len(semantic_masks)} for {len(all_gt)} scenes"
+        )
+    if not 0.0 < min_overlap_fraction <= 1.0:
+        raise ValueError(f"min_overlap_fraction must be in (0, 1], got {min_overlap_fraction}")
+    if tolerance_px < 0:
+        raise ValueError(f"tolerance_px must be >= 0, got {tolerance_px}")
+    kept: list[list[list[np.ndarray]]] = []
+    dropped: list[list[list[np.ndarray]]] = []
+    for scene, semantic in zip(all_gt, semantic_masks, strict=True):
+        inside = _grow_4connected(np.asarray(semantic, dtype=bool), tolerance_px)
+        keep_scene: list[list[np.ndarray]] = []
+        drop_scene: list[list[np.ndarray]] = []
+        for slot in scene:
+            is_kept = [
+                bool(m.any())
+                and np.count_nonzero(m & inside) >= min_overlap_fraction * np.count_nonzero(m)
+                for m in slot
+            ]
+            keep_scene.append([m for m, k in zip(slot, is_kept, strict=True) if k])
+            drop_scene.append([m for m, k in zip(slot, is_kept, strict=True) if not k])
+        kept.append(keep_scene)
+        dropped.append(drop_scene)
+    return kept, dropped
+
+
+def _grow_4connected(mask: np.ndarray, steps: int) -> np.ndarray:
+    """Dilate a boolean mask by ``steps`` 4-connected steps (numpy only)."""
+    grown = mask.copy()
+    for _ in range(steps):
+        step = grown.copy()
+        step[1:, :] |= grown[:-1, :]
+        step[:-1, :] |= grown[1:, :]
+        step[:, 1:] |= grown[:, :-1]
+        step[:, :-1] |= grown[:, 1:]
+        grown = step
+    return grown
+
+
+def build_consensus_instances(
+    gt_per_slot: list[list[np.ndarray]],
+    semantic_mask: np.ndarray,
+    min_overlap_fraction: float = 0.5,
+    tolerance_px: int = 1,
+    link_iou: float = 0.5,
+) -> list[np.ndarray]:
+    """Build one set of consensus contrail instances for a scene from all annotators.
+
+    The instance-level counterpart of the consensus semantic mask:
+
+    1. keep each annotator's instances with at least ``min_overlap_fraction`` of their
+       pixels within ``tolerance_px`` of the consensus mask, and clip them to the mask;
+    2. link instances of different annotators whose clipped masks reach ``link_iou``;
+    3. keep the linked groups drawn by more than half of the scene's annotators;
+    4. each kept instance is the union of its group's clipped masks.
+
+    Instances may share pixels where contrails cross. The result no longer depends on
+    which annotator drew what, only on what a majority agreed on.
+
+    Parameters
+    ----------
+    gt_per_slot
+        ``gt_per_slot[slot]`` is one annotator's list of boolean ``(H, W)`` instance masks.
+    semantic_mask
+        Boolean ``(H, W)`` consensus semantic mask of the scene.
+    min_overlap_fraction
+        See :func:`partition_gt_instances_by_semantic`.
+    tolerance_px
+        See :func:`partition_gt_instances_by_semantic`.
+    link_iou
+        IoU between two clipped instances of different annotators to treat them as the
+        same contrail.
+
+    Returns
+    -------
+    list[np.ndarray]
+        Boolean ``(H, W)`` consensus instance masks (empty when the scene has no consensus
+        contrail or no annotator).
+    """
+    n_slots = len(gt_per_slot)
+    semantic = np.asarray(semantic_mask, dtype=bool)
+    if n_slots == 0 or not semantic.any():
+        return []
+    kept, _ = partition_gt_instances_by_semantic(
+        [gt_per_slot], [semantic], min_overlap_fraction, tolerance_px
+    )
+    nodes = [(slot, m & semantic) for slot, masks in enumerate(kept[0]) for m in masks]
+    nodes = [(slot, clipped) for slot, clipped in nodes if clipped.any()]
+
+    parent = list(range(len(nodes)))
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    for i, (slot_i, mask_i) in enumerate(nodes):
+        for j in range(i + 1, len(nodes)):
+            slot_j, mask_j = nodes[j]
+            if slot_i == slot_j:
+                continue
+            union = np.count_nonzero(mask_i | mask_j)
+            if union and np.count_nonzero(mask_i & mask_j) / union >= link_iou:
+                parent[find(i)] = find(j)
+
+    groups: dict[int, list[int]] = {}
+    for i in range(len(nodes)):
+        groups.setdefault(find(i), []).append(i)
+
+    instances: list[np.ndarray] = []
+    for members in groups.values():
+        if len({nodes[i][0] for i in members}) * 2 > n_slots:
+            instances.append(np.logical_or.reduce([nodes[i][1] for i in members]))
+    return instances
+
+
+def annotator_masks_from_instances(raw: np.ndarray) -> np.ndarray:
+    """Return each annotator's mask: the union of the contrails they drew.
+
+    Parameters
+    ----------
+    raw
+        Instance mask array ``(N, H, W, A)`` (1 = pixel of instance n for annotator a).
+
+    Returns
+    -------
+    np.ndarray
+        ``(H, W, A)`` uint8 in ``{0, 1}``; all zeros for a scene without contrails.
+    """
+    if raw.shape[0] == 0:
+        return np.zeros(raw.shape[1:], dtype=np.uint8)
+    return np.any(raw == 1, axis=0).astype(np.uint8)
+
+
+def agreement_from_instances(raw: np.ndarray) -> np.ndarray:
+    """Return the share of annotators who marked each pixel, ``(H, W)`` float32 in ``[0, 1]``."""
+    return annotator_masks_from_instances(raw).mean(axis=-1, dtype=np.float32)
+
+
+def consensus_mask_from_instances(raw: np.ndarray) -> np.ndarray:
+    """Return the pixels marked by more than half of the annotators, ``(H, W)`` bool."""
+    return agreement_from_instances(raw) > 0.5
+
+
+def consensus_instances(raw: np.ndarray) -> list[np.ndarray]:
+    """Return the scene's consensus contrails, from its instance masks alone.
+
+    See :func:`build_consensus_instances`; the consensus mask is
+    :func:`consensus_mask_from_instances`. With a single annotator, every contrail they drew
+    is kept.
+    """
+    if raw.shape[0] == 0:
+        return []
+    return build_consensus_instances(
+        extract_all_annotator_instances(raw), consensus_mask_from_instances(raw)
+    )