Metadata-Version: 2.4
Name: libertem-holo
Version: 1.0.0rc0
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>, 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 :: 4 - Beta
Classifier: Environment :: Console
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 :: 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 a Python project 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>`_.

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
    real part of the image and 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 - residual phase ramps
    can be removed at this stage and the phase and the contour can 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>`_.

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.
