euler-loading 2.4.0__tar.gz → 2.6.0__tar.gz

{euler_loading-2.4.0 → euler_loading-2.6.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: euler-loading
-Version: 2.4.0
+Version: 2.6.0
 Summary: Multi-modal PyTorch dataloader using ds-crawler indices
 Requires-Python: >=3.9
-Requires-Dist: ds-crawler
+Requires-Dist: ds-crawler>=2.3.0
 Requires-Dist: euler-dataset-contract
 Requires-Dist: numpy
 Requires-Dist: pillow

euler_loading-2.6.0/docs/loader-attributes.md

@@ -0,0 +1,183 @@
+# Design note: passing per-file `attributes` to loaders
+
+Status: **implemented**
+
+This is a follow-up to the per-file `attributes` field added in
+ds-crawler (`file_entry["attributes"]`) and surfaced on samples in
+euler-loading (`sample["attributes"][modality]` and
+`sample["meta"][modality]["attributes"]`).
+
+That change persists arbitrary per-file metadata through the index
+schema and exposes it on the loaded sample. Loader callables can now opt
+in to receiving the per-file dict by accepting an `attributes=` keyword.
+Legacy loaders that accept only `(path, meta)` keep receiving the old
+call shape.
+
+## When this matters
+
+Cases where the loader genuinely needs `attributes` rather than the
+consumer reading it post-hoc on the sample:
+
+- Per-file noise level / scale that must be applied during decode
+  (e.g. depth scale-to-meters that varies per scan).
+- Per-file masks / clip ranges for normalization.
+- Per-file lookup keys that select an external resource (e.g. a
+  per-file calibration tag pointing into a calibration database).
+- Anything where the value can't be reconstructed once the file is
+  decoded into a tensor.
+
+If `attributes` is purely descriptive (training weight, source tag,
+log fields), keep it on `sample["attributes"][...]` and don't change
+loader signatures.
+
+## Loader signature
+
+`euler_loading/loaders/contracts.py`:
+
+```python
+def rgb(
+    self,
+    path: str | BinaryIO,
+    meta: dict[str, Any] | None = None,
+    *,
+    attributes: dict[str, Any] | None = None,
+) -> torch.Tensor: ...
+```
+
+Implemented behavior:
+
+- `dataset.py` probes each resolved loader once with `inspect.signature`
+  and caches whether it accepts `attributes` or `**kwargs`.
+- Compatible loaders receive a copied per-file attributes dict (or
+  `None` when the file entry has no attributes).
+- Legacy loaders that do not accept the keyword receive the original
+  `(path, meta)` call.
+- Hierarchical-modality cache keys include the attributes payload for
+  opted-in loaders, so the same path with different attributes can be
+  decoded differently.
+- Built-in CPU/GPU loaders accept `attributes=None`. Most ignore it;
+  `generic_dense_depth.depth` consumes
+  `attributes["scale_to_meters_override"]` when present.
+
+### Rejected alternative: merge into `meta`
+
+Extend `meta` from "modality-level meta" to "merged meta" — keep the
+original keys plus a reserved `meta["__attributes__"]` (or
+`meta["entry"]`) sub-dict. No signature change.
+
+Pros: no signature change, no probe.
+Cons: namespace collision risk; loaders parsing `meta` in surprising
+ways may misinterpret the new key. Hides the source of each field.
+Harder to type. Implicit contract.
+
+### Rejected alternative: pass the full file entry
+
+Replace `meta` with the file entry dict (carrying `attributes`,
+`path_properties`, etc.). Strictly more information, but breaks every
+existing loader.
+
+Pros: maximum flexibility.
+Cons: gratuitous churn, explicit migration of every loader.
+
+## Implementation notes
+
+### 1. Update contracts
+
+```python
+# euler_loading/loaders/contracts.py
+class DenseDepthLoader(Protocol):
+    def rgb(
+        self,
+        path: Union[str, BinaryIO],
+        meta: dict[str, Any] | None = None,
+        *,
+        attributes: dict[str, Any] | None = None,
+    ) -> torch.Tensor: ...
+    # ... and parallel updates to depth / sky_mask / read_intrinsics ...
+```
+
+### 2. Loader feature probe
+
+The utility that identifies whether each loader accepts the
+`attributes` kwarg:
+
+```python
+# euler_loading/_resolution.py
+import inspect
+
+def loader_accepts_attributes(loader: Callable[..., Any]) -> bool:
+    try:
+        sig = inspect.signature(loader)
+    except (TypeError, ValueError):
+        return False
+    params = sig.parameters
+    if "attributes" in params:
+        return True
+    return any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
+    )
+```
+
+Cache the result on the resolved-loaders dict at construction time so
+the probe runs once per modality.
+
+### 3. Update call sites
+
+In `MultiModalDataset.__getitem__`:
+
+```python
+loader = self._resolved_loaders[name]
+file_attrs = _get_file_attributes(record.file_entry)
+if self._loaders_accept_attributes[name]:
+    sample[name] = loader(file_or_path, modality_meta, attributes=file_attrs)
+else:
+    sample[name] = loader(file_or_path, modality_meta)
+```
+
+The hierarchical-modality branch follows the same rule. For opted-in
+loaders, the hierarchical cache key includes a serialized attributes
+fragment so identical paths with different per-file attributes are
+loaded independently.
+
+### 4. Update built-in loaders
+
+For each module under `euler_loading/loaders/{cpu,gpu}/`, every `read_*`
+and modality function accepts `*, attributes: ... = None`. Most ignore
+it. `generic_dense_depth.depth` consumes
+`attributes.get("scale_to_meters_override")`.
+
+### 5. Tests
+
+Mirror the existing `tests/test_writing.py` and
+`tests/test_dataset.py` structure. Minimum coverage:
+
+- A loader that accepts `attributes=` receives the per-file dict.
+- A loader that doesn't is called with the legacy 2-arg form (no
+  `TypeError`).
+- A loader with `**kwargs` is treated as accepting attributes.
+- Hierarchical-modality cache: same hierarchical file with two different
+  attributes loads twice.
+- Round-trip: file entry attributes → loader receives them → if the
+  loader passes them through, they appear on `sample["attributes"]`
+  (already the case post the existing change, but pin it).
+
+## Backwards compatibility
+
+- Stability of the existing 2-arg signature is preserved by feature
+  probing. Loaders that never opt in keep working forever.
+- The `attributes` argument is keyword-only — no position collision.
+- `sample["attributes"]` and `sample["meta"][name]["attributes"]`
+  surfaces are unchanged by this work; they already exist.
+
+## Open questions for the implementer
+
+1. Should the feature probe also be done for *writers*? Today writers
+   take `(path, value, meta)`. If we want symmetry, writers gain
+   `attributes=` too. Same Option 1 treatment.
+2. Should `loader_accepts_attributes` look at the function's
+   `__wrapped__` chain to handle `functools.wraps`-decorated loaders?
+   (Probably yes, but only if a real case appears.)
+3. Worth adding a `FileContext` dataclass — `(meta, attributes,
+   file_entry)` — to consolidate future fields rather than growing kwargs
+   one at a time? Defer this until we have a second per-file thing to
+   add; one new field doesn't justify a wrapper type.

