ci-deconvolve 0.1.0__py3-none-any.whl

ci_deconvolve/__init__.py

@@ -0,0 +1,3 @@
+"""Focused command-line package for CI-RL deconvolution."""
+
+__version__ = "0.1.0"

ci_deconvolve/cli.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import shutil
+import sys
+import time
+from pathlib import Path
+from typing import Iterable
+
+LOGGER = logging.getLogger("ci_deconvolve")
+
+OME_TIFF_SUFFIXES = (".ome.tif", ".ome.tiff")
+ZARR_SUFFIXES = (".zarr", ".ome.zarr")
+
+
+def _require_torch() -> None:
+    try:
+        import torch  # noqa: F401
+    except Exception as exc:
+        raise RuntimeError(
+            "PyTorch is required but is not installed or cannot be imported. "
+            "Install a CPU or CUDA PyTorch build first, then rerun ci_deconvolve. "
+            "See https://pytorch.org/get-started/locally/ for the current install command."
+        ) from exc
+
+
+def _is_ome_tiff(path: Path) -> bool:
+    name = path.name.lower()
+    return path.is_file() and any(name.endswith(suffix) for suffix in OME_TIFF_SUFFIXES)
+
+
+def _is_ome_zarr(path: Path) -> bool:
+    name = path.name.lower()
+    return path.is_dir() and any(name.endswith(suffix) for suffix in ZARR_SUFFIXES)
+
+
+def _discover_inputs(path: Path) -> list[Path]:
+    if _is_ome_tiff(path) or _is_ome_zarr(path):
+        return [path]
+    if path.is_dir():
+        inputs = [
+            child
+            for child in sorted(path.iterdir(), key=lambda p: p.name.lower())
+            if _is_ome_tiff(child) or _is_ome_zarr(child)
+        ]
+        if inputs:
+            return inputs
+        raise ValueError(f"No OME-TIFF files or OME-Zarr folders found in {path}")
+    raise ValueError(
+        f"Unsupported input {path}. Expected .ome.tif/.ome.tiff, .zarr/.ome.zarr, "
+        "or a folder containing those inputs."
+    )
+
+
+def _stem(path: Path) -> str:
+    name = path.name
+    lower = name.lower()
+    for suffix in (".ome.tiff", ".ome.tif", ".ome.zarr", ".zarr"):
+        if lower.endswith(suffix):
+            return name[: -len(suffix)]
+    return path.stem
+
+
+def _parse_int_list(raw: str) -> list[int]:
+    values = []
+    for item in str(raw or "").replace(";", ",").split(","):
+        item = item.strip()
+        if not item:
+            continue
+        try:
+            values.append(max(1, int(float(item))))
+        except ValueError as exc:
+            raise argparse.ArgumentTypeError(f"Invalid iteration count: {item!r}") from exc
+    if not values:
+        raise argparse.ArgumentTypeError("At least one iteration count is required")
+    return values
+
+
+def _parse_float_list(raw: str | None) -> list[float] | None:
+    if raw is None:
+        return None
+    values = []
+    for item in str(raw).replace(";", ",").split(","):
+        item = item.strip()
+        if not item:
+            continue
+        values.append(float(item))
+    return values or None
+
+
+def _parse_float_or_auto(raw: str):
+    text = str(raw).strip().lower()
+    if text == "auto":
+        return "auto"
+    if text in {"none", "0", "0.0"}:
+        return 0.0
+    return float(text)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ci_deconvolve",
+        description="Run CI-RL deconvolution on OME-TIFF and OME-Zarr inputs.",
+    )
+    parser.add_argument("input_path", nargs="?", help="Input file/folder. Alias for --input.")
+    parser.add_argument("--input", dest="input_option", help="OME-TIFF, OME-Zarr, or folder.")
+    parser.add_argument("--output", required=True, help="Output folder.")
+    parser.add_argument(
+        "--output-format",
+        choices=("ome-tiff", "ome-zarr"),
+        default="ome-tiff",
+        help="Output format. Default: ome-tiff.",
+    )
+    parser.add_argument("--iterations", type=_parse_int_list, default=[40])
+    parser.add_argument("--device", choices=("auto", "cpu", "cuda"), default="auto")
+    parser.add_argument("--background", default="auto")
+    parser.add_argument("--offset", default="auto")
+    parser.add_argument("--damping", default="none")
+    parser.add_argument("--prefilter-sigma", type=float, default=0.0)
+    parser.add_argument(
+        "--start",
+        choices=(
+            "auto",
+            "flat",
+            "percentile_flat",
+            "observed",
+            "observed_bgsub",
+            "lowpass",
+            "lowpass_bgsub",
+            "hybrid",
+        ),
+        default="auto",
+    )
+    parser.add_argument("--convergence", choices=("auto", "fixed", "none"), default="auto")
+    parser.add_argument("--rel-threshold", type=float, default=0.005)
+    parser.add_argument("--check-every", type=int, default=5)
+    parser.add_argument("--na", type=float, default=1.4)
+    parser.add_argument("--refractive-index", type=float, default=1.515)
+    parser.add_argument("--sample-ri", type=float, default=1.47)
+    parser.add_argument("--microscope-type", choices=("widefield", "confocal"), default="confocal")
+    parser.add_argument("--emission-wl", default="520")
+    parser.add_argument("--excitation-wl", default="488")
+    parser.add_argument("--pinhole-airy", default="1.0")
+    parser.add_argument("--pixel-size-xy", type=float, default=0.065, help="Micrometers.")
+    parser.add_argument("--pixel-size-z", type=float, default=0.2, help="Micrometers.")
+    parser.add_argument(
+        "--overrule-metadata",
+        action="store_true",
+        help="Use CLI metadata values even when image metadata is present.",
+    )
+    parser.add_argument(
+        "--two-d-mode",
+        choices=("auto", "legacy_2d"),
+        default="auto",
+    )
+    parser.add_argument(
+        "--two-d-wf-aggressiveness",
+        choices=("conservative", "balanced", "strong"),
+        default="balanced",
+    )
+    parser.add_argument("--two-d-wf-bg-radius-um", type=float, default=0.5)
+    parser.add_argument("--two-d-wf-bg-scale", type=float, default=1.0)
+    parser.add_argument("-v", "--verbose", action="store_true")
+    return parser
+
+
+def _normalise_convergence(value: str) -> str:
+    return "fixed" if value == "none" else value
+
+
+def _output_path(input_path: Path, output_dir: Path, output_format: str) -> Path:
+    if output_format == "ome-zarr":
+        return output_dir / f"{_stem(input_path)}_decon.ome.zarr"
+    return output_dir / f"{_stem(input_path)}_decon.ome.tiff"
+
+
+def _run_one(input_path: Path, output_dir: Path, args: argparse.Namespace) -> Path:
+    from core.deconvolve import deconvolve_image, save_result
+    from core.ome_zarr_io import is_hcs_plate, save_result_ome_zarr
+
+    if _is_ome_zarr(input_path) and is_hcs_plate(input_path):
+        if args.output_format == "ome-tiff":
+            raise ValueError("HCS plate OME-Zarr input cannot be written as one OME-TIFF output.")
+        raise ValueError("HCS plate OME-Zarr output is not supported by the focused CLI yet.")
+
+    device = None if args.device == "auto" else args.device
+    result = deconvolve_image(
+        input_path,
+        method="ci_rl",
+        niter=args.iterations,
+        na=args.na,
+        refractive_index=args.refractive_index,
+        sample_refractive_index=args.sample_ri,
+        microscope_type=args.microscope_type,
+        emission_wavelengths=_parse_float_list(args.emission_wl),
+        excitation_wavelengths=_parse_float_list(args.excitation_wl),
+        pinhole_airy_units=_parse_float_list(args.pinhole_airy),
+        overrule_metadata=bool(args.overrule_metadata),
+        pixel_size_xy=args.pixel_size_xy,
+        pixel_size_z=args.pixel_size_z,
+        background=_parse_float_or_auto(args.background),
+        damping=_parse_float_or_auto(args.damping),
+        offset=_parse_float_or_auto(args.offset),
+        prefilter_sigma=max(0.0, float(args.prefilter_sigma)),
+        start=args.start,
+        convergence=_normalise_convergence(args.convergence),
+        rel_threshold=max(1e-8, float(args.rel_threshold)),
+        check_every=max(1, int(args.check_every)),
+        two_d_mode=args.two_d_mode,
+        two_d_wf_aggressiveness=args.two_d_wf_aggressiveness,
+        two_d_wf_bg_radius_um=max(0.1, float(args.two_d_wf_bg_radius_um)),
+        two_d_wf_bg_scale=max(0.1, float(args.two_d_wf_bg_scale)),
+        device=device,
+    )
+
+    out_path = _output_path(input_path, output_dir, args.output_format)
+    if args.output_format == "ome-zarr":
+        return save_result_ome_zarr(result, out_path)
+
+    tmp_dir = output_dir / ".ci_deconvolve_tmp"
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+    tmp_path = tmp_dir / out_path.name
+    try:
+        save_result(result, tmp_path)
+        if out_path.exists():
+            out_path.unlink()
+        shutil.move(str(tmp_path), str(out_path))
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+    return out_path
+
+
+def run(argv: Iterable[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    logging.basicConfig(
+        level=logging.INFO if args.verbose else logging.WARNING,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    input_value = args.input_option or args.input_path
+    if not input_value:
+        parser.error("an input path is required via --input or positional input_path")
+    input_path = Path(input_value)
+    output_dir = Path(args.output)
+
+    _require_torch()
+    inputs = _discover_inputs(input_path)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    print("ci_deconvolve")
+    print(f"  method       : ci_rl")
+    print(f"  input count  : {len(inputs)}")
+    print(f"  output       : {output_dir}")
+    print(f"  output format: {args.output_format}")
+    print(f"  iterations   : {', '.join(str(v) for v in args.iterations)}")
+
+    failures: list[tuple[Path, Exception]] = []
+    for index, item in enumerate(inputs, start=1):
+        print(f"\n[{index}/{len(inputs)}] {item}")
+        start = time.time()
+        try:
+            out_path = _run_one(item, output_dir, args)
+            print(f"  saved: {out_path}")
+            print(f"  time : {time.time() - start:.1f}s")
+        except Exception as exc:
+            failures.append((item, exc))
+            print(f"  ERROR: {exc}", file=sys.stderr)
+
+    if failures:
+        print(f"\nFailed inputs: {len(failures)}", file=sys.stderr)
+        for item, exc in failures:
+            print(f"  {item}: {exc}", file=sys.stderr)
+        return 1
+    print("\nci_deconvolve complete.")
+    return 0
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    try:
+        return run(argv)
+    except KeyboardInterrupt:
+        print("Interrupted.", file=sys.stderr)
+        return 130
+    except Exception as exc:
+        print(f"ci_deconvolve failed: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ci_deconvolve-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: ci-deconvolve
+Version: 0.1.0
+Summary: Focused command-line CI-RL deconvolution for OME-TIFF and OME-Zarr images.
+Author: NL-BioImaging contributors
+License-Expression: MIT
+Keywords: microscopy,deconvolution,ome-tiff,ome-zarr,richardson-lucy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: Pillow>=10.0
+Requires-Dist: tifffile>=2024.1.30
+Requires-Dist: imagecodecs>=2024.1.1
+Requires-Dist: bioio==3.2.0
+Requires-Dist: bioio-ome-tiff==1.4.0
+Requires-Dist: ome-zarr<0.19,>=0.18
+Requires-Dist: numcodecs>=0.14
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# ci-deconvolve
+
+Focused command-line CI-RL deconvolution for OME-TIFF and OME-Zarr images.
+
+This package installs the `ci_deconvolve` command. On Windows, `pip` also
+creates a `ci_deconvolve.exe` console launcher in the active environment.
+
+## Prerequisite: PyTorch
+
+PyTorch is required but is not bundled in this package. Install the CPU or CUDA
+build that matches your system before running `ci_deconvolve`.
+
+Examples:
+
+```bash
+pip install torch
+```
+
+or install a CUDA build using the command from:
+
+```text
+https://pytorch.org/get-started/locally/
+```
+
+## Install
+
+From this folder during development:
+
+```bash
+pip install -e .
+```
+
+From PyPI after publishing:
+
+```bash
+pip install ci-deconvolve
+```
+
+The package depends on `ome-zarr` for OME-Zarr reading and writing. `zarr` is
+installed transitively by `ome-zarr`; it is not declared as a direct dependency.
+
+## Usage
+
+Run one OME-TIFF file:
+
+```bash
+ci_deconvolve --input image.ome.tiff --output out
+```
+
+Run one OME-Zarr image:
+
+```bash
+ci_deconvolve --input image.ome.zarr --output out --output-format ome-zarr
+```
+
+Run every supported immediate child in a folder:
+
+```bash
+ci_deconvolve --input in_folder --output out_folder --iterations 40
+```
+
+Only these inputs are accepted:
+
+- `.ome.tif`
+- `.ome.tiff`
+- `.zarr` / `.ome.zarr` directories
+
+The CLI always runs `ci_rl`. It intentionally has no `--method` option.
+
+## Examples
+
+```bash
+ci_deconvolve --input image.ome.tiff --output out ^
+  --iterations 40 ^
+  --device auto ^
+  --output-format ome-tiff ^
+  --emission-wl 520 ^
+  --excitation-wl 488 ^
+  --pixel-size-xy 0.065 ^
+  --pixel-size-z 0.2
+```
+
+Use `--overrule-metadata` when CLI metadata values should replace image
+metadata. Without it, CLI metadata values are used as fallbacks.
+
+Per-channel values can be comma-separated. If there are more channels than
+values, the last value is reused for the remaining channels.
+
+```bash
+ci_deconvolve --input image.ome.tiff --output out ^
+  --iterations 40,60,80 ^
+  --emission-wl 520,610 ^
+  --excitation-wl 488,561 ^
+  --pinhole-airy 1.0,1.2
+```
+
+## Parameters
+
+### Required Paths
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `input_path` | none | Optional positional input path. Use this or `--input`. |
+| `--input PATH` | none | Input OME-TIFF file, OME-Zarr folder, or folder containing supported inputs. |
+| `--output DIR` | required | Output folder. Created if it does not exist. |
+
+Supported inputs are immediate files/folders only:
+
+- `.ome.tif`
+- `.ome.tiff`
+- `.zarr` / `.ome.zarr` directories
+
+HCS plate OME-Zarr inputs are detected and rejected clearly; this focused CLI
+does not process plate fields.
+
+### Output And Compute
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--output-format ome-tiff\|ome-zarr` | `ome-tiff` | Writes `<stem>_decon.ome.tiff` or `<stem>_decon.ome.zarr`. |
+| `--iterations N[,N...]` | `40` | CI-RL iteration count. A comma- or semicolon-separated list applies per channel, with the last value reused for extra channels. |
+| `--device auto\|cpu\|cuda` | `auto` | Compute device. `auto` lets PyTorch choose CUDA when available, otherwise CPU. |
+| `-v`, `--verbose` | off | Enable INFO logging from the CLI and core deconvolution code. |
+
+### CI-RL Solver
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--background VALUE\|auto` | `auto` | Background level used by the solver. `auto` estimates it from the image. Numeric values are accepted. |
+| `--offset VALUE\|auto\|none` | `auto` | Positive offset added before iteration and removed afterwards. Use `none`, `0`, or `0.0` to disable. |
+| `--damping VALUE\|auto\|none` | `none` | Noise-gated damping strength. Use `auto` for automatic damping, numeric values for manual damping, or `none`/`0` to disable. |
+| `--prefilter-sigma VALUE` | `0.0` | Optional Anscombe/low-pass prefilter sigma. `0.0` disables prefiltering. |
+| `--start MODE` | `auto` | Initial estimate mode. Choices: `auto`, `flat`, `percentile_flat`, `observed`, `observed_bgsub`, `lowpass`, `lowpass_bgsub`, `hybrid`. |
+| `--convergence auto\|fixed\|none` | `auto` | `auto` enables early stopping based on convergence. `fixed` and `none` both run the requested iteration count. |
+| `--rel-threshold VALUE` | `0.005` | Relative convergence threshold used when `--convergence auto`. Values are clamped to at least `1e-8`. |
+| `--check-every N` | `5` | Check convergence every N iterations. Values below 1 are clamped to 1. |
+
+### Metadata And PSF
+
+These values are used to generate the point spread function. By default, image
+metadata wins and CLI values fill in missing metadata. With
+`--overrule-metadata`, CLI values replace image metadata.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--na VALUE` | `1.4` | Numerical aperture. |
+| `--refractive-index VALUE` | `1.515` | Immersion medium refractive index, typically oil. |
+| `--sample-ri VALUE` | `1.47` | Sample medium refractive index. |
+| `--microscope-type widefield\|confocal` | `confocal` | Microscope model used for PSF generation. |
+| `--emission-wl VALUE[,VALUE...]` | `520` | Emission wavelength(s), in nm. Per-channel list supported. |
+| `--excitation-wl VALUE[,VALUE...]` | `488` | Excitation wavelength(s), in nm. Per-channel list supported. |
+| `--pinhole-airy VALUE[,VALUE...]` | `1.0` | Confocal pinhole diameter in Airy units. Per-channel list supported. |
+| `--pixel-size-xy VALUE` | `0.065` | Lateral pixel size in micrometers. Applied to X and Y. |
+| `--pixel-size-z VALUE` | `0.2` | Axial pixel size in micrometers. |
+| `--overrule-metadata` | off | Replace image metadata with CLI metadata values instead of only using CLI values as fallbacks. |
+
+List syntax:
+
+```bash
+--emission-wl 520,610
+--excitation-wl 488;561
+--iterations 30,40,50
+```
+
+Commas and semicolons are both accepted.
+
+### 2D Widefield Options
+
+These only affect 2D widefield data when `--microscope-type widefield` and
+`--two-d-mode auto` are used.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--two-d-mode auto\|legacy_2d` | `auto` | `auto` enables the enhanced 2D widefield path. `legacy_2d` uses the historical pure-2D PSF behavior. |
+| `--two-d-wf-aggressiveness conservative\|balanced\|strong` | `balanced` | Strength preset for the enhanced 2D widefield model. |
+| `--two-d-wf-bg-radius-um VALUE` | `0.5` | Background-estimation radius in micrometers. Values below `0.1` are clamped to `0.1`. |
+| `--two-d-wf-bg-scale VALUE` | `1.0` | Multiplier for the estimated 2D widefield background. Values below `0.1` are clamped to `0.1`. |
+
+## Metadata Override Behavior
+
+Without `--overrule-metadata`:
+
+- Existing OME metadata is preserved.
+- CLI metadata values are used only when a value is missing or invalid.
+- This is the recommended mode for well-annotated OME-TIFF or OME-Zarr data.
+
+With `--overrule-metadata`:
+
+- CLI metadata values replace image metadata.
+- Use this when source metadata is known to be wrong, incomplete, or converted
+  with incorrect physical pixel sizes or wavelengths.
+
+Example:
+
+```bash
+ci_deconvolve --input image.ome.tiff --output out ^
+  --overrule-metadata ^
+  --microscope-type widefield ^
+  --na 1.40 ^
+  --refractive-index 1.515 ^
+  --sample-ri 1.47 ^
+  --pixel-size-xy 0.065 ^
+  --pixel-size-z 0.200 ^
+  --emission-wl 520,610
+```

ci_deconvolve-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ci_deconvolve/__init__.py,sha256=6KvpHMilH5eQK56n8a7npW11k1soiTXAUIsPaG-RAs4,83
+ci_deconvolve/cli.py,sha256=b1jS5DoYKKLe419xAG1RTZrzFlEKbSe9IsW-y2mQlow,10536
+core/__init__.py,sha256=-yMZ_O1WisEVjusjWyUbj3Q8o4q2C8EU8cdsvgAq-L8,460
+core/_meta_helpers.py,sha256=2VndQriokjD_BVsy1MyE__DPbuOr96iL5GDHTc5PZmY,11223
+core/deconvolve.py,sha256=2mgDsc3XlBu-WLYgfa2bs298tEtR8BUYpczQrCw8Zro,62327
+core/deconvolve_ci.py,sha256=sX1M0aONkB_Zaf1WbUygnaTMdyfFHQwzYVfw5PsAYws,80379
+core/ome_zarr_io.py,sha256=0zmHwJYKGdkgRkr_0KN9xK1f4dKFHO_GVHvsCoSyp8w,8968
+ci_deconvolve-0.1.0.dist-info/METADATA,sha256=V3l4XRg-637uAggxqSVsiFxg3BQ6cZP1Gv3wwKyBvrM,8455
+ci_deconvolve-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ci_deconvolve-0.1.0.dist-info/entry_points.txt,sha256=CUy5vVJU6ZzAmnfjI-qduljcgZCMpdsMrA-Zi3g85qo,57
+ci_deconvolve-0.1.0.dist-info/top_level.txt,sha256=76r0e8VMIoGrdcRgh-lsaWbI8bvBgRn64LkZgd70hIg,19
+ci_deconvolve-0.1.0.dist-info/RECORD,,

ci_deconvolve-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ci_deconvolve-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ci_deconvolve = ci_deconvolve.cli:main

ci_deconvolve-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+ci_deconvolve
+core

core/__init__.py

@@ -0,0 +1,23 @@
+"""Focused core package for the ci_deconvolve CLI."""
+
+from .deconvolve import (
+    deconvolve,
+    deconvolve_image,
+    generate_psf,
+    load_image,
+    save_mip_png,
+    save_result,
+    _DEFAULT_PINHOLE_AIRY_UNITS,
+    _apply_pinhole_airy_units,
+)
+
+__all__ = [
+    "deconvolve",
+    "deconvolve_image",
+    "generate_psf",
+    "load_image",
+    "save_mip_png",
+    "save_result",
+    "_DEFAULT_PINHOLE_AIRY_UNITS",
+    "_apply_pinhole_airy_units",
+]