prtools — Utility functions for image-based phase retrieval

Version: 1.3.2

Useful links: Source Repository | Issue Tracker | Releases

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

Install prtools with pip:

pip install prtools

prtools supports different numerical backends for representing N-dimensional data and performing numerical calculations. The backend is configured by the prtools.use() function. Currently Numpy (the default backend) and JAX are supported. The table below shows how to use and optionally install each of the available backends:

Backend	Install	Use
numpy [1]	pip install prtools	prtools.use('numpy')
jax	pip install prtools[jax]	prtools.use('jax')

The current backend name is given in the prtools.__backend__ attribute.

Note

The prtools API remains the same regardless of which backend is in use, but different backends may expose additional functionality. See the backend-specific documentation below for more details.

[1]

The Numpy backend is initialized by default when prtools is imported. No additional steps are required to use prtools with the Numpy backend.

Array manipulation

centroid	Compute array centroid location.
pad	Zero-pad an array.
subarray	Extract a contiguous subarray from a larger array.
boundary	Find bounding row and column indices of data within an array.
rebin	Rebin an image 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 to a reference array.

Array metrics

rms	Compute the root-mean-square of the nonzero entries
pv	Compute peak-to-valley or max(a) - min(a)
radial_avg	Compute the average radial profile of the input
ee	Compute the encircled energy diameter for a given energy fraction.

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
gauss	Generate a 2D Gaussian function.
sin	Generate a 2D sine function.
waffle	Generate a 2D waffle function.
mesh	Generate a standard mesh.

Note

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

Fourier transforms

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

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 requested sampling condition
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.

Numerical backends

use	Select the backend used for N-dimensional array operations.

JAX backend

The JAX backend has the following additional dependencies:

• JAX

• Optax

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