Metadata-Version: 2.4
Name: libertem-holo
Version: 1.0.0
Summary: Electron holography reconstruction using LiberTEM
Project-URL: Repository, https://github.com/LiberTEM/LiberTEM-holo
Project-URL: Documentation, https://libertem.github.io/LiberTEM-holo
Author-email: Alexander Clausen <a.clausen@fz-juelich.de>, Malika Khelfallah <m.khelfallah@fz-juelich.de>, Dieter Weber <d.weber@fz-juelich.de>, Patrick Adrian <patrick.adrian.gunawan@stud.th-luebeck.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: electron microscopy,holography,off-axis holography
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: empyre
Requires-Dist: libertem
Requires-Dist: natsort
Requires-Dist: ncempy
Requires-Dist: numba<0.66,>=0.55; python_version < '3.11'
Requires-Dist: numba<0.66,>=0.57; python_version < '3.12'
Requires-Dist: numba<0.66,>=0.59; python_version < '3.13'
Requires-Dist: numba<0.66,>=0.61; python_version < '3.14' and python_version >= '3.10'
Requires-Dist: numba<0.66,>=0.61; python_version >= '3.15'
Requires-Dist: numba<0.66,>=0.63; python_version < '3.15' and python_version >= '3.14'
Requires-Dist: numpy
Requires-Dist: scikit-image
Requires-Dist: scipy
Requires-Dist: sparse
Requires-Dist: sparseconverter
Provides-Extra: gpu
Requires-Dist: numba-cuda; extra == 'gpu'
Provides-Extra: gui
Requires-Dist: bokeh; extra == 'gui'
Requires-Dist: panel; extra == 'gui'
Description-Content-Type: text/x-rst

|docs|_ |gitter|_ |github|_ |precommit|_ |pypi|_

.. |docs| image:: https://img.shields.io/badge/%F0%9F%95%AE-docs-green.svg
.. _docs: https://libertem.github.io/LiberTEM-holo/

.. |gitter| image:: https://badges.gitter.im/join_chat.svg
.. _gitter: https://gitter.im/LiberTEM/Lobby

.. |github| image:: https://img.shields.io/badge/GitHub-GPLv3-informational
.. _github: https://github.com/LiberTEM/LiberTEM-holo/

.. |precommit| image:: https://results.pre-commit.ci/badge/github/LiberTEM/LiberTEM-holo/master.svg
.. _precommit: https://results.pre-commit.ci/latest/github/LiberTEM/LiberTEM-holo/master

.. |pypi| image:: https://badge.fury.io/py/libertem-holo.svg
.. _pypi: https://pypi.org/project/libertem-holo/

LiberTEM-holo
=============

LiberTEM-holo is an open source Python library for holography reconstruction using LiberTEM.
Electron Holograms are captured by interfering two parts of a coherent electron
beam passing through (1) vacuum and (2) a sample. An electron biprism is used
to interfere the two parts of this electron beam. The interference pattern is
recorded, and the complex waveform can be reconstructed from it using this
software. From the phase of the complex waveform one can then for example
determine the magnetic signal from the sample.

More information can be found on `Wikipedia 
<https://en.wikipedia.org/wiki/Electron_holography>`_ or the `Handbook of
Microscopy <https://doi.org/10.1007/978-3-030-00069-1_16>`_.

Goals
-----
- Support good Open Science practices (open source, reproducibility, interoperability)
- Fast workflows for a faster turn-around time; support full reconstruction on the GPU
- Suitability for live- near-live reconstruction and integration into automated acquisition workflows
- Platform for developments in this area (example: phase unwrapping implementations)
- Full- or semi-automatic operation from hologram stack to phase image
- Include analyses that follow reconstruction of the phase image

Workflow
--------

This software focuses on the steps required to reconstruct the electron phase
from stacks of electron holograms. In general, the steps required to
reconstruct the electron holograms to phase images are:

(1) Complex image reconstruction from electron holograms - most parameters can
    be determined automatically. Two customizable filters - circle and line
    `butterworths filters <https://en.wikipedia.org/wiki/Butterworth_filter>`_ are
    available to select the side band and filter out the fresnel fringes in the
    image. The complex image can be calculated from the filtered fft.

(2) Stack alignment - if an image stack was acquired for improving the signal,
    the sample drift and biprism drift can be compensated. The
    sample drift is calculated using cross-correlation. The `cross correlation
    <https://en.wikipedia.org/wiki/Cross-correlation>`_ is usually performed on the
    amplitude of the complex images, or a separate brightfield reconstruction of
    the holograms. The drift is applied on the complex stack. The
    biprism drift appears as a phase drift in the complex image. This phase drift
    is compensated using the `angular synchronization
    <https://arxiv.org/pdf/2005.02032>`_ method by `Filbir et al.
    <https://doi.org/10.1007/s00041-021-09834-1>`_. After drift correction and
    phase compensation, the complex stacks are summed up to create a single complex
    image. The phase of this complex image is the phase difference induced by the
    sample - this signal could be due to electric or magnetic field (as per
    `Aharonov Bohm effect <https://en.wikipedia.org/wiki/Aharonov%E2%80%93Bohm_effect>`_).

(3) Phase image processing and visualization - phase unwrapping is performend
    and residual phase ramps can be removed at this stage.
    The phase and the contour can then be plotted.

Example jupyter notebooks are available `in the GitHub repository
<https://github.com/LiberTEM/LiberTEM-holo/tree/master/notebooks>`_. 

The `Alignement.ipynb` and `Reconstruction.ipynb`
notebooks are using GPU-accelerated reconstruction on a stack of holograms collected on a iron oxide 
nanoparticles, showing the different functionalities for reconstruction and alignment of phase images for MIP removal.
The datasets are available `on Zenodo Repository 21108532 <https://zenodo.org/records/21108532>`_.

The `UDF/stack-reconstruction.ipynb` notebook is based on User Defined Function and using efficient CPU
parallelization for large stack reconstruction. The holograms were acquired on a magnetic YIG lamella. The dataset is available
`on Zenodo Repository 15222400 <https://zenodo.org/records/15222400>`_.

Installation
------------

If you are using conda, for example via `miniforge <https://conda-forge.org/download/>`_,
installation into a new environment can be done as follows:

.. code-block:: shell

  $ conda create -n holo python=3.12
  $ conda activate holo
  $ pip install libertem-holo

For GPU support, install the :code:`gpu` extra, and cupy. For example

.. code-block:: shell

  $ conda create -n holo python=3.12
  $ conda activate holo
  $ pip install libertem-holo[gpu] cupy-cuda13x 'cuda-toolkit[all]<14'

Make sure to pick a CUDA version that works with your GPU and its drivers.
For more details, please check the
`CuPy installation guide <https://docs.cupy.dev/en/latest/install.html>`_.

For using the GUI components, install the :code:`gui` extra:

.. code-block:: shell

  $ pip install libertem-holo[gui]

Input File formats
------------------
LiberTEM-holo was designed specfically for working on larger stacks of images
without loading them into memory. In addition to files created by Gatan Digital
Micrograph (.dm3, .dm4), any file format
`supported by LiberTEM <https://github.com/LiberTEM/LiberTEM>`_ can be loaded.

License
-------

LiberTEM-holo is licensed under GPLv3.
