CziReadTools
Plugin to read CZI image files and their metadata
- napari-czitools
napari plugin for reading CZI image data 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
The current release requires Python 3.12 or 3.13 and czitools>=0.22.1.
Version 0.13.0 adds optional VZIP loading and lazy scene stacking. See the v0.13.0 release notes for changes and compatibility.
VZIP support is optional:
pip install "napari-czitools[vzip]"
Creating new archives requires czitools>=0.27.3, which provides
czitools.export_tools.create_czi_vzip. The vzip extra enforces this
minimum alongside refkv. Existing CZI loading does not require refkv.
Without it, VZIP mode shows installation guidance.
To install latest development version :
pip install git+https://github.com/sebi06/napari-czitools.git
Supported Operating Systems
The test suite runs on Python 3.12 and 3.13 for:
- Linux
- Windows
- macOS
Usage - Core Functionalities
The plugin reads CZI image data into napari and displays the associated metadata in a table or tree.
Open Complete CZI Files
- Open complete CZI files and display their metadata in napari using czitools.

- Open different CZI sample datasets.
- If sample data are unavailable locally, they are downloaded from the remote repository, which may take some time.

Open CZI Sample Data
CellDivision 5D Stack

Neurons 3D Stack

AiryScan 3D Stack

Wellplate Data

Advanced CZI Reader (CziReadTools) plugin
General Usage
Open Plugins > Advanced CZI Reader (CziReadTools). The initial panel has four main areas:
- Select a local CZI or CZI-derived VZIP file. Drag and drop onto the file field is also supported.
- Inspect metadata as a table or tree. Tree view can optionally show value types.
- Configure scene handling and the 3D preview, then load the selected pixels.
- Select scene, time, channel, and Z ranges. Dimensions with only one position are hidden after metadata loads.
After Metadata Loads
Selecting a valid CZI file reads metadata but does not load its pixel data. The metadata view, Load Pixel Data, 3D preview size, and applicable dimension sliders then become available. Stack scenes remains disabled unless the CZI contains multiple scenes with different pixel dimensions.
Use Slider Type to switch between a dual-handle range slider and separate
minimum/maximum sliders. Setting both endpoints to the same value selects one
position, for example T=3-3.
Reading a subset
- Use the dimension sliders to select the scene, time, channel, and Z positions to load.
- The displayed metadata continue to describe the complete CZI, not only the selected subset.
![]()
For example, selecting timepoints 4-7, channel 0-0, and Z-planes 7-10 loads four timepoints, one channel, and four Z-planes.
![]()
3D Preview Size
3D preview size sets the target maximum width or height, in pixels, of the coarsest pyramid level sent to napari. The default is 2048 px, a conservative size that fits the minimum broadly supported OpenGL 3D texture limit.
This setting does not crop the image, change the selected S/T/C/Z ranges, or
reduce the resolution of the finest source level. If the coarsest pyramid level
stored in the CZI is already at or below the selected size, nothing additional
is generated. If it is larger, czitools lazily adds half-resolution levels
until the longest Y/X edge fits the target.
- Use a lower value to reduce GPU memory use and improve compatibility with older GPUs. The first overview will contain less spatial detail.
- Keep 2048 px for portable 3D rendering in most cases.
- Use a higher value only when more preview detail is useful and the GPU supports larger textures. Higher values can use more GPU memory.
The value is saved between napari sessions and becomes editable after valid CZI metadata loads. For small images, changing it often has no visible effect because the existing coarsest level already fits.

