deepcontrail-instance 0.1.0__py3-none-any.whl

deepcontrail/instance/scoring.py

@@ -0,0 +1,405 @@
+"""Learned contrail scores: re-rank detected contrails with a model trained on your data.
+
+The pipeline's scores (Mannstein's straightness and size, times the mean probability) rank
+detections only roughly. A :class:`ScoreModel` predicts, from a few features of each detected
+contrail (:data:`FEATURES`), how well it matches the annotated contrails, and that prediction
+replaces its score. The masks do not change, so only the ranking (and the mAP) changes.
+
+The features depend on the semantic model's probabilities, so a score model belongs to one
+semantic model and one pipeline config: train it on that model's predictions for scenes it was
+not trained on (e.g. its validation split), with :func:`training_data` and
+:meth:`ScoreModel.fit`. Fitting uses scikit-learn's gradient boosting; the fitted trees are
+exported to plain JSON, so using a model needs numpy only and loading a file runs no code.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from importlib.metadata import version
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import numpy as np
+from scipy.ndimage import binary_dilation
+
+from deepcontrail.instance.config import InstancePipelineConfig
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+FEATURES: tuple[str, ...] = (
+    "n_pixels",
+    "length",
+    "width",
+    "straightness",
+    "mean_prob",
+    "max_prob",
+    "min_prob",
+    "std_prob",
+    "p10_prob",
+    "p90_prob",
+    "frac_above_0_7",
+    "ring_mean_prob",
+    "contrast",
+    "pipeline_score",
+    "n_scene_instances",
+    "shared_pixels_frac",
+    "scene_pred_area",
+    "border_distance",
+    "orientation_sin2",
+    "orientation_cos2",
+)
+"""Names of the features of one detected contrail, in the order of :func:`instance_features`."""
+
+
+def instance_features(
+    mask: np.ndarray, probs: np.ndarray, score: float, scene_masks: Sequence[np.ndarray]
+) -> np.ndarray:
+    """Describe one detected contrail (size, shape, probabilities, surroundings).
+
+    Parameters
+    ----------
+    mask
+        Boolean ``(H, W)`` mask of the contrail.
+    probs
+        The scene's probability map ``(H, W)``.
+    score
+        The contrail's score from the pipeline.
+    scene_masks
+        All contrails detected in the scene, ``mask`` included.
+
+    Returns
+    -------
+    np.ndarray
+        One value per name in :data:`FEATURES`.
+    """
+    # A 0/1 int mask indexes ``probs`` by position and ``~mask`` is a bitwise not, so compute on a
+    # bool copy. But keep the identity test below on the original objects: a bool copy is no longer
+    # ``is`` the mask in scene_masks, and the contrail would then count as overlapping itself.
+    bool_mask = np.asarray(mask, dtype=bool)
+    ys, xs = np.nonzero(bool_mask)
+    n = len(ys)
+    values = probs[bool_mask]
+    coords = np.stack([ys, xs], axis=1).astype(float)
+    centre = coords.mean(axis=0)
+    if n >= 2:
+        eigvals, eigvecs = np.linalg.eigh(np.cov((coords - centre).T))
+        along = (coords - centre) @ eigvecs[:, -1]
+        length = float(along.max() - along.min() + 1.0)
+        straightness = float(1.0 - eigvals[0] / eigvals[-1]) if eigvals[-1] > 0 else 0.0
+        angle = float(np.arctan2(eigvecs[0, -1], eigvecs[1, -1]))
+    else:
+        length, straightness, angle = float(n), 0.0, 0.0
+    ring = binary_dilation(bool_mask, np.ones((3, 3), dtype=bool)) & ~bool_mask
+    ring_mean = float(probs[ring].mean()) if ring.any() else 0.0
+    others = [np.asarray(m, dtype=bool) for m in scene_masks if m is not mask]
+    shared = (
+        float(np.logical_and(bool_mask, np.any(np.stack(others), axis=0)).sum() / n)
+        if others
+        else 0.0
+    )
+    h, w = bool_mask.shape
+    border = min(centre[0], centre[1], h - 1 - centre[0], w - 1 - centre[1]) / max(h, w)
+    union_area = (
+        float(np.any(np.stack([np.asarray(m, dtype=bool) for m in scene_masks]), axis=0).sum())
+        if scene_masks
+        else 0.0
+    )
+    return np.array(
+        [
+            n,
+            length,
+            n / length if length else 0.0,
+            straightness,
+            values.mean(),
+            values.max(),
+            values.min(),
+            values.std(),
+            np.percentile(values, 10),
+            np.percentile(values, 90),
+            np.mean(values > 0.7),
+            ring_mean,
+            values.mean() - ring_mean,
+            score,
+            len(scene_masks),
+            shared,
+            union_area,
+            border,
+            np.sin(2 * angle),
+            np.cos(2 * angle),
+        ],
+        dtype=float,
+    )
+
+
+def scene_features(
+    masks: Sequence[np.ndarray], probs: np.ndarray, scores: Sequence[float]
+) -> np.ndarray:
+    """Return the ``(n_contrails, len(FEATURES))`` features of one scene's detections."""
+    if not masks:
+        return np.zeros((0, len(FEATURES)))
+    return np.stack(
+        [instance_features(m, probs, s, masks) for m, s in zip(masks, scores, strict=True)]
+    )
+
+
+def _best_iou(mask: np.ndarray, gts: Sequence[np.ndarray]) -> float:
+    best = 0.0
+    for g in gts:
+        union = np.logical_or(mask, g).sum()
+        if union:
+            best = max(best, float(np.logical_and(mask, g).sum() / union))
+    return best
+
+
+def match_quality(mask: np.ndarray, gts_per_annotator: Sequence[Sequence[np.ndarray]]) -> float:
+    """Training label: mean best IoU of ``mask`` over the annotators who drew a contrail.
+
+    Parameters
+    ----------
+    mask
+        Boolean ``(H, W)`` mask of one detected contrail.
+    gts_per_annotator
+        For each annotator of the scene, the boolean masks of the contrails they drew.
+
+    Returns
+    -------
+    float
+        In ``[0, 1]``; 0.0 if no annotator drew anything.
+    """
+    drawn = [g for g in gts_per_annotator if g]
+    return float(np.mean([_best_iou(mask, g) for g in drawn])) if drawn else 0.0
+
+
+def training_data(
+    probs: Sequence[np.ndarray],
+    gts: Sequence[Sequence[Sequence[np.ndarray]]],
+    config: InstancePipelineConfig,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Run the pipeline on each scene and return features and labels of every detection.
+
+    Parameters
+    ----------
+    probs
+        Probability maps of the training scenes.
+    gts
+        ``gts[i][a]`` holds the contrail masks drawn by annotator ``a`` on scene ``i``.
+    config
+        The pipeline config the score model will be used with.
+
+    Returns
+    -------
+    tuple[np.ndarray, np.ndarray]
+        Features ``(n, len(FEATURES))`` and labels ``(n,)`` (:func:`match_quality`).
+    """
+    from deepcontrail.instance.pipeline import detect_instances_from_probabilities
+
+    rows, labels = [], []
+    for scene_probs, scene_gts in zip(probs, gts, strict=True):
+        p = np.asarray(scene_probs, dtype=np.float32)
+        masks, scores = detect_instances_from_probabilities(p, config)
+        rows.append(scene_features(masks, p, scores))
+        labels.extend(match_quality(m, scene_gts) for m in masks)
+    x = np.concatenate(rows) if rows else np.zeros((0, len(FEATURES)))
+    return x, np.asarray(labels, dtype=float)
+
+
+_NODE_FIELDS = ("feature_idx", "num_threshold", "missing_go_to_left", "left", "right", "is_leaf")
+
+# The keys to_json writes per tree: _NODE_FIELDS plus the leaf values.
+_TREE_KEYS = (*_NODE_FIELDS, "value")
+
+
+def _check_tree(index: int, tree: dict[str, np.ndarray]) -> None:
+    """Reject a malformed tree before :meth:`ScoreModel.predict` walks it.
+
+    ``predict`` follows ``left``/``right`` and indexes ``feature_idx`` without checking bounds or
+    cycles, so a corrupt file would loop forever (a child pointing at its parent), read the wrong
+    feature (a negative index), or fail mid-prediction (ragged or non-finite arrays). The
+    ``left``/``right``/``feature_idx``/``num_threshold`` of leaves are unchecked scikit-learn
+    placeholders.
+    """
+    expected_keys = set(_TREE_KEYS)
+    if set(tree) != expected_keys:
+        raise ValueError(
+            f"score model tree {index}: keys {sorted(set(tree))} are not {sorted(expected_keys)}"
+        )
+    n = len(tree["value"])
+    lengths = [len(tree[key]) for key in expected_keys]
+    if n < 1 or any(length != n for length in lengths):
+        raise ValueError(
+            f"score model tree {index}: node arrays have lengths {lengths}, expected one >= 1"
+        )
+    is_leaf = tree["is_leaf"].astype(bool)
+    for j in np.nonzero(~is_leaf)[0]:
+        left, right = int(tree["left"][j]), int(tree["right"][j])
+        if not (j < left < n and j < right < n):
+            raise ValueError(
+                f"score model tree {index}: node {j} children {left}, {right} must come after it "
+                f"and within its {n} nodes"
+            )
+        if not (0 <= int(tree["feature_idx"][j]) < len(FEATURES)):
+            raise ValueError(
+                f"score model tree {index}: node {j} feature index {int(tree['feature_idx'][j])} "
+                f"is out of range for {len(FEATURES)} features"
+            )
+        if not np.isfinite(tree["num_threshold"][j]):
+            raise ValueError(
+                f"score model tree {index}: node {j} threshold {float(tree['num_threshold'][j])} "
+                f"is not finite"
+            )
+    if not np.all(np.isfinite(tree["value"])):
+        raise ValueError(f"score model tree {index}: leaf values are not all finite")
+
+
+@dataclass(frozen=True)
+class ScoreModel:
+    """Gradient-boosted trees that predict a detected contrail's match quality.
+
+    Build one with :meth:`fit` (needs scikit-learn) or :meth:`from_json` (numpy only).
+
+    Attributes
+    ----------
+    baseline
+        Constant start value of the prediction.
+    trees
+        One dict of node arrays per tree: ``feature_idx``, ``num_threshold``,
+        ``missing_go_to_left``, ``left``, ``right``, ``is_leaf`` and ``value``.
+    pipeline_config
+        The pipeline config whose detections the model was trained on.
+    features
+        Feature names, checked on load against :data:`FEATURES`.
+    trained_on
+        What the model is valid for, since its features depend on the probability maps:
+        ``semantic_model`` (and ``semantic_revision``), ``tta``, ``scene_shape`` ``[H, W]``,
+        plus the ``scikit_learn_version`` and ``deepcontrail_instance_version`` that fitted it.
+        ``scene_shape`` is checked by the pipeline, ``tta`` by :func:`load_instance_step`.
+        Empty for files written before this record existed.
+    """
+
+    baseline: float
+    trees: tuple[dict[str, np.ndarray], ...]
+    pipeline_config: InstancePipelineConfig
+    features: tuple[str, ...] = FEATURES
+    trained_on: dict[str, Any] = field(default_factory=dict)
+
+    FORMAT_VERSION: ClassVar[int] = 1
+    """Version of the JSON layout; bump it when the features or the tree format change."""
+
+    ESTIMATOR_SETTINGS: ClassVar[dict[str, Any]] = {
+        "max_iter": 300,
+        "learning_rate": 0.05,
+        "max_leaf_nodes": 15,
+        "min_samples_leaf": 20,
+        "l2_regularization": 1.0,
+        "random_state": 0,
+    }
+
+    @classmethod
+    def fit(
+        cls,
+        x: np.ndarray,
+        y: np.ndarray,
+        pipeline_config: InstancePipelineConfig,
+        trained_on: dict[str, Any] | None = None,
+    ) -> ScoreModel:
+        """Fit the trees on features ``x`` and labels ``y`` (fixed, seeded settings).
+
+        ``trained_on`` describes the probability maps behind ``x`` (see the class attributes);
+        the scikit-learn and package versions are added to it.
+        """
+        try:
+            # The [scores] extra; resolvable only where it is installed.
+            import sklearn.ensemble  # pyright: ignore[reportMissingImports]
+        except ImportError as err:
+            raise ImportError(
+                "ScoreModel.fit needs scikit-learn: pip install 'deepcontrail-instance[scores]'"
+            ) from err
+
+        estimator = sklearn.ensemble.HistGradientBoostingRegressor(**cls.ESTIMATOR_SETTINGS).fit(
+            x, y
+        )
+        trees = []
+        for (predictor,) in estimator._predictors:
+            nodes = predictor.nodes
+            tree = {name: np.asarray(nodes[name]) for name in _NODE_FIELDS}
+            tree["value"] = np.asarray(nodes["value"], dtype=float)
+            trees.append(tree)
+        baseline = float(np.ravel(estimator._baseline_prediction)[0])
+        record = {
+            **(trained_on or {}),
+            "scikit_learn_version": sklearn.__version__,
+            "deepcontrail_instance_version": version("deepcontrail-instance"),
+        }
+        return cls(baseline, tuple(trees), pipeline_config, trained_on=record)
+
+    def predict(self, x: np.ndarray) -> np.ndarray:
+        """Predict the match quality of each row of ``x``, clipped to ``[0, 1]``.
+
+        Raises
+        ------
+        ValueError
+            If ``x`` does not have one column per feature.
+        """
+        x = np.asarray(x, dtype=float)
+        if x.ndim != 2 or x.shape[1] != len(self.features):
+            raise ValueError(f"expected {len(self.features)} features per row, got shape {x.shape}")
+        out = np.full(len(x), self.baseline)
+        for tree in self.trees:
+            node = np.zeros(len(x), dtype=int)
+            active = ~tree["is_leaf"][node].astype(bool)
+            while active.any():
+                idx = np.nonzero(active)[0]
+                current = node[idx]
+                values = x[idx, tree["feature_idx"][current]]
+                go_left = np.where(
+                    np.isnan(values),
+                    tree["missing_go_to_left"][current].astype(bool),
+                    values <= tree["num_threshold"][current],
+                )
+                node[idx] = np.where(go_left, tree["left"][current], tree["right"][current])
+                active[idx] = ~tree["is_leaf"][node[idx]].astype(bool)
+            out += tree["value"][node]
+        return np.clip(out, 0.0, 1.0)
+
+    def to_json(self, path: str | Path) -> None:
+        """Write the model as plain JSON."""
+        data = {
+            "format_version": self.FORMAT_VERSION,
+            "features": list(self.features),
+            "baseline": self.baseline,
+            "pipeline_config": self.pipeline_config.model_dump(),
+            "trained_on": self.trained_on,
+            "trees": [{k: v.tolist() for k, v in tree.items()} for tree in self.trees],
+        }
+        Path(path).write_text(json.dumps(data))
+
+    @classmethod
+    def from_json(cls, path: str | Path) -> ScoreModel:
+        """Load a model written by :meth:`to_json`.
+
+        Raises
+        ------
+        ValueError
+            If the file has another format version or other feature names.
+        """
+        data = json.loads(Path(path).read_text())
+        if data.get("format_version") != cls.FORMAT_VERSION:
+            raise ValueError(
+                f"score model format version {data.get('format_version')!r} is not supported "
+                f"(expected {cls.FORMAT_VERSION}); retrain it with this library version"
+            )
+        if tuple(data["features"]) != FEATURES:
+            raise ValueError("score model features differ from this library's FEATURES")
+        trees = tuple({k: np.asarray(v) for k, v in tree.items()} for tree in data["trees"])
+        for i, tree in enumerate(trees):
+            _check_tree(i, tree)
+        config = InstancePipelineConfig.from_dict(data["pipeline_config"])
+        return cls(
+            float(data["baseline"]),
+            trees,
+            config,
+            tuple(data["features"]),
+            trained_on=dict(data.get("trained_on", {})),
+        )

deepcontrail_instance-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: deepcontrail-instance
+Version: 0.1.0
+Summary: DeepContrail — instance segmentation of contrails: separate contrails in a segmentation map.
+Keywords: contrails,instance-segmentation,remote-sensing,satellite,GOES
+Author: EUROCONTROL
+License-Expression: EUPL-1.2
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Dist: deepcontrail-core>=0.1,<0.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pycocotools>=2.0 ; extra == 'map'
+Requires-Dist: scikit-learn>=1.3,<1.10 ; extra == 'scores'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/eurocontrol-asu/deepcontrail
+Project-URL: Documentation, https://github.com/eurocontrol-asu/deepcontrail/tree/main/packages/instance#readme
+Project-URL: Repository, https://github.com/eurocontrol-asu/deepcontrail
+Project-URL: Issues, https://github.com/eurocontrol-asu/deepcontrail/issues
+Project-URL: Changelog, https://github.com/eurocontrol-asu/deepcontrail/blob/main/CHANGELOG.md
+Provides-Extra: map
+Provides-Extra: scores
+Description-Content-Type: text/markdown
+
+# deepcontrail-instance
+
+Instance segmentation of contrails, part of
+[DeepContrail](https://github.com/eurocontrol-asu/deepcontrail): it splits a contrail
+segmentation map into individual contrails, one mask and one score each.
+
+**Status: preview.** The API may still change in the next releases.
+
+It needs only `deepcontrail-core`, numpy, scipy, pydantic and PyYAML (no torch) and never imports
+`deepcontrail.segmentation`: any model's probability map works as input. Two optional extras:
+`[map]` (pycocotools) to save detections as COCO results, and `[scores]` (scikit-learn) to train a
+score model.
+
+```bash
+pip install deepcontrail-instance                # the base package
+pip install "deepcontrail-instance[map,scores]"  # with both extras
+```
+
+## Usage
+
+```python
+import numpy as np
+from deepcontrail.instance import detect_instances_from_probabilities
+
+probs = np.load("scene_probs.npy")  # (H, W) probabilities in [0, 1]
+masks, scores = detect_instances_from_probabilities(probs)
+# masks: one boolean (H, W) mask per contrail; scores: confidence in [0, 1]
+```
+
+The pipeline thresholds the map (at 0.465), splits the mask into straight contrails with a
+Mannstein-style detection, grows each contrail by one pixel into neighbours with probability above
+0.371 (annotators draw contrails wider than the thresholded mask), and weights each score by the
+contrail's mean probability. Its settings live in `InstancePipelineConfig`; the defaults equal
+[`configs/instance_pipeline.yaml`](https://github.com/eurocontrol-asu/deepcontrail/blob/main/packages/instance/configs/instance_pipeline.yaml), and
+`InstancePipelineConfig.consensus()` equals
+[`configs/instance_pipeline_consensus.yaml`](https://github.com/eurocontrol-asu/deepcontrail/blob/main/packages/instance/configs/instance_pipeline_consensus.yaml), for when
+only contrails agreed by most annotators matter. `detect_instances(binary_mask)` runs plain
+Mannstein on any binary mask (settings: `MannsteinConfig`, whose defaults are the pipeline's;
+[`configs/mannstein_annotator_masks.yaml`](https://github.com/eurocontrol-asu/deepcontrail/blob/main/packages/instance/configs/mannstein_annotator_masks.yaml) holds the
+settings for annotators' own masks).
+
+Mannstein's oriented line filter (`MannsteinConfig(line_filter=True)`) is off in the shipped
+settings: on these masks it kept every pixel and took most of the run time.
+
+**Input.** A `(H, W)` map of probabilities in [0, 1] (after the sigmoid, not logits), on the same
+pixel grid as the masks it is compared with. NaN or infinite values are rejected. A binary mask
+also works as input: probability weighting then changes nothing, but growth can still add mask
+pixels that no contrail took. For a plain binary mask, `detect_instances(mask)` runs the
+Mannstein-style step alone.
+
+**Known limits.**
+- All settings are in pixels, tuned on GOES-16 / OpenContrails scenes (about 2 km per pixel,
+  contrails 1–3 px wide). Other resolutions need re-tuning.
+- The cut (0.465) and the growth (into p > 0.371) were tuned on the validation predictions of
+  DeepContrail's earlier reference model (UPerNet + CAFormer-B36, trained on soft labels). They
+  carry over to the current Unet++ model, which scores higher with them on every measure below.
+  For another kind of model, re-tune the pipeline on its predictions for scenes it never trained
+  on; tuning needs instance annotations.
+- Two contrails crossing at a small angle come out as one: at 10° always, at 20° with the
+  consensus settings. Touching, nearly parallel contrails also merge.
+- The COCO mAP keeps at most 100 detections per sample (a warning says when a sample has more).
+
+## With a pretrained DeepContrail model
+
+A pretrained bundle of `deepcontrail-segmentation` may carry the instance step tuned for its
+model: `instance_pipeline.yaml` and a `score_model.json` trained on that model's predictions.
+`load_instance_step` reads them from the bundle's folder (the defaults when they are absent) and
+refuses a score model made with the other test-time-augmentation setting:
+
+```python
+from deepcontrail.instance import load_instance_step, to_coco_results
+from deepcontrail.segmentation import load_pretrained, predict
+
+model = load_pretrained("eurocontrol-asu/deepcontrail-segmentation")
+step = load_instance_step(model.directory, tta=model.config.tta)
+probabilities = predict(model, composite, tta=model.config.tta)
+masks, scores = step(probabilities)
+results = to_coco_results(masks, scores, image_id="scene_1")  # JSON-ready, needs [map]
+```
+
+A score model records what it was trained on (`ScoreModel.trained_on`: semantic model, TTA,
+scene size, scikit-learn and package versions); the pipeline refuses it on scenes of another size,
+since its features are in pixels. `save_instance_step` writes the two files into a bundle folder.
+
+## Annotations and results
+
+The annotation tools need only `instance_masks`: each annotator's mask, the agreement map, the
+consensus mask and the consensus contrails (drawn by more than half of the annotators) are derived
+from it by `deepcontrail.instance.labels`, for any number of annotators, one included.
+
+Instance annotations use the `instance_masks/<split>/<id>.npy` format of the
+[DeepContrail dataset format](https://github.com/eurocontrol-asu/deepcontrail/tree/main/packages/core): an `(N, H, W, A)` int8 array (1 = pixel of contrail n
+drawn by annotator a, 0 = not, -1 = annotator a drew no contrail n; `A = 1` for one annotator),
+read with `deepcontrail.core.readers.load_instance_masks`. `instance_masks_from_label_image` and
+`instance_masks_from_annotators` build it from a label image or from per-annotator masks.
+
+`to_coco_results(masks, scores, image_id)` (needs `[map]`) saves detections as COCO results with
+RLE masks, so overlapping contrails stay separate:
+
+```python
+import json
+from deepcontrail.instance import to_coco_results
+
+json.dump(to_coco_results(masks, scores, image_id="scene_1"), open("instances.json", "w"))
+```
+
+## Learned scores
+
+A `ScoreModel` predicts, from 20 features of each detected contrail (size, shape, probabilities,
+surroundings), how well it matches the annotated contrails, and that prediction replaces its
+score; the masks do not change. The features depend on the semantic model, so a score model is
+valid only for the semantic model and pipeline settings it was trained with, and refuses other
+pipeline settings. Training (`ScoreModel.fit`, with `training_data`) needs `[scores]`; a saved
+model is plain JSON and predicts with numpy only:
+
+```python
+from deepcontrail.instance import (
+    InstancePipelineConfig,
+    ScoreModel,
+    detect_instances_from_probabilities,
+)
+
+config = InstancePipelineConfig()  # the shipped defaults, = configs/instance_pipeline.yaml
+model = ScoreModel.from_json("score_model.json")  # from a bundle, or train_score_model.py
+masks, scores = detect_instances_from_probabilities(probs, config, score_model=model)
+```
+
+## Evaluation
+
+`deepcontrail.instance.metrics.evaluate_annotator_samples` (needs `[map]`) scores detections
+against each annotator's contrails as a separate ground truth: one sample per (scene, annotator)
+pair. The headline is the COCO segmentation mAP averaged over IoU 0.25–0.75, pooled over all
+samples; precision, recall and F1 are at IoU 0.5. Samples where the annotator drew no contrail are
+skipped by default; `include_empty=True` keeps them, so every detection on them counts as false,
+which is closer to real use.
+
+Results on the OpenContrails 2025 test split (1,879 scenes, 2,700 annotator samples with at least
+one contrail), from the probabilities of DeepContrail's reference semantic model (Unet++ +
+CAFormer-B36, D4 TTA); the learned scores were trained on its validation predictions. Every
+setting was chosen on validation scenes; the test split was only scored. The consensus columns
+score each scene once against its consensus contrails.
+
+| Settings | mAP | mAP, with empty | Precision (with empty) | Recall | F1 (with empty) | Consensus mAP | Consensus mAP, all scenes |
+|---|---|---|---|---|---|---|---|
+| `configs/instance_pipeline.yaml` (defaults) | 0.273 | 0.268 | 0.532 (0.504) | 0.387 | 0.448 (0.438) | 0.424 | 0.417 |
+| `configs/instance_pipeline_consensus.yaml` (no growth) | 0.252 | 0.248 | 0.510 (0.485) | 0.350 | 0.415 (0.407) | 0.446 | 0.439 |
+| defaults + learned scores | 0.280 | 0.273 | 0.532 (0.504) | 0.387 | 0.448 (0.438) | 0.435 | 0.424 |
+| consensus settings + learned scores | 0.258 | 0.253 | 0.510 (0.485) | 0.350 | 0.415 (0.407) | 0.459 | 0.450 |
+
+On each annotator's own mask instead of a prediction, the instance step alone reaches mAP 0.921
+(`configs/mannstein_annotator_masks.yaml`). Most errors therefore come from the semantic step and
+from contrail shape: the AP is 0.50 at IoU 0.25 but 0.02 at IoU 0.75. Annotators also disagree
+strongly on individual contrails: one annotator scored against the others reaches F1 ≈ 0.35 on
+validation scenes.
+
+## Scripts (repository only)
+
+Command-line tools in [`scripts/`](https://github.com/eurocontrol-asu/deepcontrail/tree/main/packages/instance/scripts), run from the repository root. They read only
+`instance_masks/<split>/` from a dataset, plus one `<id>.npy` probability map per scene for a
+semantic model's predictions.
+
+- **`evaluate_instances.py`**: the evaluation above, on predictions (`--pred-dir`), on the
+  consensus mask (`--use-gt-semantic`) or on each annotator's mask (`--use-annotator-semantic`);
+  `--score-model`, `--include-empty`, `--consensus-gt`.
+- **`train_score_model.py`**: trains a `ScoreModel` (needs `[scores]`).
+- **`optimize_pipeline.py`** and **`optimize_mannstein.py`**: Optuna searches of the pipeline and
+  Mannstein settings (optuna is in the repository's `experiments` group); they never read the
+  test split.
+
+Tuning for your own semantic model: predict the scenes it never trained on (for example its
+validation split), search the pipeline settings on them (`optimize_pipeline.py`), train a score
+model on the same predictions (`train_score_model.py`), then score the test split once
+(`evaluate_instances.py`).
+
+```bash
+uv run python packages/instance/scripts/train_score_model.py --root <dataset_root> \
+    --pred-dir <validation probability maps> \
+    --pipeline-config packages/instance/configs/instance_pipeline.yaml --output-dir <dir>
+```
+
+## References and acknowledgements
+
+The line filter and the size, length and straightness tests follow Mannstein, Meyer & Wendling
+(1999), "Operational detection of contrails from NOAA-AVHRR data", *International Journal of
+Remote Sensing* 20(8), 1641–1660, [doi:10.1080/014311699212650](https://doi.org/10.1080/014311699212650).
+
+The direction-following region growing and the related shape tests build on ideas from a
+student project (PIE) at ISAE-SUPAERO, carried out with EUROCONTROL.

deepcontrail_instance-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+deepcontrail/instance/__init__.py,sha256=RfHWIc4w7MTQbkRgxtNm_Pvx91CoM8kZJF6VORZv0kY,1553
+deepcontrail/instance/_evaluation.py,sha256=Tipiy5ovep_Phn7QOE0UUTttg819QF_q94OGx2uFnP8,13934
+deepcontrail/instance/_growing.py,sha256=eX9a2ups7yZf0knHSn7he-SgtslLVXkKrSjZZyHe8iA,9062
+deepcontrail/instance/_lines.py,sha256=u2C8VZ4dXOAJ0zOkqOwm28tY-ynUulUsCIv3WywUEw0,5423
+deepcontrail/instance/_overlap.py,sha256=J5vNicmbQNZoAIM6LT5DRy7X3xHVVjjSxydTUARySas,2598
+deepcontrail/instance/_shape.py,sha256=-wZq4BJ-u5s4zKio-rKpq0_OJgZ4eSq3itreBQBbNLs,6686
+deepcontrail/instance/_tuning.py,sha256=h9VqwjwLTTZJ5Lfwtf24ZWRA1TSTJw5HCEhdYNgTlME,3803
+deepcontrail/instance/bundle.py,sha256=PT3dVRUk4CHETilb5siJ_JXbGc_qXOg-OiDMccAgrk0,4392
+deepcontrail/instance/config.py,sha256=bksNx0unjNLUjl3Y9b1ufoQfzMW1VKjuT4tvJQ8vw1o,9710
+deepcontrail/instance/io.py,sha256=-uZMtgF2WXlhqUn2EtQBIi6y9e-6sQ5El_UpOH9i1l4,4853
+deepcontrail/instance/labels.py,sha256=9h_P7nqi7eNUJgqlZodwZXG4yWR3ia0trLyyA2TymCU,8366
+deepcontrail/instance/mannstein.py,sha256=zIPW6PMOQBjg-RXkbgEjRxA3S21wlkbcWSCKqrZ9Br0,3996
+deepcontrail/instance/metrics.py,sha256=bCi4L6Yw5VuGejZSe_6cBzuxNPliuqHRa2jSroGpoIA,9096
+deepcontrail/instance/pipeline.py,sha256=LRQLpJoQEA-EF3C-e4buyB5NzFLJ5SbAnd6In4QsYd4,3529
+deepcontrail/instance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deepcontrail/instance/refine.py,sha256=ZIzm5o_HSfBw4vKmEP103m02IZem9dr_UP9od00MOXg,4080
+deepcontrail/instance/scoring.py,sha256=k1m9dIAa2zFce6Fq0kbfUhE1X1rmFWpV-oL7Fx8_ufI,15541
+deepcontrail_instance-0.1.0.dist-info/licenses/LICENSE,sha256=Nmh3Jhi6ZRNFGD34EKZM-xbDySWW9ur1kKYvTaZW2cA,13705
+deepcontrail_instance-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+deepcontrail_instance-0.1.0.dist-info/METADATA,sha256=MgssxtYuc3OgtcEi_TH7edGUaDIKYIz3xCu1wlrQ15Y,12193
+deepcontrail_instance-0.1.0.dist-info/RECORD,,

deepcontrail_instance-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any