prysm.psf

A base point spread function interface.

prysm.psf.estimate_size(x, y, data, metric, criteria='last')

Calculate the “size” of the function in data based on a metric.

Parameters
  • x (numpy.ndarray) – x coordinates, 1D

  • y (numpy.ndarray) – y coordinates, 1D

  • data (numpy.ndarray) – f(x,y), 2D

  • metric (str or float, {‘fwhm’, ‘1/e’, ‘1/e^2’, float()}) – what metric to apply

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

the radial coordinate at which on average the function reaches <metric>

Return type

float

Raises

ValueError – metric not in (‘fwhm’, ‘1/e’, ‘1/e^2’, numbers.Number())

prysm.psf.fwhm(x, y, data, criteria='last')

Calculate the FWHM of (data).

Parameters
  • x (numpy.ndarray) – x coordinates, 1D

  • y (numpy.ndarray) – y coordinates, 1D

  • data (numpy.ndarray) – f(x,y), 2D

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

the FWHM

Return type

float

prysm.psf.one_over_e(x, y, data, criteria='last')

Calculate the 1/e radius of (data).

Parameters
  • x (numpy.ndarray) – x coordinates, 1D

  • y (numpy.ndarray) – y coordinates, 1D

  • data (numpy.ndarray) – f(x,y), 2D

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

the 1/e radius

Return type

float

prysm.psf.one_over_e2(x, y, data, criteria='last')

Calculate the 1/e^2 radius of (data).

Parameters
  • x (numpy.ndarray) – x coordinates, 1D

  • y (numpy.ndarray) – y coordinates, 1D

  • data (numpy.ndarray) – f(x,y), 2D

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

the 1/e^2 radius

Return type

float

class prysm.psf.PSF(x, y, data)

Bases: prysm.convolution.Convolvable

A Point Spread Function.

estimate_size(metric, criteria='last')

Calculate the size of self.

Parameters
  • metric (str or float, {‘fwhm’, ‘1/e’, ‘1/e^2’, float()}) – what metric to apply

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

estimate for the radius of self calculated via (metric)

Return type

float

fwhm(criteria='last')

Calculate the FWHM of self.

Parameters
  • metric (str or float, {‘fwhm’, ‘1/e’, ‘1/e^2’, float()}) – what metric to apply

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

the FWHM radius of self

Return type

float

one_over_e(criteria='last')

Calculate the 1/e radius of self.

Parameters
  • metric (str or float, {‘fwhm’, ‘1/e’, ‘1/e^2’, float()}) – what metric to apply

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

the FWHM radius of self

Return type

float

one_over_e2(criteria='last')

Calculate the 1/e^2 of self.

Parameters
  • metric (str or float, {‘fwhm’, ‘1/e’, ‘1/e^2’, float()}) – what metric to apply

  • criteria (str, optional, {‘first’, ‘last’}) – whether to use the first or last occurence of <metric>

Returns

the FWHM radius of self

Return type

float

encircled_energy(radius)

Compute the encircled energy of the PSF.

Parameters

radius (float or iterable) – radius or radii to evaluate encircled energy at

Returns

if radius is a float, returns a float, else returns a list.

Return type

encircled energy

Notes

implementation of “Simplified Method for Calculating Encircled Energy,” Baliga, J. V. and Cohn, B. D., doi: 10.1117/12.944334

ee_radius(energy=0.8377850436212378)

Radius associated with a certain amount of enclosed energy.

ee_radius_diffraction(energy=0.8377850436212378)

Radius associated with a certain amount of enclosed energy for a diffraction limited circular pupil.

ee_radius_ratio_to_diffraction(energy=0.8377850436212378)

Ratio of this PSF and the diffraction limited PSFs’ radii enclosing a certain amount of energy.

plot_encircled_energy(axlim=None, npts=50, lw=3, zorder=3, fig=None, ax=None)

Make a 1D plot of the encircled energy at the given azimuth.

Parameters
  • azimuth (float) – azimuth to plot at, in degrees

  • axlim (float) – limits of axis, will plot [0, axlim]

  • npts (int, optional) – number of points to use from [0, axlim]

  • lw (float, optional) – line width

  • zorder (int optional) – zorder

  • fig (matplotlib.figure.Figure, optional) – Figure containing the plot

  • ax (matplotlib.axes.Axis, optional:) – Axis containing the plot

Returns

  • fig (matplotlib.figure.Figure, optional) – Figure containing the plot

  • ax (matplotlib.axes.Axis, optional:) – Axis containing the plot

static from_pupil(pupil, efl, Q=2, norm='max', radpower=1, incoherent=True)

