napari-czitools

• napari-czitools
  • Installation
  • Supported Operating Systems
  • Usage - Core Functionalities
    • Open Complete CZI Files
    • Open CZI Sample Data
      • CellDivision 5D Stack
      • Neurons 3D Stack
      • AiryScan 3D Stack
      • Wellplate Data
    • Advanced CZI Reader (CziReadTools) plugin
  • Current Limitations
    • Future plans
  • Contributing
  • License
  • Issues
• Disclaimer

napari-czitools

Plugin to read CZI image file and metadata

This napari plugin was generated with copier using the napari-plugin-template.

Installation

You can install napari-czitools via pip:

pip install napari-czitools

To install latest development version :

pip install git+https://github.com/sebi06/napari-czitools.git

Supported Operating Systems

Currently this only tested on:

• Linux
• Windows

MacOS is not supported yet out of the box yet, but czitools uses pylibCZIrw. But it should be possible to install it manually: MaxOS wheels for pylibCZIrw (read and write CZI files on MacOS).

Usage - Core Functionalities

The plugin provides a reader for CZI files and allows to load the image data into napari. It also reads the metadata from the CZI file and displays it in the metadata panel of napari.

Open Complete CZI Files

• Open complete CZI Files and display the metadata in Napari using the czitools package

• Open different CZI Image sample data
• if not found locally in current directory ../src/napari_czitools/sample_data it will be opened from remote repository (might be slow)

Open CZI Sample Data

CellDivision 5D Stack

Neurons 3D Stack

AiryScan 3D Stack

Wellplate Data

Advanced CZI Reader (CziReadTools) plugin

Select the plugin to show the UI in the right panel of the Napari UI via "Plugins > Advanced CZI Reader (CziReadTools)"

• Select the CZI file to read its metadata
• Once the metadata are read the display can be toggled between a table and a tree view
• The metadata will update the dimension range sliders (powered by superqt's QLabeledRangeSlider) and enable reading the pixel data

• Metadata will be shown as a table or as a tree view
• The Load Pixel Data button will be enabled once the metadata is read
• The Dimension Sliders (using superqt's dual-handle range slider) will be enabled and allow to select a range to be read for all available dimensions. Both handles can be set to the same value for single-slice selection (e.g. 3-3)

• The dimension range sliders (from superqt) allow to define the size of a CZI subset to be read
• This allows to read parts of a CZI image dataset
• Important - when reading a subset the metadata will still reflects the size of the complete CZI

• Example for reading a subset
  • Timepoints (4-7): 4 slices or T=4
  • Channels (0-0): 1 slice or CH=1
  • Z-Plane (7-10): 4 slices or Z=4

Current Limitations

The plugin is still in its very early stage, therefor expect bugs and breaking changes

• reading CZI with multiple scenes only works when the scenes have equal size
• opening the sample CZI files will not display the CZI metadata right now

Future plans

• allow reading individual scenes when scenes have different sizes
• upgrade pylibCZIrw to allow use bioio-czi for even better reading
• export of metadata table

Feedback is always welcome!

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

Running Tests

Install test dependencies first (recommended for full local coverage):

pip install -e ".[testing]"

This installs pytest-qt, which provides the qtbot fixture used by napari/Qt tests.

Windows/macOS:

pytest

Linux (recommended - use tox):

tox -e py312-linux

(Replace py312 with your Python version: py312 or py313)

Linux (direct pytest):

pytest -v --forked --color=yes

Note: The --forked flag is required on Linux to prevent CZI + Qt crashes by running each test in its own process. This flag is not available on Windows.

Recent Compatibility Notes

• czitools>=0.14.0 is supported.
• czitools==0.15.0 changed read_tools.read_stacks to return (array6d, dims, num_stacks, metadata).
• The plugin now supports both 3-value and 4-value read_stacks return signatures for backward compatibility.
• Newer czitools may return scene data as a list of xarray stacks when lazy reading is enabled. The plugin now handles both single-stack and scene-list outputs when creating channel layers.
• Channel extraction uses positional indexing to support channel coordinates represented by names (for example "DAPI", "EGFP") instead of numeric labels.
• URL metadata tests can be affected by transient remote read failures (for example GitHub/network hiccups). The test suite retries and skips these network-dependent checks if remote headers cannot be read reliably.
• The custom dual-handle DoubleRangeSlider has been replaced with wrappers around superqt's QLabeledRangeSlider and QRangeSlider, reducing custom painting/mouse handling code and using a well-tested community component. The public slider API (low(), high(), setLow(), setHigh(), single-value mode) is unchanged.
• A small internal patch (_allow_handle_overlap) is applied to every superqt range slider so that both handles can sit on the same value, enabling single-frame extraction (e.g. T=4-4 to read one timepoint).

License

Distributed under the terms of the MIT license, "napari-czitools" is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.

Disclaimer

The software & scripts are free to use for everybody. The author undertakes no warranty concerning the use of this plugins and scripts. Use them on your own risk.

By using this plugin you agree to this disclaimer.

Version: 2025.08.20