Metadata-Version: 2.4
Name: lfdfiles
Version: 2026.3.18
Summary: Laboratory for Fluorescence Dynamics (LFD) file formats
Home-page: https://www.cgohlke.com
Author: Christoph Gohlke
Author-email: cgohlke@cgohlke.com
License: BSD-3-Clause
Project-URL: Bug Tracker, https://github.com/cgohlke/lfdfiles/issues
Project-URL: Source Code, https://github.com/cgohlke/lfdfiles
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: tifffile
Requires-Dist: click
Provides-Extra: all
Requires-Dist: imagecodecs; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: fbdfile; extra == "all"
Requires-Dist: czifile; extra == "all"
Requires-Dist: oiffile; extra == "all"
Requires-Dist: netpbmfile; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

Laboratory for Fluorescence Dynamics (LFD) file formats
=======================================================

Lfdfiles is a Python library and console script for reading, writing,
converting, and viewing many of the proprietary file formats used
to store experimental data and metadata at the
`Laboratory for Fluorescence Dynamics <https://www.lfd.uci.edu/>`_.
Supported formats include:

- SimFCS VPL, VPP, JRN, BIN, INT, CYL, REF, BH, BHZ, B64, I64, Z64, R64
- FLIMbox FBD, FBF, FBS.XML
- GLOBALS LIF, ASCII
- CCP4 MAP
- Vaa3D RAW
- Bio-Rad(r) PIC
- ISS Vista IFLI, IFI
- FlimFast FLIF

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

Quickstart
----------

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

    python -m pip install -U "lfdfiles[all]"

Print the console script usage::

    python -m lfdfiles --help

The lfdfiles library is type annotated and documented via docstrings.

See `Examples`_ for using the programming interface.

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

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

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

- `CPython <https://www.python.org>`_ 3.12.10, 3.13.12, 3.14.3 64-bit
- `NumPy <https://pypi.org/project/numpy>`_ 2.4.3
- `Tifffile <https://pypi.org/project/tifffile/>`_ 2026.3.3
- `Fbdfile <https://pypi.org/project/fbdfile>`_ 2026.2.6 (optional)
- `Czifile <https://pypi.org/project/czifile/>`_ 2026.3.17 (optional)
- `Oiffile <https://pypi.org/project/oiffile/>`_ 2026.2.8 (optional)
- `Netpbmfile <https://pypi.org/project/netpbmfile/>`_ 2026.1.29 (optional)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.10.8
  (optional, for plotting)
- `Click <https://pypi.python.org/pypi/click>`_ 8.3.1
  (optional, for command line apps)

Revisions
---------

2026.3.18

- Replace LfdFileRegistry metaclass with __init_subclass__.
- Add LfdFile.open classmethod as typed factory for auto-detection.
- Add LfdFile._probe classmethod for cheap file pre-screening.
- Add asarray overrides with typed signatures to select subclasses.
- Convert _components to classmethod.
- Drop support for Python 3.11.

2026.1.14

- Improve code quality.

2025.12.12

- Derive LfdFileError from ValueError.
- Improve code quality.

2025.9.17

- Many breaking changes to FLIMbox functionality (use fbdfile package instead):
- Discourage use of FlimboxFbd, FlimboxFbf, and FlimboxFbs classes.
- Use fbdfile package to implement FlimboxFbd, FlimboxFbf, and FlimboxFbs.
- Remove flimbox_histogram, flimbox_decode, and sflim_decode functions.
- Remove convert_fbd2b64 function and fbd2b64 command line app.
- Remove deprecated SimfcsFbf, and SimfcsFbd classes.
- Remove deprecated simfcsfbd_histogram and simfcsfbd_decode functions.

2025.7.31

- Read variants of SimFCS REF files.
- Drop support for Python 3.10.

2025.5.10

- Mark Cython extension free-threading compatible.
- Remove doctest command line option.
- Support Python 3.14.

2025.3.16

