A BioIO reader plugin for reading CZIs using pylibczirw (default) or aicspylibczi.
See the bioio documentation on our GitHub pages site - the general use and installation instructions there will work for this package.
Information about the base reader this package relies on can be found in the bioio-base repository here.
This plugin attempts to follow the latest specification for the CZI file format from Carl Zeiss Microscopy (currently v1.2).
Install bioio-czi alongside bioio:
pip install bioio bioio-czi
Stable Release: pip install bioio-czi
Development Head: pip install git+https://github.com/bioio-devs/bioio-czi.git
bioio-czi can operate in pylibczirw mode (the default) or aicspylibczi mode.
| Feature | pylibczirw mode | aicspylibczi mode |
|---|---|---|
| Read CZIs from the internet | ✅ | ❌ |
| Read single tile from tiled CZI | ❌ | ✅ |
| Read single tile's metadata from tiled CZI | ❌ | ✅ |
| Read elapsed time metadata* | ❌ | ✅ |
| Handle CZIs with different dimensions per scene** | ❌ | ✅ |
| Read stitched mosaic of a tiled CZI | ✅ | ✅ |
The primary difference is that pylibczirw supports reading CZIs over the internet but cannot access individual tiles from a tiled CZI. To use aicspylibczi, add the use_aicspylibczi=True parameter when creating a reader. For example: from bioio import BioImage; img = BioImage(..., use_aicspylibczi=True).
*Elapsed time metadata include the following. These are derived from individual subblock metadata.
BioImage(...).time_intervalBioImage(...).standard_metadata.timelapse_intervalBioImage(...).standard_metadata.total_time_duration
**The underlying pylibczirw reader assumes that each scene has the same dimension. Files that do not meet this requirement may be read incorrectly in pylibczirw mode.
from bioio import BioImage
path = (
"https://allencell.s3.amazonaws.com/aics/hipsc_12x_overview_image_dataset/"
"stitchedwelloverviewimagepath/05080558_3500003720_10X_20191220_D3.czi"
)
img = BioImage(path)
print(img.shape) # (1, 1, 1, 5684, 5925)Note: accessing files from the internet is not available in aicspylibczi mode.
img = BioImage(
"S=2_4x2_T=2=Z=3_CH=2.czi",
reconstruct_mosaic=False,
include_subblock_metadata=True,
use_aicspylibczi=True
)
print(img.dims) # <Dimensions [M: 8, T: 2, C: 2, Z: 3, Y: 256, X: 256]>
subblocks = img.metadata.findall("./Subblocks/Subblock")
print(len(subblocks)) # 192
print(img.get_image_data("TCZYX", M=3).shape) # (2, 2, 3, 256, 256)The M dimension is used to select a specific tile.
img = BioImage("S=2_4x2_T=2=Z=3_CH=2.czi")
print(img.dims) # <Dimensions [T: 2, C: 2, Z: 3, Y: 487, X: 947]>All 8 tiles are stitched together. Where tiles overlap, the pixel value is the pixel value from the tile with the highest M-index.
This example shows a simple use case for just accessing the pixel data of the image
by explicitly passing this Reader into the BioImage. Passing the Reader into
the BioImage instance is optional as bioio will automatically detect installed
plug-ins and auto-select the most recently installed plug-in that supports the file
passed in.
from bioio import BioImage
import bioio_czi
img = BioImage("my_file.czi", reader=bioio_czi.Reader)
img.dataClick here to view all open issues in bioio-devs organization at once or check this repository's issue tab.
See CONTRIBUTING.md for information related to developing the code.