API Reference

Input/output

Basic I/O for holography data.

We mostly want to support loading holograms from DM{3,4} files, and save results as numpy .npz files.

class libertem_holo.base.io.InputData(files: list[InputFile])

Input data from one or more files.

property data: InputSlicer

Access slices of the input data.

Example:

>>> i = InputData.load_from_dm(path="something.dm4")  
>>> i.data[8]  # return the 8th slice of the input data  
array([...])

property dtype: dtype[Any]

The numpy dtype of the data.

property exposure_time: float

Exposure time, in seconds.

In case of a stack, this is the sum of all exposure times.

files: list[InputFile]

ordered list of input files

classmethod from_array(data: ndarray, pixelsize: float | None = None, exposure_time: float | None = None, tags: dict[str, Any] | None = None) → InputData

Create InputData from an array.

classmethod load_from_dm(path: str | Path) → InputData

Load .dm3 or .dm4. Assumes a single 2D or 3D data set per file.

classmethod load_from_glob(*, base_path: str | Path, pattern: str, sort_files: bool = True) → InputData

Load from a glob (for example stack_1/image_*.dm4).

Parameters:

• base_path – path prefix where the data is stored

• pattern – glob pattern to match against

• sort_files – Whether the list of files should be sorted naturally (using natsort) - if disabled, files will be read in an undefined order.

Example

>>> InputData.load_from_glob(
...     base_path="/data/stack-1/",
...     pattern="*.dm4")  

classmethod load_from_list(paths: Sequence[str | pathlib.Path]) → InputData

Load from an ordered list of .dm3 or .dm4 files.

Each file should contain a single 2D image.

property pixelsize: float | None

Pixel size in m.

property shape: tuple[int, int, int]

The 3D shape of the data.

tags_for_slice(z: int) → dict[str, Any] | None

Raw dictionary of tags for slize z.

zslice(z: int) → ndarray

From a 3D stack, load a single image/slice.

class libertem_holo.base.io.Results(complex_wave: np.ndarray[tuple[int, int], npd.Complex64DType | npd.Complex128DType], unwrapped_phase: np.ndarray[tuple[int, int], npd.Float16DType | npd.Float32DType | npd.Float64DType] | None = None, brightfield: np.ndarray[tuple[int, int], npd.Float16DType | npd.Float32DType | npd.Float64DType] | None = None, metadata: dict[str, Any] | None = None)

Reconstruction results.

Parameters:

• complex_wave (np.ndarray[tuple[int, int], npd.Complex64DType | npd.Complex128DType]) – the (averaged) complex wave as 2D numpy array (dtype complex64 or complex128)

• unwrapped_phase (np.ndarray[tuple[int, int], npd.Float16DType | npd.Float32DType | npd.Float64DType] | None) – 2D numpy array of unwrapped phase (dtype float32 or float64)

• brightfield (np.ndarray[tuple[int, int], npd.Float16DType | npd.Float32DType | npd.Float64DType] | None) – 2D numpy array of a brightfield reconstruction from the centerband (dtype float32 or float64)

• metadata (dict[str, Any] | None) – Dictionary of custom metadata. The values have to be json-serializable (roughly numbers, strings, lists or dicts of these)

classmethod load(path: str | pathlib.Path) → Results

Load a result that was previously saved using the save method.

metadata_from_input(input_data: InputData, params: HoloParams | None = None) → None

Update metadata from input_data.

The following keys will be set:

• stack_shape

• exposure_time

• effective_pixelsize if params are given and input_data has a pixel size

• acquisition_timestamp if available in the input data tags (formatted in ISO format)

Parameters:

• input_data – The input hologram or hologram stack

• params – The HoloParams used for the reconstruction

save(path: str | pathlib.Path) → None

Save result data as npz file.

Parameters:

path – The path to the .npz file that will be created

Base holography functions

Reconstruction

Core reconstruction functions of LiberTEM-holo.

This includes both FFT-based and phase-shifting approaches.

libertem_holo.base.reconstr.display_fft_image(image: ndarray, sb_position: tuple[int, int], slice_fft: ndarray, mask: ndarray = 1, detail: bool = True) → None

