Holo Class

The Holo class is the preferred way to access the core functionality of PyHoloscope. The class is generally used by setting various parameters, either by passing them at instantiation or by calling methods, and then by calling the process method to process each raw hologram.

Examples are provided of Inline Holography and Off-Axis Holography in the Github repository. Also see the Inline Holography and Off-Axis Holography getting started pages.

class pyholoscope.Holo(mode=None, wavelength=None, pixel_size=None, **kwargs)

__init__(mode=None, wavelength=None, pixel_size=None, **kwargs)

Initialises an instance of the Holo class.

Mode Parameters:

mode: enum
Processing mode, either pyholoscope.INLINE or pyholsocope.OFF_AXIS.

Numerical Refocusing Parameters:

refocus: bool: Flag to enable numerical refocusing (default = False) in OFF_AXIS mode. For INLINE mode, refocusing is always enabled and this parameter is ignored.
wavelength: float: Wavelength of light (m). Only needed if refocusing is required.
pixel_size: float: Size of the pixels in the hologram (m). Only needed if refocusing is required.
depth: float: Refocus depth in same units as pixel_size and wavelength. Only needed if refocusing is required.
propagation_method: str: Wave propagation model used for refocusing propagator generation, ‘angular_spectrum’ (default) or ‘fresnel’.
correct_pixel_size: bool: Flag to correct effective pixel size for point-source magnification in propagator generation (default = False). Requires source_distance to be set.
source_distance: float or None: Distance from point source to camera plane in same units as pixel_size and wavelength. Required if correct_pixel_size or correct_curvature is True. (default = None).
correct_curvature: bool: Flag to enable curvature correction (default = False). If True, the hologram will be corrected for spherical wavefront curvature before refocusing. Requires source_distance to be set.
use_prop_lutboolean: If True, use propagator LUT to refocus.

Auto Focus Parameters:

find_focus_depth_range: tuple: Depth range to use for finding the focus, (min_depth, max_depth) in same units as pixel_size and wavelength. default = (0, 1).
find_focus_method: str: Method to use for autofocus, (default = ‘Sum’). Only needed if autofocus is used.
find_focus_roi: Roi or None: Region of interest to use for finding the autofocus, (default = None). Only used for autofocus.
find_focus_margin: int or None: Margin to use for autofocus, in pixels (default = None). Only used for autofocus.
use_auto_focus_propagator_lut: boolean: If True, use a propagator LUT to find focus. Only used for autofocus. This must be created using the create_auto_focus_propagator_lut() method before autofocus can be used, or provided manually by setting the auto_focus_propagator_lut property.

Backgound and Normalisation Parameters:

background: numpy.ndarray or None: Background hologram to be subtracted in inline holography, a 2D real array or None for no subtraction (default = None). This will also be used to create the background field in off-axis holography if relative phase is requested.
normalise: numpy.ndarray or None: Normalisation hologram to be divided by, 2D real array (default = None) during inline or off-axis holography.
relative_amplitude: bool: Flag to calculate relative amplitude in off-axis holography (default = False). If True, the background hologram will be used to calculate the relative amplitude.
relative_phase: bool: Flag to calculate relative phase in off-axis holography (default = False). If True, the background hologram will be used to calculate the relative phase.

Windowing Parameters:

auto_window: bool: Flag to automatically create a window for pre or post processing (default = False). If True, a window will be created based on the image size and the specified window radius and thickness.
post_window: bool: Flag to apply the window after refocusing (default = False). If True, the window will be applied after refocusing.
window_shape: str: Shape of the automatically generated window, ‘circle’ or ‘square’ (default = ‘square’). Only used if auto_window is True.
window_radius: int or tuple: Radius of the automatically generated window, for ‘circle’ this is the radius, for ‘square’ this is half the side length. For ‘circle’ provide an int, for ‘square’ either provide an int (resulting in a square window) or a tuple of (width, height). (default = None). If None, the window radius will be set to half the image size.
window_thickness: int: The number of pixels inside the window over which it transitions from opaque to transparent (default = 10). Only used if auto_window is True.
window: numpy.ndarray or None: A custom window as 2D real array. Will be resized to match size of img if necessary. (default = None). If None, the window will be created automatically if auto_window is True.

Off-Axis Demodulation Parameters:

crop_centre: tuple or None: Centre of the crop in the off-axis demodulation, (x, y) in pixels (default = None). If None, the calib_off_axis() method must be called to find the crop centre.
crop_radius: int or (int, int) or None: Radius of the crop in the off-axis demodulation, in pixels (default = None). If None, the calib_off_axis() method must be called to find the crop radius.
crop_mask: enum or None: Shape of crop mask to use in the off-axis demodulation, pyholoscope.CIRCLE, pyholoscope.CIRCLE_COSINE, or pyholsocope.CUSTOM. (default = None). If specified as pyholoscope.CUSTOM, the mask must be specified using the custom_crop_window parameter. Otherwise, the crop mask will be a circle or a circle with a cosine transition depending on the value of crop_mask and will be generated either when calib_off_axis() is called or when process() is first called.
custom_crop_window: numpy.ndarray or None: Custom crop window to use in the off-axis demodulation when crop_mask is set to pyholsocope.CUSTOM. Provide a 2D real array (default = None).
crop_window_skin_thickness: int: When crop_mask = pyholoscope.CIRCLE_COSINE, this parameter contols the number of pixels inside the crop window over which it transitions from opaque to transparent (default = 10).
return_fft: bool: Flag to return the FFT of the off-axis demodulated image (default = False). If True, the process() method will be return the FFT of the off-axis demodulated image instead of the demodulated image itself.
off_axis_real_fft: bool: Flag to use a real FFT for off-axis demodulation (default = False). If True, the real FFT will be used instead of the complex FFT. This is faster but should only be used if the reference beam is not tilted in such a way that the cross-term crosses the vetical axis in the FFT.

