deepcontrail-instance 0.1.0__py3-none-any.whl

deepcontrail/instance/_lines.py

@@ -0,0 +1,158 @@
+"""Oriented difference-of-Gaussians line kernels and oriented line detection.
+
+Private module (leading underscore); not exported from ``deepcontrail.instance``.
+
+A contrail is a thin, long, bright line. For each of ``num_kernels`` evenly spaced
+orientations a difference-of-Gaussians kernel responds strongly where a line of that
+orientation runs through the pixel. This is the line filter of the Mannstein-style method
+(Mannstein, Meyer & Wendling, 1999, Int. J. Remote Sensing 20(8), 1641-1660,
+doi:10.1080/014311699212650); it is optional and off by default.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+from scipy.signal import oaconvolve
+
+# A kernel is a difference of two Gaussians of the signed distance ``d`` to its axis. The two
+# sigmas, in kernel-cell units, are sigma1/size and (sigma1 + sigma_delta)/size.
+
+
+def line_orientations(num_kernels: int) -> np.ndarray:
+    """Return the ``num_kernels`` evenly spaced orientations in ``[0, 180)`` degrees.
+
+    Parameters
+    ----------
+    num_kernels
+        Number of orientations.
+
+    Returns
+    -------
+    np.ndarray
+        Orientations in degrees, ``180 * k / num_kernels`` for ``k = 0 .. num_kernels - 1``.
+    """
+    return np.linspace(0.0, 180.0, num_kernels, endpoint=False)
+
+
+def _balance(diff: np.ndarray) -> np.ndarray:
+    """Scale a zero-sum kernel so its positive lobe sums to +1 and its negative lobe to -1.
+
+    Each weight is divided by the sum of its own lobe: positives by the positive total, the rest
+    by the (positive) magnitude of the negative total. A kernel with no negative (or no positive)
+    weights is returned unchanged.
+
+    Parameters
+    ----------
+    diff
+        2D array of the kernel's raw weights.
+
+    Returns
+    -------
+    np.ndarray
+        Rescaled kernel, same shape as ``diff``.
+    """
+    positive_total = float(np.sum(np.where(diff > 0.0, diff, 0.0)))
+    negative_total = float(np.sum(np.where(diff < 0.0, -diff, 0.0)))
+    if positive_total == 0.0 or negative_total == 0.0:
+        return diff
+    normaliser = np.where(diff > 0.0, positive_total, negative_total)
+    return diff / normaliser
+
+
+def _kernel_cells(size: int) -> tuple[np.ndarray, np.ndarray]:
+    """Column and row coordinates of a ``size`` x ``size`` grid, meshgrid 'xy' indexing."""
+    axis = np.linspace(-1.0, 1.0, size)
+    cols, rows = np.meshgrid(axis, axis)  # cols vary along axis 1, rows along axis 0
+    return cols, rows
+
+
+@lru_cache(maxsize=16)
+def build_kernels(
+    num_kernels: int, kernel_size: int, sigma1: float, sigma_delta: float
+) -> np.ndarray:
+    """Return the oriented line kernels of a configuration, shape ``(num_kernels, size, size)``.
+
+    Built once per configuration and cached, so the same array is shared by every call; it is
+    returned read-only so no caller can change the kernels of later calls.
+
+    Parameters
+    ----------
+    num_kernels
+        Number of evenly spaced orientations.
+    kernel_size
+        Kernel spatial size in pixels.
+    sigma1
+        Inner Gaussian sigma in pixels.
+    sigma_delta
+        Outer minus inner Gaussian sigma, in pixels.
+
+    Returns
+    -------
+    np.ndarray
+        Read-only array of balanced difference-of-Gaussians kernels.
+    """
+    angles = np.radians(line_orientations(num_kernels))
+    cos = np.cos(angles)[:, None, None]
+    sin = np.sin(angles)[:, None, None]
+    cols, rows = _kernel_cells(kernel_size)
+    signed = cos * cols[None] - sin * rows[None]  # (num_kernels, size, size)
+
+    s = float(kernel_size)
+    sigma_a = sigma1 / s
+    sigma_b = (sigma1 + sigma_delta) / s
+    norm_a = 1.0 / (sigma_a * np.sqrt(2.0 * np.pi))
+    norm_b = 1.0 / (sigma_b * np.sqrt(2.0 * np.pi))
+    gaussian_a = norm_a * np.exp(-((signed / sigma_a) ** 2) / 2.0)
+    gaussian_b = norm_b * np.exp(-((signed / sigma_b) ** 2) / 2.0)
+    diff = gaussian_a - gaussian_b
+    kernels = np.stack([_balance(d) for d in diff])
+    kernels.setflags(write=False)
+    return kernels
+
+
+def detect_line_pixels(
+    mask: np.ndarray,
+    num_kernels: int,
+    kernel_size: int,
+    sigma1: float,
+    sigma_delta: float,
+    threshold: float,
+) -> np.ndarray:
+    """Detect linear features by convolving with oriented difference-of-Gaussians kernels.
+
+    For each orientation the mask is convolved with the oriented kernel; a pixel is detected
+    when, for at least one orientation, the response and the mask both exceed ``threshold`` and
+    the response is finite. The result is the union over orientations.
+
+    Parameters
+    ----------
+    mask
+        2D array ``(H, W)``, values in ``{0, 1}`` or float ``[0, 1]``.
+    num_kernels
+        Number of oriented kernels.
+    kernel_size
+        Kernel spatial size in pixels (odd).
+    sigma1
+        Inner Gaussian sigma in pixels.
+    sigma_delta
+        Outer minus inner Gaussian sigma, in pixels.
+    threshold
+        Response / mask value threshold for detection.
+
+    Returns
+    -------
+    np.ndarray
+        Boolean ``(H, W)`` mask of detected pixels.
+    """
+    if mask.size == 0:
+        return np.zeros(mask.shape, dtype=bool)
+
+    kernels = build_kernels(num_kernels, kernel_size, sigma1, sigma_delta)
+    above = mask > threshold
+    detected = np.zeros(mask.shape, dtype=bool)
+    for kernel in kernels:
+        response = oaconvolve(mask, kernel, mode="same")
+        detected |= (response > threshold) & above & np.isfinite(response)
+    return detected

deepcontrail/instance/_overlap.py

@@ -0,0 +1,77 @@
+"""Pixel-set overlap and greedy duplicate removal of contrail candidates.
+
+Private module (leading underscore); not exported from ``deepcontrail.instance``.
+
+Two regions overlap when they share pixels (contrails crossing). A candidate is a duplicate
+of an already-kept one when their pixel-set IoU exceeds a threshold; the first found is kept.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def region_iou(
+    index_a: np.ndarray,
+    index_b: np.ndarray,
+) -> float:
+    """Pixel-set IoU of two regions given as arrays of unique flat pixel indices.
+
+    Parameters
+    ----------
+    index_a
+        Flat pixel indices (``row * width + col``) of the first region, unique.
+    index_b
+        Flat pixel indices of the second region, unique.
+
+    Returns
+    -------
+    float
+        Intersection-over-union in ``[0, 1]``; ``0.0`` when the union is empty.
+    """
+    shared = np.intersect1d(index_a, index_b).size
+    if shared == 0:
+        return 0.0
+    union = int(index_a.size) + int(index_b.size) - int(shared)
+    return shared / union
+
+
+def _flat_indices(candidates: list[tuple[np.ndarray, np.ndarray]]) -> list[np.ndarray]:
+    """One array of unique flat pixel indices per candidate, under a shared image width."""
+    if not candidates:
+        return []
+    width = max(int(cols.max()) for _, cols in candidates) + 1
+    return [(rows * width + cols).astype(np.int64) for rows, cols in candidates]
+
+
+def remove_duplicates(
+    candidates: list[tuple[np.ndarray, np.ndarray]],
+    iou_threshold: float,
+) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Drop candidates that overlap an already-kept one beyond ``iou_threshold``.
+
+    Walks the candidates in order; a candidate is kept only if its IoU with every candidate
+    kept so far is at most ``iou_threshold``. The surviving candidates preserve the input
+    order and references.
+
+    Parameters
+    ----------
+    candidates
+        Candidate contrails as ``(rows, cols)`` coordinate arrays.
+    iou_threshold
+        IoU above which two candidates are considered duplicates.
+
+    Returns
+    -------
+    list[tuple[np.ndarray, np.ndarray]]
+        The surviving candidates, in the original order.
+    """
+    indices = _flat_indices(candidates)
+    kept: list[tuple[np.ndarray, np.ndarray]] = []
+    kept_indices: list[np.ndarray] = []
+    for candidate, index in zip(candidates, indices, strict=True):
+        duplicate = any(region_iou(index, other) > iou_threshold for other in kept_indices)
+        if not duplicate:
+            kept.append(candidate)
+            kept_indices.append(index)
+    return kept

deepcontrail/instance/_shape.py

@@ -0,0 +1,190 @@
+"""The shape tests a growing region must pass: straightness, length and quality score.
+
+Private module (leading underscore); not exported from ``deepcontrail.instance``.
+
+The direction-independent straightness and the length test follow the Mannstein-style detection of
+Mannstein, Meyer & Wendling (1999), "Operational detection of contrails from NOAA-AVHRR
+data", Int. J. Remote Sensing 20(8), 1641-1660, doi:10.1080/014311699212650: a candidate
+region is kept only when it is both straight and long.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _dominant_fit(
+    sum_cross: int, sum_dep: int, sum_indep: int, sum_indep_sq: int, n: int
+) -> tuple[float, float]:
+    """Least-squares slope and intercept of ``dep`` on ``indep`` from exact integer sums.
+
+    The sums are over the whole region: ``sum_cross`` is Σ(dep·indep), ``sum_dep`` is Σ(dep),
+    ``sum_indep`` is Σ(indep) and ``sum_indep_sq`` is Σ(indep²). With no spread in the
+    independent variable the slope is ``0.0`` and the intercept is the mean of the dependent
+    variable.
+
+    Parameters
+    ----------
+    sum_cross
+        Sum of the products of the dependent and independent coordinates.
+    sum_dep
+        Sum of the dependent coordinates.
+    sum_indep
+        Sum of the independent coordinates.
+    sum_indep_sq
+        Sum of the squares of the independent coordinates.
+    n
+        Number of coordinates summed.
+
+    Returns
+    -------
+    tuple[float, float]
+        ``(slope, intercept)``.
+    """
+    denom = n * sum_indep_sq - sum_indep * sum_indep
+    if denom == 0:
+        return 0.0, sum_dep / n
+    slope = (n * sum_cross - sum_indep * sum_dep) / denom
+    return slope, (sum_dep - slope * sum_indep) / n
+
+
+def straightness(rows: np.ndarray, cols: np.ndarray) -> float:
+    """How straight a set of pixels is, whatever its direction: ((λ1 - λ2) / (λ1 + λ2))².
+
+    λ1 ≥ λ2 are the eigenvalues of the 2x2 covariance of the pixel coordinates. A line scores 1
+    and a round blob 0. For pixels along the 45° diagonal this is the least-squares R² of rows
+    against columns; it is also the largest such R² over all rotations of the pixels, so unlike
+    that R² it does not drop to 0 for a straight contrail along an image axis.
+
+    Parameters
+    ----------
+    rows
+        Row coordinates of the pixels.
+    cols
+        Column coordinates of the pixels.
+
+    Returns
+    -------
+    float
+        Straightness in ``[0, 1]``; ``0.0`` when all pixels coincide.
+    """
+    coords = np.stack([np.asarray(rows, dtype=float), np.asarray(cols, dtype=float)])
+    coords -= coords.mean(axis=1, keepdims=True)
+    var_r, var_c = float((coords[0] ** 2).mean()), float((coords[1] ** 2).mean())
+    cov = float((coords[0] * coords[1]).mean())
+    total = var_r + var_c  # λ1 + λ2
+    if total == 0.0:
+        return 0.0
+    gap = float(np.hypot(var_r - var_c, 2.0 * cov))  # λ1 - λ2
+    return min((gap / total) ** 2, 1.0)
+
+
+def is_long_and_straight(
+    rows: np.ndarray,
+    cols: np.ndarray,
+    min_r_score: float,
+    min_length: float,
+    avg_size: int,
+) -> bool:
+    """Keep a region only if it is straight enough and long enough.
+
+    Compares the region's :func:`straightness` with ``min_r_score²`` (so ``min_r_score`` reads
+    like a correlation threshold). The length runs between the means of the ``avg_size`` extreme
+    coordinates on each axis, projected onto a line fitted along the more-spread axis from the
+    exact integer sums of the whole region, and is compared with ``min_length``.
+
+    Parameters
+    ----------
+    rows
+        Row coordinates of the region pixels.
+    cols
+        Column coordinates of the region pixels.
+    min_r_score
+        Straightness threshold, squared before the comparison.
+    min_length
+        Minimum contrail pixel length.
+    avg_size
+        Number of extreme endpoints averaged per axis.
+
+    Returns
+    -------
+    bool
+        True if the region is both linear and long enough.
+    """
+    rows_arr = np.asarray(rows, dtype=float)
+    cols_arr = np.asarray(cols, dtype=float)
+    n = len(rows_arr)
+
+    if n < avg_size * 2:
+        return False
+
+    # Endpoint means: the avg_size smallest and largest coordinates on each axis. The
+    # coordinates are integers, so partitioning for the extremes and averaging gives the same
+    # values as a full sort would.
+    r_lo, r_hi = _axis_endpoints(rows_arr, n, avg_size)
+    c_lo, c_hi = _axis_endpoints(cols_arr, n, avg_size)
+
+    # Exact integer sums of the whole region for the dominant-axis fit.
+    r_int = rows_arr.astype(np.int64)
+    c_int = cols_arr.astype(np.int64)
+    sum_r = int(r_int.sum())
+    sum_c = int(c_int.sum())
+    sum_r2 = int((r_int * r_int).sum())
+    sum_c2 = int((c_int * c_int).sum())
+    sum_rc = int((r_int * c_int).sum())
+
+    if abs(c_lo - c_hi) > abs(r_lo - r_hi):
+        # Columns spread more: predict rows from columns.
+        slope, intercept = _dominant_fit(sum_rc, sum_r, sum_c, sum_c2, n)
+        r_lo, r_hi = c_lo * slope + intercept, c_hi * slope + intercept
+    else:
+        # Rows spread more: predict columns from rows.
+        slope, intercept = _dominant_fit(sum_rc, sum_c, sum_r, sum_r2, n)
+        c_lo, c_hi = r_lo * slope + intercept, r_hi * slope + intercept
+
+    length = float(np.hypot(c_lo - c_hi, r_lo - r_hi))
+    linearity = straightness(rows_arr, cols_arr)
+    return bool(linearity > np.square(min_r_score) and length > min_length)
+
+
+def _axis_endpoints(values: np.ndarray, n: int, avg_size: int) -> tuple[float, float]:
+    """Means of the ``avg_size`` smallest and largest coordinates along one axis."""
+    lo = np.partition(values, avg_size - 1)[:avg_size]
+    hi = np.partition(values, n - avg_size)[n - avg_size :]
+    return float(lo.mean()), float(hi.mean())
+
+
+def candidate_score(
+    rows: np.ndarray,
+    cols: np.ndarray,
+    saturation: float,
+    avg_size: int,
+) -> float:
+    """Quality score of a contrail: straightness * tanh(n_pixels / saturation).
+
+    Returns ``0.0`` when the blob has fewer than ``2 * avg_size`` pixels.
+
+    Parameters
+    ----------
+    rows
+        Row coordinates of the blob pixels.
+    cols
+        Column coordinates of the blob pixels.
+    saturation
+        Pixel count at which the size term approaches 1.
+    avg_size
+        Number of end pixels averaged when measuring the length (sets the minimum size).
+
+    Returns
+    -------
+    float
+        Quality score in ``[0, 1]``.
+    """
+    rows_arr = np.asarray(rows)
+    cols_arr = np.asarray(cols)
+
+    if len(rows_arr) < 2 * avg_size:
+        return 0.0
+
+    n_pixels = float(len(rows_arr))
+    return float(straightness(rows_arr, cols_arr) * np.tanh(n_pixels / saturation))

