Code reference

Filtering / Sideband isolation

qpretrieve.filter.get_filter_array(filter_name, filter_size, freq_pos, fft_shape)[source]

Create a Fourier filter for holography

Parameters
  • filter_name (str) –

    specifies the filter to use, one of

    • ”disk”: binary disk with radius filter_size

    • ”smooth disk”: disk with radius filter_size convolved with a radial gaussian (sigma=filter_size/5)

    • ”gauss”: radial gaussian (sigma=0.6*filter_size)

    • ”square”: binary square with side length 2*filter_size

    • ”smooth square”: square with side length 2*filter_size convolved with square gaussian (sigma=filter_size/5)

    • ”tukey”: a square tukey window of width 2*filter_size and alpha=0.1

  • filter_size (float) – Size of the filter in Fourier space. The filter size interpreted as a Fourier frequency index (“pixel size”) and must be between 0 and max(fft_shape)/2

  • freq_pos (tuple of floats) – The position of the filter in frequency coordinates as returned by nunpy.fft.fftfreq().

  • fft_shape (tuple of int) – The shape of the Fourier transformed image for which the filter will be applied. The shape must be squared (two identical integers).

Returns

filt_arr – The Fourier-shifted filtering array. For mask images, this is a boolean array. For more elaborate filters, this is a float array.

Return type

2d ndarray, boolean of float

Fourier transform methods

Numpy

class qpretrieve.fourier.ff_numpy.FFTFilterNumpy(data, subtract_mean=True, padding=2, copy=True)[source]

Wraps the numpy Fourier transform

Parameters
  • data (2d real-valued np.ndarray) – The experimental input image

  • subtract_mean (bool) – If True, subtract the mean of data before performing the Fourier transform. This setting is recommended as it can reduce artifacts from frequencies around the central band.

  • padding (int) –

    Boundary padding with zeros; This value determines how large the padding region should be. If set to zero, then no padding is performed. If set to a positive integer, the size is computed to the next power of two (square image):

    2 ** np.ceil(np.log(padding * max(data.shape) / np.log(2)))
    

  • copy (bool) – If set to True, make sure that data is not edited. If you set this to False, then caching FFT results will not work anymore.

Notes

The initial Fourier transform of the input data is cached using weak references (only if copy is True).

filter(filter_name: str, filter_size: float, freq_pos: float, float, scale_to_filter: bool | float = False)
Parameters
  • filter_name (str) –

    specifies the filter to use, one of

    • ”disk”: binary disk with radius filter_size

    • ”smooth disk”: disk with radius filter_size convolved with a radial gaussian (sigma=filter_size/5)

    • ”gauss”: radial gaussian (sigma=0.6*filter_size)

    • ”square”: binary square with side length 2*filter_size

    • ”smooth square”: square with side length 2*filter_size convolved with square gaussian (sigma=filter_size/5)

    • ”tukey”: a square tukey window of width 2*filter_size and alpha=0.1

  • filter_size (float) – Size of the filter in Fourier space. The filter size interpreted as a Fourier frequency index (“pixel size”) and must be between 0 and max(fft_shape)/2

  • freq_pos (tuple of floats) – The position of the filter in frequency coordinates as returned by nunpy.fft.fftfreq().

  • scale_to_filter (bool or float) – Crop the image in Fourier space after applying the filter, effectively removing surplus (zero-padding) data and increasing the pixel size in the output image. If True is given, then the cropped area is defined by the filter size, if a float is given, the cropped area is defined by the filter size multiplied by scale_to_filter. You can safely set this to True for filters with a binary support. For filters such as “smooth square” or “gauss” (filter is not a boolean array but a floating-point array), the higher you set scale_to_filter, the more information will be included in the scaled image.

Notes

The FFT result is cached using weak references in FFTCache. If you call this function a lot of times with different arguments, then it might look like a memory leak. However, you just have to delete the FFTFilter isntance and everything will get garbage- collected.

property shape

Shape of the Fourier transform data

origin

original data (with subtracted mean)

padding

whether padding is enabled

subtract_mean

whether the mean was subtracted

origin_padded

padded input data

fft_origin

frequency-shifted Fourier transform

fft_filtered

filtered Fourier transform

fft_used

used Fourier transform (can have a different shape)

PyFFTW

Interference image analysis

