Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

A python module and a python extension for Zeiss (CZI/ZISRAW) microscopy files.

Project description


C++ Build & Test Python Build & Test codecov License: GPL v3

Python module to expose libCZI functionality for reading (subset of) Zeiss CZI files and meta-data.


The first example show how to work with a standard CZI file (Single or Multe-Scene). The second example shows how to work with a Mosaic CZI file.

Example 1: Read in a czi and select a portion of the image to display

import numpy as np
import pylibczi
import pathlib
from PIL import Image

pth = pathlib.Path('/allen/aics/assay-dev/MicroscopyData/Sue/2019/20190610/20190610_S02-02.czi')
czi = pylibczi.CziFile(pth)

# Get the shape of the data, the coordinate pairs are (start index, size)
dimensions = czi.dims()  # {'Z': (0, 70), 'C': (0, 2), 'T': (0, 146), 'S': (0, 12), 'B': (0, 1)}

# Load the image slice I want from the file
img, shp = czi.read_image(S=4, T=11, C=0, Z=30) 

# shp = [('S', 1), ('T', 1), ('C', 1), ('Z', 1), ('Y', 1300), ('X', 1900)]  # List[(Dimension, size), ...]
# img.shape = (1, 1, 1, 1, 1300, 1900)   # numpy.ndarray

# Normalize the image 
norm_by = np.percentile(img[0, 0, 0,], [50, 99.8])

# Scale the numpy array values and cast them back to integers in the 0 to 255 range
i2 = np.clip((img - norm_by[0])/(norm_by[1]-norm_by[0]), 0, 1)*255

img_disp = Image.fromarray(i2[0,0,0,0,200:1100,500:1000].astype(np.uint8))

Colony Image

Example 2: Read in a mosaic file

import numpy as np
import pylibczi
import pathlib
from PIL import Image

mosaic_file = pathlib.Path('~/Data/20190618_CL001_HB01_Rescan_002.czi').expanduser()
czi = pylibczi.CziFile(mosaic_file)

# Get the shape of the data
dimensions = czi.dims()   # {'C': (0, 5), 'S': (0, 16), 'B': (0, 1)}

czi.is_mosaic()  # True 
 # Mosaic files ignore the S dimension and use an internal mIndex to reconstruct, the scale factor allows one to generate a manageable image
mosaic_data = czi.read_mosaic(C=1, scale_factor=0.1) 

mosaic_data.shape  # (1, 1, 6265, 6998)

norm_by = np.percentile(mosaic_data, [5, 98])
normed_mosaic_data = np.clip((itwo - norm_by[0])/(norm_by[1]-norm_by[0]), 0, 1)*255
img = Image.fromarray(normed_mosaic_data[0,0, 250:750, 250:750].astype(np.uint8))

Mosaic Histology Image


The preferred installation method is with pip install. This will install the pylibczi python module and extension binaries (hosted on PyPI):

pip install pylibczi


Documentation is available on readthedocs.


Use these steps to build and install pylibczi locally:

  • Clone the repository including submodules (--recurse-submodules).
  • Requirements:
    • libCZI requires a c++11 compatible compiler. Built & Tested with clang.
    • Development requirements are those required for libCZI: libpng, zlib
    • Install the package:
      pip install .
      pip install -e .[dev] # for development (-e means editable so changes take effect when made)
      pip install .[all] # for everything including jupyter notebook to work with the Example_Usage above
    • libCZI is automatically built as a submodule and linked statically into pylibczi.
  • Note: If you get the message EXEC : Fatal Python error : initfsencoding: unable to load the file system codec ... ModuleNotFoundError: No module named 'encodings' on windows you need to set PYTHONHOME to be the folder the python.exe you are compiling against lives in.


The GPLv3 license is a consequence of libCZI which imposes GPLv3. If you wish to use libCZI or this derivative in a commercial product you'll need to talk to Zeiss.

Project details

Release history Release notifications

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for aicspylibczi, version 2.1.0
Filename, size File type Python version Upload date Hashes
Filename, size aicspylibczi-2.1.0-cp37-cp37m-macosx_10_13_x86_64.whl (494.3 kB) File type Wheel Python version cp37 Upload date Hashes View hashes
Filename, size aicspylibczi-2.1.0-cp37-cp37m-manylinux2010_x86_64.whl (547.6 kB) File type Wheel Python version cp37 Upload date Hashes View hashes
Filename, size aicspylibczi-2.1.0-cp37-cp37m-win_amd64.whl (386.4 kB) File type Wheel Python version cp37 Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page