visisipy.models.base

Base classes for eye models and surfaces.

Classes

EyeModel	Optical model of the eye.
BaseSurface	Abstract class that must be implemented by backend-specific surface classes.
NoSurface	Dummy surface class for when no surface is needed.
BaseEye	Abstract class that must be implemented by backend-specific eye model classes.

Module Contents

class visisipy.models.base.EyeModel

Optical model of the eye.

Visisipy’s eye models consist of two parts: the geometry and the material model. The geometry defines the shape of the eye, while the material model defines the optical properties of the materials in the eye. By default, this model uses the geometry and materials of the Navarro wide-field eye model [1]. The default material model has been fitted to the refractive indices reported by Escudero-Sanz and Navarro [1]. This model will work with all visible wavelengths, but could deviate slightly from the values provided in the literature for the specified wavelengths.

Attributes:

geometryEyeGeometry

Geometry of the eye. Defaults to the geometry of the Navarro eye model.

materialsEyeMaterials

Properties of the materials of the eye. Defaults to the materials of the Navarro eye model.

See also

NavarroGeometry

Geometry of the Navarro eye model.

NavarroMaterials

Materials of the Navarro eye model.

References

[1] (1,2)

Escudero-Sanz, I., & Navarro, R. (1999). Off-axis aberrations of a wide-angle schematic eye model. JOSA A, 16(8), 1881-1891. https://doi.org/10.1364/JOSAA.16.001881

build(*, start_from_index: int = 0, replace_existing: bool = False, object_distance: float = float('inf'), **kwargs) → BaseEye

Build the eye model in the backend.

If no backend has yet been initialized, the default backend is used. The eye model is built in the backend starting from the surface at index start_from_index. The cornea front surface will be located at start_from_index + 1. If replace_existing is set to True, the existing model in the backend will be overwritten. The object_distance parameter is used to set the distance between the cornea front and the surface preceding the eye model.

Parameters:

start_from_indexint

Index of the surface after which the eye model will be built.

replace_existingbool

If True, the existing model in the backend will be overwritten.

object_distancefloat

Distance between the cornea front and the surface preceding the eye model.

**kwargs

Additional keyword arguments to be passed to the backend when building the model.

Returns:

BaseEye

The built eye model in the backend.

static clear() → None

Clear the model in the backend.

static save(filename: str | os.PathLike | None = None) → None

Save the model definition to a file.

Saving is done by the backend. As a consequence, the file format depends on the backend used.

Parameters:

filenamestr | PathLike | None

Name of the file to save the model. If None, the model will be saved in the default location. The file format depends on the backend used.

to_dict() → dict[str, Any]

Convert the eye model to a dictionary.

Returns:

dict[str, Any]

A dictionary representation of the eye model with serialized geometry and materials.

classmethod from_dict(data: dict[str, Any]) → EyeModel

Create an eye model from a dictionary.

Parameters:

datadict[str, Any]

A dictionary with the eye model parameters, as produced by to_dict().

Returns:

EyeModel

An eye model instance with geometry and materials reconstructed from data.

to_json() → str

Serialize the eye model to a JSON string.

Returns:

str

A JSON representation of the eye model.

classmethod from_json(data: str) → EyeModel

Create an eye model from a JSON string.

Parameters:

datastr

A JSON string representing an eye model.

Returns:

EyeModel

An eye model instance reconstructed from data.

Raises:

ValueError

If the JSON does not contain a "visisipy_version" key.

save_json(filename: str | os.PathLike) → None

Save the eye model as JSON.

Parameters:

filenamestr | PathLike

Path to the output JSON file.

Raises:

ValueError

If the output filename does not have a .json extension.

classmethod load_json(filename: str | os.PathLike) → EyeModel

Load an eye model from a JSON file.

Parameters:

filenamestr | PathLike

Path to the input JSON file.

Returns:

EyeModel

An eye model instance reconstructed from the JSON file.

class visisipy.models.base.BaseSurface(comment: str, radius: float = float('inf'), thickness: float = 0.0, semi_diameter: float | None = None, conic: float = 0.0, material: Any | None = None, *, is_stop: bool | None = None)

Bases: abc.ABC

Abstract class that must be implemented by backend-specific surface classes.

property surface: Any

Abstractmethod:

Backend-native surface object.

abstractmethod build(*args, position: int, replace_existing: bool = False) → int

Build the surface in the backend.

class visisipy.models.base.NoSurface(*args, **kwargs)

Bases: BaseSurface

Dummy surface class for when no surface is needed.

This is a generic implementation that works with all backends, because it does not modify the optical system.

property surface: None

Return None for this placeholder surface.

build(*args, position: int, **kwargs) → int

Advance the build index without adding a physical surface.

Returns:

int

The previous surface position.

class visisipy.models.base.BaseEye(model: EyeModel)

Bases: abc.ABC

Abstract class that must be implemented by backend-specific eye model classes.

abstractmethod build(*args, start_from_index: int = 0, replace_existing: bool = False, object_distance: float = float('inf'), **kwargs)

Build the eye model in the backend.

If no backend has yet been initialized, the default backend is used. The eye model is built in the backend starting from the surface at index start_from_index. The cornea front surface will be located at start_from_index + 1. If replace_existing is set to True, the existing model in the backend will be overwritten. The object_distance parameter is used to set the distance between the cornea front and the surface preceding the eye model.

Parameters:

start_from_indexint

Index of the surface after which the eye model will be built.

replace_existingbool

If True, the existing model in the backend will be overwritten.

object_distancefloat

Distance between the cornea front and the surface preceding the eye model.

args

Additional positional arguments to be passed to the backend when building the model.

kwargs

Additional keyword arguments to be passed to the backend when building the model.

property eye_model: EyeModel

Abstractmethod:

Eye-model specification from which this backend-specific eye was built.

property surfaces: dict[str, BaseSurface]

Dictionary with surface names as keys and surfaces as values.

update_surfaces(attribute: str, value: Any, surface_names: list[str] | None = None) → None

Batch update all surfaces.

Set attribute to value for multiple surfaces. If surfaces is not specified, all surfaces of the eye model are updated.

Parameters:

attributestr

Name of the attribute to update

valueAny

New value of the surface attribute

surface_nameslist[str]

List of surfaces to be updated. If not specified, all surfaces are updated.