hologradpy.patterns =================== .. py:module:: hologradpy.patterns .. autoapi-nested-parse:: This module contains utility functions for array manipulation and functions to create binary masks, intensity and phase patterns of various shapes. The :py:class:`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 ------- .. autoapisummary:: hologradpy.patterns.Hologram Functions --------- .. autoapisummary:: hologradpy.patterns.make_grid hologradpy.patterns.pixel_corr hologradpy.patterns.unwrap_2d hologradpy.patterns.unwrap_2d_mask hologradpy.patterns.crop hologradpy.patterns.crop_to_mask hologradpy.patterns.load_filter_upscale hologradpy.patterns.rect_mask hologradpy.patterns.rect_mask_xy hologradpy.patterns.circ_mask hologradpy.patterns.circ_mask_xy hologradpy.patterns.gaussian hologradpy.patterns.super_gaussian hologradpy.patterns.gauss_array hologradpy.patterns.ring_gauss hologradpy.patterns.checkerboard hologradpy.patterns.fringes_wavefront hologradpy.patterns.init_phase hologradpy.patterns.lens hologradpy.patterns.doublet hologradpy.patterns.slm_phase_doublet hologradpy.patterns.pixel_ct_kernel hologradpy.patterns.vortex_field hologradpy.patterns.detect_vortices Module Contents --------------- .. py:function:: 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. :param im: Input array. :param scale: Optional scaling factor. :return: x and y meshgrid arrays. .. py:function:: pixel_corr(img, x, y) Replace a pixel value with coordinates x and y by the mean value of its 3x3 neighbourhood. :param img: Input image. :param x: x-coordinate of pixel. :param y: y-coordinate of pixel. :return: Corrected image. .. py:function:: unwrap_2d(img, **kwargs) Unwraps an image along the x- and y-axis. :param img: Input image. :param kwargs: kwargs for ``np.unwrap()`` function. :return: Unwrapped image. .. py:function:: unwrap_2d_mask(img, mask, **kwargs) Unwraps an image within a region of interest defined by a binary mask. :param img: Input image. :param mask: Binary mask with region of interest. :param kwargs: kwargs for np.unwrap() function. :return: Unwrapped image. .. py:function:: crop(img, n_crop) Crops an image around all four edges by n_crop pixels. :param img: Input image. :param n_crop: Number of pixels to crop at both end of each dimension. :return: Cropped image. .. py:function:: crop_to_mask(img, mask) Crops an image to the smallest size taken up by a binary mask. :param img: Input image. :param mask: Binary mask. :return: Cropped image. .. py:function:: 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. :param path: Numpy array or path to numpy array. :param npx: Number of SLM pixels. :param pix_res: Number of pixels per SLM pixel. :param crop: Number of unused pixels [SLM pixels]. :param filter_size: Size of the uniform filter. :return: Upscaled image. .. py:function:: rect_mask(im, dx, dy, w, h) Rectangular mask using pixel coordinates of an input image. :param im: Input image :param dx: X-offset of rectangle from the centre of the image. :param dy: Y-offset of rectangle from the centre of the image. :param w: Width of rectangle. :param h: Height of rectangle. :return: Binary mask. .. py:function:: rect_mask_xy(x, y, dx, dy, w, h) Rectangular mask using XY meshgrid coordinates. :param x: X meshgrid :param y: Y meshgrid :param dx: X-offset of rectangle from the centre of the image. :param dy: Y-offset of rectangle from the centre of the image. :param w: Width of rectangle. :param h: Height of rectangle. :return: Binary mask. .. py:function:: circ_mask(im, dx, dy, r) Circular mask using pixel coordinates of an input image. :param im: Input image :param dx: X-offset of circle. :param dy: Y-offset of circle. :param r: Radius of circle. :return: Binary mask. .. py:function:: circ_mask_xy(x, y, dx, dy, r, sparse=None) Circular mask using XY meshgrid coordinates. :param x: X meshgrid. :param y: Y meshgrid. :param dx: X-offset of circle. :param dy: Y-offset of circle. :param r: Radius of circle. :return: Binary mask. .. py:function:: gaussian(x, y, dx, dy, sig_x, sig_y=None, a=1, c=0) 2D Gaussian. :param x: X meshgrid. :param y: Y meshgrid. :param dx: X-offset of Gaussian. :param dy: Y-offset of Gaussian. :param sig_x: X width of Gaussian. :param sig_y: Y width of Gaussian :param a: Amplitude. :param c: Offset. :return: 2D Gaussian. .. py:function:: super_gaussian(x, y, dx, dy, nx, ny, sig_x, sig_y, a=1, c=0) 2D super-Gaussian. :param x: X meshgrid. :param y: Y meshgrid. :param dx: X-offset of Gaussian. :param dy: Y-offset of Gaussian. :param nx: X-order. :param ny: Y-order. :param sig_x: X-width. :param sig_y: Y-width. :param a: Amplitude. :param c: Offset. :return: 2D super-Gaussian. .. py:function:: gauss_array(im, nx, ny, dx, dy, d, sigma) Gaussian spot array using coordinates of input image. :param im: Input image. :param nx: Number of array columns. :param ny: Number of array rows. :param dx: X-offset of array. :param dy: Y-offset of array. :param d: Separation between neighbouring spots. :param sigma: Width of Gaussian spots. :return: Spot array. .. py:function:: ring_gauss(x, y, dx, dy, r, w, a=1) Ring with Gaussian profile. :param x: X meshgrid. :param y: Y meshgrid. :param dx: X-offset of ring. :param dy: Y-offset of ring. :param r: Radius of ring. :param w: Width of Gaussian profile. :param a: Amplitude. :return: Ring with Gaussian profile. .. py:function:: checkerboard(npx, dx, dy, rows, columns, square_size) Creates a checkerboard on a canvas of `(npx, npx)` pixels. :param npx: Size of canvas. :param dx: X-offset of checkerboard. :param dy: Y-Offset of checkerboard. :param rows: Checkerboard rows. :param columns: Checkerboard columns. :param square_size: Size of a square in pixels :return: Checkerboard. .. py:function:: 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. :param x: X meshgrid. :param y: Y meshgrid. :param dx: Separation between reference and sample patch along x [m]. :param dy: Separation between reference and sample patch along y [m]. :param k: Wavenumber [rad/m]. :param f: Focal length of Fourier lens [m]. :param phi: Phase difference between reference and sample patches (see paper above) [rad]. :param a: Amplitude on reference patch. :param b: Amplitude on sample patch. :return: Interference pattern. .. py:function:: 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). :param ndarray img: 2D array with size of desired output. :param slm_disp_obj: Instance of Params class :param ndarray lin_phase: Vector of length 2, containing parameters for the linear phase term :param ndarray quad_phase: Vector of length 2, containing parameters for the quadratic phase term :param str lin_method: 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]. :return: Phase pattern of shape ``img.shape`` .. py:function:: lens(x, y, k, f) Phase of a parabolic lens. :param x: X-meshgrid [m]. :param y: Y-meshgrid [m]. :param k: Wavenumber [rad/m]. :param f: Focal length [m]. :return: Phase of the lens [rad]. .. py:function:: doublet(x, y, k, n1, n2, r1, r2, r3, dx=None, dy=None) Phase of a doublet lens. :param x: X-meshgrid [m]. :param y: Y-meshgrid [m]. :param k: Wavenumber [rad/m]. :param n1: Refractive index of flint. :param n2: Refractive index of crown. :param r1: Radius of curvature of the first crown surface [m]. :param r2: Radius of curvature of the second crown surface/ first flint surface [m]. :param r3: Radius of curvature of the second flint surface [m]. :param dx: X-offset of lens [m]. :param dy: Y-offset of lens [m]. :return: Phase of the doublet lens [rad]. .. py:function:: 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). :param dx: X-position of sample patch [m]. :param dy: Y-position of sample patch [m]. :param k: Wavenumber [rad/m]. :param xf: X-position of phase measurement in the image plane [m]. :param yf: Y-position of phase measurement in the image plane [m]. :param z1: Distance between SLM and lens [m]. :param z2: Distance between lens and camera [m]. :param fl: Focal length of doublet lens [m]. :param n1: Refractive index of flint. :param n2: Refractive index of crown. :param r1: Radius of curvature of the first crown surface [m]. :param r2: Radius of curvature of the second crown surface/ first flint surface [m]. :param r3: Radius of curvature of the second flint surface [m]. :return: Corrective phase pattern [rad]. .. py:function:: 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). :param slm_pitch: Pixel pitch of SLM [m]. :param pix_res: Up-scaling factor (computational pixels per SLM pixel). :param extent: Spatial extent of kernel in SLM pixels. :param m: Order of the kernel. :param sigma: Width of the kernel. :return: 2D blurring kernel. .. py:function:: 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`` . :param img: 2D array with size of desired output. :param m: Vector of vortex charge (1 or -1). :param x: Vector of vortex x-coordinate [px]. :param y: Vector of vortex y-coordinate [px]. :return: Phase of vortex field with size ``img.shape``. .. py:function:: 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. :param n_pix: Number of pixels. :param e_holo: Electric field. :param i_tar: Target intensity pattern. :param 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. :return: Charge of vortices and their xy coordinates. .. py:class:: 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. .. py:attribute:: name .. py:attribute:: npix .. py:attribute:: npix_pad :value: None .. py:attribute:: slm_ones .. py:attribute:: pix_res :value: 1 .. py:attribute:: tar_res .. py:attribute:: tar_ones .. py:attribute:: guess_type :value: 'random' .. py:attribute:: lin_phase :value: None .. py:attribute:: quad_phase :value: None .. py:attribute:: slm_field_type :value: 'guess' .. py:attribute:: prop :value: 'fft' .. py:attribute:: img_pitch_fft .. py:attribute:: mask_pos .. py:attribute:: tar_width .. py:attribute:: tar_blur .. py:attribute:: phi_slm .. py:attribute:: phi_slm_native .. py:attribute:: laser_pow .. py:attribute:: i_slm .. py:attribute:: a_slm .. py:attribute:: e_slm .. py:attribute:: a_tar .. py:attribute:: i_tar