visisipy.models.geometry#

Models for the ocular geometry.

Classes#

`Surface`	Base class for optical surfaces.
`StandardSurface`	Standard conic surface.
`Stop`	Stop surface.
`BiconicSurface`	Standard biconic surface.
`ZernikeStandardSagSurface`	Zernike standard coefficients surface with surface deformations.
`ZernikeStandardPhaseSurface`	Zernike standard coefficients surface with wavefront aberrations.
`NoSurface`	A surface that does not exist.
`EyeGeometry`	Geometric parameters of an eye.
`NavarroGeometry`	Geometric parameters of the Navarro schematic eye.

Functions#

create_geometry(→ GeometryType)

Create a geometry instance from clinically used parameters.

Module Contents#

class visisipy.models.geometry.Surface#

Bases: abc.ABC

Base class for optical surfaces.

Attributes#

thicknessfloat: The thickness of the surface. Default is 0.

class visisipy.models.geometry.StandardSurface#

Bases: Surface

Standard conic surface.

Represents surfaces as conic sections (spheres, ellipsoids, paraboloids, hyperboloids), defined in terms of their radius of curvature and asphericity. For the asphericity, the following definition is used:

\[k = -\]

arepsilon^2 = - left( 1 - rac{b^2}{a^2} ight)

with \(k\) the asphericity, :math:`

arepsilon` the eccentricity, \(a\) the ellipsoid axis parallel to

the optical axis and \(b\) the ellipsoid axis perpendicular to the optical axis. This is the definition used in OpticStudio. Note that the meaning of \(a\) and \(b\) differs from the standard definition of an ellipse, where they are the semi-major and semi-minor axes.

radiusfloat: The radius of the surface. Default is infinity.
asphericityfloat: The asphericity of the surface. Default is 0.
thicknessfloat: The thickness of the surface. Default is 0.
semi_diameterfloat | None: The semi-diameter of the surface aperture. Default is None.
is_stopbool: If True, the surface is a stop surface. Default is False.

ellipsoid_radii(self) -> tuple[float, float, float]:: Calculates and returns the ellipsoid x, y and z radii (semi-axes) of the surface.

property ellipsoid_radii: _EllipsoidRadii#

Calculates and returns the ellipsoid radii (semi-axes) of the surface.

This works only if the surface is an ellipsoid (asphericity > -1), otherwise a NotImplementedError is raised. A tuple of the radii along the z, y and x axes is returned, where the z axis is the optical axis. These axes correspond to the following anatomical directions:

z: anterior-posterior
y: inferior-superior
x: left-right

Returns#

tuple[float, float, float]: The ellipsoid radii (semi-axes) of the surface.

Raises#

NotImplementedError: If the surface is not an ellipsoid (asphericity <= -1).

class visisipy.models.geometry.Stop#

Bases: StandardSurface

Stop surface.

This surface represents the aperture stop of an optical system.

Attributes#

semi_diameterfloat: The semi-diameter of the aperture stop. Default is 1.
thicknessfloat: The thickness of the stop. Default is 0.

class visisipy.models.geometry.BiconicSurface#

Bases: StandardSurface

Standard biconic surface.

Inherits from the StandardSurface class and represents a surface with different radii of curvature and asphericities in the x (left-right) and y (inferior-superior) directions. This is useful for modeling astigmatic surfaces. For the left eye, the x (left-right) direction corresponds to the temporal-nasal direction, while for the right eye, it corresponds to the nasal-temporal direction.

Attributes#

radiusfloat: The radius of the surface in the y (inferior-superior) direction. Default is infinity.
radius_xfloat: The radius of the surface in the x (left-right) direction. Default is infinity.
asphericityfloat: The asphericity of the surface in the y (inferior-superior) direction. Default is 0.
asphericity_xfloat: The asphericity of the surface in the x (left-right) direction. Default is 0.
thicknessfloat: The thickness of the surface. Default is 0.
semi_diameterfloat | None: The semi-diameter of the surface aperture. Default is None.
is_stopbool: If True, the surface is a stop surface. Default is False.

Methods#

ellipsoid_radii(self) -> tuple[float, float, float]:: Calculates and returns the ellipsoid x, y and z radii of the surface.

