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

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().

Variables:: _registry (dict[str, type[BaseSystemAperture]]) – Class-level registry mapping ap_type strings to concrete subclass types. Populated automatically via __init_subclass__.

abstract property ap_type: str#: String identifier matching the legacy type key (e.g. 'EPD').

abstractmethod compute_epd(paraxial: Paraxial, wavelength: float | None = None) → float[source]#

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

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

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().

abstractmethod scale(factor: float) → BaseSystemAperture[source]#

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.

abstractmethod to_dict() → dict[source]#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.