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
```
