hologradpy.patterns¶

This module contains utility functions for array manipulation and functions to create binary masks, intensity and phase patterns of various shapes.

The Hologram class provides arrays needed for the CG minimisation: The target light potential and the signal region, the measured constant SLM phase and intensity at the required resolution, and the initial SLM phase guess to start the CG minimisation.

Classes¶

Hologram

This class provides arrays needed for the CG minimisation:

Functions¶

`make_grid`(im[, scale])	Return a xy meshgrid based in an input array, im, ranging from -scal * im.shape[0] // 2 to scal * im.shape[0] // 2.
`pixel_corr`(img, x, y)	Replace a pixel value with coordinates x and y by the mean value of its 3x3 neighbourhood.
`unwrap_2d`(img, **kwargs)	Unwraps an image along the x- and y-axis.
`unwrap_2d_mask`(img, mask, **kwargs)	Unwraps an image within a region of interest defined by a binary mask.
`crop`(img, n_crop)	Crops an image around all four edges by n_crop pixels.
`crop_to_mask`(img, mask)	Crops an image to the smallest size taken up by a binary mask.
`load_filter_upscale`(path, npx, pix_res[, crop, ...])	Loads a 2D numpy array and crops its edges. A uniform filter is applied to the cropped image before it is upscaled
`rect_mask`(im, dx, dy, w, h)	Rectangular mask using pixel coordinates of an input image.
`rect_mask_xy`(x, y, dx, dy, w, h)	Rectangular mask using XY meshgrid coordinates.
`circ_mask`(im, dx, dy, r)	Circular mask using pixel coordinates of an input image.
`circ_mask_xy`(x, y, dx, dy, r[, sparse])	Circular mask using XY meshgrid coordinates.
`gaussian`(x, y, dx, dy, sig_x[, sig_y, a, c])	2D Gaussian.
`super_gaussian`(x, y, dx, dy, nx, ny, sig_x, sig_y[, a, c])	2D super-Gaussian.
`gauss_array`(im, nx, ny, dx, dy, d, sigma)	Gaussian spot array using coordinates of input image.
`ring_gauss`(x, y, dx, dy, r, w[, a])	Ring with Gaussian profile.
`checkerboard`(npx, dx, dy, rows, columns, square_size)	Creates a checkerboard on a canvas of (npx, npx) pixels.
`fringes_wavefront`(x, y, dx, dy, k, f, phi, a, b)	Standing wave interference pattern on the camera caused by two patches on the SLM seperated by dx and dy.
`init_phase`(img, slm_disp_obj, pms_obj[, lin_phase, ...])	SLM phase guess to initialise phase-retrieval algorithm (see https://doi.org/10.1364/OE.16.002176).
`lens`(x, y, k, f)	Phase of a parabolic lens.
`doublet`(x, y, k, n1, n2, r1, r2, r3[, dx, dy])	Phase of a doublet lens.
`slm_phase_doublet`(dx, dy, k, xf, yf, z1, z2, fl, n1, ...)	Models the phase difference in the wavefront measurement caused by the doublet lens and an out-of-focus camera
`pixel_ct_kernel`(slm_pitch, pix_res, extent, m, sigma)	2D blurring kernel to model pixel crosstalk on the SLM (see https://doi.org/10.1186/s41476-021-00174-7).
`vortex_field`(img, m, x, y)	Creates the phase of a vortex field of charge `m` at positions `x` and `y` . The origin of the coordinate
`detect_vortices`(n_pix, e_holo, i_tar[, threshold])	This function detects the positions and charges of optical vortices in an electric field.

Module Contents¶

hologradpy.patterns.make_grid(im, scale=None)¶

Return a xy meshgrid based in an input array, im, ranging from -scal * im.shape[0] // 2 to scal * im.shape[0] // 2.

Parameters:

im – Input array.
scale – Optional scaling factor.

Returns:

x and y meshgrid arrays.

hologradpy.patterns.pixel_corr(img, x, y)¶

Replace a pixel value with coordinates x and y by the mean value of its 3x3 neighbourhood.

Parameters:

img – Input image.
x – x-coordinate of pixel.
y – y-coordinate of pixel.

Returns:

Corrected image.

hologradpy.patterns.unwrap_2d(img, **kwargs)¶

Unwraps an image along the x- and y-axis.

Parameters:

img – Input image.
kwargs – kwargs for np.unwrap() function.

Returns:

Unwrapped image.

hologradpy.patterns.unwrap_2d_mask(img, mask, **kwargs)¶

Unwraps an image within a region of interest defined by a binary mask.

Parameters:

img – Input image.
mask – Binary mask with region of interest.
kwargs – kwargs for np.unwrap() function.

Returns:

Unwrapped image.

hologradpy.patterns.crop(img, n_crop)¶

Crops an image around all four edges by n_crop pixels.

Parameters:

img – Input image.
n_crop – Number of pixels to crop at both end of each dimension.

Returns:

Cropped image.

hologradpy.patterns.crop_to_mask(img, mask)¶

Crops an image to the smallest size taken up by a binary mask.

Parameters:

img – Input image.
mask – Binary mask.

Returns:

Cropped image.

hologradpy.patterns.load_filter_upscale(path, npx, pix_res, crop=None, filter_size=None)¶

Loads a 2D numpy array and crops its edges. A uniform filter is applied to the cropped image before it is upscaled using Lanczos interpolation.

Parameters:

path – Numpy array or path to numpy array.
npx – Number of SLM pixels.
pix_res – Number of pixels per SLM pixel.
crop – Number of unused pixels [SLM pixels].
filter_size – Size of the uniform filter.

Returns:

Upscaled image.

hologradpy.patterns.rect_mask(im, dx, dy, w, h)¶

Rectangular mask using pixel coordinates of an input image.

Parameters:

im – Input image
dx – X-offset of rectangle from the centre of the image.
dy – Y-offset of rectangle from the centre of the image.
w – Width of rectangle.
h – Height of rectangle.

Returns:

Binary mask.

hologradpy.patterns.rect_mask_xy(x, y, dx, dy, w, h)¶

Rectangular mask using XY meshgrid coordinates.

Parameters:

x – X meshgrid
y – Y meshgrid
dx – X-offset of rectangle from the centre of the image.
dy – Y-offset of rectangle from the centre of the image.
w – Width of rectangle.
h – Height of rectangle.

Returns:

Binary mask.

hologradpy.patterns.circ_mask(im, dx, dy, r)¶

Circular mask using pixel coordinates of an input image.

Parameters:

im – Input image
dx – X-offset of circle.
dy – Y-offset of circle.
r – Radius of circle.

Returns:

Binary mask.

hologradpy.patterns.circ_mask_xy(x, y, dx, dy, r, sparse=None)¶

Circular mask using XY meshgrid coordinates.

Parameters:

x – X meshgrid.
y – Y meshgrid.
dx – X-offset of circle.
dy – Y-offset of circle.
r – Radius of circle.

Returns:

Binary mask.

hologradpy.patterns.gaussian(x, y, dx, dy, sig_x, sig_y=None, a=1, c=0)¶

2D Gaussian.

Parameters:

x – X meshgrid.
y – Y meshgrid.
dx – X-offset of Gaussian.
dy – Y-offset of Gaussian.
sig_x – X width of Gaussian.
sig_y – Y width of Gaussian
a – Amplitude.
c – Offset.

Returns:

2D Gaussian.

hologradpy.patterns.super_gaussian(x, y, dx, dy, nx, ny, sig_x, sig_y, a=1, c=0)¶

2D super-Gaussian.

Parameters:

x – X meshgrid.
y – Y meshgrid.
dx – X-offset of Gaussian.
dy – Y-offset of Gaussian.
nx – X-order.
ny – Y-order.
sig_x – X-width.
sig_y – Y-width.
a – Amplitude.
c – Offset.

Returns:

2D super-Gaussian.

hologradpy.patterns.gauss_array(im, nx, ny, dx, dy, d, sigma)¶

Gaussian spot array using coordinates of input image.

Parameters:

im – Input image.
nx – Number of array columns.
ny – Number of array rows.
dx – X-offset of array.
dy – Y-offset of array.
d – Separation between neighbouring spots.
sigma – Width of Gaussian spots.

Returns:

Spot array.

hologradpy.patterns.ring_gauss(x, y, dx, dy, r, w, a=1)¶

Ring with Gaussian profile.

Parameters:

x – X meshgrid.
y – Y meshgrid.
dx – X-offset of ring.
dy – Y-offset of ring.
r – Radius of ring.
w – Width of Gaussian profile.
a – Amplitude.

Returns:

Ring with Gaussian profile.

hologradpy.patterns.checkerboard(npx, dx, dy, rows, columns, square_size)¶

Creates a checkerboard on a canvas of (npx, npx) pixels.

Parameters:

npx – Size of canvas.
dx – X-offset of checkerboard.
dy – Y-Offset of checkerboard.
rows – Checkerboard rows.
columns – Checkerboard columns.
square_size – Size of a square in pixels

Returns:

Checkerboard.

hologradpy.patterns.fringes_wavefront(x, y, dx, dy, k, f, phi, a, b)¶

Standing wave interference pattern on the camera caused by two patches on the SLM seperated by dx and dy. Equation adapted from https://doi.org/10.1364/OE.24.013881.

Parameters:

x – X meshgrid.
y – Y meshgrid.
dx – Separation between reference and sample patch along x [m].
dy – Separation between reference and sample patch along y [m].
k – Wavenumber [rad/m].
f – Focal length of Fourier lens [m].
phi – Phase difference between reference and sample patches (see paper above) [rad].
a – Amplitude on reference patch.
b – Amplitude on sample patch.

Returns:

Interference pattern.

hologradpy.patterns.init_phase(img, slm_disp_obj, pms_obj, lin_phase=None, quad_phase=None, lin_method=None)¶

SLM phase guess to initialise phase-retrieval algorithm (see https://doi.org/10.1364/OE.16.002176).

Parameters:

img (ndarray) – 2D array with size of desired output.
slm_disp_obj – Instance of Params class
lin_phase (ndarray) – Vector of length 2, containing parameters for the linear phase term
quad_phase (ndarray) – Vector of length 2, containing parameters for the quadratic phase term
lin_method (str) –
Determines how the linear phase term is parameterised. The options are:

-‘pixel’
Defines the linear phase in terms of Fourier pixels [px].

-‘angles’
Defines the linear phase in terms of angles [rad].

Returns:

Phase pattern of shape img.shape

hologradpy.patterns.lens(x, y, k, f)¶

Phase of a parabolic lens.

Parameters:

x – X-meshgrid [m].
y – Y-meshgrid [m].
k – Wavenumber [rad/m].
f – Focal length [m].

Returns:

Phase of the lens [rad].

hologradpy.patterns.doublet(x, y, k, n1, n2, r1, r2, r3, dx=None, dy=None)¶

Phase of a doublet lens.

Parameters:

x – X-meshgrid [m].
y – Y-meshgrid [m].
k – Wavenumber [rad/m].
n1 – Refractive index of flint.
n2 – Refractive index of crown.
r1 – Radius of curvature of the first crown surface [m].
r2 – Radius of curvature of the second crown surface/ first flint surface [m].
r3 – Radius of curvature of the second flint surface [m].
dx – X-offset of lens [m].
dy – Y-offset of lens [m].

Returns:

Phase of the doublet lens [rad].

hologradpy.patterns.slm_phase_doublet(dx, dy, k, xf, yf, z1, z2, fl, n1, n2, r1, r2, r3)¶

Models the phase difference in the wavefront measurement caused by the doublet lens and an out-of-focus camera placement (see equation S8 in the supplementary information of https://doi.org/10.1038/s41598-023-30296-6).

Parameters:

dx – X-position of sample patch [m].
dy – Y-position of sample patch [m].
k – Wavenumber [rad/m].
xf – X-position of phase measurement in the image plane [m].
yf – Y-position of phase measurement in the image plane [m].
z1 – Distance between SLM and lens [m].
z2 – Distance between lens and camera [m].
fl – Focal length of doublet lens [m].
n1 – Refractive index of flint.
n2 – Refractive index of crown.
r1 – Radius of curvature of the first crown surface [m].
r2 – Radius of curvature of the second crown surface/ first flint surface [m].
r3 – Radius of curvature of the second flint surface [m].

Returns:

Corrective phase pattern [rad].

hologradpy.patterns.pixel_ct_kernel(slm_pitch, pix_res, extent, m, sigma)¶

2D blurring kernel to model pixel crosstalk on the SLM (see https://doi.org/10.1186/s41476-021-00174-7).

Parameters:

slm_pitch – Pixel pitch of SLM [m].
pix_res – Up-scaling factor (computational pixels per SLM pixel).
extent – Spatial extent of kernel in SLM pixels.
m – Order of the kernel.
sigma – Width of the kernel.

Returns:

2D blurring kernel.

hologradpy.patterns.vortex_field(img, m, x, y)¶

Creates the phase of a vortex field of charge m at positions x and y . The origin of the coordinate system is in the top-left corner of img .

Parameters:

img – 2D array with size of desired output.
m – Vector of vortex charge (1 or -1).
x – Vector of vortex x-coordinate [px].
y – Vector of vortex y-coordinate [px].

Returns:

Phase of vortex field with size img.shape.

hologradpy.patterns.detect_vortices(n_pix, e_holo, i_tar, threshold=None)¶

This function detects the positions and charges of optical vortices in an electric field. Todo: Tidy up this function and improve documentation.

Parameters:

n_pix – Number of pixels.
e_holo – Electric field.
i_tar – Target intensity pattern.
threshold – Only look for vortices in areas which are brighter than theshold * max(abs(i_tar) ** 2). Vortices in low-intensity regions are hard to detect.

Returns:

Charge of vortices and their xy coordinates.

class hologradpy.patterns.Hologram(slm_disp_obj, pms_obj, name, npix, npix_pad=None, pix_res=1, phase_guess_type='random', linear_phase=None, quadratic_phase=None, slm_field_type='guess', propagation_type='fft', target_position=None, target_width=None, target_blur=None, checkerboard_rows=8, checkerboard_columns=10, checkerboard_square_size=32)¶

This class provides arrays needed for the CG minimisation:

The target light potential

the signal region

the measured constant SLM phase and intensity at the required resolution

and the initial SLM phase guess to start the phase retrieval.

Some patterns, including the patterns from our publication (https://doi.org/10.1038/s41598-023-30296-6), are pre-defined here. Feel free to define your own patterns, you don’t have to use this class to do this.

Todo: Tidy up this class and improve documentation.

name¶

npix¶

npix_pad = None¶

slm_ones¶

pix_res = 1¶

tar_res¶

tar_ones¶

guess_type = 'random'¶

lin_phase = None¶

quad_phase = None¶

slm_field_type = 'guess'¶

prop = 'fft'¶

img_pitch_fft¶

mask_pos¶

tar_width¶

tar_blur¶

phi_slm¶

phi_slm_native¶

laser_pow¶

i_slm¶

a_slm¶

e_slm¶

a_tar¶

i_tar¶