deepcontrail-instance 0.1.0__tar.gz

deepcontrail_instance-0.1.0/LICENSE

@@ -0,0 +1,211 @@
+Copyright (c) 2026 EUROCONTROL
+
+# European Union Public Licence v. 1.2
+
+EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the *EUPL*) applies to the Work (as defined below) which is provided under the
+terms of this Licence. Any use of the Work, other than as authorised under this Licence is prohibited (to the extent such
+use is covered by a right of the copyright holder of the Work).
+The Work is provided under the terms of this Licence when the Licensor (as defined below) has placed the following
+notice immediately following the copyright notice for the Work:
+
+*Licensed under the EUPL or has expressed by any other means his willingness to license under the EUPL.*
+
+## 1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+* *The Licence*:this Licence.
+* *The Original Work*:the work or software distributed or communicated by the Licensor under this Licence, available
+as Source Code and also as Executable Code as the case may be.
+* *Derivative Works*:the works or software that could be created by the Licensee, based upon the Original Work or
+modifications thereof. This Licence does not define the extent of modification or dependence on the Original Work
+required in order to classify a work as a Derivative Work; this extent is determined by copyright law applicable in
+the country mentioned in Article 15.
+* *The Work*:the Original Work or its Derivative Works.
+* *The Source Code*:the human-readable form of the Work which is the most convenient for people to study and
+modify.
+* *The Executable Code*:any code which has generally been compiled and which is meant to be interpreted by
+a computer as a program.
+* *The Licensor*:the natural or legal person that distributes or communicates the Work under the Licence.
+* *Contributor(s)*:any natural or legal person who modifies the Work under the Licence, or otherwise contributes to
+the creation of a Derivative Work.
+* *The Licensee* or *You*:any natural or legal person who makes any usage of the Work under the terms of the
+Licence.
+* *Distribution* or *Communication*:any act of selling, giving, lending, renting, distributing, communicating,
+transmitting, or otherwise making available, online or offline, copies of the Work or providing access to its essential
+functionalities at the disposal of any other natural or legal person.
+
+## 2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, sublicensable licence to do the following, for
+the duration of copyright vested in the Original Work:
+
+* use the Work in any circumstance and for all usage,
+* reproduce the Work,
+* modify the Work, and make Derivative Works based upon the Work,
+* communicate to the public, including the right to make available or display the Work or copies thereof to the public
+and perform publicly, as the case may be, the Work,
+* distribute the Work or copies thereof,
+* lend and rent the Work or copies thereof,
+* sublicense rights in the Work or copies thereof.
+Those rights can be exercised on any media, supports and formats, whether now known or later invented, as far as the
+applicable law permits so.
+In the countries where moral rights apply, the Licensor waives his right to exercise his moral right to the extent allowed
+by law in order to make effective the licence of the economic rights here above listed.
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to any patents held by the Licensor, to the
+extent necessary to make use of the rights granted on the Work under this Licence.
+
+## 3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as Executable Code. If the Work is provided as
+Executable Code, the Licensor provides in addition a machine-readable copy of the Source Code of the Work along with
+each copy of the Work that the Licensor distributes or indicates, in a notice following the copyright notice attached to
+the Work, a repository where the Source Code is easily and freely accessible for as long as the Licensor continues to
+distribute or communicate the Work.
+
+## 4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits from any exception or limitation to the
+exclusive rights of the rights owners in the Work, of the exhaustion of those rights or of other applicable limitations
+thereto.
+
+## 5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and obligations imposed on the Licensee. Those
+obligations are the following:
+
+**Attribution right**: The Licensee shall keep intact all copyright, patent or trademarks notices and all notices that refer to
+the Licence and to the disclaimer of warranties. The Licensee must include a copy of such notices and a copy of the
+Licence with every copy of the Work he/she distributes or communicates. The Licensee must cause any Derivative Work
+to carry prominent notices stating that the Work has been modified and the date of modification.
+
+**Copyleft clause**: If the Licensee distributes or communicates copies of the Original Works or Derivative Works, this
+Distribution or Communication will be done under the terms of this Licence or of a later version of this Licence unless
+the Original Work is expressly distributed only under this version of the Licence — for example by communicating
+*EUPL v. 1.2 only*. The Licensee (becoming Licensor) cannot offer or impose any additional terms or conditions on the
+Work or Derivative Work that alter or restrict the terms of the Licence.
+
+**Compatibility clause**: If the Licensee Distributes or Communicates Derivative Works or copies thereof based upon both
+the Work and another work licensed under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause, *Compatible Licence* refers to the licences listed
+in the appendix attached to this Licence. Should the Licensee's obligations under the Compatible Licence conflict with
+his/her obligations under this Licence, the obligations of the Compatible Licence shall prevail.
+
+**Provision of Source Code**: When distributing or communicating copies of the Work, the Licensee will provide
+a machine-readable copy of the Source Code or indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+Legal Protection: This Licence does not grant permission to use the trade names, trademarks, service marks, or names
+of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+## 6. Chain of Authorship
+
+The original Licensor warrants that the copyright in the Original Work granted hereunder is owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each Contributor warrants that the copyright in the modifications he/she brings to the Work are owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each time You accept the Licence, the original Licensor and subsequent Contributors grant You a licence to their contributions
+to the Work, under the terms of this Licence.
+
+## 7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous Contributors. It is not a finished work
+and may therefore contain defects or *bugs* inherent to this type of development.
+For the above reason, the Work is provided under the Licence on an *as is* basis and without warranties of any kind
+concerning the Work, including without limitation merchantability, fitness for a particular purpose, absence of defects or
+errors, accuracy, non-infringement of intellectual property rights other than copyright as stated in Article 6 of this
+Licence.
+This disclaimer of warranty is an essential part of the Licence and a condition for the grant of any rights to the Work.
+
+## 8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural persons, the Licensor will in no event be
+liable for any direct or indirect, material or moral, damages of any kind, arising out of the Licence or of the use of the
+Work, including without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, loss
+of data or any commercial damage, even if the Licensor has been advised of the possibility of such damage. However,
+the Licensor will be liable under statutory product liability laws as far such laws apply to the Work.
+
+## 9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional agreement, defining obligations or services
+consistent with this Licence. However, if accepting obligations, You may act only on your own behalf and on your sole
+responsibility, not on behalf of the original Licensor or any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against such Contributor by
+the fact You have accepted any warranty or additional liability.
+
+## 10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon *I agree* placed under the bottom of a window
+displaying the text of this Licence or by affirming consent in any other similar way, in accordance with the rules of
+applicable law. Clicking on that icon indicates your clear and irrevocable acceptance of this Licence and all of its terms
+and conditions.
+Similarly, you irrevocably accept this Licence and all of its terms and conditions by exercising any rights granted to You
+by Article 2 of this Licence, such as the use of the Work, the creation by You of a Derivative Work or the Distribution
+or Communication by You of the Work or copies thereof.
+
+## 11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of electronic communication by You (for example,
+by offering to download the Work from a remote location) the distribution channel or media (for example, a website)
+must at least provide to the public the information requested by the applicable law regarding the Licensor, the Licence
+and the way it may be accessible, concluded, stored and reproduced by the Licensee.
+
+## 12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon any breach by the Licensee of the terms
+of the Licence.
+Such a termination will not terminate the licences of any person who has received the Work from the Licensee under
+the Licence, provided such persons remain in full compliance with the Licence.
+
+## 13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete agreement between the Parties as to the
+Work.
+If any provision of the Licence is invalid or unenforceable under applicable law, this will not affect the validity or
+enforceability of the Licence as a whole. Such provision will be construed or reformed so as necessary to make it valid
+and enforceable.
+The European Commission may publish other linguistic versions or new versions of this Licence or updated versions of
+the Appendix, so far this is required and reasonable, without reducing the scope of the rights granted by the Licence.
+New versions of the Licence will be published with a unique version number.
+All linguistic versions of this Licence, approved by the European Commission, have identical value. Parties can take
+advantage of the linguistic version of their choice.
+
+## 14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+* any litigation resulting from the interpretation of this License, arising between the European Union institutions,
+bodies, offices or agencies, as a Licensor, and any Licensee, will be subject to the jurisdiction of the Court of Justice
+of the European Union, as laid down in article 272 of the Treaty on the Functioning of the European Union,
+* any litigation arising between other parties and resulting from the interpretation of this License, will be subject to
+the exclusive jurisdiction of the competent court where the Licensor resides or conducts its primary business.
+
+## 15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+* this Licence shall be governed by the law of the European Union Member State where the Licensor has his seat,
+resides or has his registered office,
+* this licence shall be governed by Belgian law if the Licensor has no seat, residence or registered office inside
+a European Union Member State.
+
+## Appendix
+
+*Compatible* Licences according to Article 5 EUPL are:
+
+* GNU General Public License (GPL) v. 2, v. 3
+* GNU Affero General Public License (AGPL) v. 3
+* Open Software License (OSL) v. 2.1, v. 3.0
+* Eclipse Public License (EPL) v. 1.0
+* CeCILL v. 2.0, v. 2.1
+* Mozilla Public Licence (MPL) v. 2
+* GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+* Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for works other than software
+* European Union Public Licence (EUPL) v. 1.1, v. 1.2
+* Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong Reciprocity (LiLiQ-R+).
+The European Commission may update this Appendix to later versions of the above licences without producing
+a new version of the EUPL, as long as they provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+All other changes or additions to this Appendix require the production of a new EUPL version.

deepcontrail_instance-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,188 @@
+# 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.