Use scalar diffraction propogation to generate a PSF from a pupil.

Parameters
  • pupil (Pupil) – Pupil, with OPD data and wavefunction

  • efl (int or float) – effective focal length of the optical system, mm

  • Q (int or float) – ratio of pupil sample count to PSF sample count; Q > 2 satisfies nyquist

  • norm (str, {‘max’, ‘radiometric’}, optional) – how to normalize the result, if radiometric will follow Born & Wolf with: I0 = P * A / (L^2 R^2) with P = radpower, A = integral over aperture, L = wavelength R = efl

  • radpower (float) – total power of the incident beam over the clear aperture, W only used when norm=’radiometric’

  • incoherent (bool, optional) – if True, propagate the incoherent PSF, else propagate the coherent one

Returns

A new PSF instance

Return type

PSF

static polychromatic(psfs, spectral_weights=None, interp_method='linear')

Create a new PSF instance from an ensemble of monochromatic PSFs given spectral weights.

The new PSF is the polychromatic PSF, assuming the wavelengths are sufficiently different that they do not interfere and the mode of imaging is incoherent.

center_x

Center “pixel” in x.

center_y

Center “pixel” in y.

change_xy_unit(to, inplace=True)

Change the x/y unit to a new one, scaling the data in the process.

Parameters
  • to (astropy.unit or str) – if not an astropy unit, a string that is a valid attribute of astropy.units.

  • inplace (bool, optional) – if True, returns self. Otherwise returns the modified data.

Returns

  • RichData – self, if inplace=True

  • numpy.ndarray, numpy.ndarray – x, y from self, if inplace=False

change_z_unit(to, inplace=True)

Change the z unit to a new one, scaling the data in the process.

Parameters
  • to (astropy.unit or str) – if not an astropy unit, a string that is a valid attribute of astropy.units.

  • inplace (bool, optional) – if True, returns self. Otherwise returns the modified data.

Returns

  • RichData – self, if inplace=True

  • numpy.ndarray – data from self, if inplace=False

conv(other)

Convolves this convolvable with another.

Parameters

other (Convolvable) – A convolvable object

Returns

a convolvable object

Return type

Convolvable

Notes

If self and other both have analytic Fourier transforms, no math will be done and the aFTs are merged directly.

If only one of self or other has an analytic Fourier transform, the output grid will be defined by the object which does not have an analytic Fourier transform.

If neither has an analytic transform, the output grid will: - span max(self.support, other.support) - have sample spacing min(self.sample_spacing, other.sample_spacing)

This ensures the signal remains Nyquist sampled and (probably) doesn’t expand beyond the extent of the output window. The latter condition will be violated when two large convolvables are convolved.

copy()

Return a (deep) copy of this instance.

deconv(other, balance=1000, reg=None, is_real=True, clip=False, postnormalize=True)

Perform the deconvolution of this convolvable object by another.

Parameters
  • other (Convolvable) – another convolvable object, used as the PSF in a Wiener deconvolution

  • balance (float, optional) – regularization parameter; passed through to skimage

  • reg (numpy.ndarray, optional) – regularization operator, passed through to skimage

  • is_real (bool, optional) – True if self and other are both real

  • clip (bool, optional) – clips self and other into (0,1)

  • postnormalize (bool, optional) – normalize the result such that it falls in [0,1]

Returns

a new Convolable object

Return type

Convolvable

Notes

See skimage: http://scikit-image.org/docs/dev/api/skimage.restoration.html#skimage.restoration.wiener

exact_polar(rho, phi=None)

Retrieve data at the specified radial coordinates pairs.

Parameters
  • r (iterable) – radial coordinate(s) to sample

  • phi (iterable) – azimuthal coordinate(s) to sample

Returns

data at the given points

Return type

numpy.ndarray

exact_x(x)

Return data at an exact x coordinate along the y=0 axis.

Parameters

x (number or numpy.ndarray) – x coordinate(s) to return

Returns

ndarray of values

Return type

numpy.ndarray

exact_xy(x, y=None)

Retrieve data at the specified X-Y frequency pairs.

Parameters
  • x (iterable) – X coordinate(s) to retrieve

  • y (iterable) – Y coordinate(s) to retrieve

Returns

data at the given points

Return type

numpy.ndarray

exact_y(y)

Return data at an exact y coordinate along the x=0 axis.

Parameters

y (number or numpy.ndarray) – y coordinate(s) to return

Returns

ndarray of values

Return type

numpy.ndarray

static from_file(path, scale)

Read a monochrome 8 bit per pixel file into a new Image instance.

