opticks.imaging_model.optics

Classes

Optics(**data)

Class containing generic Optics parameters.

class Optics(**data)

Class containing generic Optics parameters.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

• name (str)

• focal_length (Annotated[Quantity, BeforeValidator(func=~opticks.utils.parser_helpers._parse_quantity, json_schema_input_type=PydanticUndefined), AfterValidator(func=~opticks.utils.parser_helpers._validate_positive_quantity), PlainSerializer(func=~opticks.utils.parser_helpers._serialize_quantity, return_type=str, when_used=always)])

• aperture_diameter (Annotated[Quantity, BeforeValidator(func=~opticks.utils.parser_helpers._parse_quantity, json_schema_input_type=PydanticUndefined), AfterValidator(func=~opticks.utils.parser_helpers._validate_positive_quantity), PlainSerializer(func=~opticks.utils.parser_helpers._serialize_quantity, return_type=str, when_used=always)])

• image_diam_on_focal_plane (Annotated[Quantity, BeforeValidator(func=~opticks.utils.parser_helpers._parse_quantity, json_schema_input_type=PydanticUndefined), AfterValidator(func=~opticks.utils.parser_helpers._validate_positive_quantity), PlainSerializer(func=~opticks.utils.parser_helpers._serialize_quantity, return_type=str, when_used=always)])

• pupil_functs (dict[str, PupilFunction])

• aperture_dx (Quantity | None)

• aperture (Aperture | None)

add_mono_pupil_function(name, wavelength, opd=None)

Create a monochromatic PupilFunction and register it.

Return type:

PupilFunction

Parameters:

• name (str) – identifier for this pupil function

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

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

Returns:

PupilFunction – the created PupilFunction for convenience

add_poly_pupil_function(name, wavelengths, opds, spectral_weights=None)

Create a polychromatic PupilFunction and register it.

Return type:

PupilFunction

Parameters:

• name (str) – identifier for this pupil function

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

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

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

Returns:

PupilFunction – the created PupilFunction for convenience

aperture: Aperture | None

property aperture_area: Quantity

Aperture area.

Computed as: pi x (aperture diameter/2 )^2

aperture_diameter: Annotated[Quantity, BeforeValidator(func=_parse_quantity, json_schema_input_type=PydanticUndefined), AfterValidator(func=_validate_positive_quantity), PlainSerializer(func=_serialize_quantity, return_type=str, when_used=always)]

aperture_dx: Quantity | None

property aperture_solid_angle: Quantity

Aperture solid angle in steradians.

clear_pupil_functs()

Remove all PupilFunctions.

Return type:

None

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

Compute PSF for the named PupilFunction (caches + returns).

Return type:

RichData

Parameters:

• pupil_name (str) – identifier of the pupil function

• 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

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

Returns:

RichData – PSF model

property f_number: float

F-number.

Computed as: focal length / aperture diameter

field_mtf_model_1d(field_model, h, wavelength)

Aberrated 1D MTF at normalised field position h (Tier B path).

Uses the Seidel model to compute the total RMS WFE at the given field position and feeds it into the empirical ATF model.

Return type:

MTF_Model_1D

Parameters:

• field_model (FieldAberrationModel) – Seidel coefficient set

• h (float) – Normalised radial field coordinate (0 = on-axis, 1 = edge)

• wavelength (Quantity[``”length”``]) – Wavelength for the MTF computation

Returns:

MTF_Model_1D – Aberrated 1D MTF model at the given field position

focal_length: Annotated[Quantity, BeforeValidator(func=_parse_quantity, json_schema_input_type=PydanticUndefined), AfterValidator(func=_validate_positive_quantity), PlainSerializer(func=_serialize_quantity, return_type=str, when_used=always)]

property full_optical_fov: Quantity

Full optical Field of View.

Actual FoV depends on the detector size, but cannot be wider than this value.

get_pupil_function(name)

Retrieve a named PupilFunction.

Return type:

PupilFunction

Parameters:

name (str) – identifier of the pupil function

Returns:

PupilFunction – the requested PupilFunction

image_diam_on_focal_plane: Annotated[Quantity, BeforeValidator(func=_parse_quantity, json_schema_input_type=PydanticUndefined), AfterValidator(func=_validate_positive_quantity), PlainSerializer(func=_serialize_quantity, return_type=str, when_used=always)]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mtf(pupil_name)

Return MTF derived from cached PSF for the named PupilFunction.

Lazily computed on first access; cached until PSF is recomputed.

Return type:

RichData

Parameters:

pupil_name (str) – identifier of the pupil function

Returns:

RichData – MTF model

Raises:

ValueError – if compute_psf() has not been called yet

name: str

normalised_field_from_angle(theta_x, theta_y)

Convert a field angle to normalised field coordinates.

Maps a (theta_x, theta_y) field angle (relative to the optical axis) to dimensionless field coordinates (H_x, H_y) in [-1, 1], where H = 1 corresponds to the edge of the full optical field of view.

Return type:

tuple[float, float]

Parameters:

• theta_x (Quantity[``”angle”``]) – Field angles measured from the optical axis

• theta_y (Quantity[``”angle”``]) – Field angles measured from the optical axis

Returns:

tuple[float, float] – Normalised field coordinates (H_x, H_y)

normalised_field_from_focal_plane_xy(x, y)

Convert a focal-plane position to normalised field coordinates.

Maps a focal-plane location (x, y) (relative to the optical axis intercept) to dimensionless field coordinates (H_x, H_y) in [-1, 1], using the image diameter on the focal plane to set H = 1.

Return type:

tuple[float, float]

Parameters:

• x (Quantity[``”length”``]) – Focal-plane coordinates measured from the optical axis

• y (Quantity[``”length”``]) – Focal-plane coordinates measured from the optical axis

Returns:

tuple[float, float] – Normalised field coordinates (H_x, H_y)

psf(pupil_name)

Return cached PSF for the named PupilFunction.

Return type:

RichData

Parameters:

pupil_name (str) – identifier of the pupil function

Returns:

RichData – cached PSF model

Raises:

ValueError – if compute_psf() has not been called yet

pupil_functs: dict[str, PupilFunction]

remove_pupil_function(name)

Remove a named PupilFunction.

Return type:

None

Parameters:

name (str) – identifier of the pupil function to remove

set_aperture_model(aperture=None, samples=400)

Sets the aperture model for the optics.

The aperture model is as defined by prysm, it contains an ndarray grid of True and False data, where True allows light through. It can also be an ndarray grid of 0 and 1 (and anything in between).

If None, a new circular aperture is defined using the aperture diameter of the optics and the samples parameter (for one side of the square grid). If an aperture is defined, samples is ignored.

Grid is optional and is added only when a new aperture is defined

Return type:

None

Parameters:

• aperture (aperture) – aperture object

• samples (int, optional) – sample size of the default circular aperture, ignored if aperture is user defined

spatial_cutoff_freq(ref_wavelength)

Spatial cut-off frequency, assumes perfect incoherent optics.

Determines the theoretical limit of the optical resolution, or the smallest object resolvable by the optical system.

Computed as: 1/(wavelength x F#) in cycles per mm

Return type:

Quantity

Parameters:

ref_wavelength (Quantity) – Reference wavelength

Returns:

Quantity – Spatial cutoff frequency (in cycles/mm)

to_MTF_Model_1D(pupil_name, slice)

Convert the cached 2D MTF to a 1D MTF model for the named PupilFunction.

Return type:

MTF_Model_1D

Parameters:

• pupil_name (str) – identifier of the pupil function

• 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