opticks.imaging_model.pupil

Classes

PupilFunction(wavelengths, opds, aperture, ...)	Pupil function combining amplitude and phase information.
WvlRef(*values)	Reference wavelength selector for PSF output metadata.

class PupilFunction(wavelengths, opds, aperture, aperture_dx, focal_length, spectral_weights=None)

Pupil function combining amplitude and phase information.

A pupil function encapsulates one or more wavelength+OPD combinations (monochromatic or polychromatic) and can compute the resulting PSF.

Users should not create PupilFunction objects directly. Use Optics.add_mono_pupil_function() or Optics.add_poly_pupil_function() instead.

Parameters:

• wavelengths (Quantity) – wavelengths array (in microns)

• opds (list[OptPathDiff | None]) – list of optical path differences (in nm), one per wavelength. Use None for zero phase (perfect wavefront).

• aperture (Aperture) – aperture object

• aperture_dx (Quantity) – aperture sample distance (in mm)

• focal_length (Quantity) – focal length (in mm)

• spectral_weights (np.ndarray, optional) – spectral weight of each wavelength, by default uniform

compute_psf(psf_dx, psf_samples=512, wvl_ref=None, with_units=True)

Compute the PSF, cache internally, and return it.

Return type:

RichData

Parameters:

• psf_dx (Quantity) – sample distance of the output PSF plane grid (in microns)

• psf_samples (int, optional) – number of samples in the output plane, by default 512

• wvl_ref (WvlRef, optional) – reference wavelength selector for output metadata. For monochromatic, defaults to the only wavelength. For polychromatic, defaults to WvlRef.AVERAGE.

• with_units (bool, optional) – output the PSF with or without units, by default True

Returns:

RichData – PSF model

property is_monochromatic: bool

True if this pupil function has a single wavelength.

classmethod monochromatic(wavelength, opd, aperture, aperture_dx, focal_length)

Create a monochromatic PupilFunction (single wavelength).

This is useful for sampling of a narrow beam.

Return type:

PupilFunction

Parameters:

• wavelength (Quantity) – wavelength of light (in microns)

• opd (OptPathDiff | None) – optical path difference (in nm), or None for zero phase

• aperture (Aperture) – aperture object

• aperture_dx (Quantity) – aperture sample distance (in mm)

• focal_length (Quantity) – focal length (in mm)

property mtf: RichData

Return the MTF, computing lazily from the cached PSF if needed.

Raises:

ValueError – if compute_psf() has not been called yet

property num_wavelengths: int

Number of wavelengths in this pupil function.

classmethod polychromatic(wavelengths, opds, aperture, aperture_dx, focal_length, spectral_weights=None)

Create a polychromatic PupilFunction (multiple wavelengths).

This is useful for sampling of a broadband beam.

Return type:

PupilFunction

Parameters:

• wavelengths (Quantity) – wavelengths array (in microns)

• opds (list[OptPathDiff | None]) – list of optical path differences (in nm), one per wavelength

• aperture (Aperture) – aperture object

• aperture_dx (Quantity) – aperture sample distance (in mm)

• focal_length (Quantity) – focal length (in mm)

• spectral_weights (np.ndarray, optional) – spectral weight of each wavelength, by default uniform

property psf: RichData

Return the cached PSF.

Raises:

ValueError – if compute_psf() has not been called yet

property spectral_weights: ndarray

Spectral weights array.

to_MTF_Model_1D(slice)

Convert the cached 2D MTF to a 1D MTF model.

Extracts a 1D slice from the 2D MTF and returns it as an MTF_Model_1D object. The PSF must have been computed before calling this method.

Possible slice strings are x, y, azavg, azavmedian, azmin, azpv, azvar, azstd.

Return type:

MTF_Model_1D

Parameters:

slice (str) – slice type (e.g., “x”, “y”, “azavg”)

Returns:

MTF_Model_1D – 1D MTF model

Raises:

ValueError – if compute_psf() has not been called yet

property wavelengths: Quantity

Wavelengths array.

class WvlRef(*values)

Reference wavelength selector for PSF output metadata.

AVERAGE = 'average'

FIRST = 'first'

LAST = 'last'

MID = 'mid'

resolve(wavelengths)

Select a wavelength from the Quantity array based on this selector.

Return type:

Quantity

Parameters:

wavelengths (Quantity) – wavelengths array to select from

Returns:

Quantity – the selected wavelength