property ellipsoid_radii: _EllipsoidRadii#

Calculates and returns the ellipsoid radii (semi-axes) of the surface.

This works only if the surface is an ellipsoid (asphericity > -1), otherwise a NotImplementedError is raised. A tuple of the radii along the z, y and x axes is returned, where the z axis is the optical axis. These axes correspond to the following anatomical directions:

z: anterior-posterior
y: inferior-superior
x: left-right

Returns#

tuple[float, float, float]: The ellipsoid radii (semi-axes) of the surface.

Raises#

NotImplementedError: If the surface is not an ellipsoid (asphericity <= -1).

class visisipy.models.geometry.ZernikeStandardSagSurface#

Bases: BaseZernikeStandardSurface

Zernike standard coefficients surface with surface deformations.

Represents a surface with surface deformations described by Zernike polynomials.

Attributes#

zernike_coefficientsZernikeCoefficients | dict[int, float]: The Zernike coefficients of the surface. Default is an empty dictionary.
extrapolatebool: If True, the Zernike coefficients will be considered even if the ray lands beyond the normalization radius. Default is True.
zernike_decenter_xfloat: Decentration of the Zernike terms with respect to the conical and aspherical terms in the x-direction. Default is 0.
zernike_decenter_yfloat: Decentration of the Zernike terms with respect to the conical and aspherical terms in the y-direction. Default is 0.
maximum_termint | None: The maximum Zernike term to consider. If None is passed, this will be set to the maximum term in zernike_coefficients.
norm_radiusfloat: The normalization radius for the Zernike coefficients, in lens units (usually mm). Default is 100.

Raises#

ValueError: If the Zernike coefficients contain terms that are greater than the maximum term.

class visisipy.models.geometry.ZernikeStandardPhaseSurface#

Bases: BaseZernikeStandardSurface

Zernike standard coefficients surface with wavefront aberrations.

Represents a surface with wavefront aberrations described by Zernike polynomials.

Attributes#

zernike_coefficientsZernikeCoefficients | dict[int, float]: The Zernike coefficients of the surface. Default is an empty dictionary.
extrapolatebool: If True, the Zernike coefficients will be considered even if the ray lands beyond the normalization radius. Default is True.
diffraction_orderfloat: The diffraction order of the surface. Default is 0.
maximum_termint | None: The maximum Zernike term to consider. If None is passed, this will be set to the maximum term in zernike_coefficients.
norm_radiusfloat: The normalization radius for the Zernike coefficients, in lens units (usually mm). Default is 100.

Raises#

ValueError: If the Zernike coefficients contain terms that are greater than the maximum term.

class visisipy.models.geometry.NoSurface#

Bases: Surface

A surface that does not exist.

This surface is used to indicate that a surface is not present in the optical system. It can be used to define three-surface schematic eyes and reduced eye models.

Note

This surface does not modify the optical system, i.e. surfaces of the NoSurface type are not built when calling EyeModel.build. This means the properties of the preceding surface, e.g. the refractive index, will propagate to the next surface.

Geometric parameters of an eye.

Sizes are specified in mm. This class is mainly intended as a base class for more specific eye models. When used directly, all surfaces need to be specified manually.

Attributes#

cornea_frontSurface: The front surface of the cornea.
cornea_backSurface: The back surface of the cornea.
pupilSurface: The pupil of the eye.
lens_frontSurface: The front surface of the lens.
lens_backSurface: The back surface of the lens.
retinaSurface: The retina of the eye.

Methods#

axial_length(self) -> float:: Calculates and returns the axial length of the eye.
cornea_thickness(self) -> float:: Returns the thickness of the cornea.
anterior_chamber_depth(self) -> float:: Returns the depth of the anterior chamber.
lens_thickness(self) -> float:: Returns the thickness of the lens.
vitreous_thickness(self) -> float:: Returns the thickness of the vitreous.

property cornea_front: StandardSurface#: Cornea front geometry.

property cornea_back: StandardSurface#: Cornea back geometry.

property pupil: Stop#: Pupil geometry.

property lens_front: StandardSurface#: Lens front geometry.

property lens_back: StandardSurface#: Lens back geometry.

property retina: StandardSurface#: Retina geometry.

property axial_length: float#: Axial length of the eye, in mm.