VZIP Loading
Choose Load using: VZIP in the existing reader widget. The default remains CZI, which continues to use the normal lazy multiscale reader.
Use the single Open CZI or VZIP selector at the top, then choose the loading
mode directly below it. For a selected CZI, the archive destination defaults to
a sibling image.vzip. Save archive as..., beside Load Pixel Data, allows
a different destination; its parent directory must already exist. The selected
archive filename is shown above the loading buttons; hover over it for the full
destination path. Choosing a destination does not create the archive yet.
Load Pixel Data creates the archive in a background worker,
then adds lazy image layers. If the archive exists, choose Reuse, Rebuild,
or Cancel. Reuse never rewrites it and checks that it references the selected
CZI. Rebuild explicitly replaces it through the protected czitools exporter.
The archive references the whole CZI. Scene/Time/Channel/Z selections apply
only to the displayed layers, so changing selections does not require rebuilding.
Selecting an existing .vzip in that same selector automatically switches the
widget to VZIP mode and hides archive-creation and destination controls.
Its metadata table/tree and sliders are populated from the archive without
parsing the CZI again. For scenes with different T/C/Z lengths, the widget exposes
the ranges common to all scenes.
Compatible selected scenes are automatically stacked lazily along a leading
S axis, with one layer per channel. For example, 28 equally sized 2D scenes
become one (28, Y, X) layer per channel. Scene order follows the archive's
numeric series order, and S/T/C/Z selections still apply only to display.
Stacking requires matching axes, shapes, dtypes, physical scales and pyramid
levels; incompatible scenes remain separate without cropping or resampling.
Scene-dependent stage origins become local coordinates in the stack, while
the original per-scene transforms and metadata are retained in the layer's
metadata["scenes"] list.
Existing CZI-derived archives can also be opened through File > Open, dropped onto the napari canvas, or opened from Python:
viewer.open("image.vzip", plugin="napari-czitools")
Direct opening displays all scenes and channels. Stored pyramid levels are used when present, with OME axes, physical scale/origin, channel colors, and display windows preserved. Stack scenes and generated 3D preview size are disabled in VZIP mode; no additional pyramid levels are synthesized.
VZIP contains references, not copied CZI pixels. The original local CZI must remain unchanged at its recorded location. Missing sources and unsupported archives produce explicit errors, never a silent fallback to another reader. Reuse does not fingerprint source contents or automatically detect every source change. Rebuild after modifying a CZI. Only CZI-derived refkv archives with local sources are supported; arbitrary VZIP formats and remote sources are not claimed as supported data. CZI layouts and compression support are determined by refkv.
Lazy Loading
The advanced reader always uses lazy multiscale loading after Load Pixel Data is pressed. It requests Dask-backed xarray stacks for the selected scene, time, channel, and Z ranges, so pixel tiles are read only when napari needs them. This avoids loading the complete selection into RAM, supports differently sized scenes, and enables efficient 3D previews.
Python callers can still pass use_lazy=False to CZIDataLoader or
reader_function_adv when they explicitly need the eager read_6darray path.
That path constructs one regular array in STCZYX(A) order, loads every
selected plane into RAM, and requires compatible scene shapes.
Scene Tolerance
When a file is selected the plugin reads the bounding rectangle of every scene and computes the maximum pixel difference in width and height across all scenes. If any difference is detected, a label appears next to the load controls:
Scene size diff — W: 72px H: 9px
and the Stack scenes checkbox becomes enabled. Checking it re-evaluates the metadata with a tolerance equal to the computed maximum difference, which:

