iivs-lib 0.1.0__tar.gz

iivs_lib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaewoo Park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iivs_lib-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: iivs-lib
+Version: 0.1.0
+Summary: A Python toolkit for multi-modal holographic systems and cellular analysis.
+Keywords: 
+Author: Jaewoo Park
+Author-email: Jaewoo Park <kaparoo2001@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Dist: kaparoo-python>=0.7.0
+Requires-Dist: natsort>=8.4.0
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: tifffile>=2026.6.1
+Requires-Dist: imagecodecs>=2026.5.10 ; extra == 'image'
+Requires-Dist: torch>=2.6 ; extra == 'torch'
+Requires-Python: >=3.14
+Project-URL: GitHub, https://www.github.com/iivs-lab/iivs-lib
+Provides-Extra: image
+Provides-Extra: torch
+Description-Content-Type: text/markdown
+
+# iivs-lib
+
+[![PyPI version](https://img.shields.io/pypi/v/iivs-lib.svg)](https://pypi.org/project/iivs-lib/)
+[![Downloads](https://pepy.tech/badge/iivs-lib)](https://pypi.org/project/iivs-lib/)
+[![Python](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)
+
+*A Python toolkit for multi-modal holographic systems and cellular analysis.*
+
+## 📦 Installation
+
+Requires Python 3.14+.
+
+```bash
+# With uv (recommended)
+uv add iivs-lib
+
+# With pip
+pip install iivs-lib
+```
+
+The `[image]` extra adds `imagecodecs`, needed only to decode the
+LZW-compressed Koala `Image/*.tif` uint8 previews (`uv add "iivs-lib[image]"`).
+The `[torch]` extra adds PyTorch for `iivs.dhm.analysis.pytorch` — tensor-in /
+tensor-out OPD / dry-mass twins with autograd (`uv add "iivs-lib[torch]"`).
+
+## 🚀 Quick start
+
+```python
+from iivs.dhm.data.phase import PhaseBinFolder, PhaseUnit
+from iivs.dhm.analysis import DryMassCalculator
+
+# Lazily open a phase acquisition (a folder of numbered .bin frames).
+phase = PhaseBinFolder("scan/Phase/Float/Bin", target_unit=PhaseUnit.RADIANS)
+phase.frame_shape          # (H, W), shared across frames
+img = phase[0]             # first frame as a float32 array (decoded on access)
+
+# Per-frame dry mass over a segmented cell:
+calc = DryMassCalculator(pixel_size=phase.header.pixel_size)
+mass_pg = calc.calc_from_phase(img, mask=cell_mask)
+```
+
+## 🧩 Modules
+
+Each package ships a detailed README in the source tree — the endpoints,
+examples, and the inherited sequence interface:
+[`hologram`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data/hologram),
+[`phase`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data/phase),
+[`intensity`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data/intensity),
+[`data`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data) (overview
+and `timestamp`),
+[`analysis`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/analysis).
+
+### `iivs.dhm.data`
+
+Readers, writers, and lazy sequences for Lyncée Tec Koala acquisition data
+(validated end-to-end against a real Koala acquisition — every format, the
+sequences, and the round trips between them).
+
+- **`hologram`** — uint8 holograms: `.tif` via `load_hologram_tif` /
+  `save_hologram_tif` with `HologramTifFolder` / `HologramTifList`; a single
+  multi-frame `.raw` via `HologramRawFile` (a lazy `np.memmap`) and
+  `read_hologram_raw_header`; header-less `.npy` frames via `HologramNpyFolder`.
+- **`phase`** — float32 `.bin` phase images: `load_phase_bin` /
+  `save_phase_bin` / `read_phase_bin_header`, the typed `PhaseBinHeader` and
+  `PhaseUnit`, and `convert_phase_unit`; folder/list sequences
+  `PhaseBinFolder` / `PhaseBinList`. The same quantitative phase from Koala's
+  `Float/Txt` export via `load_phase_txt`, `PhaseTxtFolder` / `PhaseTxtList`.
+  The uint8 `Image/*.tif` display previews (not quantitative) via
+  `PhaseTifFolder` / `PhaseTifList`. Header-less `.npy` frames via
+  `PhaseNpyFolder` (`pixel_size` / `unit` / `height_scale` passed to the
+  constructor; `numpy.load`, pickle disabled).
+- **`intensity`** — float32 `.bin` intensity reconstructions (exported
+  alongside phase): `load_intensity_bin` / `save_intensity_bin` /
+  `read_intensity_bin_header`, the typed `IntensityBinHeader`, and folder/list
+  sequences `IntensityBinFolder` / `IntensityBinList`; plus the `Float/Txt`
+  twins `load_intensity_txt`, `IntensityTxtFolder` / `IntensityTxtList`, the
+  uint8 `Image/*.tif` previews `IntensityTifFolder` / `IntensityTifList`, and
+  header-less `.npy` frames via `IntensityNpyFolder` (`pixel_size` passed in).
+  The phase and intensity `.bin` formats share the `common.KoalaBinHeader` base.
+- **`timestamp`** — per-frame acquisition timing: the `Timestamp` record,
+  `TimestampsTxtFile` (Koala `timestamps.txt`), and `TimestampsFixedFPS`
+  (synthesized from a frame rate).
+
+Every sequence is a `kaparoo.data.sequences.DataSequence`, so it indexes,
+slices, and iterates lazily; same-shape sources also expose `frame_shape` by
+mixing in `common.FrameShapedMixin` (so a uniform source is its
+`<Modality>FloatSequence` / `<Modality>ImageSequence` plus that mixin). For
+phase and intensity the quantitative float32 sources are
+`<Modality>FloatSequence` and the uint8 `Image/*.tif` previews are
+`<Modality>ImageSequence`, both under the `<Modality>Sequence` base.
+Numbered-folder sequences share the `common.SequentialFileFolder`
+discovery/validation base, and validate their arrays via
+`common.validate_float32_image` / `validate_uint8_image`. These cross-modality
+building blocks live in `iivs.dhm.data.common`.
+
+### `iivs.dhm.analysis`
+
+Physical quantities derived from phase, each via an engine object that
+precomputes its conversion factor (with one-shot function conveniences):
+
+- **`opd`** — optical path difference (`OPD = phase * wavelength / (2*pi)`, in
+  nm). `OPDConverter` (`convert_to_opd` / `convert_to_phase`, scale
+  `opd_scale`); `phase_to_opd` / `opd_to_phase`.
+- **`drymass`** — dry mass (pg) via the Barer relation. `DryMassCalculator`
+  (`calc_from_opd` / `calc_from_phase` over a background-corrected, optionally
+  masked map; scale `drymass_scale`); `calc_drymass` / `calc_drymass_from_phase`.
+
+#### Using with PyTorch (autograd)
+
+The `convert_*` / `calc_*` methods operate on NumPy arrays. Install the
+`iivs-lib[torch]` extra for `iivs.dhm.analysis.pytorch` — tensor-in / tensor-out
+twins that keep the input tensor's device, dtype, and autograd graph (the
+calibration scalars are shared with the NumPy engines):
+
+```python
+from iivs.dhm.analysis.pytorch.opd import phase_to_opd
+from iivs.dhm.analysis.pytorch.drymass import calc_drymass_from_phase
+
+opd = phase_to_opd(phase, wavelength=666e-9)                    # Tensor (CPU/GPU), grad kept
+mass = calc_drymass_from_phase(phase, pixel_size=px, mask=cell) # 0-dim Tensor, grad kept
+```
+
+Or, without the dependency, multiply by the cached scale factors (plain floats)
+with native ops yourself:
+
+```python
+opd = phase * conv.opd_scale                  # phase: Tensor -> OPD (nm), grad kept
+mass = opd[mask].sum() * calc.drymass_scale   # OPD -> dry mass (pg), grad kept
+```
+
+## 📋 TODO
+
+See [TODO.md](./TODO.md) for tracked open items.
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for the version history.
+
+## 🙏 Acknowledgements
+
+The Koala file formats read and written by `iivs.dhm.data` originate from
+[Lyncée Tec](https://www.lynceetec.com/)'s Koala software. The phase `.bin`
+format was cross-checked against their reference implementation,
+[`pyKoalaUtils`](https://github.com/lynceetec/pyKoalaUtils) (MIT). iivs-lib is
+an independent reimplementation and contains no code from it.
+
+## ⚖️ License
+
+This project is distributed under the terms of the [MIT](./LICENSE) license.

iivs_lib-0.1.0/README.md

@@ -0,0 +1,154 @@
+# iivs-lib
+
+[![PyPI version](https://img.shields.io/pypi/v/iivs-lib.svg)](https://pypi.org/project/iivs-lib/)
+[![Downloads](https://pepy.tech/badge/iivs-lib)](https://pypi.org/project/iivs-lib/)
+[![Python](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)
+
+*A Python toolkit for multi-modal holographic systems and cellular analysis.*
+
+## 📦 Installation
+
+Requires Python 3.14+.
+
+```bash
+# With uv (recommended)
+uv add iivs-lib
+
+# With pip
+pip install iivs-lib
+```
+
+The `[image]` extra adds `imagecodecs`, needed only to decode the
+LZW-compressed Koala `Image/*.tif` uint8 previews (`uv add "iivs-lib[image]"`).
+The `[torch]` extra adds PyTorch for `iivs.dhm.analysis.pytorch` — tensor-in /
+tensor-out OPD / dry-mass twins with autograd (`uv add "iivs-lib[torch]"`).
+
+## 🚀 Quick start
+
+```python
+from iivs.dhm.data.phase import PhaseBinFolder, PhaseUnit
+from iivs.dhm.analysis import DryMassCalculator
+
+# Lazily open a phase acquisition (a folder of numbered .bin frames).
+phase = PhaseBinFolder("scan/Phase/Float/Bin", target_unit=PhaseUnit.RADIANS)
+phase.frame_shape          # (H, W), shared across frames
+img = phase[0]             # first frame as a float32 array (decoded on access)
+
+# Per-frame dry mass over a segmented cell:
+calc = DryMassCalculator(pixel_size=phase.header.pixel_size)
+mass_pg = calc.calc_from_phase(img, mask=cell_mask)
+```
+
+## 🧩 Modules
+
+Each package ships a detailed README in the source tree — the endpoints,
+examples, and the inherited sequence interface:
+[`hologram`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data/hologram),
+[`phase`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data/phase),
+[`intensity`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data/intensity),
+[`data`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/data) (overview
+and `timestamp`),
+[`analysis`](https://github.com/iivs-lab/iivs-lib/tree/main/iivs/dhm/analysis).
+
+### `iivs.dhm.data`
+
+Readers, writers, and lazy sequences for Lyncée Tec Koala acquisition data
+(validated end-to-end against a real Koala acquisition — every format, the
+sequences, and the round trips between them).
+
+- **`hologram`** — uint8 holograms: `.tif` via `load_hologram_tif` /
+  `save_hologram_tif` with `HologramTifFolder` / `HologramTifList`; a single
+  multi-frame `.raw` via `HologramRawFile` (a lazy `np.memmap`) and
+  `read_hologram_raw_header`; header-less `.npy` frames via `HologramNpyFolder`.
+- **`phase`** — float32 `.bin` phase images: `load_phase_bin` /
+  `save_phase_bin` / `read_phase_bin_header`, the typed `PhaseBinHeader` and
+  `PhaseUnit`, and `convert_phase_unit`; folder/list sequences
+  `PhaseBinFolder` / `PhaseBinList`. The same quantitative phase from Koala's
+  `Float/Txt` export via `load_phase_txt`, `PhaseTxtFolder` / `PhaseTxtList`.
+  The uint8 `Image/*.tif` display previews (not quantitative) via
+  `PhaseTifFolder` / `PhaseTifList`. Header-less `.npy` frames via
+  `PhaseNpyFolder` (`pixel_size` / `unit` / `height_scale` passed to the
+  constructor; `numpy.load`, pickle disabled).
+- **`intensity`** — float32 `.bin` intensity reconstructions (exported
+  alongside phase): `load_intensity_bin` / `save_intensity_bin` /
+  `read_intensity_bin_header`, the typed `IntensityBinHeader`, and folder/list
+  sequences `IntensityBinFolder` / `IntensityBinList`; plus the `Float/Txt`
+  twins `load_intensity_txt`, `IntensityTxtFolder` / `IntensityTxtList`, the
+  uint8 `Image/*.tif` previews `IntensityTifFolder` / `IntensityTifList`, and
+  header-less `.npy` frames via `IntensityNpyFolder` (`pixel_size` passed in).
+  The phase and intensity `.bin` formats share the `common.KoalaBinHeader` base.
+- **`timestamp`** — per-frame acquisition timing: the `Timestamp` record,
+  `TimestampsTxtFile` (Koala `timestamps.txt`), and `TimestampsFixedFPS`
+  (synthesized from a frame rate).
+
+Every sequence is a `kaparoo.data.sequences.DataSequence`, so it indexes,
+slices, and iterates lazily; same-shape sources also expose `frame_shape` by
+mixing in `common.FrameShapedMixin` (so a uniform source is its
+`<Modality>FloatSequence` / `<Modality>ImageSequence` plus that mixin). For
+phase and intensity the quantitative float32 sources are
+`<Modality>FloatSequence` and the uint8 `Image/*.tif` previews are
+`<Modality>ImageSequence`, both under the `<Modality>Sequence` base.
+Numbered-folder sequences share the `common.SequentialFileFolder`
+discovery/validation base, and validate their arrays via
+`common.validate_float32_image` / `validate_uint8_image`. These cross-modality
+building blocks live in `iivs.dhm.data.common`.
+
+### `iivs.dhm.analysis`
+
+Physical quantities derived from phase, each via an engine object that
+precomputes its conversion factor (with one-shot function conveniences):
+
+- **`opd`** — optical path difference (`OPD = phase * wavelength / (2*pi)`, in
+  nm). `OPDConverter` (`convert_to_opd` / `convert_to_phase`, scale
+  `opd_scale`); `phase_to_opd` / `opd_to_phase`.
+- **`drymass`** — dry mass (pg) via the Barer relation. `DryMassCalculator`
+  (`calc_from_opd` / `calc_from_phase` over a background-corrected, optionally
+  masked map; scale `drymass_scale`); `calc_drymass` / `calc_drymass_from_phase`.
+
+#### Using with PyTorch (autograd)
+
+The `convert_*` / `calc_*` methods operate on NumPy arrays. Install the
+`iivs-lib[torch]` extra for `iivs.dhm.analysis.pytorch` — tensor-in / tensor-out
+twins that keep the input tensor's device, dtype, and autograd graph (the
+calibration scalars are shared with the NumPy engines):
+
+```python
+from iivs.dhm.analysis.pytorch.opd import phase_to_opd
+from iivs.dhm.analysis.pytorch.drymass import calc_drymass_from_phase
+
+opd = phase_to_opd(phase, wavelength=666e-9)                    # Tensor (CPU/GPU), grad kept
+mass = calc_drymass_from_phase(phase, pixel_size=px, mask=cell) # 0-dim Tensor, grad kept
+```
+
+Or, without the dependency, multiply by the cached scale factors (plain floats)
+with native ops yourself:
+
+```python
+opd = phase * conv.opd_scale                  # phase: Tensor -> OPD (nm), grad kept
+mass = opd[mask].sum() * calc.drymass_scale   # OPD -> dry mass (pg), grad kept
+```
+
+## 📋 TODO
+
+See [TODO.md](./TODO.md) for tracked open items.
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for the version history.
+
+## 🙏 Acknowledgements
+
+The Koala file formats read and written by `iivs.dhm.data` originate from
+[Lyncée Tec](https://www.lynceetec.com/)'s Koala software. The phase `.bin`
+format was cross-checked against their reference implementation,
+[`pyKoalaUtils`](https://github.com/lynceetec/pyKoalaUtils) (MIT). iivs-lib is
+an independent reimplementation and contains no code from it.
+
+## ⚖️ License
+
+This project is distributed under the terms of the [MIT](./LICENSE) license.

iivs_lib-0.1.0/iivs/dhm/analysis/__init__.py

@@ -0,0 +1,24 @@
+"""Quantitative analysis derived from DHM phase data (OPD, dry mass, ...).
+
+The NumPy engines and one-shot helpers are re-exported here; the Torch twins
+live in `iivs.dhm.analysis.pytorch` (install the ``iivs-lib[torch]`` extra) and
+are *not* re-exported, so importing this package never requires PyTorch.
+"""
+
+from __future__ import annotations
+
+__all__ = (
+    "DryMassCalculator",
+    "OPDConverter",
+    "calc_drymass",
+    "calc_drymass_from_phase",
+    "opd_to_phase",
+    "phase_to_opd",
+)
+
+from iivs.dhm.analysis.drymass import (
+    DryMassCalculator,
+    calc_drymass,
+    calc_drymass_from_phase,
+)
+from iivs.dhm.analysis.opd import OPDConverter, opd_to_phase, phase_to_opd

iivs_lib-0.1.0/iivs/dhm/analysis/drymass.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+__all__ = ("DryMassCalculator", "calc_drymass", "calc_drymass_from_phase")
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from iivs.dhm.analysis.opd import OPDConverter
+from iivs.dhm.data.constants import (
+    DEFAULT_SPECIFIC_REFRACTIVE_INCREMENT,
+    DEFAULT_WAVELENGTH,
+)
+
+if TYPE_CHECKING:
+    from typing import Self
+
+    from numpy.typing import NDArray
+
+
+@dataclass(frozen=True, slots=True)
+class DryMassCalculator:
+    """Integrate OPD (or phase) into dry mass (pg) at a fixed pixel size and alpha.
+
+    Bind the pixel size, specific refractive increment, and -- for the phase
+    path -- an `OPDConverter` once; the per-pixel mass factor is precomputed::
+
+        dmc = DryMassCalculator(pixel_size=px)  # alpha, wavelength default
+        dmc = DryMassCalculator.from_wavelength(pixel_size=px, wavelength=666e-9)
+        mass = dmc.calc_from_opd(opd, mask=cell)  # opd in nm
+        mass = dmc.calc_from_phase(phase, mask=cell)  # phase in rad
+
+    Dry mass is ``(1 / alpha) * sum(OPD * pixel_area)`` (Barer), in pg, summed in
+    float64 over the last two axes (H, W) and returned as float32. Inputs are
+    batched (``(..., H, W)``)
+    and a ``(N, H, W)`` mask adds a trailing channel axis -- see `calc_from_opd`
+    for the shape / `reduce` details. The OPD must already be background-corrected
+    (≈ 0 outside the object); segmentation and background estimation stay the
+    caller's responsibility.
+
+    The free `calc_drymass` / `calc_drymass_from_phase` are one-shot conveniences
+    over this class. For PyTorch, use `iivs.dhm.analysis.pytorch.DryMass`.
+
+    Attributes:
+        pixel_size: Physical size of one (square) pixel, in m.
+        alpha: Specific refractive increment, in m^3/kg.
+        opd_converter: Phase-to-OPD converter used by `calc_from_phase`.
+            Defaults to one at the default wavelength; inject your own or use
+            `from_wavelength`.
+    """
+
+    pixel_size: float
+    alpha: float = DEFAULT_SPECIFIC_REFRACTIVE_INCREMENT
+    opd_converter: OPDConverter = field(default_factory=OPDConverter)
+
+    # pg of dry mass per nm of OPD summed over pixels:
+    _scale: float = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        """Validate inputs and precompute the per-pixel mass factor."""
+        if self.pixel_size <= 0:
+            msg = f"pixel_size must be positive (got {self.pixel_size})"
+            raise ValueError(msg)
+
+        if self.alpha <= 0:
+            msg = f"alpha must be positive (got {self.alpha})"
+            raise ValueError(msg)
+
+        # pg per summed-nm OPD: px_area(m^2) * (nm->m 1e-9) * (kg->pg 1e15) / alpha.
+        object.__setattr__(self, "_scale", self.pixel_size**2 * 1e6 / self.alpha)
+
+    @classmethod
+    def from_wavelength(
+        cls,
+        *,
+        pixel_size: float,
+        wavelength: float = DEFAULT_WAVELENGTH,
+        alpha: float = DEFAULT_SPECIFIC_REFRACTIVE_INCREMENT,
+    ) -> Self:
+        """Build a calculator whose phase path uses `wavelength` (in m)."""
+        return cls(
+            pixel_size=pixel_size,
+            alpha=alpha,
+            opd_converter=OPDConverter(wavelength=wavelength),
+        )
+
+    @property
+    def wavelength(self) -> float:
+        """The bound OPD converter's wavelength, in m."""
+        return self.opd_converter.wavelength
+
+    @property
+    def wavelength_nm(self) -> float:
+        """The bound OPD converter's wavelength, in nm."""
+        return self.opd_converter.wavelength_nm
+
+    @property
+    def drymass_scale(self) -> float:
+        """pg of dry mass per nm of OPD summed over pixels.
+
+        The cached ``pixel_area / alpha`` factor: ``mass == drymass_scale *
+        sum(opd_nm)``. The OPD analogue is `OPDConverter.opd_scale`.
+        """
+        return self._scale
+
+    def calc_from_opd(
+        self,
+        opd: NDArray[np.float32],
+        *,
+        mask: NDArray[np.bool_] | None = None,
+        reduce: bool = True,
+    ) -> NDArray[np.float32]:
+        """Dry mass [pg] from an OPD map (nm), summed over the last two axes (H, W).
+
+        Args:
+            opd: OPD map(s), in nm, shape ``(..., H, W)``.
+            mask: Optional boolean mask, shape ``(H, W)`` or ``(N, H, W)`` for
+                `N` objects; multiplied in (broadcast), the 3-D form adding a
+                trailing channel axis.
+            reduce: If True (default), sum the per-pixel mass over (H, W) and
+                return the dry mass, shape ``(...)`` (or ``(..., N)`` with a
+                ``(N, H, W)`` mask). If False, return the per-pixel mass-density
+                map (``opd * scale``, masked) without summing, shape
+                ``(..., H, W)`` (or ``(..., N, H, W)``).
+
+        Raises:
+            ValueError: If `opd` is not at least 2-D ``(..., H, W)``; if `mask`
+                is not 2-D ``(H, W)`` or 3-D ``(N, H, W)`` (a per-frame /
+                higher-rank mask like ``(T, N, H, W)`` is unsupported -- loop
+                over its leading axes); or if `mask`'s ``(H, W)`` does not match
+                `opd`'s.
+        """
+        if opd.ndim < 2:
+            msg = f"opd must be at least 2D (..., H, W) (got {opd.ndim}D)"
+            raise ValueError(msg)
+
+        use_mask = mask is not None
+
+        if use_mask:
+            if mask.ndim not in (2, 3):
+                msg = f"mask must be (H, W) or (N, H, W) (got {mask.ndim}D); loop over the extra (e.g. time) axis"
+                raise ValueError(msg)
+            if mask.shape[-2:] != opd.shape[-2:]:
+                msg = f"opd and mask (H, W) must match (got {opd.shape[-2:]} vs {mask.shape[-2:]})"
+                raise ValueError(msg)
+
+        if reduce:
+            opd = opd.astype(np.float64, copy=False)
+            if use_mask:
+                result = np.tensordot(opd, mask, axes=([-2, -1], [-2, -1]))
+            else:
+                result = np.sum(opd, axis=(-2, -1))
+        elif use_mask:
+            if mask.ndim == 3:  # (N, H, W): object axis before (H, W)
+                opd = opd[..., None, :, :]
+            result = opd * mask
+        else:
+            result = opd
+
+        # OPD (nm) -> dry mass (pg); accumulated in float64, returned as float32.
+        return (result * self._scale).astype(np.float32, copy=False)
+
+    def calc_from_phase(
+        self,
+        phase: NDArray[np.float32],
+        *,
+        mask: NDArray[np.bool_] | None = None,
+        reduce: bool = True,
+    ) -> NDArray[np.float32]:
+        """Dry mass [pg] from a phase map (rad): to OPD, then `calc_from_opd`."""
+        opd = self.opd_converter.convert_to_opd(phase)
+        return self.calc_from_opd(opd, mask=mask, reduce=reduce)
+
+
+def calc_drymass(
+    opd: NDArray[np.float32],
+    *,
+    pixel_size: float,
+    alpha: float = DEFAULT_SPECIFIC_REFRACTIVE_INCREMENT,
+    mask: NDArray[np.bool_] | None = None,
+    reduce: bool = True,
+) -> NDArray[np.float32]:
+    """Dry mass [pg] of an OPD map (nm); one-shot `DryMassCalculator.calc_from_opd`.
+
+    Args:
+        opd: OPD map(s), in nm (e.g. from `phase_to_opd`), shape ``(..., H, W)``,
+            already background-corrected.
+        pixel_size: Physical size of one (square) pixel, in m.
+        alpha: Specific refractive increment, in m^3/kg.
+        mask: Optional boolean mask, shape ``(H, W)`` or ``(N, H, W)``.
+        reduce: Sum over (H, W) to a dry mass (True), or return the per-pixel
+            mass-density map (False). See `DryMassCalculator.calc_from_opd`.
+
+    Returns:
+        Dry mass in pg, shape ``(...)`` (or ``(..., N)``); or the unreduced
+        density map when `reduce` is False.
+    """
+    return DryMassCalculator(pixel_size=pixel_size, alpha=alpha).calc_from_opd(
+        opd, mask=mask, reduce=reduce
+    )
+
+
+def calc_drymass_from_phase(
+    phase: NDArray[np.float32],
+    *,
+    pixel_size: float,
+    wavelength: float = DEFAULT_WAVELENGTH,
+    alpha: float = DEFAULT_SPECIFIC_REFRACTIVE_INCREMENT,
+    mask: NDArray[np.bool_] | None = None,
+    reduce: bool = True,
+) -> NDArray[np.float32]:
+    """Dry mass [pg] from a phase map (rad); one-shot `DryMassCalculator`.
+
+    Converts `phase` to OPD at `wavelength`, then integrates as `calc_drymass`.
+
+    Args:
+        phase: Phase map(s), in rad, shape ``(..., H, W)``, already
+            background-corrected.
+        pixel_size: Physical size of one (square) pixel, in m.
+        wavelength: Illumination wavelength, in m.
+        alpha: Specific refractive increment, in m^3/kg.
+        mask: Optional boolean mask, shape ``(H, W)`` or ``(N, H, W)``.
+        reduce: Sum over (H, W) to a dry mass (True), or return the per-pixel
+            mass-density map (False).
+
+    Returns:
+        Dry mass in pg, shape ``(...)`` (or ``(..., N)``); or the unreduced
+        density map when `reduce` is False.
+    """
+    return DryMassCalculator.from_wavelength(
+        pixel_size=pixel_size, alpha=alpha, wavelength=wavelength
+    ).calc_from_phase(phase, mask=mask, reduce=reduce)