Parameters
  • path (string) – path to a file

  • scale (float) – pixel scale, in microns

Returns

a new image object

Return type

Convolvable

msaa(factor=2)

Multi-Sample anti-aliasing

Perform anti-aliasing by averaging blocks of (factor, factor) pixels into a simple value.

Parameters

factor (int, optional) – factor by which to decimate the data

Returns

self

Return type

Convolvable

plot2d(xlim=None, ylim=None, clim=None, cmap=None, log=False, power=1, interpolation=None, show_colorbar=True, show_axlabels=True, fig=None, ax=None)

Plot the data in 2D.

Parameters
  • xlim (float or iterable, optional) – x axis limits. If not iterable, symmetric version of the single value

  • ylim (float or iterable, optional) – y axis limits. If None and xlim is not None, copied from xlim. If not iterable, symmetric version of the single value.

  • clim (iterable, optional) – clim passed directly to matplotlib. If None, looked up on self._default_clim.

  • cmap (str, optional) – colormap to use, passed directly to matplotlib if not None. If None, looks up the default cmap for self._data_type on config

  • log (bool, optional) – if True, plot on a log color scale

  • power (float, optional) – if not 1, plot on a power stretched color scale

  • interpolation (str, optional) – interpolation method to use, passed directly to matplotlib

  • show_colorbar (bool, optional) – if True, draws the colorbar

  • show_axlabels (bool, optional) – if True, draws the axis labels

  • fig (matplotlib.figure.Figure) – Figure containing the plot

  • ax (matplotlib.axes.Axis) – Axis containing the plot

Returns

  • fig (matplotlib.figure.Figure) – Figure containing the plot

  • ax (matplotlib.axes.Axis) – Axis containing the plot

renorm()

Renormalize so that the peak is at a value of unity and the minimum value is zero

sample_spacing

center-to-center sample spacing.

samples_x

Number of samples in the x dimension.

samples_y

Number of samples in the y dimension.

save(path, nbits=8)

Write the image to a png, jpg, tiff, etc.

Parameters
  • path (string) – path to write the image to

  • nbits (int) – number of bits in the output image

shape

Proxy to phase or data shape.

size

Proxy to phase or data size.

slices(twosided=None)

Create a Slices instance from this instance.

Parameters

twosided (bool, optional) – if None, copied from self._default_twosided

Returns

a Slices object

Return type

Slices

support

Width of the domain.

support_x

Width of the domain in X.

support_y

Width of the domain in Y.

class prysm.psf.AiryDisk(fno, wavelength, extent=None, samples=None)

Bases: prysm.convolution.Convolvable

An airy disk, the PSF of a circular aperture.

analytic_ft(x, y)

Analytic fourier transform of an airy disk.

Parameters
  • x (numpy.ndarray) – sample points in x axis

  • y (numpy.ndarray) – sample points in y axis

Returns

2D numpy array containing the analytic fourier transform

Return type

numpy.ndarray

center_x

Center “pixel” in x.

center_y

Center “pixel” in y.

change_xy_unit(to, inplace=True)

Change the x/y unit to a new one, scaling the data in the process.

Parameters
  • to (astropy.unit or str) – if not an astropy unit, a string that is a valid attribute of astropy.units.

  • inplace (bool, optional) – if True, returns self. Otherwise returns the modified data.

Returns

  • RichData – self, if inplace=True

  • numpy.ndarray, numpy.ndarray – x, y from self, if inplace=False

change_z_unit(to, inplace=True)

Change the z unit to a new one, scaling the data in the process.

Parameters
  • to (astropy.unit or str) – if not an astropy unit, a string that is a valid attribute of astropy.units.

  • inplace (bool, optional) – if True, returns self. Otherwise returns the modified data.

Returns

  • RichData – self, if inplace=True

  • numpy.ndarray – data from self, if inplace=False

conv(other)

Convolves this convolvable with another.

Parameters

other (Convolvable) – A convolvable object

Returns

a convolvable object

Return type

Convolvable

Notes

If self and other both have analytic Fourier transforms, no math will be done and the aFTs are merged directly.

If only one of self or other has an analytic Fourier transform, the output grid will be defined by the object which does not have an analytic Fourier transform.

If neither has an analytic transform, the output grid will: - span max(self.support, other.support) - have sample spacing min(self.sample_spacing, other.sample_spacing)

This ensures the signal remains Nyquist sampled and (probably) doesn’t expand beyond the extent of the output window. The latter condition will be violated when two large convolvables are convolved.

copy()

Return a (deep) copy of this instance.

deconv(other, balance=1000, reg=None, is_real=True, clip=False, postnormalize=True)

