fields.field_group#

Field Group Module

This module defines the FieldGroup class, which manages a collection of fields in an optical system.

Kramer Harrison, 2024

Classes

FieldGroup()

A class representing a group of fields.
class FieldGroup[source]#

A class representing a group of fields.

Variables:

  • fields (list) – A list of fields in the group.

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

Methods:

  • 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)[source]#

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.

apply_vignetting(Hx, Hy, Px, Py)[source]#

Maps normalized pupil coordinates onto the vignetted pupil.

Each pupil coordinate is compressed by (1 - v), where v is the vignetting factor of the nearest defined field. This is the single place where vignetting is applied, so every ray aimer and every trace entry point sees the same pupil. When no field is vignetted, the inputs are returned unchanged.

Parameters:

  • Hx (float or be.ndarray) – The normalized x field coordinate.

  • Hy (float or be.ndarray) – The normalized y field coordinate.

  • Px (float or be.ndarray) – The normalized x pupil coordinate.

  • Py (float or be.ndarray) – The normalized y pupil coordinate.

Returns:

The vignetted (Px, Py).

Return type:

tuple

classmethod from_dict(data)[source]#

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[source]#

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]][source]#

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)[source]#

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[source]#

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.

require_definition() → BaseFieldDefinition[source]#

Return the field definition, or raise if none has been set.

Field coordinates cannot be interpreted without a field type, so ray tracing fails with an opaque AttributeError if this is skipped. This turns that into an actionable message.

Returns:

The active field definition.

Raises:

ValueError – If no field type has been set on the system.

set_telecentric(is_telecentric: bool) → None[source]#

Set the object-space telecentric state stored by this group.

Parameters:

is_telecentric – Whether the system is telecentric in object space.

set_type(field_type: str) → None[source]#

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()[source]#

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