Display Parameters:

invert: bool
Flag to invert the image, i.e. largest value becomes smallest and vice versa (default = False).

downsample: float: Factor to downsample the image by (default = 1). If > 1, the image will be downsampled by this factor.

Back-end and Processing Parameters:

numba: bool: Flag to use numba for speed up (default = True). If False, numba optimised functions will not be used.
cuda: bool: Flag to use CUDA for GPU acceleration (default = True). If False, GPU functions will not be used.
precision: str: Numerical precision of output, ‘single’ (default) or ‘double’. This will determine the data type of the images processed by the Holo class. If ‘double’, images will be processed as float64, otherwise as float32.

auto_find_off_axis_mod(maskFraction=0.1): Detect the modulation location in frequency domain. maskFraction is the size of a mask applied to the centre of the FFT to prevent the d.c. from being detected.

auto_focus(img)

Finds the best focus for hologram ‘img’ using parameters previously defined (such as wavelength) as well as by set_find_focus_parameters(), and then refocuses to this depth and returns the refocused image. Note that this is sets the depth of the Holo class to the found focus depth, so subsequent calls to process() will be at this depth unless depth is changed again. The refocus depth can be read from the Holo class depth property after calling this method.

Arguments:

imgndarray: 2D array containing hologram

Returns:

ndarray : refocused image at optimal focus depth.

calib_off_axis(hologram=None, mask_fraction=0.1): Detect the modulation location in frequency domain using the background or a provided hologram.

clear_auto_focus_propagator_LUT(): Deletes the LUT of propagators.

clear_background(): Remove existing background hologram.

clear_normalise(): Remove existing normalisation hologram.

clear_propagator_LUT(): Deletes the LUT of propagators.

clear_window(): Removes existing window, equivalent to set_window(None)

depth_stack(img, depth_range, num_depth)

Create a depth stack using current parameters, producing a set of ‘num_depth’ refocused images equally spaced within depth_range.

Arguments:

imgndarray: hologram
depth_rangetuple: depths to focus to: (min depth, max depth)
num_depthint: number of depths to create images for within depth_range

Returns:

FocusStack : instance of FocusStack containing the refocused images.

find_focus(img)

Automatically finds the best focus position for hologram ‘img’ using parameters previously defined (such as wavelength) as well as parameters set by set_find_focus_parameters().

Arguments:

imgndarray: 2D array containing hologram

Returns:

float : optimal refocus depth

make_auto_focus_propagator_LUT(dimension, depth_range, num_depths, roi=None, margin=None)

Creates and stores a LUT of propagators for faster finding of focus.

Arguments:

dimensionint or (int, int) or ndarray: dimension of hologram to determine size of propagators in LUT.
depth_rangetuple: depths range to create propagators for: (min depth, max depth)
num_depthsint: number of depths to create propagators for, evenly spaced within depth_range.
roiinstance of Roi: area that focus will be assessed within, default is None. This only matters for the propagator if a margin is specified, in which case only the roi and a margin around it will be refocused to assess focus, so the propagators only need to be the size of this.
marginint: if specified only the roi and a margin will be refocused to assess focus, default is None in which case the whole image will be refocused to assess focus. If margin is specified, the propagators in the LUT will only be the size of the roi plus the margin, to speed up refocusing for finding focus.

make_propagator_LUT(dimension, depth_range, num_depths)

Creates and stores a LUT of propagators for faster refocus.

Arguments:

dimensionint or (int, int) or ndarray: dimension of hologram to determine size of propagators in LUT.
depth_rangetuple: depths range to create propagators for: (min depth, max depth)
num_depthsint: number of depths to create propagators for, evenly spaced within depth_range/

process(img): Process a hologram using the currently selected parameters. Calls _process_inline or __process_off_axis depending on mode.

set_find_focus_parameters(**kwargs)

Sets the parameters used by the find_focus method.

Keyword Arguments:

depth_rangedouble: tuple of (min, max) depths to search within in m.
roiinstance of Roi: area to assess focus within, default is None in which case all of image is used.
methodstr: focus metric to use.
marginint: if specified only the Roi and a margin will be refocused. If None (default) the whole image will be refocused regardless. Has no effect if roi not specified.
use_prop_lutbool: Whether or not to use the auto focus propagator LUT for finding focus. Default is False. If True, the LUT must have been generated with make_auto_focus_propagator_LUT() or set manually using the auto_focus_propagator_lut property, and must cover the depth range specified by depth_range.

set_off_axis_mod(crop_centre, crop_radius)

Sets the location of the frequency domain position of the OA modulation.

Arguments:: crop_centre : tuple of (x,y) crop_radius : radius

update_auto_window(img): Create or re-create the automatic window using current parameters. Provide an ‘img’, a 2D numpy array of the same size as the image to be processed.

update_propagator(img): Create or re-create the propagator using current parameters. img should be an 2D numpy array of the same size as the images to be processed.