Skip to main content

Fast Leica Image Format (LIF) file reader

Project description

readlif

The readlif package is a fast, pure Python reader for Leica Image Format (LIF) files. It supports Python 3.9 and above.

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

Auto-generated documentation is available here.

Project status: Ownership change

In September 2024, ownership of the readlif package was transferred from Nick Negretti, its original author, to Arcadia Science. We are committed to maintaining and improving this project for the imaging community as part of Arcadia's committment to open science. For any questions or support, please open an issue in this repo.

Roadmap

The following is a summary of recent and planned changes to the readlif package by Arcadia Science:

  • [Done] Fix a bug related to reading 16-bit images.
  • [Done] Use ruff for formatting and linting.
  • [Done] migrate to pyproject.toml for package configuration.
  • [Planned] add support for reading 32-bit images.
  • [Planned] add support for extracting relevant metadata from the raw XML metadata embedded in LIF files.
  • [Planned] refactor the get_plane method to make it easier to use.
  • [Planned] improve tests using realistic test files from internal sources.

Installation

This package is available on PyPI, so it can be installed with pip:

pip install readlif

Development

Please see the DEVELOPMENT.md readme for information on how to set up a development environment for this package.

Usage

LIF files are represented by LifFile instances. These objects can be created by passing the path to a LIF file:

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

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

# Access a specific image directly.
image_0 = new.get_image(0)

# Create a list of images using a generator.
all_images = [image for image in lif_file.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 frame in the image.
image_0.get_frame(z=0, t=0, c=0)

# Iterate over different dimensions, holding the other dimensions fixed.
images = [image for image in image_0.get_iter_t(c=0, z=0)]
images = [image for image in image_0.get_iter_z(t=0, c=0)]
images = [image for image in image_0.get_iter_c(t=0, z=0)]

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

Known issues

Below are known issues and limitations with the readlif package. If you encounter these issues, please open an issue.

  • There may be an issue where a truncated 16-bit file will load incorrectly; however, this is not tested.

  • There is not support for FlipX, FlipY and SwapXY metadata.

  • Truncated images are returned as blank images.

  • There is currently no support for returning arbitrary planes from get_plane by specifying display_dims.

  • The package has only been tested with LIF files that were generated with Leica LAS X and Leica LAS AF. It may not work with LIF files from other sources.

Note about 16-bit images

As of 0.3.0, reaflif supports images with bit depths greater than 8.

However, while some images will be returned as 16-bit arrays, the image data in the LIF file may actually be 10- or 12-bit. The original bit depth of each channel can be found in the bit_depth attribute of LifImage.

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.6.6.tar.gz (25.3 kB view details)

Uploaded Source

Built Distribution

readlif-0.6.6-py3-none-any.whl (24.3 kB view details)

Uploaded Python 3

File details

Details for the file readlif-0.6.6.tar.gz.

File metadata

  • Download URL: readlif-0.6.6.tar.gz
  • Upload date:
  • Size: 25.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.0 Darwin/22.6.0

File hashes

Hashes for readlif-0.6.6.tar.gz
Algorithm Hash digest
SHA256 54620db7d9532afbff7fa2ba5f05d96b5b79d351213b91edd88d15145c7a6b4b
MD5 1843afc3980cf436ac60226cf9b6cc0e
BLAKE2b-256 a1ae1f9e205c22c14920ea21f64ca26bd5fdae05d23cf049099bcee26fda31b0

See more details on using hashes here.

File details

Details for the file readlif-0.6.6-py3-none-any.whl.

File metadata

  • Download URL: readlif-0.6.6-py3-none-any.whl
  • Upload date:
  • Size: 24.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.0 Darwin/22.6.0

File hashes

Hashes for readlif-0.6.6-py3-none-any.whl
Algorithm Hash digest
SHA256 f7dc4d515a4cd992ecc064fcd88552f48c8a33ac811c7d2c33cb155b0c889d84
MD5 b56cb801be36bdcf0c018a712b8183c6
BLAKE2b-256 e96fb4736b507ede5ffd6abb1d9e3957e154d6e367823ac9ea9d88a10633f21e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page