property cornea_thickness: float#: Thickness of the cornea, in mm.

property anterior_chamber_depth: float#: Depth of the anterior chamber, in mm.

property pupil_lens_distance: float#: Distance between the pupil and the lens, in mm.

property lens_thickness: float#: Thickness of the crystalline lens, in mm.

property vitreous_thickness: float#: Thickness of the vitreous body, in mm.

class visisipy.models.geometry.NavarroGeometry(**kwargs)#

Bases: EyeGeometry

Geometric parameters of the Navarro schematic eye.

This schematic eye is based on the Navarro model as described in [1]. Sizes are specified in mm.

[1]
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

Attributes#

cornea_frontStandardSurface: The front surface of the cornea.
cornea_backStandardSurface: The back surface of the cornea.
pupilStop: The pupil of the eye.
lens_frontStandardSurface: The front surface of the lens.
lens_backStandardSurface: The back surface of the lens.
retinaStandardSurface: The retina of the eye.

Examples#

Use the default Navarro geometry:

>>> from visisipy import NavarroGeometry
>>> geometry = NavarroGeometry()

Create a Navarro geometry with a custom retina:

>>> geometry = NavarroGeometry(
...     retina=StandardSurface(radius=-12.5, asphericity=0.5)
... )

Create a default Navarro gometry and change only the lens back radius:

>>> geometry = NavarroGeometry()
>>> geometry.lens_back.radius = -5.8

visisipy.models.geometry.create_geometry(base: type[GeometryType] = NavarroGeometry, *, estimate_cornea_back: bool = False, **parameters: visisipy.types.Unpack[GeometryParameters]) → GeometryType#

Create a geometry instance from clinically used parameters.

All parameters are optional, and if not provided, the default values will be used. Sizes are specified in mm. If estimate_cornea_back is True, the back cornea radius will be estimated from the front cornea radius as cornea_back_radius = 0.81 * cornea_front_radius. The retina can be specified either by its radius and asphericity or by its y and z ellipsoid radii. If both methods are specified, a ValueError will be raised.

Parameters#

basetype[GeometryType]: The base geometry class to use. Must be a subclass of EyeGeometry.
axial_lengthfloat, optional: Axial length of the eye, measured from cornea front to retina.
cornea_thicknessfloat, optional: Thickness of the cornea.
cornea_front_radiusfloat, optional: Radius of curvature of the frontal cornea surface.
cornea_front_asphericityfloat, optional: Asphericity of the frontal cornea surface.
cornea_back_radiusfloat, optional: Radius of curvature of the back cornea surface.
cornea_back_asphericityfloat, optional: Asphericity of the back cornea surface.
anterior_chamber_depthfloat, optional: Depth of the anterior chamber.
pupil_radiusfloat, optional: Radius of the pupil.
pupil_lens_distancefloat, optional: Distance between the pupil and the lens.
lens_thicknessfloat, optional: Thickness of the crystalline lens.
lens_back_radiusfloat, optional: Radius of curvature of the back lens surface.
lens_back_asphericityfloat, optional: Asphericity of the back lens surface.
lens_front_radiusfloat, optional: Radius of curvature of the frontal lens surface.
lens_front_asphericityfloat, optional: Asphericity of the frontal lens surface.
retina_radiusfloat, optional: Radius of curvature of the retina.
retina_asphericityfloat, optional: Asphericity of the retina.
retina_ellipsoid_z_radiusfloat, optional: Radius (semi-axis length) of the retina ellipsoid in the z-direction.
retina_ellipsoid_y_radiusfloat, optional: Radius (semi-axis length) of the retina ellipsoid in the y-direction. For rotationally symmetric retinas, this is also the radius in the x-direction.
estimate_cornea_backbool, optional: If True, the back cornea radius will be estimated from the front cornea radius. Default is False.

Returns#

EyeGeometry: An instance of the EyeGeometry class.

Raises#

ValueError: If the base geometry is not a class or if it is not a subclass of EyeGeometry. If the retina radius/asphericity and y/z ellipsoid radii are both specified. If only one of the retina ellipsoid radii is specified. If the sum of the cornea thickness, anterior chamber depth and lens thickness is greater than or equal to the axial length.