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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-preprocess
-Version: 3.3.0
+Version: 3.5.0
 Summary: Physics-based preprocessing (fog, etc.) for RGB+depth datasets
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -148,6 +148,7 @@ Controls the fog simulation.
   "depth_scale": 1.0,
   "resize_depth": true,
   "contrast_threshold": 0.05,
+  "mode": "sample",
   "device": "cpu",
   "gpu_batch_size": 4,
   "capture": { "preset": "camera" },
@@ -165,6 +166,7 @@ Controls the fog simulation.
 | `depth_scale` | Multiplier applied to depth values after loading. |
 | `resize_depth` | Resize the depth map to match the RGB resolution (bilinear). |
 | `contrast_threshold` | Threshold *C_t* used in the visibility-to-attenuation conversion (default `0.05`). |
+| `mode` | Optional scenario mode. Omit it or use `"sample"` for current one-scenario-per-image behavior; use `"progressive"` to render every scenario step for every image. |
 | `device` | `"cpu"`, `"cuda"`, `"mps"`, or `"gpu"` (alias for cuda). |
 | `gpu_batch_size` | Batch size when running on GPU. Uniform-model samples are batched; heterogeneous samples are processed individually. |
 | `capture` / `capture_artifacts` | Optional post-fog camera artifact pipeline. Omit it or set `{"stages": []}` for the legacy no-op path. Set `true`, `{"preset": "camera"}`, or a custom `stages` list to enable optics, raw sensor, ISP, and compression artifacts. |
@@ -404,6 +406,19 @@ compression together:
 `condition_profiles`; if omitted, the stage continues sampling its own profile
 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 `"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.
+
 ### Fog Model
 
 The core equation is the **Koschmieder model** (atmospheric scattering):
@@ -482,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.3.0 → euler_preprocess-3.5.0}/README.md

@@ -134,6 +134,7 @@ Controls the fog simulation.
   "depth_scale": 1.0,
   "resize_depth": true,
   "contrast_threshold": 0.05,
+  "mode": "sample",
   "device": "cpu",
   "gpu_batch_size": 4,
   "capture": { "preset": "camera" },
@@ -151,6 +152,7 @@ Controls the fog simulation.
 | `depth_scale` | Multiplier applied to depth values after loading. |
 | `resize_depth` | Resize the depth map to match the RGB resolution (bilinear). |
 | `contrast_threshold` | Threshold *C_t* used in the visibility-to-attenuation conversion (default `0.05`). |
+| `mode` | Optional scenario mode. Omit it or use `"sample"` for current one-scenario-per-image behavior; use `"progressive"` to render every scenario step for every image. |
 | `device` | `"cpu"`, `"cuda"`, `"mps"`, or `"gpu"` (alias for cuda). |
 | `gpu_batch_size` | Batch size when running on GPU. Uniform-model samples are batched; heterogeneous samples are processed individually. |
 | `capture` / `capture_artifacts` | Optional post-fog camera artifact pipeline. Omit it or set `{"stages": []}` for the legacy no-op path. Set `true`, `{"preset": "camera"}`, or a custom `stages` list to enable optics, raw sensor, ISP, and compression artifacts. |
@@ -390,6 +392,19 @@ compression together:
 `condition_profiles`; if omitted, the stage continues sampling its own profile
 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 `"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.
+
 ### Fog Model
 
 The core equation is the **Koschmieder model** (atmospheric scattering):
@@ -468,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.3.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(