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.

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.

abstract 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.

abstract 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.

abstract 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

Defines fields by the chief ray’s real 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

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