{euler_loading-2.4.0 → euler_loading-2.6.0}/euler_loading/_resolution.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import importlib
+import inspect
 import logging
 from collections.abc import Mapping
 from types import ModuleType
@@ -68,6 +69,32 @@ def resolve_writer_module(name: str) -> ModuleType:
     return resolve_loader_module(name)
 
 
+def loader_accepts_attributes(loader: Callable[..., Any]) -> bool:
+    """Return whether *loader* can accept an ``attributes=`` keyword.
+
+    Loaders historically accepted ``(path, meta=None)``.  Per-file
+    attributes are opt-in so legacy loaders keep receiving the old call
+    shape, while loaders declaring ``attributes`` or ``**kwargs`` receive
+    the new context.
+    """
+    try:
+        signature = inspect.signature(loader)
+    except (TypeError, ValueError):
+        return False
+
+    attributes_param = signature.parameters.get("attributes")
+    if (
+        attributes_param is not None
+        and attributes_param.kind is not inspect.Parameter.POSITIONAL_ONLY
+    ):
+        return True
+
+    return any(
+        param.kind is inspect.Parameter.VAR_KEYWORD
+        for param in signature.parameters.values()
+    )
+
+
 def _resolve_loader(
     *,
     modality_name: str,

{euler_loading-2.4.0 → euler_loading-2.6.0}/euler_loading/_writing.py

@@ -244,15 +244,29 @@ def _write_value_to_destination(
     full_id: str,
     basename: str,
     relative_path: str,
-    source_meta: Mapping[str, Any] | None,
+    source_entry: Mapping[str, Any] | None,
+    entry_attributes: Mapping[str, Any] | None = None,
     create_dirs: bool,
 ) -> str:
+    """Write *value* to the destination and (when applicable) record a
+    ds-crawler file entry.
+
+    ``meta`` is the modality-level metadata passed to the loader/writer
+    callable.  ``entry_attributes`` is the per-file ``attributes`` dict
+    written onto the ds-crawler file entry; it is a no-op for plain
+    filesystem destinations (no index to record into).
+    """
+    entry_attributes_dict = (
+        dict(entry_attributes) if entry_attributes is not None else None
+    )
+
     if isinstance(destination, ZipDatasetWriter):
         if supports_stream_target(writer):
             with destination.open(
                 full_id,
                 basename,
-                source_meta=dict(source_meta or {}),
+                source_entry=dict(source_entry or {}),
+                attributes=entry_attributes_dict,
             ) as stream:
                 _set_stream_name(stream, basename)
                 writer(stream, value, meta)
@@ -264,7 +278,8 @@ def _write_value_to_destination(
                     full_id,
                     basename,
                     temp_path.read_bytes(),
-                    source_meta=dict(source_meta or {}),
+                    source_entry=dict(source_entry or {}),
+                    attributes=entry_attributes_dict,
                 )
         _register_destination_rel_path(destination, relative_path)
         return _destination_location(destination, relative_path)
@@ -273,12 +288,21 @@ def _write_value_to_destination(
         target_path = destination.get_path(
             full_id,
             basename,
-            source_meta=dict(source_meta or {}),
+            source_entry=dict(source_entry or {}),
+            attributes=entry_attributes_dict,
         )
         writer(str(target_path), value, meta)
         _register_destination_rel_path(destination, relative_path)
         return str(target_path)
 
+    if entry_attributes_dict:
+        logger.debug(
+            "Filesystem destination %s has no index — entry attributes "
+            "for %s will not be persisted.",
+            destination,
+            relative_path,
+        )
+
     target_path = Path(destination) / relative_path
     if create_dirs:
         target_path.parent.mkdir(parents=True, exist_ok=True)

{euler_loading-2.4.0 → euler_loading-2.6.0}/euler_loading/dataset.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import io
+import json
 import logging
 import os
 from pathlib import Path
@@ -29,6 +30,7 @@ from ._metadata import _build_runlog_entry, _get_ds_crawler_descriptor
 from ._resolution import (
     _resolve_loader,
     _resolve_writer,
+    loader_accepts_attributes,
     resolve_loader_module,
     resolve_writer_module,
 )
@@ -118,6 +120,33 @@ def _get_index_meta(index_output: Mapping[str, Any]) -> dict[str, Any] | None:
     return None
 
 
+def _get_file_attributes(file_entry: Mapping[str, Any]) -> dict[str, Any] | None:
+    attributes = file_entry.get("attributes")
+    if isinstance(attributes, Mapping):
+        return dict(attributes)
+    return None
+
+
+def _attributes_cache_key(attributes: Mapping[str, Any] | None) -> str:
+    if attributes is None:
+        return "null"
+    return json.dumps(attributes, sort_keys=True, separators=(",", ":"), default=repr)
+
+
+def _load_with_optional_attributes(
+    loader: Callable[..., Any],
+    file_or_path: Any,
+    meta: dict[str, Any] | None,
+    attributes: dict[str, Any] | None,
+    *,
+    accepts_attributes: bool,
+) -> Any:
+    if accepts_attributes:
+        loader_attributes = dict(attributes) if attributes is not None else None
+        return loader(file_or_path, meta, attributes=loader_attributes)
+    return loader(file_or_path, meta)
+
+
 def _extract_id_schema(index_output: Mapping[str, Any]) -> dict[str, Any]:
     """Pull id/hierarchy separators from a ds-crawler output payload.
 
@@ -394,6 +423,7 @@ class MultiModalDataset(_BaseDataset):
         # -- Index each modality and build ID → FileRecord lookups -----------
         self._lookups: dict[str, dict[str, FileRecord]] = {}
         self._resolved_loaders: dict[str, Callable[..., Any]] = {}
+        self._loaders_accept_attributes: dict[str, bool] = {}
         self._resolved_writers: dict[str, Callable[..., Any] | None] = {}
 
         for name, modality in modalities.items():
@@ -406,6 +436,9 @@ class MultiModalDataset(_BaseDataset):
             self._resolved_loaders[name] = _resolve_loader(
                 modality_name=name, modality=modality, index=index,
             )
+            self._loaders_accept_attributes[name] = loader_accepts_attributes(
+                self._resolved_loaders[name]
+            )
             self._resolved_writers[name] = _resolve_writer(
                 modality_name=name, modality=modality, index=index,
             )
@@ -438,6 +471,9 @@ class MultiModalDataset(_BaseDataset):
             self._resolved_loaders[name] = _resolve_loader(
                 modality_name=name, modality=modality, index=index,
             )
+            self._loaders_accept_attributes[name] = loader_accepts_attributes(
+                self._resolved_loaders[name]
+            )
             self._resolved_writers[name] = _resolve_writer(
                 modality_name=name, modality=modality, index=index,
             )
@@ -623,6 +659,7 @@ class MultiModalDataset(_BaseDataset):
         *,
         create_dirs: bool = True,
         overwrite: bool = True,
+        attributes: Mapping[str, Mapping[str, Any]] | None = None,
     ) -> dict[str, str]:
         """Write model outputs for one sample to disk or a dataset writer.
 
@@ -640,6 +677,13 @@ class MultiModalDataset(_BaseDataset):
                 filesystem destinations.
             overwrite: If false, raise when a target file already exists or a
                 duplicate writer entry would be created.
+            attributes: Optional per-modality ``{modality: {key: value}}``
+                mapping recorded on the destination's ds-crawler file
+                entry under the ``"attributes"`` field.  Only applies when
+                the destination is a :class:`DatasetWriter` /
+                :class:`ZipDatasetWriter`; ignored for plain filesystem
+                paths.  When omitted, any ``attributes`` carried on the
+                source file entry is inherited.
 
         Returns:
             Mapping ``{modality_name: written_location}``. For filesystem
@@ -677,6 +721,9 @@ class MultiModalDataset(_BaseDataset):
             if _destination_rel_exists(destination, relative_path) and not overwrite:
                 raise FileExistsError(_destination_location(destination, relative_path))
 
+            per_modality_attrs = (
+                attributes.get(modality_name) if attributes is not None else None
+            )
             written_paths[modality_name] = _write_value_to_destination(
                 destination=destination,
                 writer=writer,
@@ -685,7 +732,8 @@ class MultiModalDataset(_BaseDataset):
                 full_id=full_id,
                 basename=basename,
                 relative_path=relative_path,
-                source_meta=record.file_entry,
+                source_entry=record.file_entry,
+                entry_attributes=per_modality_attrs,
                 create_dirs=create_dirs,
             )
 
@@ -764,6 +812,7 @@ class MultiModalDataset(_BaseDataset):
         sample: dict[str, Any] = {}
 
         meta: dict[str, dict[str, Any]] = {}
+        attributes: dict[str, dict[str, Any]] = {}
         file_id: str = ""
         hierarchy_path: tuple[str, ...] = ()
 
@@ -778,8 +827,16 @@ class MultiModalDataset(_BaseDataset):
             else:
                 file_or_path = f"{modality.path}/{record.file_entry['path']}"
 
-            sample[name] = self._resolved_loaders[name](file_or_path, modality_meta)
+            entry_attributes = _get_file_attributes(record.file_entry)
+            sample[name] = _load_with_optional_attributes(
+                self._resolved_loaders[name],
+                file_or_path,
+                modality_meta,
+                entry_attributes,
+                accepts_attributes=self._loaders_accept_attributes[name],
+            )
             meta[name] = record.file_entry
+            attributes[name] = entry_attributes or {}
 
             # Hierarchy path from the first modality that has one.
             if not hierarchy_path:
@@ -792,24 +849,40 @@ class MultiModalDataset(_BaseDataset):
             matched = match_hierarchical_files(hierarchy_path, files_by_level)
             modality_meta = _get_index_meta(self._hierarchical_index_outputs[name])
             loaded: dict[str, Any] = {}
+            attrs_for_modality: dict[str, dict[str, Any]] = {}
             for entry in matched:
+                entry_attributes = _get_file_attributes(entry)
                 cache_key = f"{modality.path}/{entry['path']}"
+                accepts_attributes = self._loaders_accept_attributes[name]
+                if accepts_attributes:
+                    cache_key = (
+                        f"{cache_key}::attributes="
+                        f"{_attributes_cache_key(entry_attributes)}"
+                    )
                 if cache_key not in self._hierarchical_cache:
                     if name in self._zip_modalities:
                         file_or_path = self._open_from_zip(
                             name, modality.path, entry["path"],
                         )
                     else:
-                        file_or_path = cache_key
-                    self._hierarchical_cache[cache_key] = self._resolved_loaders[name](
-                        file_or_path, modality_meta
+                        file_or_path = f"{modality.path}/{entry['path']}"
+                    self._hierarchical_cache[cache_key] = _load_with_optional_attributes(
+                        self._resolved_loaders[name],
+                        file_or_path,
+                        modality_meta,
+                        entry_attributes,
+                        accepts_attributes=accepts_attributes,
                     )
                 loaded[entry["id"]] = self._hierarchical_cache[cache_key]
+                if entry_attributes:
+                    attrs_for_modality[entry["id"]] = entry_attributes
             sample[name] = loaded
+            attributes[name] = attrs_for_modality
 
         sample["id"] = file_id
         sample["full_id"] = "/" + "/".join(hierarchy_path + (file_id,))
         sample["meta"] = meta
+        sample["attributes"] = attributes
 
         for transform in self._transforms:
             sample = transform(sample)

{euler_loading-2.4.0 → euler_loading-2.6.0}/euler_loading/loaders/contracts.py

@@ -23,8 +23,8 @@ class DenseDepthLoader(Protocol):
     """Contract for dense-depth dataset loaders.
 
     A conforming module must expose the following callables, each accepting
-    a file path and an optional ``meta`` dict, and returning a
-    ``torch.Tensor``:
+    a file path, an optional modality-level ``meta`` dict, and optional
+    per-file ``attributes`` keyword, and returning a ``torch.Tensor``:
 
     - **rgb** – ``(3, H, W)`` float32 in ``[0, 1]``
     - **depth** – ``(1, H, W)`` float32 in metres
@@ -32,10 +32,10 @@ class DenseDepthLoader(Protocol):
     - **read_intrinsics** – ``(3, 3)`` float32 camera matrix *K*
     """
 
-    def rgb(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -> torch.Tensor: ...
-    def depth(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -> torch.Tensor: ...
-    def sky_mask(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -> torch.Tensor: ...
-    def read_intrinsics(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -> torch.Tensor: ...
+    def rgb(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> torch.Tensor: ...
+    def depth(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> torch.Tensor: ...
+    def sky_mask(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> torch.Tensor: ...
+    def read_intrinsics(self, path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> torch.Tensor: ...
 
 
 @runtime_checkable

{euler_loading-2.4.0 → euler_loading-2.6.0}/euler_loading/loaders/cpu/generic.py

@@ -10,6 +10,8 @@ Supported file extensions:
 
 Return types
 ------------
+- **map_2d** / **scattering_coefficient** -- ``np.ndarray`` of shape ``(H, W)`` float32.
+- **map_3d** / **atmospheric_light** -- ``np.ndarray`` of shape ``(H, W, C)`` float32.
 - **spherical_map** -- ``np.ndarray`` of shape ``(H, W, C)`` float32.
 - **intrinsics** -- ``np.ndarray`` of shape ``(3, 3)`` float32.
 - **sh_coeffs** -- ``np.ndarray`` of shape ``(N, 3)`` float32.
@@ -19,9 +21,11 @@ Usage::
     from euler_loading.loaders.cpu import generic
     from euler_loading import Modality
 
-    Modality("/data/my_dataset/spherical_map", loader=generic.spherical_map)
-    Modality("/data/my_dataset/intrinsics", loader=generic.intrinsics)
-    Modality("/data/my_dataset/sh_coeffs", loader=generic.sh_coeffs)
+    Modality("/data/my_dataset/scattering_coefficient", loader=generic.scattering_coefficient)
+    Modality("/data/my_dataset/atmospheric_light",      loader=generic.atmospheric_light)
+    Modality("/data/my_dataset/spherical_map",          loader=generic.spherical_map)
+    Modality("/data/my_dataset/intrinsics",             loader=generic.intrinsics)
+    Modality("/data/my_dataset/sh_coeffs",              loader=generic.sh_coeffs)
 """
 
 from __future__ import annotations
@@ -36,6 +40,7 @@ from euler_loading.loaders._writer_utils import (
     ensure_parent,
     get_target_name,
     mark_stream_supported,
+    to_hw,
     to_numpy,
 )
 
@@ -85,13 +90,69 @@ def _write_numpy(path: Union[str, BinaryIO], value: Any) -> None:
 # ---------------------------------------------------------------------------
 
 
+@modality_meta(
+    modality_type="map_2d",
+    dtype="float32",
+    shape="HW",
+    file_formats=[".npy", ".npz"],
+)
+def map_2d(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> np.ndarray:
+    """Load an arbitrary 2D map as an ``(H, W)`` float32 array.
+
+    Suitable for any single-channel dense quantity (e.g. scattering
+    coefficient, attenuation, opacity) where no dataset-specific decoding
+    is required.
+    """
+    return _load_numpy(path)
+
+
+@modality_meta(
+    modality_type="map_3d",
+    dtype="float32",
+    shape="HWC",
+    file_formats=[".npy", ".npz"],
+)
+def map_3d(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> np.ndarray:
+    """Load an arbitrary 3D map as an ``(H, W, C)`` float32 array.
+
+    The file is expected to be stored in ``(C, H, W)`` layout and is
+    transposed to ``(H, W, C)`` for CPU-oriented processing.  Suitable
+    for any per-pixel vector quantity (e.g. atmospheric light, surface
+    normals, flow).
+    """
+    arr = _load_numpy(path)
+    return np.transpose(arr, (1, 2, 0))
+
+
+@modality_meta(
+    modality_type="scattering_coefficient",
+    dtype="float32",
+    shape="HW",
+    file_formats=[".npy", ".npz"],
+)
+def scattering_coefficient(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> np.ndarray:
+    """Load a scattering-coefficient map as an ``(H, W)`` float32 array."""
+    return map_2d(path, meta)
+
+
+@modality_meta(
+    modality_type="atmospheric_light",
+    dtype="float32",
+    shape="HWC",
+    file_formats=[".npy", ".npz"],
+)
+def atmospheric_light(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> np.ndarray:
+    """Load an atmospheric-light map as an ``(H, W, C)`` float32 array."""
+    return map_3d(path, meta)
+
+
 @modality_meta(
     modality_type="spherical_map",
     dtype="float32",
     shape="HWC",
     file_formats=[".npy", ".npz"],
 )
-def spherical_map(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -> np.ndarray:
+def spherical_map(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> np.ndarray:
     """Load a spherical map as an ``(H, W, C)`` float32 array.
 
     The file is expected to be stored in ``(C, H, W)`` layout and is
@@ -112,7 +173,7 @@ def spherical_map(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None
     shape="3x3",
     file_formats=[".npy", ".npz"],
 )
-def intrinsics(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -> np.ndarray:
+def intrinsics(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> np.ndarray:
     """Load a camera intrinsics matrix as a ``(3, 3)`` float32 array.
 
     The file is expected to contain a ``(3, 3)`` array::
@@ -130,7 +191,7 @@ def intrinsics(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -
     shape="NC",
     file_formats=[".npy", ".npz"],
 )
-def sh_coeffs(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) -> np.ndarray:
+def sh_coeffs(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None, *, attributes: dict[str, Any] | None = None) -> np.ndarray:
     """Load spherical-harmonic coefficients as an ``(N, 3)`` float32 array.
 
     *N* is the number of SH basis functions (e.g. 15 for degree-3 SH with
@@ -145,6 +206,51 @@ def sh_coeffs(path: Union[str, BinaryIO], meta: dict[str, Any] | None = None) ->
 # ---------------------------------------------------------------------------
 
 
+@mark_stream_supported
+def write_map_2d(path: Union[str, BinaryIO], value: Any, meta: dict[str, Any] | None = None) -> None:
+    """Write a 2D map to NumPy formats based on extension.
+
+    Accepts ``(H, W)``, ``(1, H, W)``, or ``(H, W, 1)`` input and stores
+    the array in ``(H, W)`` layout.
+    """
+    arr = to_hw(value, name="map_2d")
+    _write_numpy(path, arr)
+
+
+@mark_stream_supported
+def write_map_3d(path: Union[str, BinaryIO], value: Any, meta: dict[str, Any] | None = None) -> None:
+    """Write a 3D map to NumPy formats based on extension.
+
+    Input is expected in ``(H, W, C)`` layout and is transposed to
+    ``(C, H, W)`` for storage.
+    """
+    ensure_parent(path)
+    ext = os.path.splitext(_get_name(path))[1].lower()
+    arr = to_numpy(value).astype(np.float32)
+    arr = np.transpose(arr, (2, 0, 1))
+
+    if ext == _NPY_EXTENSION:
+        np.save(path, arr)
+        return
+    if ext == _NPZ_EXTENSION:
+        np.savez_compressed(path, data=arr)
+        return
+
+    raise ValueError(f"Unsupported map_3d output extension: {ext}")
+
+
+@mark_stream_supported
+def write_scattering_coefficient(path: Union[str, BinaryIO], value: Any, meta: dict[str, Any] | None = None) -> None:
+    """Write a scattering-coefficient map (delegates to :func:`write_map_2d`)."""
+    write_map_2d(path, value, meta)
+
+
+@mark_stream_supported
+def write_atmospheric_light(path: Union[str, BinaryIO], value: Any, meta: dict[str, Any] | None = None) -> None:
+    """Write an atmospheric-light map (delegates to :func:`write_map_3d`)."""
+    write_map_3d(path, value, meta)
+
+
 @mark_stream_supported
 def write_spherical_map(path: Union[str, BinaryIO], value: Any, meta: dict[str, Any] | None = None) -> None:
     """Write spherical-map data to NumPy formats based on extension.