prtools — Utility functions for image-based phase retrieval

Version: 2.0.0

Useful links: Source Repository | Issue Tracker | Releases

Installation: install prtools with pip

pip install prtools

The prtools library provides functionality and tools that may be useful when performing image-based phase retrieval including:

• Image processing, reduction, and analysis

• Creating, fitting, and removing Zernike polynomials

• Drawing various shapes in arrays

• Computing statistics and optical simulation parameters

Note

Many prtools functions support both matrix (ij) and Cartesian (xy) indexing conventions via the indexing parameter. The default is matrix (indexing='ij') for all functions.

Array API support

prtools supports the Python array API standard. This means that prtools functions should work seamlessly with any array API-compatible ararys like those provided by NumPy, CuPy, PyTorch, and JAX.

Note

Only NumPy and JAX interoperability is currently tested. Additional backend libraries may be tested in the future.

Array manipulation

centroid	Compute array centroid location.
pad	Zero-pad an array.
crop	Extract a contiguous subarray from a larger array.
boundary	Find bounding row and column indices of data within an array.
rebin	Rebin an array by an integer factor.
rescale	Rescale an image by interpolation.
medfix	Fix masked entries in a 2-dimensional array via median filtering.
normpow	Normalizie the power in an array.
shift	Shift an array via FFT.
register	Compute the subpixel image translation to register the input array x1 to a reference array x2.

Array metrics

rms	Compute the root-mean-square of the nonzero entries
nanrms	Compute the root-mean-square of the nonzero entries, ignoring any NaNs.
pv	Compute range of values (max - min)
nanpv	Compute range of values (max - min), ignoring any NaNs.
radial_avg	Compute the average radial profile of the input
ee	Compute the encircled energy diameter for a given energy fraction.
teng	The Tenengrad function computes image sharpness as the mean squared Sobel gradient magnitude.

Shapes

circle	Draw a circle
rectangle	Draw a rectangle
hexagon	Draw a hexagon
hex_segments	Draw a segmented aperture made up of hexagonal segments
spider	Draw a spider
sin	Generate a 2D sine function.
waffle	Generate a 2D waffle function.
mesh	Generate a standard mesh.

Fourier transforms

dft2	Compute the 2-dimensional discrete Fourier Transform.
idft2	Compute the 2-dimensional inverse discrete Fourier Transform.

Convolution and filtering

fftconv	Convolve an array with a kernel using the FFT.
gauss_blur	Blur an image using a Gaussian filter using the FFT.
pixelate	Apply the aperture effects of an idealized square pixel using the FFT.
gauss	2D Gaussian function
sinc	2D sinc function
gauss_kernel	2D Gaussian filter kernel
pixel_kernel	2D pixel MTF filter kernel

Morphology

binary_dilation	Binary dilation using the given structure element.
binary_erosion	Binary erosion using the given structure element.
binary_opening	Binary opening using the given structure element.
binary_closing	Binary closing using the given structure element.

Sparse matrices

index	Sparse coordinate list (COO) index
sparse	Create a sparse array from a dense matrix
dense	Create a dense matrix from a sparse array
index_from_mask	Create a sparse coordinate list (COO) index object from a mask.
mask_from_index	Create a mask from a sparse coordinate list (COO) index.

Zernike polynomials

zernike	Compute the circular Zernike polynomial for a given mask.
zernike_fit	Fit a Zernike basis set to an OPD.
zernike_remove	Fit and remove a Zernike basis set from an OPD.
zernike_compose	Create an OPD based on the supplied Zernike coefficients.
zernike_basis	Compute a Zernike basis set for a given mask.
zernike_coordinates	Compute the Zernike coordinate system for a given mask.

Cost functions

sserror

Compute the normalized sum squared error between two arrays.

Miscellaneous

calcpsf	Calculate a point spread function using far-field diffraction.
pixelscale_nyquist	Compute the output plane sampling that is Nyquist sampled for intensity.
min_sampling	Compute the minimum pupil plane sampling to satisfy given constraints.
fft_shape	Compute FFT pad shape to satisfy sampling constraints
translation_defocus	Compute the peak-to-valley defocus imparted by a given translation along the optical axis
find_wrapped	Attempt to find phase wrapping using gradient edge detection while automatically ignoring large gradients at mask edges.

prtools.jax

jax.lbfgs	Minimize a scalar function of one or more variables using the L-BFGS algorithm
jax.JaxOptimizeResult	Represents the optimization result.

Note

The jax module has the following additional dependencies:

• JAX

• Optax

prtools can be installed with the additional jax dependencies with

pip install prtools[jax]