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?