fields.field_types

Field Types Package

This package defines different field types for optical systems, including angle, object height, paraxial image height, and real image height fields. Each field type implements methods to calculate ray origins and paraxial object positions based on the field definition.

Kramer Harrison, 2025

class AngleField

Defines fields by angle (in degrees) relative to the optical axis.

For an object at infinity the field direction is composed from the two component angles against the entry axis; (u, v) pupil/field offsets use the entry frame’s transverse basis for folded or off-axis-entered systems. Two-dimensional fields at or beyond 90 degrees total are ambiguous under this representation and are rejected (see _validate_unambiguous_field()).

classmethod create(field_type: str) → BaseFieldDefinition

Instantiate a field definition by its registered name.

Parameters:

field_type – The registered name of the field type.

Returns:

A new instance of the corresponding field definition.

Raises:

ValueError – If field_type is not in the registry.

classmethod from_dict(field_def_dict: dict) → BaseFieldDefinition

Create a field definition from a dictionary.

Parameters:

field_def_dict (dict) – A dictionary representation of the field definition.

Returns:

A field definition object created from the

dictionary.

Return type:

BaseFieldDefinition

Raises:

ValueError – If field_type is missing or not in the registry.

get_paraxial_object_position(optic, Hy, y1, EPL)

Calculate the position of the object in the paraxial optical system.

Parameters:

• Hy (float) – The normalized field height.

• y1 (ndarray) – The initial y-coordinate of the ray.

• EPL (float) – The entrance pupil location.

Returns:

A tuple containing the y and z coordinates of the object

position.

Return type:

tuple

get_ray_origins(optic, Hx, Hy, Px, Py, vx, vy)

Calculate the initial positions for rays originating at the object.

Parameters:

• Hx (float) – Normalized x field coordinate.

• Hy (float) – Normalized y field coordinate.

• Px (float or be.ndarray) – x-coordinate of the pupil point.

• Py (float or be.ndarray) – y-coordinate of the pupil point.

• vx (float) – Vignetting factor in the x-direction.

• vy (float) – Vignetting factor in the y-direction.

Returns:

A tuple containing the x, y, and z coordinates of the

object position.

Return type:

tuple

classmethod register(name: str)

Class decorator to register a field type by name.

Parameters:

name – The string key used to look up this field type.

Returns:

A decorator that registers the subclass and returns it unchanged.

scale_chief_ray_for_field(optic, y_obj_unit, u_obj_unit, y_img_unit)

Calculates the scaling factor for a unit chief ray based on the field definition.

This is used in the paraxial chief_ray calculation. It uses the results of a forward and backward “unit” trace from the stop to determine the final scaling factor.

Parameters:

• optic (Optic) – The optical system.

• y_obj_unit (float) – The object-space height of the unit ray.

• u_obj_unit (float) – The object-space angle of the unit ray.

• y_img_unit (float) – The image-space height of the unit ray.

Returns:

The scaling factor.

Return type:

float

to_dict() → dict

Convert the field definition to a dictionary.

Returns:

A dictionary representation of the field definition.

Return type:

dict

class BaseFieldDefinition

Abstract base class for defining how fields map to ray properties.

classmethod create(field_type: str) → BaseFieldDefinition

Instantiate a field definition by its registered name.

Parameters:

field_type – The registered name of the field type.

Returns:

A new instance of the corresponding field definition.

Raises:

ValueError – If field_type is not in the registry.

classmethod from_dict(field_def_dict: dict) → BaseFieldDefinition

Create a field definition from a dictionary.

Parameters:

field_def_dict (dict) – A dictionary representation of the field definition.

Returns:

A field definition object created from the

dictionary.

Return type:

BaseFieldDefinition

Raises:

ValueError – If field_type is missing or not in the registry.

abstractmethod get_paraxial_object_position(optic: Optic, Hy: ScalarOrArray, y1: ScalarOrArray, EPL: ScalarOrArray) → tuple[BEArray, BEArray]

Calculate the position of the object in the paraxial optical system.

Parameters:

• Hy – The normalized field height.

• y1 – The initial y-coordinate of the ray.

• EPL – The entrance pupil location.

Returns:

A tuple containing the y and z coordinates of the object

position.

abstractmethod get_ray_origins(optic: Optic, Hx: ScalarOrArray, Hy: ScalarOrArray, Px: ScalarOrArray, Py: ScalarOrArray, vx: ScalarOrArray, vy: ScalarOrArray) → tuple[ScalarOrArray, ScalarOrArray, ScalarOrArray]

Calculate the initial positions for rays originating at the object.

Parameters:

• Hx – Normalized x field coordinate.

• Hy – Normalized y field coordinate.

• Px – x-coordinate of the pupil point.

• Py – y-coordinate of the pupil point.

• vx – Vignetting factor in the x-direction.

• vy – Vignetting factor in the y-direction.

Returns:

A tuple containing the x, y, and z coordinates of the

