aperture

Aperture Package

Provides the system aperture type hierarchy for Optiland. Each aperture type encapsulates how to compute the entrance pupil diameter (EPD), whether the type supports telecentric object space, and whether its value scales with system scaling.

Public API

• BaseSystemAperture — abstract base class

• EPDAperture — entrance pupil diameter

• ImageFNOAperture — image-space F-number

• ObjectNAAperture — object-space numerical aperture

• FloatByStopAperture — float by stop surface diameter

• make_system_aperture() — factory from legacy type string

Functions

make_system_aperture(aperture_type, value)

Create a system aperture from a legacy type string and value.

class BaseSystemAperture

Abstract base class for system aperture type definitions.

Each concrete subclass encapsulates the logic for computing the entrance pupil diameter (EPD) for one aperture specification style (e.g. EPD, image-space F-number, object-space NA, or float-by-stop-size).

Subclasses must declare a class-level ap_type string (e.g. "EPD") that matches the legacy type key used in serialized lens files. This string is used both for serialization round-trips and for the __init_subclass__ auto-registration that powers from_dict().

_registry

Class-level registry mapping ap_type strings to concrete subclass types. Populated automatically via __init_subclass__.

Type:

dict[str, type[BaseSystemAperture]]

abstract property ap_type: str

String identifier matching the legacy type key (e.g. 'EPD').

abstract compute_epd(paraxial: Paraxial, wavelength: float | None = None) → float

Return the entrance pupil diameter using paraxial context.

Parameters:

• paraxial – The paraxial engine for the current optical system.

• wavelength – Primary wavelength in micrometers. When None, implementations may fall back to paraxial.optic.primary_wavelength.

Returns:

Entrance pupil diameter in lens units.

direct_fno() → float | None

Return the F-number directly if this type stores it, else None.

Overridden only by ImageFNOAperture to avoid a redundant EPD computation in FNO().

Returns:

F-number value, or None if this type does not store one directly.

classmethod from_dict(data: dict | None) → BaseSystemAperture | None

Deserialize from a dictionary, dispatching by the "type" field.

Parameters:

data – Dictionary produced by to_dict(). Passing None returns None (mirrors legacy Aperture.from_dict behaviour).

Returns:

A concrete BaseSystemAperture instance, or None if data is None.

Raises:

ValueError – If required keys are missing or the type is not registered.

abstract property is_scalable: bool

True if the stored value should be scaled during optic.scale().

abstract scale(factor: float) → BaseSystemAperture

Return a new aperture with the value scaled by factor.

Non-scalable types (where is_scalable is False) return self unchanged since they are immutable and scaling has no effect.

Parameters:

factor – Multiplicative scale factor (e.g. 0.001 to convert mm to m).

Returns:

A new BaseSystemAperture instance, or self for non-scalable types.

abstract property supports_telecentric: bool

True if this aperture type is compatible with telecentric object space.

abstract to_dict() → dict

Serialize to a JSON-compatible dictionary.

Returns:

A dict with at least "type" and "value" keys.

abstract property value: float

Raw aperture value as supplied by the user.

class EPDAperture(value: float)

Aperture specified directly as an entrance pupil diameter.

The stored value is the entrance pupil diameter in lens units.

Parameters:

value – Entrance pupil diameter.

property ap_type: str

String identifier matching the legacy type key (e.g. 'EPD').

compute_epd(paraxial: Paraxial, wavelength: float | None = None) → float

Return the stored EPD value directly.

Parameters:

• paraxial – Unused for this aperture type.

• wavelength – Unused for this aperture type.

Returns:

The entrance pupil diameter.

direct_fno() → float | None

Return the F-number directly if this type stores it, else None.

Overridden only by ImageFNOAperture to avoid a redundant EPD computation in FNO().

Returns:

F-number value, or None if this type does not store one directly.

classmethod from_dict(data: dict | None) → BaseSystemAperture | None

Deserialize from a dictionary, dispatching by the "type" field.

Parameters:

data – Dictionary produced by to_dict(). Passing None returns None (mirrors legacy Aperture.from_dict behaviour).

Returns:

A concrete BaseSystemAperture instance, or None if data is None.

Raises:

ValueError – If required keys are missing or the type is not registered.

property is_scalable: bool

True if the stored value should be scaled during optic.scale().

scale(factor: float) → EPDAperture

Return a new EPDAperture with value scaled by factor.

Parameters:

factor – Multiplicative scale factor.

Returns:

A new EPDAperture instance.

property supports_telecentric: bool

True if this aperture type is compatible with telecentric object space.

to_dict() → dict

Serialize to a JSON-compatible dictionary.

Returns:

A dict with at least "type" and "value" keys.

property value: float

Raw aperture value as supplied by the user.

class FloatByStopAperture(value: float)

Aperture specified as the diameter of the stop surface.

The entrance pupil diameter is derived via paraxial ray tracing through the stop surface. For infinite-conjugate systems the marginal ray is traced forward; for finite-conjugate systems the object-space angle is scaled from the paraxial stop height.

Parameters:

value – Stop surface diameter in lens units.

property ap_type: str

String identifier matching the legacy type key (e.g. 'EPD').

compute_epd(paraxial: Paraxial, wavelength: float | None = None) → float

Compute EPD by paraxial ray tracing through the stop surface.

Parameters:

• paraxial – Paraxial engine providing ray tracing and system access.

