euler-preprocess 3.4.0__tar.gz → 3.5.0__tar.gz

{euler_preprocess-3.4.0 → euler_preprocess-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-preprocess
-Version: 3.4.0
+Version: 3.5.0
 Summary: Physics-based preprocessing (fog, etc.) for RGB+depth datasets
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -408,10 +408,14 @@ weights locally.
 
 Set top-level `"mode": "progressive"` to emit every configured scenario for
 every input image instead of sampling one scenario. Each scenario accepts
-`"steps"` and `"weight"`; the transform writes steps from weight `0` through
-the scenario's configured weight, and weight `1` matches the original scenario.
-Fog density is progressed in scattering-coefficient space, while numeric
-camera/config values blend from the base config toward the scenario config.
+`"steps"` and `"progressive_weight"` (or `"max_weight"` / `"weight"` as
+aliases); the transform writes steps from weight `0` through the scenario's
+configured weight, and weight `1` matches the original scenario. Fog density is
+progressed in scattering-coefficient space, while numeric camera/config values
+blend from the base config toward the scenario config. Progressive blends clamp
+probability-like values and non-negative physical factors back into valid
+mathematical domains so extrapolated weights above `1` do not create invalid
+render parameters.
 Source-backed outputs are written as `fog_progression` variants under each
 source file id.
 
@@ -493,6 +497,10 @@ Each fog model can override the dampening curve:
 
 The factor is:
 `min_factor + (max_factor - min_factor) / (1 + strength * beta / reference_beta)`.
+`min_factor` and `max_factor` must be finite and non-negative. Values above
+`1.0` are allowed when you intentionally want to brighten estimated airlight;
+the final RGB output is still clamped to the valid image range. `strength`
+must remain finite and non-negative.
 `reference_beta` is either `reference_scattering_coefficient` /
 `reference_beta`, or it is derived from `reference_visibility_m` using the
 model's contrast threshold. The default applies only when `atmospheric_light`

{euler_preprocess-3.4.0 → euler_preprocess-3.5.0}/README.md

@@ -394,10 +394,14 @@ weights locally.
 
 Set top-level `"mode": "progressive"` to emit every configured scenario for
 every input image instead of sampling one scenario. Each scenario accepts
-`"steps"` and `"weight"`; the transform writes steps from weight `0` through
-the scenario's configured weight, and weight `1` matches the original scenario.
-Fog density is progressed in scattering-coefficient space, while numeric
-camera/config values blend from the base config toward the scenario config.
+`"steps"` and `"progressive_weight"` (or `"max_weight"` / `"weight"` as
+aliases); the transform writes steps from weight `0` through the scenario's
+configured weight, and weight `1` matches the original scenario. Fog density is
+progressed in scattering-coefficient space, while numeric camera/config values
+blend from the base config toward the scenario config. Progressive blends clamp
+probability-like values and non-negative physical factors back into valid
+mathematical domains so extrapolated weights above `1` do not create invalid
+render parameters.
 Source-backed outputs are written as `fog_progression` variants under each
 source file id.
 
@@ -479,6 +483,10 @@ Each fog model can override the dampening curve:
 
 The factor is:
 `min_factor + (max_factor - min_factor) / (1 + strength * beta / reference_beta)`.
+`min_factor` and `max_factor` must be finite and non-negative. Values above
+`1.0` are allowed when you intentionally want to brighten estimated airlight;
+the final RGB output is still clamped to the valid image range. `strength`
+must remain finite and non-negative.
 `reference_beta` is either `reference_scattering_coefficient` /
 `reference_beta`, or it is derived from `reference_visibility_m` using the
 model's contrast threshold. The default applies only when `atmospheric_light`

{euler_preprocess-3.4.0 → euler_preprocess-3.5.0}/euler_preprocess/fog/models.py

@@ -100,8 +100,12 @@ DEFAULT_MODEL_CONFIGS = {
 
 
 def visibility_to_k(visibility_m: float, contrast_threshold: float) -> float:
-    if visibility_m <= 0:
+    if not math.isfinite(visibility_m) or visibility_m <= 0:
         raise ValueError(f"Visibility must be > 0, got {visibility_m}")
+    if not math.isfinite(contrast_threshold) or not 0.0 < contrast_threshold < 1.0:
+        raise ValueError(
+            f"Contrast threshold must be in (0, 1), got {contrast_threshold}"
+        )
     return -math.log(contrast_threshold) / visibility_m
 
 
@@ -132,7 +136,7 @@ def resolve_scattering_coefficient(
     beta_spec = model_cfg.get("scattering_coefficient", model_cfg.get("beta"))
     if beta_spec is not None:
         beta = float(sample_value(beta_spec, rng))
-        if beta < 0:
+        if not math.isfinite(beta) or beta < 0:
             raise ValueError(f"Scattering coefficient must be >= 0, got {beta}")
         return beta, None, contrast_threshold
 
@@ -222,13 +226,13 @@ def resolve_airlight_dampening_config(
         rng,
         "airlight_dampening.strength",
     )
-    if not 0.0 <= min_factor <= 1.0:
+    if min_factor < 0.0:
         raise ValueError(
-            f"airlight_dampening.min_factor must be in [0, 1], got {min_factor}"
+            f"airlight_dampening.min_factor must be >= 0, got {min_factor}"
         )
-    if not 0.0 <= max_factor <= 1.0:
+    if max_factor < 0.0:
         raise ValueError(
-            f"airlight_dampening.max_factor must be in [0, 1], got {max_factor}"
+            f"airlight_dampening.max_factor must be >= 0, got {max_factor}"
         )
     if min_factor > max_factor:
         raise ValueError("airlight_dampening.min_factor must be <= max_factor")
@@ -504,9 +508,12 @@ def _scale_pixels(value, rng: np.random.Generator, name: str) -> int:
 def _sample_float(value, rng: np.random.Generator, name: str) -> float:
     sampled = sample_value(value, rng)
     try:
-        return float(sampled)
+        resolved = float(sampled)
     except (TypeError, ValueError) as exc:
         raise ValueError(f"{name} must resolve to a number, got {sampled!r}") from exc
+    if not math.isfinite(resolved):
+        raise ValueError(f"{name} must be finite, got {resolved}")
+    return resolved
 
 
 def _unique_positive_scales(scales: list[int]) -> list[int]:
@@ -801,9 +808,11 @@ def _gradient_enabled(
         rng,
         f"{name}.probability",
     )
-    if not 0.0 <= probability <= 1.0:
-        raise ValueError(f"{name}.probability must be in [0, 1], got {probability}")
-    return probability >= 1.0 or bool(rng.random() < probability)
+    if probability <= 0.0:
+        return False
+    if probability >= 1.0:
+        return True
+    return bool(rng.random() < probability)
 
 
 def _ls_gradient_factors_np(
@@ -885,10 +894,7 @@ def _weight_ls_gradient_by_opacity_np(
         rng,
         "ls_gradient.fog_opacity_weight",
     )
-    if not 0.0 <= weight <= 1.0:
-        raise ValueError(
-            f"ls_gradient.fog_opacity_weight must be in [0, 1], got {weight}"
-        )
+    weight = float(np.clip(weight, 0.0, 1.0))
     if weight <= 0.0:
         return factors
     gamma = _sample_float(
@@ -917,10 +923,7 @@ def _weight_ls_gradient_by_opacity_torch(
         rng,
         "ls_gradient.fog_opacity_weight",
     )
-    if not 0.0 <= weight <= 1.0:
-        raise ValueError(
-            f"ls_gradient.fog_opacity_weight must be in [0, 1], got {weight}"
-        )
+    weight = float(np.clip(weight, 0.0, 1.0))
     if weight <= 0.0:
         return factors
     gamma = _sample_float(

{euler_preprocess-3.4.0 → euler_preprocess-3.5.0}/euler_preprocess/fog/transform.py

@@ -129,6 +129,53 @@ _GPU_BATCH_SCOPE_VALUES = {"sample", "batch"}
 _CONFIG_MODE_VALUES = {"sample", "sampled", "random", "default", "legacy"}
 _PROGRESSIVE_ATTRIBUTE_KEY = "fog_progression"
 _PROGRESSIVE_FILE_ID_HIERARCHY_NAME = "file_id"
+_PROGRESSIVE_EPSILON = 1e-6
+_PROGRESSIVE_UNIT_INTERVAL_KEYS = {
+    "probability",
+    "fog_opacity_weight",
+    "highlight_protection",
+    "center_weight",
+    "black_noise_floor",
+}
+_PROGRESSIVE_NON_NEGATIVE_KEYS = {
+    "beta",
+    "scattering_coefficient",
+    "strength",
+    "min_factor",
+    "max_factor",
+    "top_factor",
+    "bottom_factor",
+    "contrast",
+    "noise_contrast",
+    "smooth_sigma",
+    "smoothing_sigma",
+    "blur_sigma",
+    "smooth_sigma_fraction",
+    "smoothing_sigma_fraction",
+    "blur_sigma_fraction",
+    "read_noise_electrons",
+    "read_noise_sigma",
+    "fixed_pattern_sigma",
+    "row_noise_sigma",
+    "column_noise_sigma",
+    "hot_pixel_probability",
+    "dead_pixel_probability",
+}
+_PROGRESSIVE_POSITIVE_KEYS = {
+    "visibility_m",
+    "reference_visibility_m",
+    "reference_beta",
+    "reference_scattering_coefficient",
+    "gamma",
+    "fog_opacity_gamma",
+    "correlation_length_fraction",
+    "min_scale_fraction",
+    "max_scale_fraction",
+    "iso",
+    "base_iso",
+    "resize_scale",
+}
+_PROGRESSIVE_MIN_MAX_PAIRS = (("min_factor", "max_factor"),)
 
 
 @dataclass(frozen=True)
@@ -826,16 +873,20 @@ class FogTransform(Transform):
         base_model_cfg = _freeze_distribution_specs(base_model_cfg, rng)
         target_model_cfg = _freeze_distribution_specs(target_model_cfg, rng)
 
-        step_effective_config = self._progressive_blend_value(
-            base_effective_config,
-            target_effective_config,
-            step.weight,
+        step_effective_config = self._sanitize_progressive_blended_config(
+            self._progressive_blend_value(
+                base_effective_config,
+                target_effective_config,
+                step.weight,
+            )
         )
-        model_cfg = self._progressive_model_config(
-            base_model_cfg,
-            target_model_cfg,
-            step.weight,
-            rng,
+        model_cfg = self._sanitize_progressive_blended_config(
+            self._progressive_model_config(
+                base_model_cfg,
+                target_model_cfg,
+                step.weight,
+                rng,
+            )
         )
         airlight_method = (
             None
@@ -953,6 +1004,57 @@ class FogTransform(Transform):
 
         return copy.deepcopy(target)
 
+    def _sanitize_progressive_blended_config(
+        self,
+        value: Any,
+        *,
+        key: str | None = None,
+    ) -> Any:
+        if isinstance(value, dict):
+            sanitized = {
+                child_key: self._sanitize_progressive_blended_config(
+                    child,
+                    key=child_key,
+                )
+                for child_key, child in value.items()
+            }
+            for min_key, max_key in _PROGRESSIVE_MIN_MAX_PAIRS:
+                min_value = sanitized.get(min_key)
+                max_value = sanitized.get(max_key)
+                if (
+                    _is_progressive_number(min_value)
+                    and _is_progressive_number(max_value)
+                    and float(max_value) < float(min_value)
+                ):
+                    sanitized[max_key] = float(min_value)
+            return sanitized
+
+        if isinstance(value, list):
+            return [
+                self._sanitize_progressive_blended_config(item, key=key)
+                for item in value
+            ]
+        if isinstance(value, tuple):
+            return tuple(
+                self._sanitize_progressive_blended_config(item, key=key)
+                for item in value
+            )
+
+        if not _is_progressive_number(value):
+            return copy.deepcopy(value)
+
+        numeric = float(value)
+        if not np.isfinite(numeric):
+            label = key or "value"
+            raise ValueError(f"progressive blended {label} must be finite")
+        if key in _PROGRESSIVE_UNIT_INTERVAL_KEYS:
+            return float(np.clip(numeric, 0.0, 1.0))
+        if key in _PROGRESSIVE_POSITIVE_KEYS:
+            return max(numeric, _PROGRESSIVE_EPSILON)
+        if key in _PROGRESSIVE_NON_NEGATIVE_KEYS:
+            return max(numeric, 0.0)
+        return copy.deepcopy(value)
+
     def _progressive_neutral_value(self, key: str | None, target: Any) -> Any:
         if _is_progressive_number(target):
             return self._progressive_neutral_number(key, float(target))

{euler_preprocess-3.4.0 → euler_preprocess-3.5.0}/euler_preprocess.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-preprocess
-Version: 3.4.0
+Version: 3.5.0
 Summary: Physics-based preprocessing (fog, etc.) for RGB+depth datasets
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -408,10 +408,14 @@ weights locally.
 
 Set top-level `"mode": "progressive"` to emit every configured scenario for
 every input image instead of sampling one scenario. Each scenario accepts
-`"steps"` and `"weight"`; the transform writes steps from weight `0` through
-the scenario's configured weight, and weight `1` matches the original scenario.
-Fog density is progressed in scattering-coefficient space, while numeric
-camera/config values blend from the base config toward the scenario config.
+`"steps"` and `"progressive_weight"` (or `"max_weight"` / `"weight"` as
+aliases); the transform writes steps from weight `0` through the scenario's
+configured weight, and weight `1` matches the original scenario. Fog density is
+progressed in scattering-coefficient space, while numeric camera/config values
+blend from the base config toward the scenario config. Progressive blends clamp
+probability-like values and non-negative physical factors back into valid
+mathematical domains so extrapolated weights above `1` do not create invalid
+render parameters.
 Source-backed outputs are written as `fog_progression` variants under each
 source file id.
 
@@ -493,6 +497,10 @@ Each fog model can override the dampening curve:
 
 The factor is:
 `min_factor + (max_factor - min_factor) / (1 + strength * beta / reference_beta)`.
+`min_factor` and `max_factor` must be finite and non-negative. Values above
+`1.0` are allowed when you intentionally want to brighten estimated airlight;
+the final RGB output is still clamped to the valid image range. `strength`
+must remain finite and non-negative.
 `reference_beta` is either `reference_scattering_coefficient` /
 `reference_beta`, or it is derived from `reference_visibility_m` using the
 model's contrast threshold. The default applies only when `atmospheric_light`

{euler_preprocess-3.4.0 → euler_preprocess-3.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "euler-preprocess"
-version = "3.4.0"
+version = "3.5.0"
 description = "Physics-based preprocessing (fog, etc.) for RGB+depth datasets"
 readme = "README.md"
 requires-python = ">=3.9"

{euler_preprocess-3.4.0 → euler_preprocess-3.5.0}/tests/test_fog_aux_outputs.py

@@ -462,6 +462,70 @@ def test_progressive_scenario_profiles_write_steps_and_attributes(
     }
 
 
+def test_progressive_scenario_profiles_accept_extrapolated_airlight_dampening(
+    tmp_path: Path,
+) -> None:
+    dataset = _make_dataset(tmp_path)
+    pipeline_root = tmp_path / "pipeline_root_progressive_airlight"
+    manifest_path = pipeline_root / ".euler_pipeline" / "pipeline_outputs.json"
+    config = _build_pipeline_config(
+        pipeline_root,
+        manifest_path,
+        include_scattering=False,
+        include_airlight=True,
+    )
+    fog_config_path = tmp_path / "fog_progressive_airlight.json"
+    fog_config_path.write_text(
+        json.dumps(
+            {
+                "mode": "progressive",
+                "airlight": "from_sky",
+                "device": "cpu",
+                "seed": 7,
+                "contrast_threshold": 0.05,
+                "scenario_profiles": [
+                    {
+                        "name": "bright-airlight",
+                        "steps": 1,
+                        "progressive_weight": 1.5,
+                        "model": "uniform",
+                        "models": {
+                            "uniform": {
+                                "visibility_m": 20.0,
+                                "atmospheric_light": "from_sky",
+                                "airlight_dampening": {
+                                    "min_factor": 0.8,
+                                    "max_factor": 1.1,
+                                    "strength": 0.0,
+                                },
+                            }
+                        },
+                    }
+                ],
+            }
+        )
+    )
+
+    backends = prepare_output_backends(config, dataset, FogTransform)
+    transform = FogTransform(
+        config_path=str(fog_config_path),
+        out_path=str(backends["rgb"].root),
+        output_backends=backends,
+    )
+
+    saved_paths = transform.run(dataset)
+
+    assert saved_paths[-1] == (
+        pipeline_root
+        / "foggy_rgb"
+        / "Scene01"
+        / "Camera_0"
+        / "00001"
+        / "bright-airlight_w1.5.png"
+    )
+    assert saved_paths[-1].exists()
+
+
 def test_only_scattering_target_writes_only_scattering(tmp_path: Path) -> None:
     dataset = _make_dataset(tmp_path)
     pipeline_root = tmp_path / "pipeline_root_scat_only"
@@ -2424,6 +2488,76 @@ def test_airlight_dampening_alias_can_disable_default() -> None:
     np.testing.assert_allclose(airlight, estimated, atol=1e-6)
 
 
+def test_airlight_dampening_accepts_brightening_factors() -> None:
+    from euler_preprocess.fog.models import apply_model
+
+    rgb = np.full((4, 5, 3), 0.35, dtype=np.float32)
+    depth = np.full((4, 5), 30.0, dtype=np.float32)
+    estimated = np.array([0.35, 0.4, 0.45], dtype=np.float32)
+    cfg = {
+        "scattering_coefficient": 0.1,
+        "atmospheric_light": "from_sky",
+        "airlight_dampening": {
+            "min_factor": 1.1,
+            "max_factor": 1.25,
+            "strength": 0.0,
+        },
+    }
+
+    _, _, airlight, _, _ = apply_model(
+        rgb,
+        depth,
+        "uniform",
+        cfg,
+        np.random.default_rng(0),
+        contrast_threshold_default=0.05,
+        estimated_airlight=estimated,
+    )
+
+    np.testing.assert_allclose(airlight, estimated * 1.25, atol=1e-6)
+
+
+def test_ls_gradient_probability_and_opacity_weight_saturate() -> None:
+    from euler_preprocess.fog.models import apply_model
+
+    rng = np.random.default_rng(123)
+    rgb = np.zeros((20, 16, 3), dtype=np.float32)
+    depth = np.full((20, 16), 80.0, dtype=np.float32)
+    estimated = np.array([0.6, 0.65, 0.7], dtype=np.float32)
+    cfg = {
+        "scattering_coefficient": 0.08,
+        "atmospheric_light": "from_sky",
+        "airlight_dampening": {"enabled": False},
+        "ls_hetero": {
+            "scales": [4],
+            "min_factor": 1.0,
+            "max_factor": 1.0,
+            "normalize_to_mean": False,
+            "ls_gradient": {
+                "enabled": True,
+                "probability": 1.4,
+                "top_factor": 1.18,
+                "bottom_factor": 0.82,
+                "gamma": 1.0,
+                "normalize_to_mean": False,
+                "fog_opacity_weight": 1.5,
+            },
+        },
+    }
+
+    _, _, _, _, ls_map = apply_model(
+        rgb,
+        depth,
+        "heterogeneous_ls",
+        cfg,
+        rng,
+        contrast_threshold_default=0.05,
+        estimated_airlight=estimated,
+    )
+
+    assert np.isfinite(ls_map).all()
+
+
 def test_heterogeneous_ls_uses_dampened_airlight_base() -> None:
     """Perlin L_s modes should modulate around the already dampened base airlight."""
     from euler_preprocess.fog.models import apply_model