object position.

classmethod register(name: str)

Class decorator to register a field type by name.

Parameters:

name – The string key used to look up this field type.

Returns:

A decorator that registers the subclass and returns it unchanged.

abstractmethod scale_chief_ray_for_field(optic: Optic, y_obj_unit: ScalarOrArray, u_obj_unit: ScalarOrArray, y_img_unit: ScalarOrArray) → ScalarOrArray

Calculates the scaling factor for a unit chief ray based on the field definition.

This is used in the paraxial chief_ray calculation. It uses the results of a forward and backward “unit” trace from the stop to determine the final scaling factor.

Parameters:

• optic – The optical system.

• y_obj_unit – The object-space height of the unit ray.

• u_obj_unit – The object-space angle of the unit ray.

• y_img_unit – The image-space height of the unit ray.

Returns:

The scaling factor.

to_dict() → dict

Convert the field definition to a dictionary.

Returns:

A dictionary representation of the field definition.

Return type:

dict

class ObjectHeightField

Defines fields by height on the object surface.

classmethod create(field_type: str) → BaseFieldDefinition

Instantiate a field definition by its registered name.

Parameters:

field_type – The registered name of the field type.

Returns:

A new instance of the corresponding field definition.

Raises:

ValueError – If field_type is not in the registry.

classmethod from_dict(field_def_dict: dict) → BaseFieldDefinition

Create a field definition from a dictionary.

Parameters:

field_def_dict (dict) – A dictionary representation of the field definition.

Returns:

A field definition object created from the

dictionary.

Return type:

BaseFieldDefinition

Raises:

ValueError – If field_type is missing or not in the registry.

get_paraxial_object_position(optic, Hy, y1, EPL)

Calculate the position of the object in the paraxial optical system.

Parameters:

• Hy (float) – The normalized field height.

• y1 (ndarray) – The initial y-coordinate of the ray.

• EPL (float) – The entrance pupil location.

Returns:

A tuple containing the y and z coordinates of the object

position.

Return type:

tuple

Raises:

ValueError – If the field type is “object_height” and the object is at infinity.

get_ray_origins(optic, Hx, Hy, Px, Py, vx, vy)

Calculate the initial positions for rays originating at the object.

Parameters:

• Hx (float) – Normalized x field coordinate.

• Hy (float) – Normalized y field coordinate.

• Px (float or be.ndarray) – x-coordinate of the pupil point.

• Py (float or be.ndarray) – y-coordinate of the pupil point.

• vx (float) – Vignetting factor in the x-direction.

• vy (float) – Vignetting factor in the y-direction.

Returns:

A tuple containing the x, y, and z coordinates of the

object position.

Return type:

tuple

Raises:

ValueError – If the field type is “object_height” for an object at infinity.

classmethod register(name: str)

Class decorator to register a field type by name.

Parameters:

name – The string key used to look up this field type.

Returns:

A decorator that registers the subclass and returns it unchanged.

scale_chief_ray_for_field(optic, y_obj_unit, u_obj_unit, y_img_unit)

Calculates the scaling factor for a unit chief ray based on the field definition.

This is used in the paraxial chief_ray calculation. It uses the results of a forward and backward “unit” trace from the stop to determine the final scaling factor.

Parameters:

• optic (Optic) – The optical system.

• y_obj_unit (float) – The object-space height of the unit ray.

• u_obj_unit (float) – The object-space angle of the unit ray.

• y_img_unit (float) – The image-space height of the unit ray.

Returns:

The scaling factor.

Return type:

float

to_dict() → dict

Convert the field definition to a dictionary.

Returns:

A dictionary representation of the field definition.

Return type:

dict

class ParaxialImageHeightField

Defines fields by the chief ray’s paraxial height at the image plane.

classmethod create(field_type: str) → BaseFieldDefinition

Instantiate a field definition by its registered name.

Parameters:

field_type – The registered name of the field type.

Returns:

A new instance of the corresponding field definition.

Raises:

ValueError – If field_type is not in the registry.

classmethod from_dict(field_def_dict: dict) → BaseFieldDefinition

Create a field definition from a dictionary.

Parameters:

field_def_dict (dict) – A dictionary representation of the field definition.

Returns:

A field definition object created from the

dictionary.

Return type:

BaseFieldDefinition

Raises:

ValueError – If field_type is missing or not in the registry.

get_paraxial_object_position(optic, Hy, y1, EPL)

Calculate the position of the object in the paraxial optical system.

Parameters:

• Hy (float) – The normalized field height.

• y1 (ndarray) – The initial y-coordinate of the ray.

• EPL (float) – The entrance pupil location.

Returns:

A tuple containing the y and z coordinates of the object

position.

Return type:

tuple

get_ray_origins(optic, Hx, Hy, Px, Py, vx, vy)

Calculate the initial positions for rays originating at the object.

Parameters:

