Skip to main content

Fast Leica LIF file reader written in python

Project description

Documentation Status CI-Tests

readlif README file

The readlif package was developed to be a fast, python only, reader for Leica Lif files. This is tested in Python 3.6 through 3.9.

The basic premise is to read an image from a Lif file into a Pillow object. The only additional requirement for this package is Pillow>=7.2.0.

This code is inspired by the Open Microscopy Bio-Formats project.

Auto-generated documentation is available here.


This package is available on pypi, so you can install it with pip

pip install readlif

Alternatively, clone the git repo and install with setuptools

python install

Known issues

There may be an issue where a truncated 16-bit file will load incorrectly, however this is not tested. If you have an example file, open an issue!

There is not support for FlipX, FlipY and SwapXY metadata. If you need this, please open an issue!

12- and 16-bit images

As of 0.3.0, reaflif will now support images with bit depth greater than 8.

However, note that while some images will be returned as a 16 bit array, they may actually 10 or 12 bit images. It is not simple to easily convert these without the potential of losing data, so a new bit_depth attribute has been added to LifImage to indicate the bit depth of each channel in the image.

It is up to the user to decide how, or if, to convert these. There is an upscaling example below.


Everything in this package is numbered starting from 0, which is not consistent with how things like ImageJ operate.

The basic object is the LifFile object.

from readlif.reader import LifFile
new = LifFile('./path/to/file.lif')

This object contains a few methods to access the images contained within the Lif file. All images, in a folder or not, will be accessible sequentially from the LifFile object.

# Access a specific image directly
img_0 = new.get_image(0)
# Create a list of images using a generator
img_list = [i for i in new.get_iter_image()]

The resulting LifImage object has a few methods to access the specific two-dimensional frame contained in the image, where z is the z position, t is the timepoint, and c is the channel.

# Access a specific item
img_0.get_frame(z=0, t=0, c=0)
# Iterate over different items
frame_list   = [i for i in img_0.get_iter_t(c=0, z=0)]
z_list       = [i for i in img_0.get_iter_z(t=0, c=0)]
channel_list = [i for i in img_0.get_iter_c(t=0, z=0)]

The two dimensional images returned by these methods are Pillow objects, so the applicable methods (.show()) will work with them.

If it is necessary to scale a 12-bit image to the full 16-bit range, it is possible to do this with numpy.

import numpy as np

# Assumes all channels have the same bit depth
scale_factor = (16 - img_0.bit_depth[0]) ** 2  
frame = img_0.get_frame(z=0, t=0, c=0)
img_array = np.uint16(np.array(frame) * scale_factor)


This has only been tested on Lif files that were generated with Leica LAS X and Leica LAS AF. There will likely be files that will not work with this software. In that case, please open an issue on github!



  • Fixed critical documentaiton error:
    • LifImage.scale is in px/µm, not px/nm for X and Y dimensions


  • Added support for tiled images
    • m was added as a new dimension (for tiled images)
    • LifImage changes:
      • New get_iter_m() function
      • New mosaic_position attribute with (FieldX, FieldY, PosX, PosY)
  • Under the hood changes
    • LifImage.dims is now a named tuple for clearer code
  • Other things
    • Prettier outputs for repr()
    • Switch to github CI


  • Added error message for tiled images, pending feature addition


  • Added support for 16-bit images, increased minimum Pillow version to 7.2.0.
    • New LifImage attribute bit_depth is a tuple of intigers descibing the bit depth for each channel in the image.
  • Changed type from str to int for dims and channels in the info dictionary
  • Added python 3.9 to build testing


  • Fixed ZeroDivisionError when the Z-dimension is defined, but has a length of 0. Clarified an error message. Added fix for truncated files.


  • LifImage.scale now returns px/nm conversions


  • Style changes


  • Initial release

Project details

Download files

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

Source Distribution

readlif-0.4.1.tar.gz (10.9 kB view hashes)

Uploaded source

Built Distribution

readlif-0.4.1-py3-none-any.whl (21.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page