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: visisipy.types.OpticStudioRayAimingType

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

class visisipy.opticstudio.backend.OpticStudioBackend(**settings: visisipy.types.Unpack[OpticStudioSettings])

Bases: visisipy.backend.BaseBackend[OpticStudioSettings]

OpticStudio backend.

property zos: zospy.zpcore.ZOS

The ZOS instance for the OpticStudio backend.

Returns:

ZOS

The ZOS instance for the OpticStudio backend.

Raises:

BackendAccessError

If the ZOS instance is not initialized.

property oss: zospy.zpcore.OpticStudioSystem

The OpticStudio system instance for the OpticStudio backend.

Returns:

OpticStudioSystem

The OpticStudio system instance for the OpticStudio backend.

Raises:

BackendAccessError

If the OpticStudio system instance is not initialized.

property model: visisipy.opticstudio.models.BaseOpticStudioEye | None

The current optical system model for the OpticStudio backend.

property settings: OpticStudioSettings

The current settings for the OpticStudio backend.

property analysis: visisipy.opticstudio.analysis.OpticStudioAnalysisRegistry

Analysis registry for the OpticStudio backend.

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.

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

Initialize a new optical system.

This method initializes a new, empty optical system.

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

Build 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.

clear_model() → None

Clear the current optical system model.

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

save_model(filename: 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:

filenamestr | PathLike | None, optional

The path where the model should be saved. If None, the model is saved in the current working directory.

load_model(filename: str | os.PathLike, *, apply_settings: bool = False) → None

Load an optical system model from a file.

This only loads the optical system into the backend. The model is not parsed to an OpticStudioEye or EyeModel instance. Furthermore, backend settings are not applied automatically after loading a model.

Parameters:

filenamestr | PathLike

The path to the file from which to load the model.

apply_settingsbool, optional

If True, the currently configured backend settings will be applied after loading the model.

Raises:

FileNotFoundError

If the specified file does not exist.

ValueError

If the file extension is not supported by the OpticStudio backend.

connect() → None

Connect to OpticStudio if not already connected.

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.

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.

set_aperture()

Set the aperture type and value in the OpticStudio system data.

Raises:

ValueError

If the configured aperture type is not supported.

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.

get_field_type() → visisipy.types.FieldType

Get the field type of the optical system.

Returns:

FieldType

The field type of the optical system, either “angle” or “object_height”.

Raises:

ValueError

If the field type in the optical system is not supported.

set_field_type(field_type: visisipy.types.FieldType) → None

Set the field type of the optical system.

Parameters:

field_typeFieldType

The field type to set for the optical system, either “angle” or “object_height”.

Raises:

ValueError

If field_type is not “angle” or “object_height”.

set_fields(coordinates: collections.abc.Iterable[tuple[float, float]], field_type: visisipy.types.FieldType = '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_typeFieldType, optional

The type of field to be used in the optical system. Can be either “angle” or “object_height”. Defaults to “angle”.

add_field(coordinate: tuple[float, float]) → int

Add a field to the optical system.

Parameters:

coordinatetuple[float, float]

The field coordinate to add.

Returns:

int

The field number of the added field.

get_field_number(coordinate: tuple[float, float]) → int | None

Get the field number for the given field coordinate.

If the field coordinate is not found, None is returned.

Parameters:

coordinatetuple[float, float]

The field coordinate to find.

Returns:

int | None

The field number, or None if the field coordinate is not present.

get_wavelengths() → list[float]

Get the wavelengths in the optical system.

Returns:

list[float]

The wavelengths in the optical system.

set_wavelengths(wavelengths: collections.abc.Sequence[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:

wavelengthsSequence[float]

A sequence of wavelengths to be set for the optical system.

Raises:

ValueError

If no wavelengths are provided.

add_wavelength(wavelength: float) → int

Add a wavelength to the optical system.

Parameters:

wavelengthfloat

The wavelength to add.

Returns:

int

The wavelength number of the added wavelength.

get_wavelength_number(wavelength: float) → int | None

Get 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.

static set_ray_aiming(oss: zospy.zpcore.OpticStudioSystem, ray_aiming: visisipy.types.OpticStudioRayAimingType) → None

Set the OpticStudio ray aiming mode.

Raises:

ValueError

If ray_aiming is not one of the supported modes.

iter_fields() → collections.abc.Generator[tuple[int, zospy.api._ZOSAPI.SystemData.IField], Any, None]

Iterate over the fields in the optical system.

Yields:

tuple[int, IField]

A tuple containing the field number and the field object.

iter_wavelengths() → collections.abc.Generator[tuple[int, float], Any, None]

Iterate over the wavelengths in the optical system.

Yields:

tuple[int, float]

A tuple containing the wavelength number and the wavelength value.

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.