Perform the deconvolution of this convolvable object by another.

Parameters
  • other (Convolvable) – another convolvable object, used as the PSF in a Wiener deconvolution

  • balance (float, optional) – regularization parameter; passed through to skimage

  • reg (numpy.ndarray, optional) – regularization operator, passed through to skimage

  • is_real (bool, optional) – True if self and other are both real

  • clip (bool, optional) – clips self and other into (0,1)

  • postnormalize (bool, optional) – normalize the result such that it falls in [0,1]

Returns

a new Convolable object

Return type

Convolvable

Notes

See skimage: http://scikit-image.org/docs/dev/api/skimage.restoration.html#skimage.restoration.wiener

exact_polar(rho, phi=None)

Retrieve data at the specified radial coordinates pairs.

Parameters
  • r (iterable) – radial coordinate(s) to sample

  • phi (iterable) – azimuthal coordinate(s) to sample

Returns

data at the given points

Return type

numpy.ndarray

exact_x(x)

Return data at an exact x coordinate along the y=0 axis.

Parameters

x (number or numpy.ndarray) – x coordinate(s) to return

Returns

ndarray of values

Return type

numpy.ndarray

exact_xy(x, y=None)

Retrieve data at the specified X-Y frequency pairs.

Parameters
  • x (iterable) – X coordinate(s) to retrieve

  • y (iterable) – Y coordinate(s) to retrieve

Returns

data at the given points

Return type

numpy.ndarray

exact_y(y)

Return data at an exact y coordinate along the x=0 axis.

Parameters

y (number or numpy.ndarray) – y coordinate(s) to return

Returns

ndarray of values

Return type

numpy.ndarray

static from_file(path, scale)

Read a monochrome 8 bit per pixel file into a new Image instance.

Parameters
  • path (string) – path to a file

  • scale (float) – pixel scale, in microns

Returns

a new image object

Return type

Convolvable

msaa(factor=2)

Multi-Sample anti-aliasing

Perform anti-aliasing by averaging blocks of (factor, factor) pixels into a simple value.

Parameters

factor (int, optional) – factor by which to decimate the data

Returns

self

Return type

Convolvable

plot2d(xlim=None, ylim=None, clim=None, cmap=None, log=False, power=1, interpolation=None, show_colorbar=True, show_axlabels=True, fig=None, ax=None)

Plot the data in 2D.

Parameters
  • xlim (float or iterable, optional) – x axis limits. If not iterable, symmetric version of the single value

  • ylim (float or iterable, optional) – y axis limits. If None and xlim is not None, copied from xlim. If not iterable, symmetric version of the single value.

  • clim (iterable, optional) – clim passed directly to matplotlib. If None, looked up on self._default_clim.

  • cmap (str, optional) – colormap to use, passed directly to matplotlib if not None. If None, looks up the default cmap for self._data_type on config

  • log (bool, optional) – if True, plot on a log color scale

  • power (float, optional) – if not 1, plot on a power stretched color scale

  • interpolation (str, optional) – interpolation method to use, passed directly to matplotlib

  • show_colorbar (bool, optional) – if True, draws the colorbar

  • show_axlabels (bool, optional) – if True, draws the axis labels

  • fig (matplotlib.figure.Figure) – Figure containing the plot

  • ax (matplotlib.axes.Axis) – Axis containing the plot

Returns

  • fig (matplotlib.figure.Figure) – Figure containing the plot

  • ax (matplotlib.axes.Axis) – Axis containing the plot

renorm()

Renormalize so that the peak is at a value of unity and the minimum value is zero

sample_spacing

center-to-center sample spacing.

samples_x

Number of samples in the x dimension.

samples_y

Number of samples in the y dimension.

save(path, nbits=8)

Write the image to a png, jpg, tiff, etc.

Parameters
  • path (string) – path to write the image to

  • nbits (int) – number of bits in the output image

shape

Proxy to phase or data shape.

size

Proxy to phase or data size.

slices(twosided=None)

Create a Slices instance from this instance.

Parameters

twosided (bool, optional) – if None, copied from self._default_twosided

Returns

a Slices object

Return type

Slices

support

Width of the domain.

support_x

Width of the domain in X.

support_y

Width of the domain in Y.

prysm.psf.airydisk(unit_r, fno, wavelength)

Compute the airy disk function over a given spatial distance.

Parameters
  • unit_r (numpy.ndarray) – ndarray with units of um

  • fno (float) – F/# of the system

  • wavelength (float) – wavelength of light, um

Returns

ndarray containing the airy pattern

Return type

numpy.ndarray