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, OMERO channel display metadata, and OME/METADATA.ome.xml for Bio-Formats/QuPath readers that prefer OME-XML 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