Documentation for readlif

class readlif.reader.LifFile(filename)

Given a path or buffer to a lif file, returns objects containing the image and data.

This is based on the java openmicroscopy bioformats lif reading code that is here: https://github.com/openmicroscopy/bioformats/blob/master/components/formats-gpl/src/loci/formats/in/LIFReader.java # noqa

Variables:
  • xml_header (string) – The LIF xml header with tons of data
  • xml_root (ElementTree) – ElementTree XML representation
  • offsets (list) – Byte positions of the files
  • num_images (int) – Number of images
  • image_list (dict) – Has the keys: path, folder_name, folder_uuid, name, image_id, frames

Example

>>> from readlif.reader import LifFile
>>> new = LifFile('./path/to/file.lif')
>>> for image in new.get_iter_image():
>>>     for frame in image.get_iter_t():
>>>         frame.image_info['name']
>>>         # do stuff
>>> # For non-xy imaging experiments
>>> img_0 = new.get_image(0)
>>> for i in range(0, img_0.dims_n[4]):
>>>     plane = img_0.get_plane(requested_dims = {4: i})
get_image(img_n=0)

Specify the image number, and this returns a LifImage object of that image.

Parameters:img_n (int) – Image number to retrieve
Returns:LifImage object with specified image
get_iter_image(img_n=0)

Returns an iterator of LifImage objects in the lif file.

Parameters:img_n (int) – Image to start iteration at
Returns:Iterator of LifImage objects.
class readlif.reader.LifImage(image_info, offsets, filename)

This should not be called directly. This should be generated while calling get_image or get_iter_image from a LifFile object.

Variables:
  • path (str) – path / name of the image
  • dims (tuple) – (x, y, z, t, m)
  • display_dims (tuple) – The first two dimensions of the lif file. This is used to decide what dimensions are returned in a 2D plane.
  • dims_n (dict) –

    {0: length, 1: length, 2: length, n: length}

    For atypical imaging experiments, i.e. those not simple photos of XY frames, this attribute will be more useful than dims. This attribute will hold a dictionary with the length of each dimension, in the order it is referenced in the .lif file.

    Currently, only some of the 10 possible dimensions are used / known:

    • 1: x-axis
    • 2: y-axis
    • 3: z-axis
    • 4: time
    • 5: detection wavelength
    • 6-8: Unknown
    • 9: illumination wavelength
    • 10: mosaic tile
  • name (str) – image name
  • offsets (list) – Byte position offsets for each image.
  • filename (str, bytes, os.PathLike, io.IOBase) – The name of the LIF file being read
  • channels (int) – Number of channels in the image
  • nz (int) –

    number of ‘z’ frames

    Note, it is recommended to use dims.z instead. However, this will be kept for compatibility.

  • nt (int) –

    number of ‘t’ frames

    Note, it is recommended to use dims.t instead. However, this will be kept for compatibility.

  • scale (tuple) –

    (scale_x, scale_y, scale_z, scale_t).

    Conversion factor: px/µm for x, y and z; images/frame for t. For time, this is the duration for the entire image acquisition.

  • scale_n (dict) –

    {1: scale_x, 2: scale_y, 3: scale_z, 4: scale_t}.

    Conversion factor: px/µm for x, y and z; images/sec for t. Related to dims_n above.

  • bit_depth (tuple) – A tuple of ints that indicates the bit depth of each channel in the image.
  • mosaic_position (list) – If the image is a mosaic (tiled), this contains a list of tuples with four values: (FieldX, FieldY, PosX, PosY). The length of this list is equal to the number of tiles.
  • settings (dict) – ATLConfocalSettingDefinition (if it exists), which contains values like NumericalAperture and Magnification.
  • info (dict) – Direct access to data dict from LifFile, this is most useful for debugging. These are values pulled from the Leica XML.
get_frame(z=0, t=0, c=0, m=0)

Gets the specified frame (z, t, c, m) from image.

Parameters:
  • z (int) – z position
  • t (int) – time point
  • c (int) – channel
  • m (int) – mosaic image
Returns:

Pillow Image object

get_iter_c(z=0, t=0, m=0)

Returns an iterator over the channels at time t and position z.

Parameters:
  • z (int) – z position
  • t (int) – time point
  • m (int) – mosaic image
Returns:

Iterator of Pillow Image objects

get_iter_m(z=0, t=0, c=0)

Returns an iterator over the z series of time t and channel c.

Parameters:
  • t (int) – time point
  • c (int) – channel
  • z (int) – z position
Returns:

Iterator of Pillow Image objects

get_iter_t(z=0, c=0, m=0)

Returns an iterator over time t at position z and channel c.

Parameters:
  • z (int) – z position
  • c (int) – channel
  • m (int) – mosaic image
Returns:

Iterator of Pillow Image objects

get_iter_z(t=0, c=0, m=0)

Returns an iterator over the z series of time t and channel c.

Parameters:
  • t (int) – time point
  • c (int) – channel
  • m (int) – mosaic image
Returns:

Iterator of Pillow Image objects

get_plane(display_dims=None, c=0, requested_dims=None)

Gets the specified frame from image.

Known issue: LASX Navigator saves channel as the second channel, this reader will fail in that case.

Parameters:
  • display_dims (tuple) – Two value tuple (1, 2) specifying the two dimension plane to return. This will default to the first two dimensions in the LifFile, specified by LifFile.display_dims
  • c (int) – channel
  • requested_dims (dict) – Dictionary indicating the item to be returned, as described by a numerical dictionary, ex: {3: 0, 4: 1}
Returns:

Pillow Image object

readlif.utilities.get_xml(filename)

Given a lif file, returns two values (xml_root, xml_header) where xml_root is an ElementTree root, and xml_header is the text.

This is useful for debugging.

Some private functions are used from readlif.reader.

Parameters:filename (string) – what file to open?

Indices and tables