deepcontrail/instance/_tuning.py

@@ -0,0 +1,97 @@
+"""Search spaces of the instance tuning scripts (Optuna trials).
+
+Private module (leading underscore): it serves the repository scripts in ``scripts/`` and is
+not part of the public API, so it may change between releases.
+
+Each ``suggest_*`` function builds a config from a trial; each ``*_trial_params`` function turns
+a config back into the trial parameters, so known configs can be enqueued as starting trials.
+Optuna is only needed by the caller: nothing here imports it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from deepcontrail.instance.config import InstancePipelineConfig, MannsteinConfig
+
+if TYPE_CHECKING:
+    from optuna.trial import BaseTrial
+
+
+def suggest_mannstein_config(trial: BaseTrial) -> MannsteinConfig:
+    """Build a ``MannsteinConfig`` from a trial; the line filter stays off.
+
+    The line-filter settings are not searched: the filter is off in every search, as it kept
+    every mask pixel at the tuned settings. ``filter_avg_size`` is searched separately from
+    ``fit_avg_size``, so the length filter and the score can average a different number of end
+    pixels. Parameters are suggested in a fixed order, which determines what a seeded sampler
+    draws.
+    """
+    return MannsteinConfig(
+        line_filter=False,
+        min_pixels=trial.suggest_int("min_pixels", 3, 50),
+        min_length=trial.suggest_float("min_length", 3.0, 50.0),
+        min_r_score=trial.suggest_float("min_r_score", 0.05, 0.6),
+        lookback=trial.suggest_int("lookback", 10, 60),
+        alignment_threshold=trial.suggest_float("alignment_threshold", 0.5, 5.0),
+        fit_avg_size=trial.suggest_int("fit_avg_size", 1, 10),
+        iou_threshold=trial.suggest_float("iou_threshold", 0.2, 0.8),
+        score_saturation=trial.suggest_float("score_saturation", 10.0, 100.0),
+        filter_avg_size=trial.suggest_int("filter_avg_size", 1, 10),
+    )
+
+
+_SEARCHED = (
+    "min_pixels",
+    "min_length",
+    "min_r_score",
+    "lookback",
+    "alignment_threshold",
+    "fit_avg_size",
+    "iou_threshold",
+    "score_saturation",
+    "filter_avg_size",
+)
+
+
+def mannstein_trial_params(config: MannsteinConfig) -> dict[str, Any]:
+    """Return the searched settings of a config as trial parameters.
+
+    ``filter_avg_size=None`` becomes ``fit_avg_size``; the line-filter settings are dropped.
+    """
+    params = {name: getattr(config, name) for name in _SEARCHED}
+    if params["filter_avg_size"] is None:
+        params["filter_avg_size"] = params["fit_avg_size"]
+    return params
+
+
+def suggest_pipeline_config(trial: BaseTrial) -> InstancePipelineConfig:
+    """Build an ``InstancePipelineConfig`` from a trial; scores are always probability-weighted.
+
+    The Mannstein part is :func:`suggest_mannstein_config`, suggested first.
+    """
+    mannstein = suggest_mannstein_config(trial)
+    return InstancePipelineConfig(
+        semantic_threshold=trial.suggest_float("semantic_threshold", 0.3, 0.7),
+        grow_threshold=trial.suggest_float("grow_threshold", 0.2, 0.6),
+        grow_steps=trial.suggest_int("grow_steps", 0, 3),
+        grow_connectivity=cast(
+            "Literal[4, 8]", trial.suggest_categorical("grow_connectivity", [4, 8])
+        ),
+        probability_scores=True,
+        mannstein=mannstein,
+    )
+
+
+def pipeline_trial_params(config: InstancePipelineConfig) -> dict[str, Any]:
+    """Flatten a pipeline config into the trial parameter names of the pipeline search."""
+    params = mannstein_trial_params(config.mannstein)
+    params.update(
+        {
+            "semantic_threshold": config.semantic_threshold,
+            "grow_threshold": config.grow_threshold,
+            "grow_steps": config.grow_steps,
+            "grow_connectivity": config.grow_connectivity,
+        }
+    )
+    return params

deepcontrail/instance/bundle.py

@@ -0,0 +1,116 @@
+"""The instance step stored in a pretrained semantic bundle.
+
+A pretrained bundle (``deepcontrail.segmentation.load_pretrained``) may carry the instance step
+tuned for its model, as two optional files next to the weights:
+
+- ``instance_pipeline.yaml``: the :class:`InstancePipelineConfig` to run on its probabilities;
+- ``score_model.json``: a :class:`ScoreModel` trained on that model's predictions.
+
+This module reads and writes them from a folder only, so ``deepcontrail.instance`` never imports
+``deepcontrail.segmentation``::
+
+    model = load_pretrained("eurocontrol-asu/deepcontrail-segmentation")
+    step = load_instance_step(model.directory, tta=True)
+    masks, scores = step(predict(model, composite, tta=True))
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from deepcontrail.instance.config import InstancePipelineConfig
+from deepcontrail.instance.pipeline import detect_instances_from_probabilities
+from deepcontrail.instance.scoring import ScoreModel
+
+if TYPE_CHECKING:
+    import numpy as np
+
+PIPELINE_FILE = "instance_pipeline.yaml"
+SCORE_MODEL_FILE = "score_model.json"
+
+
+@dataclass(frozen=True)
+class InstanceStep:
+    """Pipeline settings and optional learned scores; call it on a probability map."""
+
+    config: InstancePipelineConfig
+    score_model: ScoreModel | None = None
+
+    def __call__(self, probs: np.ndarray) -> tuple[list[np.ndarray], list[float]]:
+        """Run :func:`detect_instances_from_probabilities` with this step's settings."""
+        return detect_instances_from_probabilities(probs, self.config, self.score_model)
+
+
+def load_instance_step(directory: str | Path, *, tta: bool | None = None) -> InstanceStep:
+    """Read the instance step of a bundle folder; defaults where its files are absent.
+
+    Parameters
+    ----------
+    directory
+        The bundle folder, e.g. ``Pretrained.directory``.
+    tta
+        Whether the probabilities will be made with test-time augmentation. A score model that
+        records the other setting is refused: TTA changes the probabilities its features are
+        computed from. ``None`` skips the check.
+
+    Returns
+    -------
+    InstanceStep
+        ``instance_pipeline.yaml`` (else ``InstancePipelineConfig()``) and ``score_model.json``
+        (else ``None``).
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``directory`` does not exist (a typo would otherwise silently drop the learned scores).
+    ValueError
+        If the score model was trained with other pipeline settings than the bundle's, or with
+        the other TTA setting.
+    """
+    directory = Path(directory)
+    if not directory.is_dir():
+        raise FileNotFoundError(f"{directory}: no such bundle folder")
+    pipeline_path = directory / PIPELINE_FILE
+    config = (
+        InstancePipelineConfig.from_yaml(pipeline_path)
+        if pipeline_path.is_file()
+        else InstancePipelineConfig()
+    )
+    score_path = directory / SCORE_MODEL_FILE
+    if not score_path.is_file():
+        return InstanceStep(config)
+    score_model = ScoreModel.from_json(score_path)
+    if score_model.pipeline_config != config:
+        raise ValueError(
+            f"{score_path} was trained with another pipeline config than {pipeline_path.name}"
+        )
+    trained_tta = score_model.trained_on.get("tta")
+    if tta is not None and trained_tta is not None and trained_tta != tta:
+        raise ValueError(
+            f"{score_path} was trained on probabilities made with TTA={trained_tta}, "
+            f"but they will be made with TTA={tta}"
+        )
+    return InstanceStep(config, score_model)
+
+
+def save_instance_step(
+    directory: str | Path,
+    config: InstancePipelineConfig,
+    score_model: ScoreModel | None = None,
+) -> None:
+    """Write ``instance_pipeline.yaml`` (and ``score_model.json``) into a bundle folder.
+
+    Raises
+    ------
+    ValueError
+        If ``score_model`` was trained with other pipeline settings than ``config``.
+    """
+    if score_model is not None and score_model.pipeline_config != config:
+        raise ValueError("the score model was trained with another pipeline config")
+    directory = Path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    config.to_yaml(directory / PIPELINE_FILE)
+    if score_model is not None:
+        score_model.to_json(directory / SCORE_MODEL_FILE)