euler-preprocess 3.20.0__tar.gz → 3.22.0__tar.gz

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+- `fog` no longer requires `semantic_segmentation`. Without a sky mask no pixel
+  is sky: `from_sky` airlight falls back to white, sky-only options have no
+  effect, and one warning per run says so. A configured mask is joined and
+  used exactly as before. For indoor datasets such as Hypersim.
+- The white `from_sky` fallback for samples without sky pixels is logged as a
+  warning once per run, then at debug level, instead of once per sample and
+  fog variant.
+- `fog` reads the depth head's `radial_depth` (the CLI logs what it found):
+  - `true`: the depth is used as the distance along the ray, and intrinsics
+    never convert it again (before, a radial depth plus intrinsics was
+    converted twice, up to 1.9× too far for Hypersim's tilt-shift cameras).
+  - `false` without intrinsics: an error, instead of silently using planar
+    depth as distance. `"planar_depth_as_distance": true` in the fog config
+    accepts it with one warning.
+  - Undeclared: unchanged (converted when intrinsics are present).
+  - With a `function` override, the loader function's own `radial_depth`
+    annotation decides, e.g. Hypersim's `depth` index read with `radial_distance`.
+  - Standalone `FogTransform(...)` takes it as `depth_radial`.
+- Transforms can declare `OPTIONAL_MODALITIES`: per-sample inputs that anchor
+  the role inference like required ones when configured.
+
 - `crop` crops label rasters in the stored file: semantic segmentation (the
   ground truth that also holds the sky), instance and panoptic segmentation,
   and sky masks.

{euler_preprocess-3.20.0/euler_preprocess.egg-info → euler_preprocess-3.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-preprocess
-Version: 3.20.0
+Version: 3.22.0
 Summary: Physics-based preprocessing (fog, etc.) for RGB+depth datasets
 Author-email: Daniel Rothenpieler <rothenpielerdaniel@gmail.com>
 License-Expression: MIT
@@ -120,13 +120,17 @@ loader.
 
 | Transform | Required | Optional |
 |---|---|---|
-| `fog` | `rgb`, `depth`, `semantic_segmentation` | `intrinsics`; used for radial depth conversion and camera-profile optics |
+| `fog` | `rgb`, `depth` | `semantic_segmentation` (sky mask; without it no pixel is sky); `intrinsics`, used to convert planar depth to the distance along the ray and for camera-profile optics |
 | `sky-depth` | `depth`, `semantic_segmentation` | — |
 | `radial` | `depth`, `intrinsics` | — |
 | `lidar-motion` | `sparse_depth`, `gnss`, `sensor_timing`, `lidar_to_gnss` | — |
 
-`fog` and `sky-depth` need `semantic_segmentation` as a boolean sky mask. They load
-it with the `sky_mask` function of the euler-loading module that the index's
+`sky-depth` needs `semantic_segmentation` as a boolean sky mask, and `fog` uses one
+when it is configured. Without it, `fog` treats no pixel as sky, e.g. for indoor
+datasets: `from_sky` airlight falls back to white `[1, 1, 1]`, sky-only options
+(`sky_fog_path`, `sky_weight`, sky-aware metering) have no effect, and one warning
+per run says so. Both transforms load the mask
+with the `sky_mask` function of the euler-loading module that the index's
 dataset head names, so a `class_segmentation` index works as is: the sky is the
 head's `skyclass` (Synscapes `[23, 23, 23]`, Real Drive Sim `[29, 0, 0]`, VKITTI2
 `[90, 200, 255]`), and the log names the loader and the sky definition in use.
@@ -208,6 +212,7 @@ whole dataset.
 | `seed` | Random seed for reproducibility; `null` for non-deterministic. |
 | `depth_scale` | Multiplier applied to depth values after loading. |
 | `resize_depth` | Bilinearly resize the depth map to the RGB resolution. |
+| `planar_depth_as_distance` | `true` accepts planar depth without intrinsics as the distance along the ray, with one warning, instead of failing (see [How Each Modality Is Used](#how-each-modality-is-used)). Default `false`. |
 | `contrast_threshold` | Threshold *C_t* in the visibility-to-attenuation conversion (default `0.05`). |
 | `render_input_space` | Colour space of the input RGB. `"srgb"` for display-encoded images (fog is mixed in scene-linear RGB); `"linear"` for already-linear radiance. |
 | `mode` | `"sample"` (default) renders one sampled scenario per image; `"progressive"` renders every scenario step for every image. |
@@ -251,12 +256,28 @@ inf, negative) are clamped to zero, i.e. treated as infinitely close and receivi
 fog. Depth stays authoritative even where the semantic map says sky, unless
 `sky_fog_path` is configured.
 
-**Semantic Segmentation** — a per-pixel semantic map from which a boolean sky mask is
-derived. Used for airlight estimation when `airlight` is `"from_sky"`: the mean RGB of
-all sky pixels becomes *L_s*.
+Fog attenuates with the distance along each pixel's ray, so *d(x)* must be radial
+(Euclidean) distance. The depth's dataset head says which kind it holds in
+`modality.meta.radial_depth`, and the CLI logs what it found:
 
-**Intrinsics** *(optional)* — when present, planar (z-buffer) depth is converted to
-radial (Euclidean) depth before fog is applied.
+| Head declares | With intrinsics | Without intrinsics |
+|---|---|---|
+| `radial_depth: true` | Used as it is; the intrinsics never convert it | Used as it is |
+| `radial_depth: false` | Converted: `d * ‖K⁻¹ [u, v, 1]‖` (see [Radial Transform](#radial-transform)) | **Error**, unless the fog config sets `planar_depth_as_distance: true` (then one warning) |
+| nothing (the dataset contract requires it for the `depth` key, so e.g. older heads or other keys) | Converted | Used as it is |
+
+When the modality entry selects another loader `function` than the head names (e.g.
+Hypersim's planar `depth` index read with `radial_distance`), that function's own
+`radial_depth` annotation decides instead. Standalone `FogTransform(...)` use takes it
+as `depth_radial=True/False/None`; `None`, the default, keeps the last row.
+
+**Semantic Segmentation** *(optional)* — a per-pixel semantic map from which a boolean
+sky mask is derived. Used for airlight estimation when `airlight` is `"from_sky"`: the
+mean RGB of all sky pixels becomes *L_s*. Without it no pixel is sky (see
+[Dataset Config](#dataset-config)).
+
+**Intrinsics** *(optional)* — convert planar (z-buffer) depth to radial distance before
+fog is applied, as in the table above, and place camera-profile optics.
 
 For a bounded valley-fog treatment of sky, add `sky_fog_path` inside a model config:
 
@@ -285,7 +306,7 @@ this without intrinsics raises an error rather than silently falling back.
 
 | Method | Description |
 |---|---|
-| `from_sky` | Mean RGB of sky pixels. Falls back to white `[1, 1, 1]` when no sky pixels exist. |
+| `from_sky` | Mean RGB of sky pixels. Falls back to white `[1, 1, 1]` when no sky pixels exist; the first such sample is logged as a warning, later ones at debug level only. |
 | `dcp` | Dark Channel Prior — brightest pixel (by channel sum) among the top 0.1% darkest-channel pixels. |
 | `dcp_heuristic` | Robust DCP — pools the brighter half of the top 0.1% darkest-channel pixels; when sky pixels exist their brightest colours act as a chromaticity prior while DCP-derived luminance is preserved. |
 
@@ -801,6 +822,7 @@ The crop config (`configs/crop_config.json`) describes the box relative to the
 
 | Key | Meaning |
 |---|---|
+| `reference` | The per-sample raster the box is relative to (default `rgb`). Any image-shaped modality works, so `"reference": "semantic_segmentation"` with only that modality in the dataset config crops the labels alone; other rasters must have its size |
 | `crop.remove` | What to cut off each edge (`top`, `bottom`, `left`, `right`) |
 | `crop.keep` + `crop.anchor` | The kept `height` / `width`, placed at `center` (default), `top`, `bottom`, `left`, `right`, `top_left`, `top_right`, `bottom_left` or `bottom_right` |
 | `crop.unit` | `fraction` (default) or `pixel`. Fractions lie in `[0, 1)` (`keep`: `(0, 1]`) and round half up per edge: `floor(f · size + 0.5)` |

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/README.md

@@ -100,13 +100,17 @@ loader.
 
 | Transform | Required | Optional |
 |---|---|---|
-| `fog` | `rgb`, `depth`, `semantic_segmentation` | `intrinsics`; used for radial depth conversion and camera-profile optics |
+| `fog` | `rgb`, `depth` | `semantic_segmentation` (sky mask; without it no pixel is sky); `intrinsics`, used to convert planar depth to the distance along the ray and for camera-profile optics |
 | `sky-depth` | `depth`, `semantic_segmentation` | — |
 | `radial` | `depth`, `intrinsics` | — |
 | `lidar-motion` | `sparse_depth`, `gnss`, `sensor_timing`, `lidar_to_gnss` | — |
 
-`fog` and `sky-depth` need `semantic_segmentation` as a boolean sky mask. They load
-it with the `sky_mask` function of the euler-loading module that the index's
+`sky-depth` needs `semantic_segmentation` as a boolean sky mask, and `fog` uses one
+when it is configured. Without it, `fog` treats no pixel as sky, e.g. for indoor
+datasets: `from_sky` airlight falls back to white `[1, 1, 1]`, sky-only options
+(`sky_fog_path`, `sky_weight`, sky-aware metering) have no effect, and one warning
+per run says so. Both transforms load the mask
+with the `sky_mask` function of the euler-loading module that the index's
 dataset head names, so a `class_segmentation` index works as is: the sky is the
 head's `skyclass` (Synscapes `[23, 23, 23]`, Real Drive Sim `[29, 0, 0]`, VKITTI2
 `[90, 200, 255]`), and the log names the loader and the sky definition in use.
@@ -188,6 +192,7 @@ whole dataset.
 | `seed` | Random seed for reproducibility; `null` for non-deterministic. |
 | `depth_scale` | Multiplier applied to depth values after loading. |
 | `resize_depth` | Bilinearly resize the depth map to the RGB resolution. |
+| `planar_depth_as_distance` | `true` accepts planar depth without intrinsics as the distance along the ray, with one warning, instead of failing (see [How Each Modality Is Used](#how-each-modality-is-used)). Default `false`. |
 | `contrast_threshold` | Threshold *C_t* in the visibility-to-attenuation conversion (default `0.05`). |
 | `render_input_space` | Colour space of the input RGB. `"srgb"` for display-encoded images (fog is mixed in scene-linear RGB); `"linear"` for already-linear radiance. |
 | `mode` | `"sample"` (default) renders one sampled scenario per image; `"progressive"` renders every scenario step for every image. |
@@ -231,12 +236,28 @@ inf, negative) are clamped to zero, i.e. treated as infinitely close and receivi
 fog. Depth stays authoritative even where the semantic map says sky, unless
 `sky_fog_path` is configured.
 
-**Semantic Segmentation** — a per-pixel semantic map from which a boolean sky mask is
-derived. Used for airlight estimation when `airlight` is `"from_sky"`: the mean RGB of
-all sky pixels becomes *L_s*.
+Fog attenuates with the distance along each pixel's ray, so *d(x)* must be radial
+(Euclidean) distance. The depth's dataset head says which kind it holds in
+`modality.meta.radial_depth`, and the CLI logs what it found:
 
-**Intrinsics** *(optional)* — when present, planar (z-buffer) depth is converted to
-radial (Euclidean) depth before fog is applied.
+| Head declares | With intrinsics | Without intrinsics |
+|---|---|---|
+| `radial_depth: true` | Used as it is; the intrinsics never convert it | Used as it is |
+| `radial_depth: false` | Converted: `d * ‖K⁻¹ [u, v, 1]‖` (see [Radial Transform](#radial-transform)) | **Error**, unless the fog config sets `planar_depth_as_distance: true` (then one warning) |
+| nothing (the dataset contract requires it for the `depth` key, so e.g. older heads or other keys) | Converted | Used as it is |
+
+When the modality entry selects another loader `function` than the head names (e.g.
+Hypersim's planar `depth` index read with `radial_distance`), that function's own
+`radial_depth` annotation decides instead. Standalone `FogTransform(...)` use takes it
+as `depth_radial=True/False/None`; `None`, the default, keeps the last row.
+
+**Semantic Segmentation** *(optional)* — a per-pixel semantic map from which a boolean
+sky mask is derived. Used for airlight estimation when `airlight` is `"from_sky"`: the
+mean RGB of all sky pixels becomes *L_s*. Without it no pixel is sky (see
+[Dataset Config](#dataset-config)).
+
+**Intrinsics** *(optional)* — convert planar (z-buffer) depth to radial distance before
+fog is applied, as in the table above, and place camera-profile optics.
 
 For a bounded valley-fog treatment of sky, add `sky_fog_path` inside a model config:
 
@@ -265,7 +286,7 @@ this without intrinsics raises an error rather than silently falling back.
 
 | Method | Description |
 |---|---|
-| `from_sky` | Mean RGB of sky pixels. Falls back to white `[1, 1, 1]` when no sky pixels exist. |
+| `from_sky` | Mean RGB of sky pixels. Falls back to white `[1, 1, 1]` when no sky pixels exist; the first such sample is logged as a warning, later ones at debug level only. |
 | `dcp` | Dark Channel Prior — brightest pixel (by channel sum) among the top 0.1% darkest-channel pixels. |
 | `dcp_heuristic` | Robust DCP — pools the brighter half of the top 0.1% darkest-channel pixels; when sky pixels exist their brightest colours act as a chromaticity prior while DCP-derived luminance is preserved. |
 
@@ -781,6 +802,7 @@ The crop config (`configs/crop_config.json`) describes the box relative to the
 
 | Key | Meaning |
 |---|---|
+| `reference` | The per-sample raster the box is relative to (default `rgb`). Any image-shaped modality works, so `"reference": "semantic_segmentation"` with only that modality in the dataset config crops the labels alone; other rasters must have its size |
 | `crop.remove` | What to cut off each edge (`top`, `bottom`, `left`, `right`) |
 | `crop.keep` + `crop.anchor` | The kept `height` / `width`, placed at `center` (default), `top`, `bottom`, `left`, `right`, `top_left`, `top_right`, `bottom_left` or `bottom_right` |
 | `crop.unit` | `fraction` (default) or `pixel`. Fractions lie in `[0, 1)` (`keep`: `(0, 1]`) and round half up per edge: `floor(f · size + 0.5)` |

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/docs/plans/coherent-cropping.md

@@ -394,7 +394,9 @@ ground truth for every class, the sky included:
 - Labels are never interpolated.
 
 euler-view's crop addon offers `semantic_segmentation` instead of `sky_mask`,
-which is only a model output. Depth PNGs (§7.3) could use the same path later.
+which is only a model output. RGB is optional in the addon: the crop's
+`reference` is the first included of RGB, depth and semantic segmentation, so
+a single modality (e.g. the semantic GT) can be cropped on its own. Depth PNGs (§7.3) could use the same path later.
 
 **MUSES lidar needs motion compensation.** The sensor is not a spinning lidar.
 It scans a ~124° × 25° forward window top to bottom in 84.5 ms: point

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/euler_preprocess/cli.py

@@ -13,7 +13,7 @@ from collections.abc import Iterable, Iterator, Sequence
 from pathlib import Path
 from typing import Any
 
-from euler_preprocess.common.dataset import build_dataset
+from euler_preprocess.common.dataset import build_dataset, declared_radial_depth
 from euler_preprocess.common.logging import get_logger, log_dataset_info
 from euler_preprocess.common.output import prepare_output_backends
 
@@ -186,6 +186,7 @@ def _run_transform(args: argparse.Namespace, transform_class: type) -> int:
         required_modalities,
         required_hierarchical,
         transform_class.MODALITY_FUNCTIONS,
+        optional_modalities=getattr(transform_class, "OPTIONAL_MODALITIES", None),
     )
     output_backends = prepare_output_backends(config, dataset, transform_class)
     primary_backend = next(iter(output_backends.values()))
@@ -222,6 +223,14 @@ def _run_transform(args: argparse.Namespace, transform_class: type) -> int:
                 transform_class.__name__,
                 extra,
             )
+    if "depth_radial" in init_params and "depth" in dataset.modality_paths():
+        depth_radial, source = declared_radial_depth(dataset, "depth")
+        logger.info(
+            "Depth: radial_depth=%s (from the %s)",
+            "undeclared" if depth_radial is None else str(depth_radial).lower(),
+            source,
+        )
+        transform_kwargs["depth_radial"] = depth_radial
     if "strict" in init_params:
         transform_kwargs["strict"] = bool(getattr(args, "strict", False))
     elif getattr(args, "strict", False):

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/euler_preprocess/common/dataset.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections import Counter
+from collections.abc import Mapping
 
 from euler_preprocess.common.logging import get_logger
 
@@ -153,6 +154,7 @@ def build_dataset(
     required_modalities: set[str],
     required_hierarchical: set[str] | None = None,
     modality_functions: dict[str, str] | None = None,
+    optional_modalities: set[str] | None = None,
 ):
     """Build a ``MultiModalDataset`` from a config dict.
 
@@ -177,6 +179,10 @@ def build_dataset(
     e.g. ``sky_mask`` for a ``class_segmentation`` index; the sky then comes
     from the head's ``skyclass``.  A modality entry's own ``function`` key
     overrides it, and ``"function": null`` keeps the head's function.
+
+    *optional_modalities* (a transform's ``OPTIONAL_MODALITIES``) are
+    per-sample inputs the transform can do without.  When configured, they
+    anchor the role inference exactly like required ones.
     """
     from euler_loading import MultiModalDataset, SamplePreprocessor
 
@@ -204,7 +210,10 @@ def build_dataset(
         name: _make_modality(entry, functions.get(name))
         for name, entry in configured.items()
     }
-    regular, hierarchical = _resolve_roles(modalities, set(required_modalities))
+    per_sample = set(required_modalities) | (
+        set(optional_modalities or ()) & configured.keys()
+    )
+    regular, hierarchical = _resolve_roles(modalities, per_sample)
     logger = get_logger()
     for name in regular:
         if name in raw_hierarchical:
@@ -222,3 +231,41 @@ def build_dataset(
         if config.get("preprocessing")
         else None,
     )
+
+
+def _head_loader_function(index: dict) -> str | None:
+    """The loader function a ds-crawler index's dataset head names, if any."""
+    try:
+        from euler_loading._resolution import _get_euler_loading_meta
+
+        addon = _get_euler_loading_meta(index)
+    except Exception:  # pragma: no cover - depends on the euler-loading version
+        addon = index.get("euler_loading") if isinstance(index, Mapping) else None
+    function = addon.get("function") if isinstance(addon, Mapping) else None
+    return function if isinstance(function, str) and function else None
+
+
+def declared_radial_depth(dataset, name: str = "depth") -> tuple[bool | None, str]:
+    """Whether modality *name* holds distances along the ray, as declared.
+
+    Returns ``(radial, source)``.  *radial* is the dataset head's
+    ``modality.meta.radial_depth``: ``True`` for the Euclidean distance to
+    the camera centre, ``False`` for planar z-depth, ``None`` when the head
+    does not declare it.  When the modality is read with another loader
+    function than the head names (a ``function`` override, e.g. Hypersim's
+    planar ``depth`` index read with ``radial_distance``), the head describes the
+    files but not the loaded values, so that function's own
+    ``radial_depth`` annotation is used if it has one.  *source* says where
+    the answer came from, for logging.
+    """
+    head_value = dataset.get_modality_metadata(name).get("radial_depth")
+    loader_name = getattr(dataset.get_loader(name), "__name__", None)
+    head_function = _head_loader_function(dataset.get_modality_index(name))
+    if head_function is not None and loader_name not in (None, head_function):
+        annotation = (dataset.get_loader_meta(name) or {}).get("meta") or {}
+        loader_value = annotation.get("radial_depth")
+        if isinstance(loader_value, bool):
+            return loader_value, f"loader function '{loader_name}'"
+    if isinstance(head_value, bool):
+        return head_value, "dataset head"
+    return None, "dataset head"

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/euler_preprocess/common/transform.py

@@ -15,7 +15,11 @@ class Transform(ABC):
     Required modalities:
         :attr:`REQUIRED_MODALITIES` are per-sample inputs (RGB, depth, masks);
         they are always joined per sample and anchor the role inference of
-        every other modality.  :attr:`REQUIRED_HIERARCHICAL_MODALITIES` are
+        every other modality.  :attr:`OPTIONAL_MODALITIES` are per-sample
+        inputs the transform can do without (fog's sky mask): a configured
+        one is joined and anchors the role inference like a required one;
+        otherwise the samples simply lack it.
+        :attr:`REQUIRED_HIERARCHICAL_MODALITIES` are
         further required inputs, such as camera intrinsics, that a dataset may
         store per sample or once per hierarchy level; their role is inferred
         from the ds-crawler indexes (see
@@ -35,6 +39,7 @@ class Transform(ABC):
     """
 
     REQUIRED_MODALITIES: ClassVar[set[str]] = set()
+    OPTIONAL_MODALITIES: ClassVar[set[str]] = set()
     REQUIRED_HIERARCHICAL_MODALITIES: ClassVar[set[str]] = set()
     MODALITY_FUNCTIONS: ClassVar[dict[str, str]] = {}
     SOURCE_MODALITY: ClassVar[str | None] = None

euler_preprocess-3.22.0/euler_preprocess/fog/airlight_from_sky.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+
+logger = logging.getLogger("euler-preprocess.fog")
+
+# Default fallback when no sky pixels are available (white, standard
+# assumption in the Koschmieder atmospheric scattering model).
+DEFAULT_AIRLIGHT_FALLBACK = np.array([1.0, 1.0, 1.0], dtype=np.float32)
+
+
+class NoSkyWarning:
+    """Report the white-airlight fallback for samples without sky pixels.
+
+    The first sample is logged as a warning, every later one at debug level
+    only, so a run over an indoor dataset (no sky anywhere) logs one line
+    instead of one per sample and fog variant. :attr:`count` holds the number
+    of fallbacks so far.
+    """
+
+    def __init__(self, log: logging.Logger | None = None) -> None:
+        self.log = log or logger
+        self.count = 0
+
+    def __call__(self, sample_id: str | None = None) -> None:
+        self.count += 1
+        id_str = f" (sample {sample_id})" if sample_id else ""
+        if self.count == 1:
+            self.log.warning(
+                "No sky pixels in segmentation mask%s; using default airlight "
+                "fallback %s. Later samples without sky pixels fall back the "
+                "same way and are logged at debug level only.",
+                id_str,
+                DEFAULT_AIRLIGHT_FALLBACK.tolist(),
+            )
+        else:
+            self.log.debug(
+                "No sky pixels in segmentation mask%s; using default airlight "
+                "fallback %s",
+                id_str,
+                DEFAULT_AIRLIGHT_FALLBACK.tolist(),
+            )
+
+
+class AirlightFromSky:
+    def __init__(
+        self,
+        sky_depth_threshold: float,
+        no_sky_warning: NoSkyWarning | None = None,
+    ) -> None:
+        self.sky_depth_threshold = sky_depth_threshold
+        self.no_sky_warning = no_sky_warning or NoSkyWarning()
+
+    def estimate_airlight(
+        self,
+        image: np.ndarray,
+        sky_mask: np.ndarray,
+        sample_id: str | None = None,
+    ) -> np.ndarray:
+        n_sky = int(sky_mask.sum())
+        if n_sky == 0:
+            self.no_sky_warning(sample_id)
+            return DEFAULT_AIRLIGHT_FALLBACK.copy()
+
+        airlight_pixels = image[sky_mask]
+        airlight = np.mean(airlight_pixels, axis=0)
+
+        if not np.all(np.isfinite(airlight)):
+            id_str = f" (sample {sample_id})" if sample_id else ""
+            logger.warning(
+                "Airlight estimated from sky pixels contains non-finite values "
+                "(%s)%s; using default airlight fallback %s",
+                airlight,
+                id_str,
+                DEFAULT_AIRLIGHT_FALLBACK.tolist(),
+            )
+            return DEFAULT_AIRLIGHT_FALLBACK.copy()
+
+        return airlight

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/euler_preprocess/fog/atmospheric_light.py

@@ -6,7 +6,7 @@ from typing import Any
 import numpy as np
 
 from euler_preprocess.common.sampling import sample_value
-from euler_preprocess.fog.airlight_from_sky import AirlightFromSky
+from euler_preprocess.fog.airlight_from_sky import AirlightFromSky, NoSkyWarning
 from euler_preprocess.fog.dcp_airlight import DCPAirlight
 from euler_preprocess.fog.dcp_heuristic_airlight import DCPHeuristicAirlight
 from euler_preprocess.fog.models import (
@@ -41,6 +41,9 @@ class AtmosphericLightResolver:
             )
         self.method = method
         self.logger = logger or logging.getLogger("euler-preprocess.fog")
+        # One report for the whole run: the white fallback of every sample
+        # without sky pixels after the first is logged at debug level only.
+        self.no_sky_warning = NoSkyWarning()
         dcp_heuristic_config = (
             {} if dcp_heuristic_config is None else dcp_heuristic_config
         )
@@ -90,7 +93,12 @@ class AtmosphericLightResolver:
     ) -> "torch.Tensor":
         resolved_method = method or self.method
         if resolved_method == "from_sky":
-            return estimate_airlight_torch(rgb_t, sky_mask_t, sample_id=sample_id)
+            return estimate_airlight_torch(
+                rgb_t,
+                sky_mask_t,
+                sample_id=sample_id,
+                no_sky_warning=self.no_sky_warning,
+            )
         estimator = self._get_estimator_torch(resolved_method)
         if estimator is None:
             raise RuntimeError(
@@ -254,12 +262,7 @@ class AtmosphericLightResolver:
         ]
         if no_sky.any():
             for idx_ns in no_sky.nonzero(as_tuple=False):
-                i = int(idx_ns.item())
-                self.logger.warning(
-                    "No sky pixels in segmentation mask (sample %s); using "
-                    "default airlight fallback [1.0, 1.0, 1.0]",
-                    items[i]["sample_id"],
-                )
+                self.no_sky_warning(items[int(idx_ns.item())]["sample_id"])
             airlight[no_sky] = 1.0
         return airlight
 
@@ -268,7 +271,9 @@ class AtmosphericLightResolver:
         if estimator is not None:
             return estimator
         if method == "from_sky":
-            estimator = AirlightFromSky(sky_depth_threshold=0.0)
+            estimator = AirlightFromSky(
+                sky_depth_threshold=0.0, no_sky_warning=self.no_sky_warning
+            )
         elif method == "dcp":
             estimator = DCPAirlight()
         elif method == "dcp_heuristic":

{euler_preprocess-3.20.0 → euler_preprocess-3.22.0}/euler_preprocess/fog/models.py

@@ -399,14 +399,24 @@ def estimate_airlight_torch(
     image: "torch.Tensor",
     sky_mask: "torch.Tensor",
     sample_id: str | None = None,
+    *,
+    no_sky_warning=None,
 ) -> "torch.Tensor":
+    """Mean colour of the sky pixels, white ``[1, 1, 1]`` without any.
+
+    *no_sky_warning* (a :class:`~euler_preprocess.fog.airlight_from_sky.NoSkyWarning`)
+    reports the fallback; without one, every fallback logs a warning.
+    """
     if sky_mask.sum() == 0:
-        id_str = f" (sample {sample_id})" if sample_id else ""
-        _logger.warning(
-            "No sky pixels in segmentation mask%s; "
-            "using default airlight fallback [1.0, 1.0, 1.0]",
-            id_str,
-        )
+        if no_sky_warning is not None:
+            no_sky_warning(sample_id)
+        else:
+            id_str = f" (sample {sample_id})" if sample_id else ""
+            _logger.warning(
+                "No sky pixels in segmentation mask%s; "
+                "using default airlight fallback [1.0, 1.0, 1.0]",
+                id_str,
+            )
         return torch.ones(3, device=image.device, dtype=image.dtype)
     airlight_pixels = image[sky_mask]
     airlight = airlight_pixels.mean(dim=0)