Plugin to read CZI image file and metadata
This napari plugin was generated with copier using the napari-plugin-template.
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
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).
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 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_datait will be opened from remote repository (might be slow)
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 double-range sliders 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 will be enabled and allow to select an range to be read for all available dimensions
- The dimensions slider allow to define size of 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
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
- 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!
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.
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:
pytestLinux (recommended - use tox):
tox -e py311-linux(Replace py311 with your Python version: py310, py312, or py313)
Linux (direct pytest):
pytest -v --forked --color=yesNote: 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.
czitools>=0.14.0is supported.- Newer
czitoolsmay 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.
Distributed under the terms of the MIT license, "napari-czitools" is free and open source software
If you encounter any problems, please file an issue along with a detailed description.
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