fields

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 Field(x: float = 0, y: float = 0, vignette_factor_x: float = 0.0, vignette_factor_y: float = 0.0, weight: float = 1.0)

Represents a field with specific properties.

x

The x-coordinate of the field.

Type:

float

y

The y-coordinate of the field.

Type:

float

vx

The vignette factor in the x-direction.

Type:

float

vy

The vignette factor in the y-direction.

Type:

float

weight

The relative importance scalar for this field. Non-negative; 0.0 means excluded from weighted contexts.

Type:

float

classmethod from_dict(field_dict: dict) → Field

Create a field from a dictionary.

Parameters:

field_dict – A dictionary representation of the field.

Returns:

A field object created from the dictionary.

to_dict() → dict

Convert the field to a dictionary.

Returns:

A dictionary representation of the field.

property weight: float

Non-negative relative importance scalar for this field.

Type:

float

class FieldGroup

A class representing a group of fields.

fields

A list of fields in the group.

Type:

list

telecentric

Whether the system is telecentric in object space.

Type:

bool

get_vig_factor(Hx, Hy)

Returns the vignetting factors for given Hx and Hy values.

get_field_coords()

Returns the normalized coordinates of the fields.

add_field(field)

Adds a field to the group.

get_field(field_number)

Returns the field at the specified index.

add(y: float, x: float = 0.0, vx: float = 0.0, vy: float = 0.0, weight: float = 1.0)

Add a field to the list of fields.

Parameters:

• y – The y-coordinate of the field.

• x – The x-coordinate of the field. Defaults to 0.0.

• vx – The x-component of the field’s vignetting factor. Defaults to 0.0.

• vy – The y-component of the field’s vignetting factor. Defaults to 0.0.

• weight – Non-negative relative importance scalar (default 1.0). A weight of 0.0 means this field is excluded from optimization and weighted analysis but is still present in standalone analysis outputs. Negative values raise ValueError.

classmethod from_dict(data)

Create a field group from a dictionary.

Parameters:

data (dict) – A dictionary representation of the field group.

Returns:

A field group object created from the dictionary.

Return type:

FieldGroup

get_field(field_number: int) → Field

Retrieve the field at the specified field_number.

Parameters:

field_number (int) – The index of the field to retrieve.

Returns:

The field at the specified index.

Return type:

Field

Raises:

IndexError – If the field_number is out of range.

get_field_coords() → list[tuple[ScalarOrArray, ScalarOrArray]]

Returns the coordinates of the fields.

If the maximum field size is 0, it returns a single coordinate (0, 0). Otherwise, it calculates the normalized coordinates for each field based on the maximum field size.

Returns:

A list of tuples, where each tuple contains the (normalized_x, normalized_y) coordinates of a field.

get_vig_factor(Hx, Hy)

Calculates the vignetting factors for a given field position.

Note that the vignetting factors are interpolated using the nearest neighbor method.

Args

Hx (float): The normalized x component of the field. Hy (float): The normalized y component of the field.

Returns:

The interpolated x-component of the

vignetting factor.

vy_new (float): The interpolated y-component of the

vignetting factor.

Return type:

vx_new (float)

property max_field

Maximum radial field value.

Type:

float

property max_x_field

Maximum field value in the x-direction.

Type:

float

property max_y_field

Maximum field value in the y-direction.

Type:

float

property num_fields

number of fields in field group

Type:

int

remove(field_number: int) → None

Remove the field at the specified field_number.

Parameters:

field_number (int) – The index of the field to remove.

Raises:

IndexError – If the field_number is out of range.

set_telecentric(is_telecentric)

Specify whether the system is telecentric in object space.

Parameters:

is_telecentric (bool) – Whether the system is telecentric in object space.

set_type(field_type: str) → None

Set the type of field used in the optical system.

Parameters:

field_type – The type of field, e.g., ‘angle’, ‘object_height’, or ‘paraxial_image_height’.

to_dict()

Convert the field group to a dictionary.

Returns:

A dictionary representation of the field group.

Return type:

dict

property vx

Vignetting factors in x for each field.

Type:

be.ndarray

property vy

Vignetting factors in y for each field.

Type:

be.ndarray

property weights: tuple[float, ...]

Weights for all fields as a tuple.

Type:

tuple[float, …]

property x_fields

x field values.

Type:

be.ndarray

property y_fields

y field values.

Type:

be.ndarray

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