• wavelength – Primary wavelength in micrometers. When None, falls back to paraxial.optic.primary_wavelength.

Returns:

Entrance pupil diameter.

Raises:

ValueError – If the object surface is not defined.

direct_fno() → float | None

Return the F-number directly if this type stores it, else None.

Overridden only by ImageFNOAperture to avoid a redundant EPD computation in FNO().

Returns:

F-number value, or None if this type does not store one directly.

classmethod from_dict(data: dict | None) → BaseSystemAperture | None

Deserialize from a dictionary, dispatching by the "type" field.

Parameters:

data – Dictionary produced by to_dict(). Passing None returns None (mirrors legacy Aperture.from_dict behaviour).

Returns:

A concrete BaseSystemAperture instance, or None if data is None.

Raises:

ValueError – If required keys are missing or the type is not registered.

property is_scalable: bool

True if the stored value should be scaled during optic.scale().

scale(factor: float) → FloatByStopAperture

Return a new FloatByStopAperture with value scaled by factor.

Parameters:

factor – Multiplicative scale factor.

Returns:

A new FloatByStopAperture instance.

property supports_telecentric: bool

True if this aperture type is compatible with telecentric object space.

to_dict() → dict

Serialize to a JSON-compatible dictionary.

Returns:

A dict with at least "type" and "value" keys.

property value: float

Raw aperture value as supplied by the user.

class ImageFNOAperture(value: float)

Aperture specified as an image-space F-number.

The entrance pupil diameter is derived as EPD = f2 / FNO.

Parameters:

value – Image-space F-number.

property ap_type: str

String identifier matching the legacy type key (e.g. 'EPD').

compute_epd(paraxial: Paraxial, wavelength: float | None = None) → float

Compute EPD as f2 / FNO.

Parameters:

• paraxial – Paraxial engine used to obtain the back focal length.

• wavelength – Unused for this aperture type.

Returns:

Entrance pupil diameter.

direct_fno() → float

Return the stored F-number directly, bypassing EPD computation.

Returns:

The image-space F-number.

classmethod from_dict(data: dict | None) → BaseSystemAperture | None

Deserialize from a dictionary, dispatching by the "type" field.

Parameters:

data – Dictionary produced by to_dict(). Passing None returns None (mirrors legacy Aperture.from_dict behaviour).

Returns:

A concrete BaseSystemAperture instance, or None if data is None.

Raises:

ValueError – If required keys are missing or the type is not registered.

property is_scalable: bool

True if the stored value should be scaled during optic.scale().

scale(factor: float) → ImageFNOAperture

Return self — F-number is dimensionless and does not scale.

Parameters:

factor – Ignored.

Returns:

This same instance (immutable, so returning self is safe).

property supports_telecentric: bool

True if this aperture type is compatible with telecentric object space.

to_dict() → dict

Serialize to a JSON-compatible dictionary.

Returns:

A dict with at least "type" and "value" keys.

property value: float

Raw aperture value as supplied by the user.

class ObjectNAAperture(value: float)

Aperture specified as an object-space numerical aperture.

The entrance pupil diameter is derived from the object-space NA using the object distance, primary wavelength, and the refractive index of the medium at the object surface.

Parameters:

value – Object-space numerical aperture (NA = n * sin(θ)).

property ap_type: str

String identifier matching the legacy type key (e.g. 'EPD').

compute_epd(paraxial: Paraxial, wavelength: float | None = None) → float

Compute EPD from object-space NA.

Parameters:

• paraxial – Paraxial engine providing access to system geometry and material data.

• wavelength – Primary wavelength in micrometers. When None, falls back to paraxial.optic.primary_wavelength.

Returns:

Entrance pupil diameter.

Raises:

ValueError – If the object surface is not defined.

direct_fno() → float | None

Return the F-number directly if this type stores it, else None.

Overridden only by ImageFNOAperture to avoid a redundant EPD computation in FNO().

Returns:

F-number value, or None if this type does not store one directly.

classmethod from_dict(data: dict | None) → BaseSystemAperture | None

Deserialize from a dictionary, dispatching by the "type" field.

Parameters:

data – Dictionary produced by to_dict(). Passing None returns None (mirrors legacy Aperture.from_dict behaviour).

Returns:

A concrete BaseSystemAperture instance, or None if data is None.

Raises:

ValueError – If required keys are missing or the type is not registered.

property is_scalable: bool

True if the stored value should be scaled during optic.scale().

scale(factor: float) → ObjectNAAperture

Return self — NA is dimensionless and does not scale.

Parameters:

factor – Ignored.

Returns:

This same instance (immutable, so returning self is safe).

property supports_telecentric: bool

True if this aperture type is compatible with telecentric object space.

to_dict() → dict

Serialize to a JSON-compatible dictionary.

Returns:

A dict with at least "type" and "value" keys.

property value: float

Raw aperture value as supplied by the user.

make_system_aperture(aperture_type: str, value: float) → BaseSystemAperture

Create a system aperture from a legacy type string and value.

This is the preferred factory for constructing aperture objects when using the string-based API (e.g. via set_aperture()).

Parameters:

• aperture_type – One of 'EPD', 'imageFNO', 'objectNA', 'float_by_stop_size'.

• value – The aperture value in lens units (or dimensionless for FNO/NA).

Returns:

A concrete BaseSystemAperture instance.

Raises:

ValueError – If aperture_type is not a registered type.