visisipy.backend#

Backends for optical simulations.

This module provides a unified interface for different optical simulation backends, as well as functions to interact with these backends.

Interfaces:

BaseAnalysisRegistry: Base class for the backend analysis registry.
BaseBackend: Base class for simulation backends.

Functions:

set_backend: Set the backend to use for optical simulations.
get_backend: Get the current backend, or initialize the default backend if not set.
get_oss: Get the OpticStudioSystem instance if the current backend is OpticStudio.
get_optic: Get the Optic instance if the current backend is Optiland.
update_settings: Update settings on the current backend.

Exceptions#

BackendAccessError

Error raised when trying to access unavailable or non-initialized backend features.

Classes#

`BackendSettings`	A dictionary containing the settings for the backend.
`BaseBackend`	Base class for optical simulation backends.

Functions#

`set_backend`(…)	Set the backend to use for optical simulations.
`get_backend`(→ BaseBackend)	Get the current backend.
`get_oss`(→ zospy.zpcore.OpticStudioSystem)	Get the OpticStudioSystem instance from the current backend.
`get_optic`(→ optiland.optic.Optic)	Get the Optic instance from the current backend.
`update_settings`([backend])	Update settings on the current backend.
`save_model`(→ None)	Save the current model to a file.

Module Contents#

class visisipy.backend.BackendSettings#

Bases: visisipy.types.TypedDict

A dictionary containing the settings for the backend.

field_type: visisipy.types.FieldType#: The field type to use in the optical system. Must be one of ‘angle’ or ‘object_height’.

fields: collections.abc.Sequence[visisipy.types.FieldCoordinate]#: List of field coordinates to use in the optical system. The field unit depends on the field type. For angle fields, the unit is degrees. For object height fields, the unit is millimeters.

wavelengths: collections.abc.Sequence[float]#: List of wavelengths to use in the optical system, in microns.

aperture_type: visisipy.types.ApertureType#: The aperture type to use in the optical system. Must be one of ‘float_by_stop_size’, ‘entrance_pupil_diameter’, ‘image_f_number’, or ‘object_numeric_aperture’.

aperture_value: float#: The aperture value to use in the optical system. Not required for ‘float_by_stop_size’.

class visisipy.backend.BaseBackend#

Bases: abc.ABC, Generic[_Settings]

Base class for optical simulation backends.

Backends should implement this interface to provide a unified interface for optical simulations.

classmethod get_instance() → visisipy.types.Self | None#

Get the current instance of the backend.

Returns:

BaseBackend | None: The current instance of the backend, or None if it has not been initialized yet.

property model: visisipy.models.BaseEye | None#

Abstractmethod:

The currently loaded backend-specific eye model.

property settings: _Settings#

Abstractmethod:

Backend settings.

property analysis: BaseAnalysisRegistry#

Abstractmethod:

The analysis registry exposed by the backend.

abstractmethod update_settings(**settings: visisipy.types.Unpack[BackendSettings]) → None#: Apply backend settings to the active backend instance.

abstractmethod build_model(model: visisipy.models.EyeModel, *, start_from_index: int = 0, replace_existing: bool = False, object_distance: float = float('inf'), **kwargs) → visisipy.models.BaseEye#: Build an eye model in the backend and return the backend-specific model.

abstractmethod clear_model() → None#: Clear the currently loaded model from the backend.

abstractmethod save_model(filename: str | os.PathLike | None = None) → None#: Save the current backend model to a file.

abstractmethod load_model(filename: str | os.PathLike, *, apply_settings: bool = False) → None#: Load a backend model from a file.

validate_settings(name: str | _Settings | collections.abc.Sequence[str]) → None#

Check if the backend has the specified setting.

Parameters:

namestr | BackendSettings | Sequence[str]: The name or settings to check.

Raises:

KeyError: If the setting does not exist.
TypeError: If the name parameter is not a string, a settings dictionary, or a sequence of strings.

get_setting(name: str) → Any#

Get a value from the backend settings.

This method is mainly intended for internal use, to prevent the type checker from warning about potentially missing keys in the settings dictionary.

Parameters:

namestr: The name of the setting to get.

Returns:

Any: The value of the setting.

Raises:

KeyError: If the setting does not exist.

save_settings(filename: str | os.PathLike) → None#

Save backend settings to a JSON file.

Raises:

ValueError: If filename does not end with .json.

exception visisipy.backend.BackendAccessError#

Bases: RuntimeError

Error raised when trying to access unavailable or non-initialized backend features.

visisipy.backend.set_backend(backend: Literal['opticstudio'], **settings: visisipy.types.Unpack[visisipy.opticstudio.backend.OpticStudioSettings]) → None#

visisipy.backend.set_backend(backend: Literal['optiland'], **settings: visisipy.types.Unpack[visisipy.optiland.backend.OptilandSettings]) → None

Set the backend to use for optical simulations.

Parameters:

backendBackendType: The backend to use. Must be one of {‘opticstudio’, ‘optiland’}. Defaults to ‘opticstudio’ on Windows and ‘optiland’ elsewhere.
settingsBackendSettings, optional: Dictionary with settings for the backend. Defaults to None.

Raises:

ValueError: If an invalid backend is specified.

visisipy.backend.get_backend() → BaseBackend#

Get the current backend.

The backend is set to the default backend if it has not been set yet.

Returns:

BaseBackend: The current backend.

visisipy.backend.get_oss() → zospy.zpcore.OpticStudioSystem#

Get the OpticStudioSystem instance from the current backend.

Returns:

OpticStudioSystem: The OpticStudioSystem instance if the OpticStudio backend is currently initialized.

Raises:

BackendAccessError: If the OpticStudioBackend is not currently initialized, or if the platform is not Windows.

visisipy.backend.get_optic() → optiland.optic.Optic#

Get the Optic instance from the current backend.

Returns:

Optic: The Optic instance if the Optiland backend is currently initialized.

Raises:

BackendAccessError: If the OptilandBackend is not currently initialized.

visisipy.backend.update_settings(backend: BaseBackend | None = None, **settings: visisipy.types.Unpack[BackendSettings])#

Update settings on the current backend.

Optionally, the backend can be manually specified. By default, the current backend is used.

Parameters:

backendBaseBackend | None: The backend to update. If None, the current backend is used.
**settingsUnpack[BackendSettings]: The settings to update. The keys and values should match the backend’s configuration schema.

visisipy.backend.save_model(filename: str | os.PathLike | None = None) → None#

Save the current model to a file.

Parameters:

filenamestr | PathLike | None: The filename to save the model to. If None, a default filename is used. The default filename depends on the backend.

Raises:

BackendAccessError: If no model is currently loaded in the backend.

visisipy.backend#

See Also#

Exceptions#

Classes#

Functions#

Module Contents#