..
  This file is generated by setup.py

Read Leica image files (LIF)
============================

Liffile is a Python library to read image and metadata from Leica image files
(LIF). LIF 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: 2025.1.30
: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.10.11, 3.11.9, 3.12.8, 3.13.1 64-bit
- `NumPy <https://pypi.org/project/numpy>`_ 2.2.2
- `Xarray <https://pypi.org/project/xarray>`_ 2025.1.1 (recommended)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.10.0 (optional)
- `Tifffile <https://pypi.org/project/tifffile/>`_ 2025.1.10 (optional)

Revisions
---------

2025.1.30

- Remove LifFile.flim_rawdata (breaking).
- Add index, guid, and xml_element_smd properties to LifImage.

2025.1.26

- Fix image coordinate values.
- Prompt for file name if main is called without arguments.

2025.1.25

- Initial alpha release.

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 implemented:
related Leica file formats (XLEF, XLLF, LOF, LIFEXT), image mosaics and
pyramids, partial image reads, reading non-image data like FLIM/TCSPC,
and heterogeneous channels.

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

The Leica Image File format is 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 LIF 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.series:
    ...         name = image.name
    ...     image = lif.series['Fast Flim']
    ...     assert image.shape == (1024, 1024)
    ...     assert image.dims == ('Y', 'X')
    ...     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
        F16:            {'Name': 'F16',...
        TileScanInfo:   {'Tile': {'FieldX': 0,...
        ViewerScaling:  {'ChannelScalingInfo': {...

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

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