• Hx (float) – Normalized x field coordinate.

• Hy (float) – Normalized y field coordinate.

• Px (float or be.ndarray) – x-coordinate of the pupil point.

• Py (float or be.ndarray) – y-coordinate of the pupil point.

• vx (float) – Vignetting factor in the x-direction.

• vy (float) – Vignetting factor in the y-direction.

Returns:

A tuple containing the x, y, and z coordinates of the

object position.

Return type:

tuple

Raises:

ValueError – If the field type is “object_height” for an object at infinity.

classmethod register(name: str)

Class decorator to register a field type by name.

Parameters:

name – The string key used to look up this field type.

Returns:

A decorator that registers the subclass and returns it unchanged.

scale_chief_ray_for_field(optic, y_obj_unit, u_obj_unit, y_img_unit)

Calculates the scaling factor for a unit chief ray based on the field definition.

This is used in the paraxial chief_ray calculation. It uses the results of a forward and backward “unit” trace from the stop to determine the final scaling factor.

Parameters:

• optic (Optic) – The optical system.

• y_obj_unit (float) – The object-space height of the unit ray.

• u_obj_unit (float) – The object-space angle of the unit ray.

• y_img_unit (float) – The image-space height of the unit ray.

Returns:

The scaling factor.

Return type:

float

to_dict() → dict

Convert the field definition to a dictionary.

Returns:

A dictionary representation of the field definition.

Return type:

dict

class RealImageHeightField(max_iter: int = 20)

Defines fields by the chief ray’s real height at the image plane.

Coordinate contract:

The requested image height (h_x, h_y) is defined in the global x/y coordinates of the chief ray’s traced intercept on the image surface (surfaces globalize ray coordinates after each trace). For a tilted or decentered image surface the solve therefore drives the global transverse coordinates to the target, not coordinates local to the image surface.

Note

The chief ray is constructed by aiming at the paraxial entrance-pupil center. This is not exact stop-center aiming: in systems with strong pupil aberration or a tilted/decentered stop, the traced ray does not necessarily cross the physical stop at its center. Exact aiming through the local stop center for arbitrary tilted/decentered systems (which requires a nested field-plus-ray-aiming solve and accounts for pupil aberration) is deliberately out of scope here; see the ray-aiming machinery for that problem.

classmethod create(field_type: str) → BaseFieldDefinition

Instantiate a field definition by its registered name.

Parameters:

field_type – The registered name of the field type.

Returns:

A new instance of the corresponding field definition.

Raises:

ValueError – If field_type is not in the registry.

classmethod from_dict(field_def_dict: dict) → BaseFieldDefinition

Create a field definition from a dictionary.

Parameters:

field_def_dict (dict) – A dictionary representation of the field definition.

Returns:

A field definition object created from the

dictionary.

Return type:

BaseFieldDefinition

Raises:

ValueError – If field_type is missing or not in the registry.

get_paraxial_object_position(optic, Hy, y1, EPL)

Calculate the position of the object in the paraxial optical system.

Parameters:

• Hy (float) – The normalized field height.

• y1 (ndarray) – The initial y-coordinate of the ray.

• EPL (float) – The entrance pupil location.

Returns:

A tuple containing the y and z coordinates of the object

position.

Return type:

tuple

get_ray_origins(optic, Hx, Hy, Px, Py, vx, vy)

Calculate the initial positions for rays originating at the object.

The field parameters are solved once per field point – pupil coordinates do not define additional solves and are broadcast against the converged parameters afterwards.

Parameters:

• optic (Optic) – The optical system.

• Hx (float) – Normalized x field coordinate.

• Hy (float) – Normalized y field coordinate.

• Px (float or be.ndarray) – x-coordinate of the pupil point.

• Py (float or be.ndarray) – y-coordinate of the pupil point.

• vx (float) – Vignetting factor in the x-direction.

• vy (float) – Vignetting factor in the y-direction.

Returns:

A tuple containing the x, y, and z coordinates of the

object position.

Return type:

tuple

Raises:

• RuntimeError – If the field solve fails to converge, in which case the implicit derivative is undefined.

• ValueError – If the paraxial seed or the field Jacobian is singular.

classmethod register(name: str)

Class decorator to register a field type by name.

Parameters:

name – The string key used to look up this field type.

Returns:

A decorator that registers the subclass and returns it unchanged.

scale_chief_ray_for_field(optic, y_obj_unit, u_obj_unit, y_img_unit)

Calculates the scaling factor for a unit chief ray based on the field definition.

Parameters:

• optic (Optic) – The optical system.

• y_obj_unit (float) – The object-space height of the unit ray.

• u_obj_unit (float) – The object-space angle of the unit ray.

• y_img_unit (float) – The image-space height of the unit ray.

Returns:

The scaling factor.

Return type:

float

to_dict() → dict

Convert the field definition to a dictionary.

Returns:

A dictionary representation of the field definition.

Return type:

dict