- Replace deprecated tifffile.stripnull function.
- Fix misspelled VistaIfli.header keys.
- Drop support for Python 3.9.

2024.10.24

- …

Refer to the CHANGES file for older revisions.

Notes
-----

The API is not stable yet and might change between revisions.

Python <= 3.11 is no longer supported. 32-bit versions are deprecated.

Many of the LFD file formats are not documented and might change arbitrarily.
This implementation is mostly based on reverse engineering existing files.
No guarantee can be made as to the correctness of code and documentation.

Experimental data are often stored in plain binary files with metadata
available in separate, human readable journal files (`.jrn`).

Unless specified otherwise, data are stored in little-endian, C contiguous
order.

The Laboratory for Fluorescence Dynamics (LFD) was a national research
resource center for biomedical fluorescence spectroscopy funded by the
National Institutes of Health from 1986 to 2022 (grant P41GM103540).

References
----------

The following software is referenced in this module:

1.  `SimFCS <https://www.lfd.uci.edu/globals/>`_, a.k.a. Globals for
    Images, is software for fluorescence image acquisition, analysis, and
    simulation, developed by Enrico Gratton at UCI.
2.  `Globals <https://www.lfd.uci.edu/globals/>`_, a.k.a. Globals for
    Spectroscopy, is software for the analysis of multiple files from
    fluorescence spectroscopy, developed by Enrico Gratton at UIUC and UCI.
3.  ImObj is software for image analysis, developed by LFD at UIUC.
    Implemented on Win16.
4.  `FlimFast <https://www.cgohlke.com/flimfast/>`_ is software for
    frequency-domain, full-field, fluorescence lifetime imaging at video
    rate, developed by Christoph Gohlke at UIUC.
5.  `FLImage <https://www.cgohlke.com/#software>`_ is software for
    frequency-domain, full-field, fluorescence lifetime imaging, developed
    by Christoph Gohlke at UIUC. Implemented in LabVIEW.
6.  FLIez is software for frequency-domain, full-field, fluorescence
    lifetime imaging, developed by Glen Redford at UIUC.
7.  Flie is software for frequency-domain, full-field, fluorescence
    lifetime imaging, developed by Peter Schneider at MPIBPC.
    Implemented on a Sun UltraSPARC.
8.  `FLOP97 <https://www.cgohlke.com/#software>`__ is software for
    frequency-domain, cuvette, fluorescence lifetime measurements, developed
    by Christoph Gohlke at MPIBPC. Implemented in LabVIEW.
9.  `VistaVision <http://www.iss.com/microscopy/software/vistavision.html>`_
    is commercial software for instrument control, data acquisition and data
    processing by ISS Inc (Champaign, IL).
10. `Vaa3D <https://github.com/Vaa3D>`_ is software for multi-dimensional
    data visualization and analysis, developed by the Hanchuan Peng group at
    the Allen Institute.
11. `Voxx <https://voxx.sitehost.iu.edu/>`_ is a volume rendering program
    for 3D microscopy, developed by Jeff Clendenon et al. at the Indiana
    University.
12. `CCP4 <https://www.ccp4.ac.uk/>`_, the Collaborative Computational Project
    No. 4, is software for macromolecular X-Ray crystallography.

Examples
--------

Create a Bio-Rad PIC file from a NumPy array:

>>> data = numpy.arange(1000000).reshape((100, 100, 100)).astype('u1')
>>> bioradpic_write(TEMP / '_biorad.pic', data)

Read the volume data from the PIC file as NumPy array, and access metadata:

>>> with BioradPic(TEMP / '_biorad.pic') as f:
...     f.shape
...     f.spacing
...     data = f.asarray()
...
(100, 100, 100)
(1.0, 1.0, 1.0)

Convert the PIC file to a compressed TIFF file:

>>> with BioradPic(TEMP / '_biorad.pic') as f:
...     f.totiff(TEMP / '_biorad.tif', compression='zlib')
...
