..
  This file is generated by setup.py

Read Leica image files (LIF, LOF, XLIF, XLCF, XLEF, and LIFEXT)
===============================================================

Liffile is a Python library to read image and metadata from Leica image files:
LIF (Leica Image File), LOF (Leica Object File), XLIF (XML Image File),
XLCF (XML Collection File), XLEF (XML Experiment File), and LIFEXT (Leica
Image File Extension). These files are written by LAS X software to store
collections of images and metadata from microscopy experiments.

:Author: `Christoph Gohlke <https://www.cgohlke.com>`_
:License: BSD-3-Clause
:Version: 2026.2.16
:DOI: `10.5281/zenodo.14740657 <https://doi.org/10.5281/zenodo.14740657>`_

Quickstart
----------

Install the liffile package and all dependencies from the
`Python Package Index <https://pypi.org/project/liffile/>`_::

    python -m pip install -U liffile[all]

See `Examples`_ for using the programming interface.

Source code and support are available on
`GitHub <https://github.com/cgohlke/liffile>`_.

Requirements
------------

This revision was tested with the following requirements and dependencies
(other versions may work):

- `CPython <https://www.python.org>`_ 3.11.9, 3.12.10, 3.13.12, 3.14.3 64-bit
- `NumPy <https://pypi.org/project/numpy>`_ 2.4.2
- `Imagecodecs <https://pypi.org/project/imagecodecs>`_ 2026.1.14
  (required for decoding TIFF, JPEG, PNG, and BMP)
- `Tifffile <https://pypi.org/project/tifffile/>`_ 2026.2.16
  (required for reading multi-page TIFF)
- `Xarray <https://pypi.org/project/xarray>`_ 2026.2.0 (recommended)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.10.8 (optional)

Revisions
---------

2026.2.16

- Change timestamps to None if not present (breaking).
- Fix inefficient timestamp parsing.
- Fix inefficient LifFile.close().
- Add tilescan property to LifImage.

2026.2.15

- Add experimental frame-based interface to LifImage.
- Fix code review issues.

2026.1.22

- Fix reading sequence of LifMemoryBlocks.
- Change unknown axis code to '?'.

2026.1.14

- Improve code quality.

2025.12.12

- Remove deprecated LifFile.series and xml_element_smd properties (breaking).
- Improve code quality.

2025.11.8

- Add option to find other LifImageSeries attributes than path.
- Return UniqueID in LifImage.attrs.
- Factor out BinaryFile base class.

2025.9.28

- Derive LifFileError from ValueError.
- Minor fixes.
- Drop support for Python 3.10.

2025.5.10

- Support Python 3.14.

2025.4.12

- Improve case_sensitive_path function.

2025.3.8

- Support LOF files without LMSDataContainerHeader XML element.

2025.3.6

- Support stride-aligned RGB images.

2025.2.20

- …

Refer to the CHANGES file for older revisions.

Notes
-----

`Leica Microsystems GmbH <https://www.leica.com/>`_ is a manufacturer of
microscopes and scientific instruments for the analysis of micro and
nanostructures.

This library is in its early stages of development. It is not feature-complete.
Large, backwards-incompatible changes may occur between revisions.

Specifically, the following features are currently not supported:
XLLF formats, image mosaics and pyramids, reading non-image data such as
FLIM/TCSPC, and bit increments.

The library has been tested with a limited number of version 2 files only.

The Leica image file formats are documented at:

- Leica Image File Formats - LIF, XLEF, XLLF, LOF. Version 3.2.
  Leica Microsystems GmbH. 21 September 2016.
- Annotations to Leica Image File Formats for LAS X Version 3.x. Version 1.4.
  Leica Microsystems GmbH. 24 August 2016.
- TSC SP8 FALCON File Format Description. LAS X Version 3.5.0.

Other implementations for reading Leica image files are
`readlif <https://github.com/Arcadia-Science/readlif>`_ and
`Bio-Formats <https://github.com/ome/bioformats>`_.

Examples
--------

Read a FLIM lifetime image and metadata from a LIF file:

.. code-block:: python

    >>> with LifFile('tests/data/FLIM.lif') as lif:
    ...     for image in lif.images:
    ...         _ = image.name
    ...     image = lif.images['Fast Flim']  # by name
    ...     assert image.dtype == 'float16'
    ...     assert image.sizes == {'Y': 1024, 'X': 1024}
    ...     lifetimes = image.asxarray()
    ...
    >>> lifetimes
    <xarray.DataArray 'Fast Flim' (Y: 1024, X: 1024)> Size: 2MB
    array([[...]],
          shape=(1024, 1024), dtype=float16)
    Coordinates:
      * Y        (Y) float64... 0.0005564
      * X        (X) float64... 0.0005564
    Attributes...
        path:           FLIM_testdata.lif/sample1_slice1/FLIM Compressed/Fast Flim
        UniqueID:       694efd02-95a9-436e-0fa6-f146120b1e15
        F16:            {'Name': 'F16',...
        TileScanInfo:   {'Tile': {'FieldX': 0,...
        ViewerScaling:  {'ChannelScalingInfo': {...

Iterate over selected XLEF image frames in ZTM dimension order:

.. code-block:: python

    >>> with LifFile('tests/data/XYZCST/XYZCST.xlef') as lif:
    ...     image = lif.images[0]  # by index
    ...     image.sizes
    ...     frames = image.frames(C=1, Z=slice(1, 3), T=[1, 0], M=None)
    ...     frames.sizes
    ...     for index, frame in frames.items():
    ...         index, frame.shape
    ...
    {'T': 2, 'M': 4, 'C': 3, 'Z': 5, 'Y': 1200, 'X': 1600}
    {'Z': 2, 'T': 2, 'M': 4, 'Y': 1200, 'X': 1600}
    ((0, 0, 0), (1200, 1600))
    ((0, 0, 1), (1200, 1600))
    ...
    ((1, 1, 2), (1200, 1600))
    ((1, 1, 3), (1200, 1600))

View image and metadata in a LIF file from the console::

    $ python -m liffile tests/data/FLIM.lif