Off-Axis Holography (DHM)

class qpretrieve.interfere.if_oah.OffAxisHologram(data, subtract_mean=True, padding=2, copy=True, **pipeline_kws)[source]

Off-axis hologram data analysis

Parameters
  • subtract_mean (bool) – If True, remove the mean of the hologram before performing the Fourier transform. This setting is recommended as it can reduce artifacts from frequencies around the central band.

  • padding (bool) –

    Boundary padding with zeros; This value determines how large the padding region should be. If set to zero, then no padding is performed. If set to a positive integer, the size is computed to the next power of two (square image):

    2 ** np.ceil(np.log(padding * max(data.shape) / np.log(2)))
    

  • copy (bool) – Whether to create a copy of the input data.

  • pipeline_kws – Any additional keyword arguments for run_pipeline() as defined in default_pipeline_kws.

default_pipeline_kws = {'filter_name': 'disk', 'filter_size': 0.3333333333333333, 'filter_size_interpretation': 'sideband distance', 'invert_phase': False, 'scale_to_filter': False, 'sideband_freq': None}

Default OAH pipeline keyword arguments

property phase

Retrieved phase information

property amplitude

Retrieved amplitude information

run_pipeline(**pipeline_kws)[source]

Run OAH analysis pipeline

Parameters
  • filter_name (str) – specifies the filter to use, see qpretrieve.filter.get_filter_array().

  • filter_size (float) – Size of the filter in Fourier space. The interpretation of this value depends on filter_size_interpretation.

  • filter_size_interpretation (str) – If set to “sideband distance”, the filter size is interpreted as the relative distance between central band and sideband (this is the default). If set to “frequency index”, the filter size is interpreted as a Fourier frequency index (“pixel size”) and must be between 0 and max(hologram.shape)/2.

  • scale_to_filter (bool or float) – Crop the image in Fourier space after applying the filter, effectively removing surplus (zero-padding) data and increasing the pixel size in the output image. If True is given, then the cropped area is defined by the filter size, if a float is given, the cropped area is defined by the filter size multiplied by scale_to_filter. You can safely set this to True for filters with a binary support. For filters such as “smooth square” or “gauss” (filter is not a boolean array but a floating-point array), the higher you set scale_to_filter, the more information will be included in the scaled image.

  • sideband_freq (tuple of floats) – Frequency coordinates of the sideband to use. By default, a heuristic search for the sideband is done.

  • invert_phase (bool) – Invert the phase data.

compute_filter_size(filter_size, filter_size_interpretation, sideband_freq=None)

Compute the actual filter size in Fourier space

property field

Retrieved amplitude information

get_pipeline_kw(key)

Current pipeline keyword argument with fallback to defaults

process_like(other)

Process this dataset in the same way as other dataset

fft

qpretrieve Fourier transform interface class

fft_origin

originally computed Fourier transform

fft_filtered

filtered Fourier data from last run of run_pipeline

pipeline_kws

pipeline keyword arguments

qpretrieve.interfere.if_oah.find_peak_cosine(ft_data, copy=True)[source]

Find the side band position of a regular off-axis hologram

The Fourier transform of a cosine function (known as the striped fringe pattern in off-axis holography) results in two sidebands in Fourier space.

The hologram is Fourier-transformed and the side band is determined by finding the maximum amplitude in Fourier space.

Parameters
  • ft_data (2d ndarray) – FFt-shifted Fourier transform of the hologram image

  • copy (bool) – copy ft_data before modification

Returns

fsx, fsy – coordinates of the side band in Fourier space frequencies

Return type

tuple of floats

Quadriwave lateral shearing interferometry (QLSI)

class qpretrieve.interfere.if_qlsi.QLSInterferogram(data, reference=None, *args, **kwargs)[source]

Interferometric analysis of quadri-wave lateral shearing holograms

Parameters
  • subtract_mean (bool) – If True, remove the mean of the hologram before performing the Fourier transform. This setting is recommended as it can reduce artifacts from frequencies around the central band.

  • padding (bool) –

    Boundary padding with zeros; This value determines how large the padding region should be. If set to zero, then no padding is performed. If set to a positive integer, the size is computed to the next power of two (square image):

    2 ** np.ceil(np.log(padding * max(data.shape) / np.log(2)))
    

  • copy (bool) – Whether to create a copy of the input data.

  • pipeline_kws – Any additional keyword arguments for run_pipeline() as defined in default_pipeline_kws.

