visisipy.opticstudio.backend#

OpticStudio backend for Visisipy.

Classes#

`OpticStudioSettings`	Backend settings that are specific to the OpticStudio backend.
`OpticStudioBackend`	OpticStudio backend.

Module Contents#

class visisipy.opticstudio.backend.OpticStudioSettings#

Bases: visisipy.backend.BackendSettings

Backend settings that are specific to the OpticStudio backend.

mode: Literal['standalone', 'extension']#: ZOSPy connection mode. Must be one of ‘standalone’ or ‘extension’.

zosapi_nethelper: visisipy.types.NotRequired[str]#: Path to the ZOSAPI_NetHelper.dll file. If not provided, the path is automatically determined.

opticstudio_directory: visisipy.types.NotRequired[str]#: Path to the OpticStudio installation directory. If not provided, the path is automatically determined.

ray_aiming: RayAimingType#: The ray aiming method to be used in the optical system. Must be one of ‘off’, ‘paraxial’, or ‘real’.

class visisipy.opticstudio.backend.OpticStudioBackend#

Bases: visisipy.backend.BaseBackend

OpticStudio backend.

property analysis: visisipy.opticstudio.analysis.OpticStudioAnalysisRegistry#

Provides access to the OpticStudioAnalysisRegistry instance.

This property provides access to the OpticStudioAnalysisRegistry instance for performing various analyses on the optical system.

Returns#

OpticStudioAnalysisRegistry: The OpticStudioAnalysisRegistry instance.

Raises#

RuntimeError: If the OpticStudio backend has not been initialized.

classmethod initialize(**settings: visisipy.types.Unpack[OpticStudioSettings]) → None#

Initialize the OpticStudio backend.

This method connects to the OpticStudio backend and initializes a new optical system.

Parameters#

settingsOpticStudioSettings | None, optional: The settings to be used for the OpticStudio backend. If None, the default settings are used.

classmethod update_settings(**settings: visisipy.types.Unpack[OpticStudioSettings]) → None#

Apply the provided settings to the OpticStudio backend.

This method applies the provided settings to the OpticStudio backend.

classmethod new_model(*, save_old_model: bool = False) → None#

Initialize a new optical system.

This method initializes a new, empty optical system.

classmethod build_model(model: visisipy.EyeModel, *, start_from_index: int = 0, replace_existing: bool = False, object_distance: float = float('inf'), **kwargs) → visisipy.opticstudio.models.OpticStudioEye#

Builds an optical system based on the provided eye model.

This method creates an OpticStudioEye instance from the provided eye model and builds the optical system. If replace_existing is True, any existing model is updated instead of building a completely new system.

Parameters#

modelEyeModel: The eye model to be used for building the optical system model.
start_from_indexint, optional: The index of the surface after which the eye model will be built. The cornea front surface will be located at start_from_index + 1.
replace_existingbool, optional: Whether to replace any existing model before building the new one. Defaults to False.
object_distancefloat: Distance between the cornea front and the surface preceding the eye model.
**kwargs: Additional keyword arguments to be passed to the OpticStudioEye build method.

Returns#

OpticStudioEye: The built optical system model.

classmethod clear_model() → None#

Clear the current optical system model.

This method initializes a new optical system, discarding any existing model.

classmethod save_model(path: str | os.PathLike | None = None) → None#

Save the current optical system model.

This method saves the current optical system to the specified path. If no path is provided, it saves the model to the current working directory with the default name.

Parameters#

pathstr | PathLike | None, optional: The path where the model should be saved. If None, the model is saved in the current working directory.

classmethod disconnect() → None#

Disconnects the OpticStudio backend.

This method closes the current optical system, sets the system and ZOS instances to None, and disconnects the ZOS instance.

classmethod get_oss() → zospy.zpcore.OpticStudioSystem#

Returns the current optical system.

Returns#

OpticStudioSystem: The current optical system.

Raises#

RuntimeError: If the OpticStudio system is not initialized.

classmethod get_aperture() → tuple[visisipy.types.ApertureType, float]#

Get the current aperture type and value of the optical system.

This method retrieves the current aperture type and value from the optical system. If the aperture type is float_by_stop_size, the diameter of the stop surface is returned as the aperture value. Note that the diameter, and not the semi-diameter, is returned, to be consistent with the other aperture types. For other aperture types, the aperture value is returned directly from the SystemData.

Returns#

zp.constants.SystemData.ZemaxApertureType: The current aperture type.

classmethod get_fields() → list[visisipy.types.FieldCoordinate]#

Get the fields in the optical system.

Returns#

list[tuple[float, float]]: The fields in the optical system as tuples of (x, y) coordinates.

classmethod set_fields(coordinates: collections.abc.Iterable[tuple[float, float]], field_type: Literal['angle', 'object_height'] = 'angle') → None#

Set the fields for the optical system.

This method removes any existing fields and adds the new ones provided.

Parameters#

coordinatesIterable[tuple[float, float]]: An iterable of tuples representing the coordinates for the fields.
field_typeLiteral[“angle”, “object_height”], optional: The type of field to be used in the optical system. Can be either “angle” or “object_height”. Defaults to “angle”.

classmethod get_wavelengths() → list[float]#

Get the wavelengths in the optical system.

Returns#

list[float]: The wavelengths in the optical system.

classmethod set_wavelengths(wavelengths: collections.abc.Iterable[float]) → None#

Set the wavelengths for the optical system.

This method removes any existing wavelengths and adds the new ones provided. The weight for each wavelength is set to 1.0.

Parameters#

wavelengthsIterable[float]: An iterable of wavelengths to be set for the optical system.

classmethod get_wavelength_number(wavelength: float) → int | None#

Returns the wavelength number for the given wavelength.

If the wavelength is not found, None is returned.

Parameters#

wavelengthfloat: The wavelength to find.

Returns#

int | None: The wavelength number, or None if the wavelength is not present.

classmethod iter_fields() → collections.abc.Generator[tuple[int, zospy.api._ZOSAPI.SystemData.IField], Any, None]#: Iterate over the fields in the optical system.

classmethod iter_wavelengths() → collections.abc.Generator[tuple[int, float], Any, None]#: Iterate over the wavelengths in the optical system.

classmethod update_pupil(new_value: float) → None#

Update the pupil size in the optical system.

This method updates the pupil size in the optical system to the new value provided. Which value is updated depends on the aperture type set in the optical system. For float_by_stop_size, the semi-diameter of the stop surface is updated; new_value is interpreted as the pupil diameter. For other aperture types, the aperture value in SystemData is updated.

Parameters#

new_valuefloat: The new pupil size to be set.