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:

pip install torch

or install a CUDA build using the command from:

https://pytorch.org/get-started/locally/

Install

From this folder during development:

pip install -e .

From PyPI after publishing:

pip install ci-deconvolve

The package depends on ome-zarr for OME-Zarr reading and zarr>=2.16,<4 for writing QuPath- and OMERO-compatible OME-Zarr output.

Usage

Run one OME-TIFF file:

ci_deconvolve --input image.ome.tiff --output out

Run one OME-Zarr image:

ci_deconvolve --input image.ome.zarr --output out --output-format ome-zarr

Run every supported immediate child in a folder:

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

ci_deconvolve --input image.ome.tiff --output out ^
  --iterations 40 ^
  --device auto ^
  --output-format ome-tiff ^
  --projection none ^
  --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.

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

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

CI-RL Solver

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.

List syntax:

--emission-wl 520,610
--excitation-wl 488;561
--iterations 30,40,50

Commas and semicolons are both accepted.

OME-Zarr Compatibility

OME-Zarr output is written as OME-NGFF 0.4 on Zarr v2, with .zgroup and .zattrs metadata plus OMERO channel display metadata. This layout is intended to open in QuPath 0.7 and remain compatible with OMERO tooling.

2D Widefield Options

These only affect 2D widefield data when --microscope-type widefield and --two-d-mode auto are used.

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:

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