Display an fft image.

This function helps to show the steps of the reconstruction and to define the best length and width of line mask

Parameters:

• image (array) – the input image

• sb_position (tuple) – the sideband position (y, x), referred to the non-shifted FFT.

• fft (slice) – contain minimum and maximum value in y and x axis.

• mask (array) – contain the aperture and line mask

• detail (bolean) –

libertem_holo.base.reconstr.estimate_omega(image: ndarray, sideband_position: tuple[float, float], *, flip: bool = False) → tuple[float, float]

Estimates the frequency carrier of the hologram.

Parameters:

• image (array) – Holographic data array

• sideband_position (tuple) – The sideband position (y, x), referred to the non-shifted FFT.

• flip – ??? TODO

Returns:

omega – frequency carrier in y and x axis

Return type:

tuple

libertem_holo.base.reconstr.get_phase(hologram: ~numpy.ndarray, params: ~libertem_holo.base.utils.HoloParams, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → ndarray

Reconstruct hologram using HoloParams and extract and unwrap phase.

libertem_holo.base.reconstr.phase_offset_correction(aligned_stack: ~numpy.ndarray[tuple[int, int, int]], wtype: ~typing.Literal['weighted', 'unweighted'] = 'weighted', threshold: float = 1e-12, return_stack: bool = False, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → tuple[ndarray, ndarray, ndarray | None]

Correct for phase offset in a stack of complex images.

This corrects for the phase drift in the holograms due to the biprism drift with time. Since we are dealing with the phase of the image which wraps from -pi to pi a simple scalar correction of the phase doesnt work as the phase wraps around the phase axis. So the options for a solution would be either iterative solution which is computationally heavy or an eigenvalue solution which is implemented here.

We start with a stack of holograms acquired using Holoworks or stack acquisition and this function returns a phase corrected complex image and optionally a stack of the phase corrected complex images before averaging.

Adapted from a function by oleh.melnyk: https://github.com/Ptychography-4-0/ptychography/blob/master/src/ptychography40/stitching/stitching.py for more details, see https://arxiv.org/pdf/2005.02032.pdf

Parameters:

aligned_stack

Array of shape (N, sy, sx) where N is the number of complex images; should have dtype complex64 or complex128.

threshold

Minimum absolute value to be considered in finding the phase match for stitching.

wtype

Selected type of weights to be used in the angular synchronization There are 2 possible choices: “unweighted” or “weighted”, depending on usage or not of the weights for angular synchronization (explained above)

return_stack

Also returns a stack shaped like the input stack, where the phase offset correction is applied.

xp

Either numpy or cupy for GPU support

libertem_holo.base.reconstr.reconstruct_bf(frame: ~numpy.ndarray[tuple[int, int]], aperture: ~numpy.ndarray, slice_fft: tuple[slice, slice], *, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → ndarray

Reconstruct a brightfield image from a hologram.

Please use libertem_holo.base.filter.central_line_filter() to filter out fresnel fringes as appropriate.

libertem_holo.base.reconstr.reconstruct_direct(stack: ndarray[tuple[int, int, int]], omega: tuple[float, float]) → ndarray

Reconstruct a stack of phase shifted holograms.

This is using the direct reconstruction method.

Parameters:

• stack (array_like) – Stack of holograms

• omega (tuple) – frequency carrier in y and x axis

Returns:

phase final – the reconstructed phase image

Return type:

2D array

libertem_holo.base.reconstr.reconstruct_direct_euler(stack: ndarray[tuple[int, int, int]], omega: tuple[float, float]) → ndarray[tuple[int, int]]

Reconstruct a stack of phase shifted holograms.

This is using the direct reconstruction method by Ru et.al. 1994 (euler form)

Parameters:

• stack – Holographic data array

• omega – frequency carrier in y and x axis

Returns:

phase final – the reconstructed phase image

Return type:

2D array

libertem_holo.base.reconstr.reconstruct_double_resolution(frames: ~numpy.ndarray, sb_pos: tuple[float, float], aperture: ~numpy.ndarray, slice_fft: tuple[slice, slice], *, precision: bool = True, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → ndarray

Reconstruct a stack of phase shifted holography with double resolution method.

Parameters:

• frames (array_like) – Two holograms taken at a phase offset of π; shape (2, height, width)

• sb_pos – The sideband position, for example as returned by estimate_sideband_position

• aperture – A numpy or cupy array containing the aperture to apply in fourier space

• slice_fft – A slice to crop to the selected output shape in fourier space, as returned by get_slice_fft.

• precision – Defines precision of the reconstruction, True for complex128 for the resulting complex wave, otherwise results will be complex64

• xp – Pass in either the numpy or cupy module to select CPU or GPU processing

Returns:

wav – the reconstructed complex image

Return type:

complex array

libertem_holo.base.reconstr.reconstruct_frame(frame: ~numpy.ndarray[tuple[int, int]], sb_pos: tuple[float, float], aperture: ~numpy.ndarray, slice_fft: tuple[slice, slice], *, precision: bool = True, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → ndarray

Reconstruct a single hologram.

Parameters:

• frame – A numpy or cupy array containing the input hologram

• sb_pos – The sideband position, for example as returned by estimate_sideband_position

• aperture – A numpy or cupy array containing the aperture to apply in fourier space

• slice_fft – A slice to crop to the selected output shape in fourier space, as returned by get_slice_fft.

• precision – Defines precision of the reconstruction, True for complex128 for the resulting complex wave, otherwise results will be complex64

• xp – Pass in either the numpy or cupy module to select CPU or GPU processing

Image filtering and aperture building

Useful image filtering helpers.

libertem_holo.base.filters.butterworth_disk(shape: tuple[int, int], radius: float, order: int = 12, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Generate a filered disk-shaped aperture.

The edges are filtered with a butterworth filter of the given order.

Parameters:

• shape – output shape of the aperture

• radius – radius in pixels

• order – order of the butterworth filter

• xp – Either numpy or cupy

libertem_holo.base.filters.butterworth_line(shape: tuple[int, int], width: float, sb_position: tuple[int, int], length_ratio: float = 0.9, order: int = 12, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Generate a line filter.

This is useful to remove fresnel fringes.

Parameters:

• shape – output shape of the aperture

• width – width of the line in pixels

• order – order of the butterworth filter

• xp – Either numpy or cupy

libertem_holo.base.filters.central_line_filter(sb_position, out_shape, orig_shape, length_ratio=0.9, width=20, crop_to_out_shape=False)

Return a line filter for the central band, that can be applied by multiplying it with the aperture.

libertem_holo.base.filters.clipped(img: ndarray, sigma: float = 6)

Mask out outliers.

Return img, but with pixels deviating more than sigma from the mean masked out.

Useful for plotting:

>>> plt.imshow(img, vmax=np.max(clipped(img)))  

libertem_holo.base.filters.disk_aperture(out_shape: tuple[int, int], radius: float, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → ndarray

Generate a disk-shaped aperture

Parameters:

• out_shape (interger) – Shape of the output array

• radius (float) – Radius of the disk

• xp – Either numpy or cupy

Returns:

2d array containing aperture

Return type:

aperture

libertem_holo.base.filters.exclusion_mask(img: ndarray, sigma: float = 6) → ndarray

Generate outlier mask.

Return a mask with True entries for pixels deviating more than sigma from the mean.

libertem_holo.base.filters.highpass(img: ndarray, sigma: float = 2) → ndarray

Return highpass by subtracting a gaussian lowpass filter.

libertem_holo.base.filters.line_filter(sb_position, out_shape, orig_shape, length_ratio=0.9, width=20, crop_to_out_shape=True)

Return a line filter for the sideband.

It can be applied by multiplying it with the aperture. The filter has the zero frequency at the center of the image.

libertem_holo.base.filters.phase_unwrap(image)

A phase_unwrap function that is unwrap the complex / wrapped phase image.

Parameters:

image (2d nd array) – Complex or Wrapped phase image

Return type:

2d nd array of the unwrapped phase image

libertem_holo.base.filters.remove_dead_pixels(img, sigma_lowpass=2.0, sigma_exclusion=6.0)

Remove dead pixels.

Parameters:

• img (np.array) – Input array

• sigma_lowpass (float) – How much of the low frequencies should be removed before finding bad pixels

• sigma_exclusion (float) – Pixels deviating more than this value from the mean will be removed

libertem_holo.base.filters.window_filter(input_array, window_type, window_shape)

Apply window-based filter.

Return a filtered array with the same size of the input array

Parameters:

• input_array (array) – Input array

• window_type (string, float or tuple) – The type of window to be created. Any window type supported by scipy.signal.get_window is allowed here. See notes below for a current list, or the SciPy documentation for the version of SciPy on your machine.

• window_shape (tuple of int or int) – The shape of the window. If an integer is provided, a 2D window is generated.

Notes

This function is based on scipy.signal.get_window and thus can access all of the window types available to that function (e.g., "hann", "boxcar"). Note that certain window types require parameters that have to be supplied with the window name as a tuple (e.g., ("tukey", 0.8)). If only a float is supplied, it is interpreted as the beta parameter of the Kaiser window. https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.windows.get_window.html

it is recommended to check the that after fft shift, the input array has value of 0 at the border.

Stack alignment

class libertem_holo.base.align.AmplitudeCorrelator(holoparams: ~libertem_holo.base.utils.HoloParams, upsample_factor: int = 1, normalization: ~typing.Literal['phase'] | None = 'phase', hanning: bool = False, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Cross correlation on reconstructed amplitude.

class libertem_holo.base.align.BiprismDeletionCorrelator(mask: ~numpy.ndarray, upsample_factor: int = 1, normalization: ~typing.Literal['phase'] | None = 'phase', xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Cross correlation on low magnification while removing biprism.

classmethod get_masked(img, coords)

Uses coordinates from plot_get_coords to create a mask of biprism.

classmethod plot_get_coords(img, coords_out)

At low magnification, plot image of area with biprism visible. Click on edges of biprism to create the coordinates to mask it out, for cross correlation. First, click one edge of biprism from left side, then same edge, right side. Then, click other edge of biprism from left side, then right side. —–1——-2—– —–3——-4—–

class libertem_holo.base.align.BrightFieldCorrelator(holoparams: ~libertem_holo.base.utils.HoloParams, upsample_factor: int = 1, normalization: ~typing.Literal['phase'] | None = 'phase', hanning: bool = True, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Cross correlation on bright field of hologram.

class libertem_holo.base.align.GradAngleCorrelator(holoparams: ~libertem_holo.base.utils.HoloParams, upsample_factor: int = 1, normalization: ~typing.Literal['phase'] | None = 'phase', xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Cross correlation on gradient angle of phase image.

class libertem_holo.base.align.GradXYCorrelator(holoparams: ~libertem_holo.base.utils.HoloParams, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Cross correlation on gradient x and Y, correlation maps summed.

class libertem_holo.base.align.ImageCorrelator(upsample_factor: int = 1, normalization: ~typing.Literal['phase'] | None = 'phase', hanning: bool = True, binning: int = 1, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Cross correlation based image registration with some pre-filtering. Assumes real-space images as input.

class libertem_holo.base.align.NoopCorrelator

Do nothing, successfully.

class libertem_holo.base.align.PhaseImageCorrelator(holoparams: ~libertem_holo.base.utils.HoloParams, upsample_factor: int = 1, normalization: ~typing.Literal['phase'] | None = 'phase', hanning: bool = True, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Cross correlation on reconstructed phase image.

class libertem_holo.base.align.RegResult(maximum, shift, corrmap)

corrmap: ndarray

Alias for field number 2

maximum: tuple[float, float]

Alias for field number 0

shift: tuple[float, float]

Alias for field number 1

libertem_holo.base.align.align_stack(stack: ~numpy.ndarray, wave_stack: ~numpy.ndarray, static: ~numpy.ndarray | None = None, correlator: ~libertem_holo.base.align.Correlator | None = None, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → tuple[ndarray, ndarray, ndarray, ndarray]

Align stacks of N holograms.

Parameters:

• stack – Stack of images with shape (N, h, w) which is used for the alignment. It should be of dtype float32 or float64, so for holograms, you may want to align on the abs(wave). You can also slice the original data, if you want to align to a region of interest.

• wave_stack – The (complex) result of the reconstruction. This should have shape (N, h’, w’), meaning it should have the same number of complex images as the stack argument, but the 2d items in the stack can have a different shape.

• static – A reference image to align against. If this is not given, the first image of the stack will be taken.

• correlator – A Correlator instance. By default, an ImageCorrelator is used, with reasonable default parameters. If you need control over these, you can construct your own Correlator and pass it in. A requirement is that it has to work on the value given as the stack parameter.

Returns:

• aligned_stack – The aligned stack. Same shape and dtype as wave_stack

• shifts – The shifts that were applied to the stack. Shape (N, 2)

• reference – The pre-processed reference image, as used in the registration. Useful for debugging, for example if the correlator filters its input.

• corrs – The correlation maps, as returned from the correlator. Useful for debugging.

libertem_holo.base.align.cross_correlate(src, target, plot: bool = False, plot_title: str = '', normalization: ~typing.Literal['phase'] | None = 'phase', upsample_factor=1, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → tuple[ndarray, ndarray]

Rigid image registration by cross-correlation.

Supports optional phase normalization. Based on the phase_cross_correlation function of scikit-image, but with added GPU support via cupy, and some debugging facilities built in.

Parameters:

• src – The static image, either a numpy or cupy array (if cupy, you should set xp=cp, too)

• target – The moving image, either a numpy or cupy array (if cupy, you should set xp=cp, too)

• normalization – ‘phase’ or None, same as for phase_cross_correlation

• upsample_factor – Subpixel scaling factor, same as for phase_cross_correlation. Note that we test with a factor of up to 10; with larger values the results may not improve.

• xp – numpy or cupy

libertem_holo.base.align.get_grad_angle(image, scale=3)

From an image, get the angle of the gradient.

libertem_holo.base.align.get_grad_xy(image, scale=3)

From an image, get the angle of the gradient.

libertem_holo.base.align.is_left(a: ndarray, b: ndarray, c: ndarray) → ndarray

Points a and b are points on a line and result is an array of True or False if c is left or right of line resp.

libertem_holo.base.align.stack_alignment_quality(wave_stack: ndarray, shifts)

Stack quality ,judged by standard deviation on the stacking axis.

This should be mostly noise, if not, there may be issues from the alignment.

Phase unwrapping

Various phase unwrapping tools and algorithms.

libertem_holo.base.unwrap.derivative_variance(array: ndarray[tuple[int, int]], k: int = 3) → ndarray[tuple[int, int]]

Calculate variance of the derivative of array.

Can be used as a quality map for libertem_holo.base.unwrap.quality_unwrap().

Parameters:

array

Input phase with a float dtype

k

Window size

libertem_holo.base.unwrap.phase_unwrap(image: ndarray[tuple[int, int], Float16DType | Float32DType | Float64DType | Complex64DType | Complex128DType], method: Literal['skimage', 'quality', 'laplacian'] = 'skimage') → ndarray[tuple[int, int]]

Unwrap phase from wrapped phase or complex wave.

You can choose different methods, which might perform better or worse depending on the input data. For tweaking the unwrapping, please call the specific unwrap methods directly.

Parameters:

• image – Complex wave or wrapped phase image

• method –

  The method to use for unwrapping the phase.

  • skimage: use the unwrap_phase function from scikit-image

  • quality: unwrap based on the variance of the derivative

  • laplacian: qualitative unwrapping based on

Return type:

2d nd array of the unwrapped phase image

libertem_holo.base.unwrap.prepare_laplacian_unwrap(shape: tuple[int, int], xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → LaplaceParams

Prepare unwrap parameteres for a given shape.

Create the analytical discrete laplace operator and it’s inverse in the frequency domain.

You can use this if you plan to repeatedly unwrap phases of the same shape.

libertem_holo.base.unwrap.quality_unwrap(phase: ndarray[tuple[int, int]], quality: ndarray[tuple[int, int]]) → ndarray[tuple[int, int]]

Unwrap phase guided by a quality map.

Examples:

>>> import numpy as np
>>> from libertem_holo.base.unwrap import derivative_variance, quality_unwrap
>>> rng = np.random.default_rng()
>>> phase = rng.random(128*128).reshape(128, 128)
>>> dv = derivative_variance(phase)
>>> unwrapped = quality_unwrap(phase, dv)

Parameters:

phase

Input phase as a 2D ndarray

quality

Inverse score quality map for each pixel of the phase: lower values are higher quality

libertem_holo.base.unwrap.unwrap_phase_laplacian(wrapped_phase: ~numpy.ndarray[tuple[int, int]], params: ~libertem_holo.base.unwrap.laplace.LaplaceParams | None = None, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → ndarray[tuple[int, int]]

2D Laplacian Phase Unwrapping.

Note that the result is qualitative and not guaranteed to be an integer multiple of 2π from the original phase. A potential use case is a quick phase preview, as this method is GPU-accelerated by passing in xp=cp. The result can also be used as a starting point for further processing.

Implements part of: Marvin A. Schofield and Yimei Zhu, “Fast phase unwrapping algorithm for interferometric applications,” Opt. Lett. 28, 1194-1196 (2003) https://doi.org/10.1364/OL.28.001194

Parameters:

wrapped_phase

The input phase, wrapped between -π and +π

params

Optional pre-computed parameters using prepare_laplacian_unwrap, useful if many phases of the same shape need to be unwrapped.

xp

numpy or cupy array module

Convenience functions

High-level helper functions for reconstruction and visualization.

Convenience functions for reconstruction and visualization.

libertem_holo.base.convenience.plot_mag_induction(phase: ndarray, axis: Axes, mask: ndarray | None = None, clip: float = 0.001, binning: int = 1, gain: float = 8, smooth: float = 5, cmap=None, **kwargs) → Axes

Plot a magnetic induction map from a magnetic phase image.

This function combines a color-encoded visualization of the magnetic induction (obtained from the curl of the phase) with cosine contours of the smoothed phase image. The induction direction is encoded using colorvec(), while the cosine contours provide a visual representation of the phase. Optionally, a mask outline can be overlaid.

Parameters:

• phase (ndarray) – Two-dimensional magnetic phase image.

• axis (matplotlib.axes.Axes) – Axis on which to draw the visualization.

• mask (ndarray, optional) – Binary mask whose boundary is overlaid as a white contour, by default None.

• clip (float, optional) – Maximum induction magnitude to display. Larger values are clipped before color encoding, by default 1e-3.

• binning (int, optional) – Spatial binning factor applied to the phase image and mask before processing, by default 1.

• gain (float, optional) – Gain factor applied when computing the cosine contours, by default 8.

• smooth (float, optional) – Standard deviation of the Gaussian filter applied to the phase image before computing the induction field, by default 5.

• cmap (str or matplotlib.colors.Colormap, optional) – Colormap used for the induction map. By default, emp.vis.colors.cmaps.cyclic_cubehelix is used.

• **kwargs – Additional keyword arguments passed to empyre.vis.colorvec() and empyre.vis.cosine_contours().

Returns:

The plotting axis.

Return type:

matplotlib.axes.Axes

Notes

The visualization consists of

• a color-encoded induction map computed from the curl of the smoothed phase image,

• cosine contours of the smoothed phase image,

• a color wheel indicating the direction encoding,

• an optional white contour showing the supplied mask.

libertem_holo.base.convenience.reconstruct_stack(stack: InputData, stack_ref: InputData | None = None, holoparams: HoloParams | None = None, correlator: Correlator | None = None) → Results

Reconstruct and align a stack of holograms.

Optionally use a reference stack for phase correction.

Parameters:

• stack (InputData) – The input stack of holograms to reconstruct. Shape should be (N, H, W) or (H, W).

• stack_ref (InputData, optional) – An optional reference stack of holograms for phase correction. Shape should be (N, H, W) or (H, W).

• holoparams (HoloParams, optional) – Parameters for hologram reconstruction. If None, parameters will be estimated from the first hologram in the stack.

• correlator (Correlator, optional) – Parameters for frame by frame alignment. If None, phase correlation will be used.

Returns:

The results, packaged up in a Results instance

Return type:

results

Utility functions

Utility functions for working with holography data.

class libertem_holo.base.utils.HoloParams(sb_size: tuple[float, float], sb_position: tuple[float, float], aperture: np.ndarray, orig_shape: tuple[int, int], out_shape: tuple[int, int], scale_factor: float, xp: XPType)

HoloParams class contians all parameters necessary for reconstruction.

aperture: ndarray

Alias for field number 2

classmethod from_hologram(hologram: ~numpy.ndarray, *, central_band_mask_radius: float | None = None, out_shape: tuple = None, sb_size: float | None = None, sb_position: tuple[float, float] | None = None, circle_filter_order: int = 20, line_filter_length: float = 0.9, line_filter_width: float | None = 3, line_filter_order: int = 2, sb: ~typing.Literal['lower', 'upper'] = 'upper', xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → HoloParams

Determine reconstruction parameters from a hologram.

Automatically estimates sideband position and size, and returns the main parameters needed for holography reconstruction.

Parameters:

• hologram – A single hologram, can be either a numpy or a cupy array

• central_band_mask_radius – When estimating the sideband position, use a mask of this size to remove the central band

• out_shape – The reconstruction shape, should be larger than the sideband size

• sb_size – Override the sideband size; determined automatically if not given

• sb_position – Override the sideband position; determined automatically if not given

• circle_filter_order – Order of the butterworth filter applied to the circular part

• line_filter_length – Length ratio of the line filter; as a fraction of the distance between the central band and the sideband

• line_filter_width – Width of the line filter, in pixels. Passing in None will disable the line filter completely

• line_filter_order – Order of the butterworth filter applied to the line part

• sb – Chooses which sideband is taken. ‘lower’ or ‘upper’

• xp – Pass in either the numpy or cupy module to select CPU or GPU processing

orig_shape: tuple[int, int]

Alias for field number 3

out_shape: tuple[int, int]

Alias for field number 4

sb_position: tuple[float, float]

Alias for field number 1

property sb_position_int: tuple[int, int]

Sideband position from float to int.

sb_size: tuple[float, float]

Alias for field number 0

scale_factor: float

Alias for field number 5

xp: Any

Alias for field number 6

libertem_holo.base.utils.estimate_sideband_position(holo_data: ~numpy.ndarray, holo_sampling: tuple[float, float], central_band_mask_radius: float | None = None, sb: ~typing.Literal['lower', 'upper'] = 'lower', xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → tuple[float, float]

Find the position of the sideband and return its position.

Parameters:

• holo_data (ndarray) – The data of the hologram.

• holo_sampling (tuple) – The sampling rate in both image directions.

• central_band_mask_radius (float, optional) – The aperture radius used to mask out the centerband.

• sb (str, optional) – Chooses which sideband is taken. ‘lower’ or ‘upper’

• xp – Pass in either the numpy or cupy module to select CPU or GPU processing

Return type:

Tuple of the sideband position (y, x), referred to the unshifted FFT.

libertem_holo.base.utils.estimate_sideband_size(sb_position: tuple[float, float], holo_shape: tuple[int, int], sb_size_ratio: float = 0.5, xp: ~typing.Any = <module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → float

Estimate the size of sideband filter.

Parameters:

• holo_shape (array_like) – Holographic data array

• sb_position (tuple) – The sideband position (y, x), referred to the non-shifted FFT.

• sb_size_ratio (float, optional) – Size of sideband as a fraction of the distance to central band

• xp – Pass in either the numpy or cupy module to select CPU or GPU processing

Returns:

sb_size – Size of sideband filter

Return type:

float

libertem_holo.base.utils.freq_array(shape: tuple[int, int], sampling: tuple[float, float] = (1.0, 1.0), xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>) → ndarray

Generate a frequency array.

Parameters:

• shape ((int, int)) – The shape of the array.

• sampling ((float, float), optional, (Default: (1., 1.))) – The sampling rates of the array.

Return type:

Array of the frequencies.

libertem_holo.base.utils.get_slice_fft(out_shape: tuple[int, int], sig_shape: tuple[int, int]) → tuple[slice, slice]

Get a slice in fourier space to achieve the given output shape.

libertem_holo.base.utils.other_sb(sb_position, shape)

Given the sb_position (as from the estimate function in fft coordinates), and the shape of the hologram, calculate the position of the other sideband position (also in fft coordinates)

libertem_holo.base.utils.remove_phase_ramp(img: np.ndarray, *, roi=None, method: Literal['gradient' | 'fit'] = 'gradient') → tuple[np.ndarray, np.ndarray, tuple[float, float]]

Remove a phase ramp from img.

Returns both the compensated image and the ramp that was removed.

Parameters:

• img – The (phase) input image, has to be already unwrapped

• roi – Either a slice (as returned by np.s_ for example), or an array of the region of interest in img. If not specified, the whole img is used. In any case, the ramp is subtraced from the whole image.

• method –

  • ‘gradient’: the average gradient in the specified region of interest

  • ’fit’: a least-square fit of a linear gradient to the data in the region of interest

Returns:

• corrected_img – The image with the ramp removed

• ramp – The ramp that was found, as a 2D gradient

• (ramp_y, ramp_x) – The ramp slopes

Simulation

libertem_holo.base.generate.hologram_frame(amp, phi, counts=1000.0, sampling=5.0, visibility=1.0, f_angle=30.0, gaussian_noise=None, poisson_noise=None, xp=<module 'numpy' from '/home/runner/work/LiberTEM-holo/LiberTEM-holo/.tox/docs-build-ci/lib/python3.11/site-packages/numpy/__init__.py'>)

Generates holograms using phase and amplitude as an input

See Usage for detailed application example

New in version 0.3.0.

Notes

Theoretical basis for hologram simulations see in: Lichte, H., and M. Lehmann. Rep. Prog. Phys. 71 (2008): 016102. doi:10.1088/0034-4885/71/1/016102 [LL08]

Parameters:

• amp (np.ndarray, 2d) – normalized amplitude and phase images of the same shape

• phi (np.ndarray, 2d) – normalized amplitude and phase images of the same shape

• counts (float, default: 1000.) – Number of electron counts in vacuum

• sampling (float, default: 5.) – Hologram fringe sampling (number of pixels per fringe)

• visibility (float, default: 1.) – Hologram fringe visibility (aka fringe contrast)

• f_angle (float, default: 30.) – Angle in degrees of hologram fringes with respect to X-axis

• gaussian_noise (float or int or None, default: None.) – Amount of Gaussian smoothing determined by sigma parameter applied to the hologram simulating effect of focus spread or PSF of the detector.

• poisson_noise (float or int or None, default: None.) – Amount of Poisson applied to the hologram.

Returns:

holo – hologram image

Return type:

np.ndarray, 2d

Holography UDFs

class libertem_holo.udf.HoloReconstructUDF(*, out_shape: tuple[int, int], sb_position: tuple[float, float], aperture: ndarray, precision: bool = True)

Reconstruct off-axis electron holograms using a Fourier-based method.

Running run_udf() on an instance of this class will reconstruct a complex electron wave. Use the wave key to access the raw data in the result.

See Usage for detailed application example

New in version 0.3.0.

Examples

>>> from libertem_holo.base.filters import butterworth_disk
>>> shape = tuple(dataset.shape.sig)
>>> # NOTE: in real use, one would use `HoloParams.from_hologram` to
>>> # directly estimate parameters from the data, instead of specifying manually
>>> sb_position = [2, 3]
>>> sb_size = 4.4
>>> aperture = butterworth_disk(shape=shape, radius=sb_size)
>>> holo_udf = HoloReconstructUDF(
...     out_shape=shape,
...     sb_position=sb_position,
...     aperture=np.fft.fftshift(aperture),
... )
>>> wave = ctx.run_udf(dataset=dataset, udf=holo_udf)['wave'].data