- Unlocks the scene slider so you can select any range of scenes.
- Crops all scenes to the smallest common W×H shape when pixel data is loaded — no zero-padding is introduced.
When the checkbox is unchecked (default), scenes must be pixel-identical to be stacked; files where scene sizes differ are limited to one scene at a time.
This is particularly useful for HCS plate CZIs where each scene is a multi-tile mosaic covering one well: the per-well tile grids are assembled from stage coordinates independently, so the total pixel extent of each well can differ by tens of pixels even when the acquisition settings are identical.
Gigapixel CZIs (whole-slide, large 2D scans)
For files whose individual 2D planes are larger than about 256 MB uncompressed
(for example a 93,555 × 138,996 uint16 plane ≈ 24 GB), czitools
automatically switches to spatial Y/X tiling: each Dask chunk becomes one
ROI-based read via pylibCZIrw, so napari only fetches the tiles that
intersect the current viewport instead of full planes. Small planes keep the
faster whole-plane path.
On top of tiling, lazy mode also enables multiscale rendering. The plugin
calls czitools.read_tools.read_stacks_multiscale to detect the CZI's stored
pyramid levels (via pylibCZIrw subblock enumeration) and hands napari one
lazy Dask array per level as viewer.add_image(..., multiscale=True). This
lets napari render the coarsest level immediately from a single GPU texture
and stream finer tiles on zoom. If the coarsest stored level is still larger
than DEFAULT_MAX_COARSE_EDGE (2048 px), extra synthetic coarser levels are
added on the fly using libCZI's C++ resampler. The conservative default fits
the minimum broadly supported OpenGL 3D texture size; 2D texture limits are
often much larger. Files without an on-disk pyramid are passed to napari as
single-scale images when no additional level is needed.
To keep opening these files usable, the plugin also passes an explicit
contrast_limits argument to viewer.add_image (derived from the CZI's
embedded display settings). Without this, napari would auto-scan every chunk
of the Dask array to determine the display range and materialize the entire
plane in RAM before the first pixel is shown.
Advanced Python usage
The Python reader API forwards the same lazy behaviour:
from napari_czitools._io import DEFAULT_MAX_COARSE_EDGE
from napari_czitools._reader import reader_function_adv
reader_function_adv(
"image.czi",
use_lazy=True, # read pixel data only when requested
use_dask=True, # required for on-demand reads
use_multiscale=True, # napari renders coarse-level tiles first
max_coarse_edge=DEFAULT_MAX_COARSE_EDGE,
)
The complete example below is also available as
scripts/open_czi_with_napari_czitools.py.
It opens scene 0, timepoints 0-2, channel 1, and Z planes 4-8. Run it from the
repository root in an environment with napari-czitools installed using
python scripts/open_czi_with_napari_czitools.py.
"""Open the bundled CellDivision CZI sample with napari-czitools."""
from pathlib import Path
import napari
from napari_czitools._reader import reader_function_adv
SAMPLE_CZI_PATH = (
Path(__file__).resolve().parents[1]
/ "src"
/ "napari_czitools"
/ "sample_data"
/ "CellDivision_T10_Z20_CH2_X600_Y500_DCV_ZSTD.czi"
)
def main() -> None:
"""Open the bundled CZI sample in napari."""
if not SAMPLE_CZI_PATH.is_file():
raise FileNotFoundError(
f"Bundled CZI sample was not found: {SAMPLE_CZI_PATH}"
)
# The reader accepts `planes`; viewer.open forwards extra kwargs
# to layer creation instead of to the reader.
napari.Viewer()
planes = {
"S": (0, 0),
"T": (0, 2),
"C": (1, 1),
"Z": (4, 8),
}
reader_function_adv(
str(SAMPLE_CZI_PATH),
planes=planes,
)
napari.run()
if __name__ == "__main__":
main()
max_coarse_edge is the Python equivalent of 3D preview size. Keep the
default for portable 3D rendering, lower it to reduce GPU memory use, or raise
it when the GPU supports larger textures.
With use_lazy=True, czitools reads the CZI metadata and builds Dask task
graphs first — individual pixel planes are not loaded at that point. When
use_multiscale=True (the default) the plugin also constructs a per-level
pyramid so napari can render gigapixel planes without materialising layer 0.
Disabling use_lazy, even with use_dask=True, still reads all pixels
eagerly before wrapping the result in a Dask array.
Current Limitations
The sample-data commands add image layers directly and do not open the Advanced CZI Reader metadata panel.
Future plans
- Evaluate interoperability with bioio-czi.
- Add metadata-table export.
Feedback is always welcome!
Contributing
Contributions are welcome. Tests can be run with tox; please ensure coverage does not decrease when submitting 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.22.1is required.- Optional VZIP support requires
czitools>=0.27.3andrefkv[zarr,images]>=0.2.0; installingnapari-czitools[vzip]supplies both. - The testing extra requires
pytest<9.2because pytest-forked cannot serialize the new report fields introduced in pytest 9.2. read_tools.read_stacksreturns(arrays_or_list, dims, num_stacks, metadata). The plugin handles both a single stacked xarray object and a list containing one xarray stack per scene.- 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
DoubleRangeSliderhas been replaced with wrappers around superqt'sQLabeledRangeSliderandQRangeSlider, 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 and scripts are free to use. The author provides no warranty for their use. Use them at your own risk.
By using this plugin you agree to this disclaimer.
Version:
- 0.13.0
Last updated:
- 2026-11-06
First released:
- 2025-08-20
License:
- MIT
Supported data:
- Information not submitted
Plugin type:
Save extension:
Python versions supported:
3.12, 3.13Operating system:
- Information not submitted
Requirements:
- numpy
- magicgui
- qtpy
- superqt
- scikit-image
- pyqtgraph
- czitools>=0.22.1
- czitools>=0.27.3; extra == "vzip"
- refkv[images,zarr]>=0.2.0; extra == "vzip"
- refkv[images,zarr]>=0.2.0; extra == "testing"
- tox; extra == "testing"
- pytest<9.2; extra == "testing"
- pytest-cov; extra == "testing"
- pytest-mock; extra == "testing"
- pytest-qt; extra == "testing"
- pytest-timeout; extra == "testing"
- pytest-forked; extra == "testing"
- napari; extra == "testing"
- pyqt6!=6.11.0,!=6.11.1,>=6.7; extra == "testing"

