euler-train 2.0.0__tar.gz → 2.1.0__tar.gz

{euler_train-2.0.0 → euler_train-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-train
-Version: 2.0.0
+Version: 2.1.0
 Summary: Lightweight file-based experiment logger for PyTorch
 Requires-Python: >=3.9
 Requires-Dist: numpy

{euler_train-2.0.0 → euler_train-2.1.0}/README.md

@@ -80,7 +80,7 @@ The run ID and directory are available as `run.run_id` and `run.dir`.
 
 ## API reference
 
-### `euler_train.init(dir, config=None, meta=None, output_formats=None, run_id=None, datasets=None, run_name=None, evaluations=None, mode=None) → Run`
+### `euler_train.init(dir, config=None, meta=None, output_formats=None, output_visualization=None, run_id=None, datasets=None, run_name=None, evaluations=None, mode=None) → Run`
 
 Creates the run directory and writes `meta.json`, `config.json`, `code_ref.json`, and `run_environment.json`. On resume (`run_id` provided), only `meta.json` and `config.json` are updated.
 
@@ -90,6 +90,7 @@ Creates the run directory and writes `meta.json`, `config.json`, `code_ref.json`
 | `config` | `dict \| str \| Path \| Namespace \| dataclass` | Hyperparameters. Paths to `.json` / `.yaml` files are loaded automatically. |
 | `meta` | `dict \| None` | Extra fields merged into `meta.json` (e.g. `{"tags": ["baseline"]}`). |
 | `output_formats` | `dict[str, str] \| None` | Override format inference (see [Format inference](#format-inference)). |
+| `output_visualization` | `dict[str, Any] \| None` | Override PNG visualization policy per output type / slot (see [Output visualization](#output-visualization)). |
 | `run_id` | `str \| None` | Resume an existing run at `{dir}/runs/{run_id}` instead of creating a new one. |
 | `datasets` | `dict[str, Any] \| None` | Optional split → dataset map. If a dataset exposes `describe_for_runlog()`, that contract is used directly; otherwise euler_train infers structured modality metadata (`path`, `used_as`, `slot`, `modality_type`, and hierarchical fields), resolving fixed namespaced properties from `properties.euler_loading` and `properties.euler_train` before heuristics. |
 | `run_name` | `str \| None` | Optional human-readable run label stored in `meta.json`. |
@@ -218,7 +219,7 @@ Arrays are saved as `.png` or `.npy` based on shape and dtype:
 |---|---|
 | `uint8` with shape `(H,W)` | `.png` (grayscale) |
 | Any dtype with shape `(H,W,1)`, `(H,W,3)`, `(H,W,4)` | `.png` |
-| Float `.png` | clipped to `[0,1]`, scaled to `[0,255]` |
+| Float `.png` | defaults to `unit_range`: clip to `[0,1]`, then scale to `[0,255]` |
 | Everything else (e.g. `float32 (H,W)`) | `.npy` |
 | PIL Image | `.png` |
 
@@ -240,6 +241,33 @@ run = euler_train.init(
 
 Supported formats: `"png"`, `"npy"`, `"npz"`.
 
+## Output visualization
+
+Float PNG outputs use a rendering policy before quantization to `uint8`. Policies are configured once at `init()` via `output_visualization`, and keys resolve most-specific-first just like `output_formats`:
+
+```python
+run = euler_train.init(
+    dir="runs/exp",
+    config=cfg,
+    output_visualization={
+        "depth": {"mode": "percentile", "pmin": 1, "pmax": 99},
+        "depth.pred": {"mode": "fixed_range", "vmin": 0.0, "vmax": 80.0},
+        "confidence": "minmax",
+    },
+)
+```
+
+Supported visualization modes:
+
+| Mode | Parameters | Description |
+|---|---|---|
+| `unit_range` | none | Clip float data to `[0,1]` before saving. |
+| `minmax` | none | Normalize using the finite-value min / max of the saved item. |
+| `percentile` | `pmin`, `pmax` | Normalize using finite-value percentiles, useful for depth-like outputs. |
+| `fixed_range` | `vmin`, `vmax` | Normalize against an explicit numeric range. |
+
+All float PNG policies also accept `invert: true` to flip black ↔ white after normalization.
+
 ## `meta.json` schema
 
 Auto-managed, not written to directly.

{euler_train-2.0.0 → euler_train-2.1.0}/euler_train/__init__.py

@@ -1,6 +1,8 @@
 """runlog — lightweight file-based experiment logging."""
 from __future__ import annotations
 
+from typing import Any
+
 from . import _dataset_contract  # noqa: F401
 from .run import Run
 from .architecture import export_architecture
@@ -14,6 +16,7 @@ def init(
     config=None,
     meta: dict | None = None,
     output_formats: dict[str, str] | None = None,
+    output_visualization: dict[str, Any] | None = None,
     run_id: str | None = None,
     datasets: dict | None = None,
     run_name: str | None = None,
@@ -51,6 +54,11 @@ def init(
         (``"depth"``), a slot / aux name (``"transmission"``), or a
         dotted combination (``"depth.pred"``).  Values are ``"png"``,
         ``"npy"``, or ``"npz"``.
+    output_visualization:
+        Optional PNG rendering policy overrides. Keys resolve the same way
+        as *output_formats* (``"depth.pred"`` → ``"depth"`` → ``"pred"``).
+        Values can be a string mode (for example ``"percentile"``) or a
+        mapping such as ``{"mode": "fixed_range", "vmin": 0, "vmax": 80}``.
     run_id:
         If given, resume an existing run instead of creating a new one.
         The run directory ``{dir}/runs/{run_id}/`` must already exist.
@@ -84,7 +92,9 @@ def init(
     """
     return Run(
         dir=dir, config=config, meta=meta,
-        output_formats=output_formats, run_id=run_id,
+        output_formats=output_formats,
+        output_visualization=output_visualization,
+        run_id=run_id,
         datasets=datasets, run_name=run_name,
         evaluations=evaluations, mode=mode,
     )

{euler_train-2.0.0 → euler_train-2.1.0}/euler_train/outputs.py

@@ -1,6 +1,7 @@
 """Save prediction / ground-truth / auxiliary outputs to disk."""
 from __future__ import annotations
 
+from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 
@@ -15,6 +16,7 @@ def save_output_tree(
     type_dir: Path,
     slots: dict[str, Any],
     format_overrides: dict[str, str],
+    visualization_overrides: dict[str, Any],
     output_type: str,
 ) -> None:
     """Persist all slots (pred, gt, input, aux/…) for one *output_type*.
@@ -35,13 +37,21 @@ def save_output_tree(
                 if aux_data is None:
                     continue
                 _save_slot(
-                    type_dir / "aux" / aux_name, aux_data,
-                    output_type, aux_name, format_overrides,
+                    type_dir / "aux" / aux_name,
+                    aux_data,
+                    output_type,
+                    aux_name,
+                    format_overrides,
+                    visualization_overrides,
                 )
         else:
             _save_slot(
-                type_dir / slot_name, data,
-                output_type, slot_name, format_overrides,
+                type_dir / slot_name,
+                data,
+                output_type,
+                slot_name,
+                format_overrides,
+                visualization_overrides,
             )
 
 
@@ -55,12 +65,16 @@ def _save_slot(
     output_type: str,
     leaf_name: str,
     format_overrides: dict[str, str],
+    visualization_overrides: dict[str, Any],
 ) -> None:
     slot_dir.mkdir(parents=True, exist_ok=True)
     items = _unpack(data)
+    visualization = _resolve_visualization(
+        output_type, leaf_name, visualization_overrides,
+    )
     for idx, item in enumerate(items):
         fmt = _resolve_format(item, output_type, leaf_name, format_overrides)
-        _save_item(slot_dir / f"{idx:04d}.{fmt}", item, fmt)
+        _save_item(slot_dir / f"{idx:04d}.{fmt}", item, fmt, visualization)
 
 
 # ---- normalisation -------------------------------------------------------
@@ -88,7 +102,12 @@ def _prepare(data: Any) -> Any:
 
     # torch Tensor → numpy, channels-first → channels-last
     if hasattr(data, "detach"):
-        arr: np.ndarray = data.detach().cpu().numpy()
+        tensor = data.detach().cpu()
+        try:
+            arr: np.ndarray = tensor.numpy()
+        except TypeError:
+            # NumPy cannot represent some torch dtypes (for example bfloat16).
+            arr = tensor.float().numpy()
         # (C, H, W) → (H, W, C)  when C looks like a channel dim
         if (
             arr.ndim == 3
@@ -119,14 +138,11 @@ def _is_image_like(arr: np.ndarray) -> bool:
     return False
 
 
-def _resolve_format(
-    item: Any,
+def _resolve_override(
     output_type: str,
     leaf_name: str,
-    overrides: dict[str, str],
-) -> str:
-    """Pick save format: check overrides (most-specific first), then infer."""
-    # "rgb.pred" > "rgb" > "pred"
+    overrides: Mapping[str, Any],
+) -> Any:
     specific = f"{output_type}.{leaf_name}"
     if specific in overrides:
         return overrides[specific]
@@ -134,6 +150,19 @@ def _resolve_format(
         return overrides[output_type]
     if leaf_name in overrides:
         return overrides[leaf_name]
+    return None
+
+
+def _resolve_format(
+    item: Any,
+    output_type: str,
+    leaf_name: str,
+    overrides: dict[str, str],
+) -> str:
+    """Pick save format: check overrides (most-specific first), then infer."""
+    override = _resolve_override(output_type, leaf_name, overrides)
+    if override is not None:
+        return str(override)
 
     # PIL Image
     try:
@@ -148,11 +177,34 @@ def _resolve_format(
     return "npy"
 
 
+def _resolve_visualization(
+    output_type: str,
+    leaf_name: str,
+    overrides: Mapping[str, Any],
+) -> dict[str, Any] | None:
+    override = _resolve_override(output_type, leaf_name, overrides)
+    if override is None:
+        return None
+    if isinstance(override, str):
+        return {"mode": override}
+    if isinstance(override, Mapping):
+        return dict(override)
+    raise TypeError(
+        "Visualization overrides must be strings or mappings, "
+        f"got {type(override)!r}",
+    )
+
+
 # ---- writers -------------------------------------------------------------
 
-def _save_item(path: Path, item: Any, fmt: str) -> None:
+def _save_item(
+    path: Path,
+    item: Any,
+    fmt: str,
+    visualization: dict[str, Any] | None = None,
+) -> None:
     if fmt == "png":
-        _save_png(path, item)
+        _save_png(path, item, visualization)
     elif fmt == "npy":
         np.save(str(path), item if isinstance(item, np.ndarray) else np.asarray(item))
     elif fmt == "npz":
@@ -164,7 +216,11 @@ def _save_item(path: Path, item: Any, fmt: str) -> None:
         raise ValueError(f"Unsupported format: {fmt!r}")
 
 
-def _save_png(path: Path, item: Any) -> None:
+def _save_png(
+    path: Path,
+    item: Any,
+    visualization: dict[str, Any] | None = None,
+) -> None:
     from PIL import Image
 
     # PIL Image — save directly
@@ -174,10 +230,9 @@ def _save_png(path: Path, item: Any) -> None:
 
     arr: np.ndarray = item
 
-    # float → [0,1] → uint8
+    # float → visualization policy → uint8
     if np.issubdtype(arr.dtype, np.floating):
-        arr = np.clip(arr, 0.0, 1.0)
-        arr = (arr * 255).astype(np.uint8)
+        arr = _render_float_png(arr, visualization)
     elif arr.dtype != np.uint8:
         arr = arr.astype(np.uint8)
 
@@ -192,3 +247,75 @@ def _save_png(path: Path, item: Any) -> None:
         Image.fromarray(plane, mode=mode).save(str(path))
     else:
         raise ValueError(f"Cannot save {arr.ndim}D array as PNG")
+
+
+def _render_float_png(
+    arr: np.ndarray,
+    visualization: dict[str, Any] | None,
+) -> np.ndarray:
+    policy = {"mode": "unit_range"}
+    if visualization is not None:
+        policy.update(visualization)
+
+    mode = str(policy.get("mode", "unit_range"))
+    finite = np.isfinite(arr)
+
+    if mode == "unit_range":
+        scaled = np.asarray(arr, dtype=np.float32)
+    elif mode == "minmax":
+        scaled = _normalize_minmax(arr, finite)
+    elif mode == "percentile":
+        pmin = float(policy.get("pmin", 1.0))
+        pmax = float(policy.get("pmax", 99.0))
+        if pmax <= pmin:
+            raise ValueError(
+                "Percentile visualization requires pmax > pmin, "
+                f"got pmin={pmin} pmax={pmax}",
+            )
+        scaled = _normalize_percentile(arr, finite, pmin, pmax)
+    elif mode == "fixed_range":
+        vmin = float(policy.get("vmin", 0.0))
+        vmax = float(policy.get("vmax", 1.0))
+        if vmax <= vmin:
+            raise ValueError(
+                "Fixed-range visualization requires vmax > vmin, "
+                f"got vmin={vmin} vmax={vmax}",
+            )
+        scaled = (np.asarray(arr, dtype=np.float32) - vmin) / (vmax - vmin)
+    else:
+        raise ValueError(f"Unsupported visualization mode: {mode!r}")
+
+    scaled = np.nan_to_num(scaled, nan=0.0, posinf=1.0, neginf=0.0)
+    if bool(policy.get("invert", False)):
+        scaled = 1.0 - scaled
+    scaled = np.clip(scaled, 0.0, 1.0)
+    return (scaled * 255).astype(np.uint8)
+
+
+def _normalize_minmax(arr: np.ndarray, finite: np.ndarray) -> np.ndarray:
+    values = arr[finite]
+    if values.size == 0:
+        return np.zeros_like(arr, dtype=np.float32)
+
+    vmin = float(values.min())
+    vmax = float(values.max())
+    if vmax <= vmin:
+        return np.zeros_like(arr, dtype=np.float32)
+    return (np.asarray(arr, dtype=np.float32) - vmin) / (vmax - vmin)
+
+
+def _normalize_percentile(
+    arr: np.ndarray,
+    finite: np.ndarray,
+    pmin: float,
+    pmax: float,
+) -> np.ndarray:
+    values = arr[finite]
+    if values.size == 0:
+        return np.zeros_like(arr, dtype=np.float32)
+
+    lo = float(np.percentile(values, pmin))
+    hi = float(np.percentile(values, pmax))
+    if hi <= lo:
+        return np.zeros_like(arr, dtype=np.float32)
+    return (np.asarray(arr, dtype=np.float32) - lo) / (hi - lo)

{euler_train-2.0.0 → euler_train-2.1.0}/euler_train/run.py

@@ -38,6 +38,7 @@ class Run:
         config: Any = None,
         meta: dict | None = None,
         output_formats: dict[str, str] | None = None,
+        output_visualization: dict[str, Any] | None = None,
         gpu_stats_every: int = 100,
         run_id: str | None = None,
         datasets: dict[str, Any] | None = None,
@@ -73,6 +74,7 @@ class Run:
 
         self.checkpoint_dir: Path | None = None
         self._output_formats: dict[str, str] = output_formats or {}
+        self._output_visualization: dict[str, Any] = output_visualization or {}
         self._start_time = time.time()
         self._finished = False
         self._gpu_handle: Any | None = None
@@ -305,7 +307,11 @@ class Run:
             if slots is None:
                 continue
             save_output_tree(
-                base / output_type, slots, self._output_formats, output_type,
+                base / output_type,
+                slots,
+                self._output_formats,
+                self._output_visualization,
+                output_type,
             )
         return base
 

{euler_train-2.0.0 → euler_train-2.1.0}/euler_train.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: euler-train
-Version: 2.0.0
+Version: 2.1.0
 Summary: Lightweight file-based experiment logger for PyTorch
 Requires-Python: >=3.9
 Requires-Dist: numpy

{euler_train-2.0.0 → euler_train-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "euler-train"
-version = "2.0.0"
+version = "2.1.0"
 description = "Lightweight file-based experiment logger for PyTorch"
 requires-python = ">=3.9"
 dependencies = ["numpy", "euler-dataset-contract"]

{euler_train-2.0.0 → euler_train-2.1.0}/tests/test_runlog.py

@@ -1168,6 +1168,61 @@ class TestSaveOutputsOverrides:
         run.finish()
 
 
+class TestSaveOutputsVisualization:
+    def test_fixed_range_visualization_for_single_channel_png(self, tmp_path):
+        run = euler_train.init(
+            dir=str(tmp_path / "r"),
+            config={},
+            output_visualization={
+                "depth": {"mode": "fixed_range", "vmin": 0.0, "vmax": 10.0},
+            },
+        )
+        depth = np.linspace(0.0, 10.0, 16, dtype=np.float32).reshape(4, 4, 1)
+        run.save_outputs(epoch=0, step=0, depth=dict(pred=depth))
+
+        f = list((run.dir / "outputs" / "epoch_0_step_0" / "depth" / "pred").iterdir())[0]
+        img = np.array(Image.open(f))
+        assert f.suffix == ".png"
+        assert img.min() == 0
+        assert img.max() == 255
+        run.finish()
+
+    def test_visualization_override_specific_dotted_key(self, tmp_path):
+        run = euler_train.init(
+            dir=str(tmp_path / "r"),
+            config={},
+            output_visualization={
+                "depth.pred": {"mode": "fixed_range", "vmin": 5.0, "vmax": 15.0},
+            },
+        )
+        depth = np.linspace(5.0, 15.0, 16, dtype=np.float32).reshape(4, 4, 1)
+        run.save_outputs(epoch=0, step=0, depth=dict(pred=depth, gt=depth))
+
+        base = run.dir / "outputs" / "epoch_0_step_0" / "depth"
+        pred_f = list((base / "pred").iterdir())[0]
+        gt_f = list((base / "gt").iterdir())[0]
+        pred_img = np.array(Image.open(pred_f))
+        gt_img = np.array(Image.open(gt_f))
+        assert pred_img.min() == 0
+        assert pred_img.max() == 255
+        assert gt_img.min() == 255
+        assert gt_img.max() == 255
+        run.finish()
+
+    def test_torch_bfloat16_single_channel_png_promoted_to_float32(self, tmp_path):
+        run = euler_train.init(dir=str(tmp_path / "r"), config={})
+        t = torch.linspace(0, 1, steps=16, dtype=torch.bfloat16).reshape(4, 4, 1)
+        run.save_outputs(epoch=0, step=0, confidence=dict(pred=t))
+
+        f = list((run.dir / "outputs" / "epoch_0_step_0" / "confidence" / "pred").iterdir())[0]
+        img = np.array(Image.open(f))
+        assert f.suffix == ".png"
+        assert img.dtype == np.uint8
+        assert img.min() == 0
+        assert img.max() >= 254
+        run.finish()
+
+
 # ═══════════════════════════════════════════════════════════════════════════
 #  save_outputs  — batches, lists, aux, PIL, torch
 # ═══════════════════════════════════════════════════════════════════════════