default_pipeline_kws = {'filter_name': 'square', 'filter_size': 0.5, 'filter_size_interpretation': 'sideband distance', 'invert_phase': False, 'qlsi_pitch_term': None, 'scale_to_filter': False, 'sideband_freq': None, 'wavelength': None}

Default QLSI pipeline keyword arguments

property amplitude

Retrieved amplitude information

property field

Retrieved amplitude information

property phase

Retrieved phase information

run_pipeline(**pipeline_kws)[source]

Run QLSI analysis pipeline

Parameters
  • filter_name (str) – specifies the filter to use, see qpretrieve.filter.get_filter_array().

  • filter_size (float) – Size of the filter in Fourier space. The interpretation of this value depends on filter_size_interpretation.

  • filter_size_interpretation (str) – If set to “sideband distance”, the filter size is interpreted as the relative distance between central band and sideband (this is the default). If set to “frequency index”, the filter size is interpreted as a Fourier frequency index (“pixel size”) and must be between 0 and max(hologram.shape)/2.

  • scale_to_filter (bool or float) – Crop the image in Fourier space after applying the filter, effectively removing surplus (zero-padding) data and increasing the pixel size in the output image. If True is given, then the cropped area is defined by the filter size, if a float is given, the cropped area is defined by the filter size multiplied by scale_to_filter. You can safely set this to True for filters with a binary support. For filters such as “smooth square” or “gauss” (filter is not a boolean array but a floating-point array), the higher you set scale_to_filter, the more information will be included in the scaled image.

  • sideband_freq (tuple of floats) – Frequency coordinates of the sideband to use. By default, a heuristic search for the sideband is done.

  • invert_phase (bool) – Invert the phase data.

  • wavelength (float) – Wavelength to convert from the wavefront in meters to radians.

  • qlsi_pitch_term (float) –

    Scaling term converting the integrated gradient image to the unit meters. This term is computed from the lattice constant of the grating \(L\), the distance between the grating and the camera sensor \(d\) and the physical camera pixel width \(a\) according to

    \[\text{pitch_term} = \frac{La}{d}\]

    For the case where the lattice constant is four times the pixel width, this simplifies to \(4a^2/d\). Note that for a relay-lens system (grating not directly attached to the sensor) this factor is wavelength dependent due to chromatic aberrations introduced by the lenses. For gratings-on-a-camera configurations (e.g. Phasics SID4Bio), this is a device-specific quantity which has to be determined only once. E.g. for our SID4Bio camera, this value is 0.01887711 µm (1.87711e-08 m).

compute_filter_size(filter_size, filter_size_interpretation, sideband_freq=None)

Compute the actual filter size in Fourier space

get_pipeline_kw(key)

Current pipeline keyword argument with fallback to defaults

process_like(other)

Process this dataset in the same way as other dataset

fft

qpretrieve Fourier transform interface class

fft_origin

originally computed Fourier transform

fft_filtered

filtered Fourier data from last run of run_pipeline

pipeline_kws

pipeline keyword arguments

qpretrieve.interfere.if_qlsi.find_peaks_qlsi(ft_data, periodicity=4, copy=True)[source]

Find the two peaks in Fourier space for the x and y gradient

Parameters
  • ft_data (2d complex ndarray) – FFT-shifted Fourier transform of the QLSI image

  • periodicity (float) – Grid size of the QLSI image. For the Phasics SID4Bio camera, this is 4 (i.e. the peak-to-peak distance of the individual foci in the QLSI image is four pixels)

  • copy (bool) – Set to False to perform operations in-place.

Returns

  • (f1x, f1y) (tuple of floats) – Coordinates of the first gradient peak in frequency coordinates.

  • (f2x, f2y) (tuple of floats) – Coordinates of the second gradient peak in frequency coordinates.

Notes

At some point it might be necessary to add an angle keyword argument that gives the algorithm a hint about te rotation of the QLSI grid. Currently, peak detection is only done in the lower half of ft_data. If the peaks are exactly aligned with the pixel grid, then the current approach might not work. Also, setting angle=np.pi would be equivalent to setting sideband to -1 in holo.py (would be a nice feature).