PAROS 0.1.0__py3-none-any.whl

PAROS/__init__.py

@@ -0,0 +1,10 @@
+"""PARaxial Optical fundus Scaling (PAROS)
+
+Paros is a method to calculate the magnification of fundus images based on the optical characteristics of the patient's
+eye. The full method and validation are described in (article reference to be added upon acceptance).
+"""
+
+from PAROS import data, eyephantom, fundscale
+
+__all__ = ("data", "eyephantom", "fundscale")
+__version__ = "0.1.0"

PAROS/data/__init__.py

@@ -0,0 +1,70 @@
+"""Calibration and lens data files."""
+
+import importlib.resources
+from pathlib import Path
+from typing import cast
+
+import pandas as pd
+
+__all__ = ("get_camera_calibration_data", "get_lens_data")
+
+calibration = importlib.resources.files("PAROS.data.calibration")
+lenses = importlib.resources.files("PAROS.data.lenses")
+
+
+def _find_available_manufacturers():
+    return [i.name for i in calibration.iterdir() if i.is_dir()]
+
+
+_camera_manufacturers = _find_available_manufacturers()
+
+
+def get_camera_calibration_data(manufacturer: str, camera: str) -> pd.DataFrame:
+    """Get camera calibration data for a given manufacturer and camera.
+
+    Reads the data file at `PAROS/data/calibration/{manufacturer}/{camera}.csv` and
+    returns it as a pandas DataFrame.
+
+    Parameters
+    ----------
+    manufacturer : str
+        Camera manufacturer name.
+    camera : str
+        Camera model name.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Dataframe containing the camera calibration data.
+    """
+    if manufacturer not in _camera_manufacturers:
+        raise KeyError(f"Manufacturer {manufacturer} does not exist.")
+
+    try:
+        camera_data_file = cast(Path, calibration.joinpath(manufacturer, camera + ".csv"))
+
+        return pd.read_csv(camera_data_file)
+    except FileNotFoundError as e:
+        raise KeyError(f"Camera {camera} does not exist for manufacturer {manufacturer}.") from e
+
+
+def get_lens_data(name: str) -> pd.DataFrame:
+    """Get lens data.
+
+    Reads the data file at `PAROS/data/lenses/{name}.csv` and returns it as a pandas DataFrame.
+
+    Parameters
+    ----------
+    name : str
+        Name of the lens data set.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Dataframe containing the lens data.
+    """
+    try:
+        lens_data_file = cast(Path, lenses.joinpath(name + ".csv"))
+        return pd.read_csv(lens_data_file)
+    except FileNotFoundError as e:
+        raise KeyError(f"Lens data does not exist for name {name}.") from e

PAROS/data/calibration/Topcon/TRC_50DX.csv

@@ -0,0 +1,10 @@
+experiment_number,lens_1,lens_2,uncorrected_measurement,distance_camera_eye_mm,distance_camera_pinhole_mm,distance_pinhole_lens1_mm,distance_lens1_lens2_mm,distance_lens2_grid_mm,axial_length
+0,LB_1471,LB_1945,6.966666667,5.5,49.61969784,2.880302163,3.027080745,29.69261709,40.71969784
+1,LB_1471,LB_1945,6.726666667,5.5,49.61969784,2.880302163,3.027080745,31.69261709,42.71969784
+2,LB_1471,LB_1945,6.6,5.5,49.61969784,2.880302163,3.027080745,33.69261709,44.71969784
+3,LB_1471,LB_1945,6.37,5.5,49.61969784,2.880302163,3.027080745,35.69261709,46.71969784
+4,LB_1471,LB_1945,6.25,5.5,49.61969784,2.880302163,3.027080745,37.69261709,48.71969784
+5,LB_1471,LB_1945,6.086666667,5.5,49.61969784,2.880302163,3.027080745,39.69261709,50.71969784
+6,LB_1471,LB_1945,5.973333333,5.5,49.61969784,2.880302163,3.027080745,41.69261709,52.71969784
+7,LB_1471,LB_1945,5.746666667,5.5,49.61969784,2.880302163,3.027080745,43.69261709,54.71969784
+8,LB_1471,LB_1945,5.613333333,5.5,49.61969784,2.880302163,3.027080745,45.39261709,56.41969784

PAROS/data/calibration/Topcon/TRC_50IX.csv

@@ -0,0 +1,11 @@
+lens_1,lens_2,axial_length,distance_camera_eye_mm,uncorrected_measurement,distance_camera_pinhole_mm,distance_pinhole_lens1_mm,distance_lens1_lens2_mm,distance_lens2_grid_mm,experiment_number
+LE_1156,LB_1945,83.9874534,5.5,3.31,50.2374534,2.262546596,6.344836312,71.54261709,0
+LE_1156,LB_1945,90.7374534,5.5,3.13,50.2374534,2.262546596,6.344836312,78.29261709,1
+LE_1156,LB_1945,78.0374534,5.5,3.46,50.2374534,2.262546596,6.344836312,65.59261709,2
+LE_1156,LB_1945,134.6374534,5.5,2.24,50.2374534,2.262546596,6.344836312,122.1926171,3
+LE_1156,LB_1945,107.9374534,5.5,2.69,50.2374534,2.262546596,6.344836312,95.49261709,4
+LE_1156,LB_1945,72.0374534,5.5,3.71,50.2374534,2.262546596,6.344836312,59.59261709,5
+LE_1156,LB_1945,63.6374534,5.5,4.08,50.2374534,2.262546596,6.344836312,51.19261709,6
+LE_1234,LB_1056,62.51915876,5,4.28,45.31915876,2.180841236,5.205295461,51.1138633,7
+LE_1234,LB_1056,75.91915876,5,3.66,45.31915876,2.180841236,5.205295461,64.5138633,8
+LE_1234,LB_1056,96.51915876,5,2.98,45.31915876,2.180841236,5.205295461,85.1138633,9

PAROS/data/calibration/__init__.py

@@ -0,0 +1 @@
+"""Camera calibration data files."""

PAROS/data/lenses/__init__.py

@@ -0,0 +1 @@
+"""Lens data files."""

PAROS/data/lenses/phantom.csv

@@ -0,0 +1,13 @@
+name,lens_type,thickness_centre,thickness_edge,diameter,power,front_radius,back_radius,refractive_index,power_calculated
+LB_1409,biconvex,2.2,2.0,25.6,1.0,1029.8,-1029.8,1.515,1.0001942124684402
+LB_1869,biconvex,2.3,2.0,25.6,2.0,514.7,-514.7,1.515,2.001165727608315
+LB_1056_1,biconvex,2.6,2.0,25.6,4.0,257.1,-257.1,1.515,4.006223259432127
+LE_1234,convex-concave,3.6,2.0,25.6,10.0,-82.2,-32.1,1.515,9.77840689451304
+LE_1156,convex-concave,3.3,2.0,25.6,8.0,-106.9,-40.6,1.515,7.867142534572616
+LE_1104,convex-concave,3.1,2.0,25.6,6.7,-131.6,-49.1,1.515,6.575424510489725
+LE_1202,convex-concave,2.8,2.0,25.6,5.0,-182.2,-66.2,1.515,4.952891978205283
+LB_1945,biconvex,2.8,2.0,25.6,5.0,205.6,-205.6,1.515,5.009727626459142
+LB_1056,biconvex,2.6,2.0,25.6,4.0,257.1,-257.1,1.515,4.006223259432127
+LB_1779,biconvex,2.5,2.0,25.6,3.3,308.6,-308.6,1.515,3.3376539209332456
+LB_1471,biconvex,5.2,2.0,25.6,20.0,50.6,-50.6,1.515,20.355731225296400
+LB_1757,biconvex,7.7,2.0,25.6,33.3,29.5,-29.5,1.515,34.91525423728813

PAROS/eyephantom.py

@@ -0,0 +1,197 @@
+"""Paraxial optical modelling of an eye phantom for fundus camera calibrations.
+
+This module contains classes to model an eye phantom used to calibrate a fundus camera.
+Lenses are specified using the `Lens` class. The full phantom is modeled with the `EyePhantom` class.
+Lens and phantom data is included in `PAROS.data`.
+This module can be used in conjunction with `PAROS.fundscale` to calculate the central magnification of the phantom.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import pandas as pd
+import sympy as sp
+
+from PAROS.fundscale import spherical_interface, uniform_medium
+
+sp.init_printing(use_unicode=True)
+
+
+class Lens:
+    """Ray transfer model of a lens."""
+
+    def __init__(
+        self,
+        name: str,
+        center_thickness: float,
+        edge_thickness: float,
+        back_curvature: float,
+        front_curvature: float,
+        refractive_index: float,
+        diameter: float,
+        power: float,
+        lens_type: Literal["biconvex", "convex-concave"],
+    ):
+        """Initialize a lens model.
+
+        Parameters
+        ----------
+        name : str
+            Name of the lens.
+        center_thickness : float
+            Central thickness of the lens, in millimeters.
+        edge_thickness : float
+            Edge thickness of the lens, in millimeters.
+        back_curvature : float
+            Radius of curvature of the back surface, in millimeters.
+        front_curvature : float
+            Radius of curvature of the front surface, in millimeters.
+        refractive_index : float
+            Refractive index of the lens.
+        diameter : float
+            Diameter of the lens, in millimeters.
+        power : float
+            Power according to the lens data sheet, in diopters.
+        lens_type : str
+            Lens type, one of ['biconvex', 'convex-concave'].
+        """
+        self.name = name
+        self.center_thickness = center_thickness
+        self.edge_thickness = edge_thickness
+        self.back_curvature = back_curvature
+        self.front_curvature = front_curvature
+        self.refractive_index = refractive_index
+        self.lens_type = lens_type
+        self.diameter = diameter
+        self.power = power
+
+    def __str__(self):
+        return f"{self.name}"
+
+    def ray_transfer_matrix(self) -> sp.Matrix:
+        """Calculate the ray transfer matrix for the lens.
+
+        Returns
+        -------
+        sympy.Matrix
+            Ray transfer matrix for the lens.
+        """
+        air_refractive_index = 1.0
+
+        return (
+            spherical_interface(self.refractive_index, air_refractive_index, self.back_curvature * 1e-3)
+            * uniform_medium(self.center_thickness * 1e-3)
+            * spherical_interface(air_refractive_index, self.refractive_index, self.front_curvature * 1e-3)
+        )
+
+
+def make_lens(lens_file: pd.DataFrame, name: str) -> Lens:
+    """Create a `Lens` object for the lens `name` from `lens_file`.
+
+    Parameters
+    ----------
+    lens_file : pandas.DataFrame
+        DataFrame with lens specifications.
+    name : str
+        Name of the lens, must occur in `lens_file`.
+
+    Returns
+    -------
+    Lens
+        `Lens` object.
+    """
+    lens_info = lens_file[lens_file["name"] == name].iloc[0]
+
+    return Lens(
+        name=lens_info["name"],  # 'name' is a property of pandas.Series
+        center_thickness=float(lens_info.thickness_centre),
+        edge_thickness=float(lens_info.thickness_edge),
+        back_curvature=float(lens_info.back_radius),
+        front_curvature=float(lens_info.front_radius),
+        refractive_index=float(lens_info.refractive_index),
+        diameter=float(lens_info.diameter),
+        power=float(lens_info.power),
+        lens_type=lens_info.lens_type,
+    )
+
+
+class EyePhantom:
+    """Eye phantom consisting of two lenses and a grid.
+
+    Specification of an eye phantom consisting of two lenses and a grid.
+    The first lens models the cornea, the second lens the eye lens.
+
+    Attributes
+    ----------
+    name : str
+        Name of the phantom.
+    iol : Lens
+        `Lens` object for the eye lens.
+    cornea : Lens
+        `Lens` object for the cornea.
+    lens_to_lens_distance : float
+        Distance between the cornea and the lens.
+    lens_to_grid_distance : float
+        Distance between the lens and the grid.
+    camera_distance : float
+        Distance from the cornea front to the camera.
+    ray_transfer_matrix : sympy.Matrix
+        Ray transfer matrix for the phantom.
+    ray_transfer_matrix_to_camera : sympy.Matrix
+        Ray transfer matrix between the phantom and the camera.
+    """
+
+    def __init__(self, experiment: pd.Series = None, lens_file: pd.DataFrame = None):
+        """Initialize an eye phantom from a dataframe.
+
+        Currently only implemented for models of type 'set1'. If the dataframe
+        contains another model type, an empty model is created.
+
+        Parameters
+        ----------
+        experiment : pandas.Series
+            Series with experiment parameters.
+        lens_file : pandas.DataFrame
+            DataFrame with lens specifications.
+        """
+        if experiment is not None and lens_file is not None:
+            self.build_from_dataframe(experiment, lens_file)
+        else:
+            self.name = "unknown"
+            self.iol = None
+            self.cornea = None
+            self.lens_to_lens_distance = None
+            self.lens_to_grid_distance = None
+            self.camera_distance = None
+            self.ray_transfer_matrix = None
+            self.ray_transfer_matrix_to_camera = None
+
+    def __str__(self):
+        return f"{self.name}"
+
+    def build_from_dataframe(self, experiment: pd.Series, lens_file: pd.DataFrame) -> None:
+        """Initializes an `EyePhantom` instance from a pandas DataFrame.
+
+        Parameters
+        ----------
+        experiment : pandas.Series
+            Series with experiment parameters.
+        lens_file : pandas.DataFrame
+            DataFrame with lens specifications.
+        """
+        self.name: str = experiment.get("name")
+        self.iol: Lens = make_lens(lens_file, experiment.lens_2)
+        self.cornea: Lens = make_lens(lens_file, experiment.lens_1)
+        self.lens_to_lens_distance: float = float(experiment.distance_lens1_lens2_mm)
+        self.lens_to_grid_distance: float = float(experiment.distance_lens2_grid_mm)
+        self.camera_distance: float = experiment.distance_camera_eye_mm
+
+        matrix = (
+            self.cornea.ray_transfer_matrix()
+            * uniform_medium(self.lens_to_lens_distance * 1e-3)
+            * self.iol.ray_transfer_matrix()
+            * uniform_medium(self.lens_to_grid_distance * 1e-3)
+        )
+        self.ray_transfer_matrix: sp.Matrix = matrix
+        self.ray_transfer_matrix_to_camera = uniform_medium(self.camera_distance * 1e-3)

PAROS/fundscale.py

@@ -0,0 +1,667 @@
+"""Paraxial central scaling of fundus images.
+
+This module implements a paraxial method to calculate the central scaling
+of fundus images. The scaling is calculated by defining an eye using the
+`Eye` class and a fundus camera using the `Camera` class. The magnification
+can then be calculated using `calculate_magnification`.
+
+Throughout this module, the following abbreviations are used for ocular
+geometrical parameters:
+
+- R_corF: cornea front radius
+- R_corB: cornea back radius
+- R_lensF: lens front radius
+- R_lensB: lens back radius
+- D_cor: cornea thickness
+- D_ACD: anterior chamber depth
+- D_lens: lens thickness
+- D_vitr: vitreous thickness
+
+Unless otherwise specified, sizes and distances are specified in meters.
+"""
+
+from __future__ import annotations
+
+import copy
+import math
+from typing import Literal, NamedTuple, Union
+from warnings import warn
+
+import numpy as np
+import sympy as sp
+
+sp.init_printing(use_unicode=True)
+
+NumberOrSymbol = Union[int, float, sp.Symbol]
+EyeModelType = Literal["Navarro", "VughtIOL"]
+
+
+def _round_expr(expr: sp.Expr, num_digits: int = 3) -> sp.Expr:
+    return expr.xreplace({n: round(n, num_digits) for n in expr.atoms(sp.Number)})
+
+
+def uniform_medium(thickness: float) -> sp.Matrix:
+    """Uniform medium without refraction.
+
+    Parameters
+    ----------
+    thickness : float
+        Thickness of the medium.
+
+    Returns
+    -------
+    sympy.Matrix
+        Ray transfer matrix for the uniform medium.
+    """
+    return sp.Matrix([[1, thickness], [0, 1]])
+
+
+def medium_change(n_in: float, n_out: float) -> sp.Matrix:
+    """Change between media.
+
+    Parameters
+    ----------
+    n_in : float
+        Refractive index of the first medium.
+    n_out : float
+        Refractive index of the second medium.
+
+    Returns
+    -------
+    sympy.Matrix
+        Ray transfer matrix for the medium change.
+    """
+    return sp.Matrix([[1, 0], [0, n_in / n_out]])
+
+
+def spherical_interface(n_in: float, n_out: float, curvature: float) -> sp.Matrix:
+    """Spherical interface between two media.
+
+    Parameters
+    ----------
+    n_in : float
+        Refractive index of the first medium.
+    n_out : float
+        Refractive index of the second medium.
+    curvature : float
+        Radius of curvature of the interface.
+
+    Returns
+    -------
+    sympy.Matrix
+        Ray transfer matrix for the spherical interface.
+    """
+    return sp.Matrix([[1, 0], [(n_in - n_out) / (n_out * curvature), (n_in / n_out)]])
+
+
+def calculate_piol_curvature(piol_power: float, thickness: float = 0.2e-3, n_iol: float = 1.47) -> float:
+    """Calculate the radius of curvature for a phakic IOL.
+
+    Calculate the IOL radii for a pIOL with power `piol_power`. The front and back
+    curvatures of the IOL are equal.
+
+    The radii are calculated according to ISO 11979-2-2014 A.2.1:
+
+    .. math:: D_{iol} = 2 D_{front} - (t / n_{iol}) D_{front} ^ 2
+    .. math:: D_{front} = (n_{iol} - n_{medium}) / R_{front}
+    .. math:: n_{medium} = 1.336
+
+    Parameters
+    ----------
+    piol_power : float
+        Power of the pIOL, in diopters.
+    thickness : float
+        Thickness of the pIOL, in meters.
+    n_iol : float
+        Refractive index of the pIOL.
+
+    Returns
+    -------
+    float
+        Radius of curvature of the front and back pIOL surface.
+
+    Notes
+    -----
+    The calculation of the pIOL curvature seems to be in congruence with ANSI standard
+    and signs are correct.
+    """
+    n_medium = 1.336
+
+    A = -thickness / n_iol  # noqa: N806
+    B = 2  # noqa: N806
+    C = -piol_power  # noqa: N806
+
+    front_power = (-B + math.sqrt(B * B - 4 * A * C)) / (2 * A)
+
+    return (n_iol - n_medium) / front_power
+
+
+def calculate_piol_matrix(
+    piol_power: NumberOrSymbol,
+    thickness: float,
+    n_iol: float,
+    distance_iol_lens: float,
+    n_aq: float,
+) -> sp.Matrix:
+    """Calculate the ray transfer matrix for a phakic IOL.
+
+    Parameters
+    ----------
+    piol_power : float
+        Power of the pIOL, in diopters.
+    thickness : float
+        Thickness of the pIOL, in meters.
+    n_iol : float
+        Refractive index of the pIOL.
+    distance_iol_lens : float
+        Distance between the pIOL and the crystalline lens, in m.
+    n_aq : float
+        Refractive index of the aqueous humor.
+
+    Returns
+    -------
+    sympy.Matrix
+        Ray transfer matrix for the pIOL.
+    """
+    piol_curvature = calculate_piol_curvature(piol_power, thickness, n_iol)
+
+    piol_matrix = (
+        spherical_interface(n_iol, n_aq, -1 * piol_curvature)
+        * uniform_medium(thickness)
+        * spherical_interface(n_aq, n_iol, piol_curvature)
+    )
+    distance_matrix = uniform_medium(distance_iol_lens)
+
+    return piol_matrix * distance_matrix
+
+
+class PhakicIOL(NamedTuple):
+    """Parameters of a phakic IOL.
+
+    Attributes
+    ----------
+    power : NumberOrSymbol
+        Power in diopters.
+    thickness : NumberOrSymbol
+        Thickness in meters.
+    refractive_index : NumberOrSymbol
+        Refractive index of the pIOL material.
+    lens_distance : NumberOrSymbol
+        Distance to the crystalline lens in meters.
+    """
+
+    power: NumberOrSymbol
+    thickness: NumberOrSymbol
+    refractive_index: NumberOrSymbol
+    lens_distance: NumberOrSymbol
+
+
+class Eye:
+    """Symbolic representation of an eye model."""
+
+    def __init__(
+        self,
+        name: str = "testEye",
+        geometry: dict[str, float] | None = None,
+        model_type: EyeModelType = "Navarro",
+        NType: EyeModelType = "Navarro",  # noqa: N803
+        refraction: float | None = None,
+        pIOL: PhakicIOL | None = None,  # noqa: N803
+    ) -> None:
+        """Initialize an eye model.
+
+        This class works with a symbolic representation of the eye model, in which the
+        numeric values of the model parameters as defined in `geometry` are substituted
+        when needed. The eye's geometry can be passed to this function as a dictionary.
+        If this is a partial dictionary, the geometrical parameters corresponding to
+        `model_type` are updated with these values.
+
+        Parameters
+        ----------
+        name : str
+            Name of the eye model.
+        geometry : dict[str, float]
+            Dictionary with numerical geometric parameters of the eye. If `None`, the
+            geometry is based on `model_type`. Can be a partial dictionary, in which
+            case missing values are based on the eye model specified by `model_type`.
+        model_type : EyeModelType
+            Standard eye model on which the eye geometry is based. One of
+            ["Navarro", "VughtIOL"].
+        NType : EyeModelType
+            Standard eye model from which the refractive indices are used. One of
+            ["Navarro", "VughtIOL"].
+        refraction : float
+            Spherical equivalent of refraction of the eye model. The lens back curvature
+            can be adjusted to obtain this refraction with `Eye.adjust_lens_back`.
+        pIOL : PhakicIOL
+            Properties of the pIOL, if present. Tuple of power, thickness, refractive
+            index, distance to lens.
+        """
+        self.name = name
+        self.spherical_equivalent = refraction
+        self.is_pseudophakic = model_type == "VughtIOL"
+        self.axial_length = None
+        self.pIOL = pIOL
+
+        self.geometry = self._build_geometry_dictionary(model_type, geometry)
+
+        if NType == "Navarro":
+            self.refractive_indices = {
+                "cor": 1.3777,
+                "aq": 1.3391,
+                "lens": 1.4222,
+                "vit": 1.3377,
+            }
+        elif NType == "VughtIOL":
+            self.refractive_indices = {
+                "cor": 1.3777,
+                "aq": 1.3391,
+                "lens": 1.47,
+                "vit": 1.3377,
+            }
+        else:
+            raise ValueError(f"Model type {NType} is undefined.")
+
+        self.R_corF, self.R_corB, self.R_lensF, self.R_lensB = sp.symbols("R_corF R_corB R_lensF R_lensB")
+        self.D_cor, self.D_ACD, self.D_lens, self.D_vitr = sp.symbols("D_cor D_ACD D_lens D_vitr")
+
+        self.axial_length = (
+            self.geometry["D_cor"] + self.geometry["D_ACD"] + self.geometry["D_lens"] + self.geometry["D_vitr"]
+        )
+        self.ray_transfer_matrix = self.calculate_ray_transfer_matrix()
+
+    def __str__(self) -> str:
+        return f"{self.name}"
+
+    @staticmethod
+    def _build_geometry_dictionary(model_type: EyeModelType, partial_geometry: dict[str, float] | None = None):
+        if model_type == "Navarro":
+            geometry = {
+                "R_corF": -7.72e-3,
+                "R_corB": -6.50e-3,
+                "R_lensF": -10.20e-3,
+                "R_lensB": +6.00e-3,
+                "D_cor": 0.55e-3,
+                "D_ACD": 3.05e-3,
+                "D_lens": 4.00e-3,
+                "D_vitr": 16.3203e-3,
+            }
+        elif model_type == "VughtIOL":
+            geometry = {
+                "R_corF": -7.72e-3,
+                "R_corB": -6.50e-3,
+                "R_lensF": -8.16e-3,
+                "R_lensB": +11.18e-3,
+                "D_cor": 0.55e-3,
+                "D_ACD": 3.05e-3,
+                "D_lens": 0.6896e-3,
+                "D_vitr": 19.3203e-3,
+            }
+        else:
+            raise ValueError(f"Model type {model_type} is undefined.")
+
+        if partial_geometry is not None:
+            # Estimate the cornea back curvature if it is unspecified and the cornea
+            # front curvature is specified
+            if "R_corF" in partial_geometry and "R_corB" not in partial_geometry:
+                partial_geometry["R_corB"] = 0.81 * partial_geometry["R_corF"]
+
+            # Update the geometry with the parameters specified in partial_geometry
+            geometry.update(partial_geometry)
+
+        return geometry
+
+    def calculate_ray_transfer_matrix(self) -> sp.Matrix:
+        """Calculate the eye's ray transfer matrix.
+
+        Returns
+        -------
+        sp.Matrix
+            Ray transfer matrix of the eye.
+        """
+
+        # Cornea
+        cornea = (
+            spherical_interface(self.refractive_indices["cor"], 1.0, self.R_corF)
+            * uniform_medium(self.D_cor)
+            * spherical_interface(
+                self.refractive_indices["aq"],
+                self.refractive_indices["cor"],
+                self.R_corB,
+            )
+        )
+
+        # Lens
+        lens = (
+            spherical_interface(
+                self.refractive_indices["lens"],
+                self.refractive_indices["aq"],
+                self.R_lensF,
+            )
+            * uniform_medium(self.D_lens)
+            * spherical_interface(
+                self.refractive_indices["vit"],
+                self.refractive_indices["lens"],
+                self.R_lensB,
+            )
+        )
+
+        # pIOL
+        if self.pIOL:  # (Diol,tiol,Niol,d_iollens)
+            phakic_iol = calculate_piol_matrix(
+                self.pIOL[0],
+                self.pIOL[1],
+                self.pIOL[2],
+                self.pIOL[3],
+                self.refractive_indices["aq"],
+            )
+        else:  # Identity matrix
+            phakic_iol = sp.Matrix([[1, 0], [0, 1]])
+
+        # Retina to cornea
+        return cornea * uniform_medium(self.D_ACD) * phakic_iol * lens * uniform_medium(self.D_vitr)
+
+    def adjust_lens_back(self, target_refraction: float, *, update_model: bool = False) -> tuple[float, float]:
+        """Fit the lens back curvature to the eye's refraction.
+
+        A corrective lens (glasses) for an eye with `target_refraction` is place in
+        front of the eye. The lens back surface is then solved for a focused image on
+        the retina. A vertex distance of 1.4 cm between the glasses and the eye is
+        assumed.
+
+        Parameters
+        ----------
+        target_refraction : float
+            Desired spherical of refraction of the eye in diopters.
+        update_model : bool
+            If `True`, the eye's lens back curvature is set to the calculated value.
+
+        Returns
+        -------
+        lens_back_curvature : float
+            Radius of curvature of the lens back surface.
+        r_glasses : float
+            Radius of curvature of the glasses.
+        """
+        n_glasses = 1.5
+        r_glasses = 2.0 * (n_glasses - 1.0) / (target_refraction + 0.0000000001)
+
+        m_glasses = spherical_interface(n_glasses, 1, -r_glasses) * spherical_interface(1, n_glasses, r_glasses)
+
+        # Reversed eye with glasses
+        # Assuming average vertex distance of 1.4cm
+        matrix_glasses_eye = m_glasses * uniform_medium(0.014) * self.ray_transfer_matrix
+        temp_geometry = copy.deepcopy(self.geometry)
+
+        temp_geometry.pop("R_lensB")
+
+        solve_output = sp.solveset(
+            matrix_glasses_eye.evalf(subs=temp_geometry)[1, 1], self.R_lensB
+        )  # parallel rays from glasses
+
+        if len(list(solve_output)) != 1:
+            warn(f"Multiple solutions found. {target_refraction=}, {solve_output=}")
+
+        lens_back_curvature = next(iter(solve_output))
+
+        if update_model:
+            self.geometry["R_lensB"] = lens_back_curvature
+
+        return lens_back_curvature, r_glasses
+
+    def calculate_refraction(self, *, display=True) -> tuple[float, float]:
+        """Calculate the refraction of the eye.
+
+        A corrective lens (glasses) for an eye with `target_refraction` is place in
+        front of the eye. Its radius of curvature is then solved for a focused image on
+        the retina. A vertex distance of 1.4 cm between the glasses and the eye is
+        assumed.
+
+        Parameters
+        ----------
+        display : bool
+            If `True`, the results are printed.
+
+        Returns
+        -------
+        glasses_curvature : float
+            Radius of curvature of the corrective lens, in meters.
+        glasses_power : float
+            Power of the corrective lens, in diopters.
+
+        Warnings
+        --------
+        When multiple solutions for the curvature are found, a warning is displayed.
+        """
+        n_glasses = 1.5
+        R = sp.symbols("R")  # noqa: N806
+        glasses = spherical_interface(n_glasses, 1, -R * 10**-3) * spherical_interface(1, n_glasses, R * 10**-3)
+        eye = self.evaluate_matrix()
+
+        glasses_curvature_solutions = sp.solveset((glasses * uniform_medium(0.014) * eye)[1, 1], R)
+        if len(list(glasses_curvature_solutions)) != 1:
+            warn(f"Multiple solutions found: {glasses_curvature_solutions}")
+
+        glasses_curvature = next(iter(glasses_curvature_solutions)) * 1e-3
+        glasses_power = 2.0 * (n_glasses - 1.0) / (glasses_curvature)
+        if display:
+            print(f"{glasses_curvature=:.2f} m, {glasses_power=:.2f} D")  # noqa: T201
+
+        return glasses_curvature, glasses_power
+
+    def evaluate_matrix(self) -> sp.Matrix:
+        """Evaluate the eye's ray transfer matrix using its geometrical parameters.
+
+        Returns
+        -------
+        sympy.Matrix
+            Ray transfer matrix for the eye model.
+        """
+        return self.ray_transfer_matrix.evalf(subs=self.geometry)
+
+    def calculate_camera_magnification(
+        self, camera: Camera, distance_eye_camera: float = 0.05
+    ) -> tuple[float, sp.Matrix, float]:
+        """Calculate the total magnification of the eye - camera system.
+
+        A structure on the central retina is depicted `magnification` times larger
+        on the camera sensor.
+
+        Parameters
+        ----------
+        camera : Camera
+            Camera model.
+        distance_eye_camera : float
+            Distance between eye and camera in meters, measured from the cornea front to
+            the camera lens front.
+
+        Returns
+        -------
+        magnification : float
+            Central magnification of the eye - camera system.
+        focused_system_matrix : sympy.Matrix
+            Ray transfer matrix for the full system.
+        focus_lens_radius : float
+            Radius of curvature of the camera's focal length, in meters.
+        """
+        eye_matrix = self.evaluate_matrix()
+        focused_system_matrix, focus_lens_radius = camera.focused_system_matrix(
+            eye_matrix, distance_eye_camera, return_focus_lens_curvature=True
+        )
+
+        magnification = focused_system_matrix[0, 0]
+
+        return magnification, focused_system_matrix, focus_lens_radius
+
+
+class Camera:
+    def __init__(
+        self,
+        F_cond: NumberOrSymbol = None,  # noqa: N803
+        a1: NumberOrSymbol = None,
+        camera_type: Literal["default"] = "default",
+    ) -> None:
+        self.camera_type = "lensTaylor"
+        self.F_cond = sp.Symbol("F_cond", real=True)
+        self.d_CCD = sp.symbols("d_CCD")
+        self.R_foc = sp.Symbol("R_foc", real=True)  # in m
+        self.a1 = sp.Symbol("a1", real=True)
+
+        if camera_type == "default":
+            self.d_CCD = self.F_cond
+        else:
+            raise NotImplementedError("Custom CCD distances are not implemented.")
+
+        self.n_glas = 1.5
+        self.a1_value = a1
+
+        self.condenser_lens = spherical_interface(self.n_glas, 1.0, -self.F_cond) * spherical_interface(
+            1.0, self.n_glas, self.F_cond
+        )
+        self.focus_lens = spherical_interface(self.n_glas, 1.0, -self.R_foc) * spherical_interface(
+            1.0, self.n_glas, self.R_foc
+        )
+        self.correction_term = sp.Matrix([[1 + self.a1 / self.R_foc, 0], [0, 1.0 / (1 + self.a1 / self.R_foc)]])
+        self.ray_transfer_matrix = (
+            self.correction_term * uniform_medium(self.d_CCD) * self.focus_lens * self.condenser_lens
+        )
+
+        self.M_camera_alg = self.ray_transfer_matrix
+
+        if F_cond and (a1 is not None):
+            self.ray_transfer_matrix = self.M_camera_alg.evalf(subs={self.F_cond: F_cond, self.a1: a1})
+
+    def calculate_focus_lens_radius(self, eye_matrix: sp.Matrix, distance_eye_camera: float = 0.05) -> float:
+        """Calculate the radius of curvature of the focus lens.
+
+        Solves for the radius of curvature of the camera's focus lens, so that the image
+        of an object on the retina is in focus.
+
+        Parameters
+        ----------
+        eye_matrix : sympy.Matrix
+            Ray transfer matrix of the eye model.
+        distance_eye_camera : float
+            Distance between the eye and camera in meters, measured from the cornea
+            front to the camera lens front. Defaults to 0.05 m.
+
+        Returns
+        -------
+        float
+            Radius of curvature of the focus lens, in meters.
+        """
+        system_matrix = self.ray_transfer_matrix * uniform_medium(distance_eye_camera) * eye_matrix
+
+        # Ror contact cameras such as the Panoret fundus camera, the refractive index (of air) needs to be changed to
+        # that of the medium used between the eye and camera. This can be done by changing the use of uniform_medium()
+        # to medium_change().
+        # The camera should correct for the patients refraction, so the image should be
+        # focused, i.e. B = 0
+        B = system_matrix[0, 1] + 0.0000000001  # noqa: N806
+
+        if self.a1 in B.free_symbols:
+            possible_curvatures = list(sp.solve(B.evalf(subs={self.a1: 0}), self.R_foc))
+        else:
+            possible_curvatures = list(sp.solve(B, self.R_foc))
+
+        return np.max(np.abs(possible_curvatures))
+
+    def focused_system_matrix(
+        self,
+        eye_matrix: sp.Matrix,
+        distance_eye_camera: float = 0.05,
+        *,
+        return_focus_lens_curvature: bool = False,
+    ) -> sp.Matrix | tuple[sp.Matrix, float]:
+        system_matrix = self.ray_transfer_matrix * uniform_medium(distance_eye_camera) * eye_matrix
+
+        # For contact cameras such as the Panoret fundus camera, the refractive index (of air) needs to be changed to
+        # that of the medium use dbetween the eye and camera. This can be done by changing the use of uniform_medium()
+        # to medium_change().
+        focus_lens_curvature = self.calculate_focus_lens_radius(eye_matrix, distance_eye_camera)
+        if return_focus_lens_curvature:
+            return (
+                system_matrix.evalf(subs={self.R_foc: focus_lens_curvature}),
+                focus_lens_curvature,
+            )
+
+        return system_matrix.evalf(subs={self.R_foc: focus_lens_curvature})
+
+
+# Maximum allowed difference between the calculated and specified refraction of the eye model
+_MAXIMUM_REFRACTION_DEVIATION = 0.05
+
+# Maximum allowed value of the B-element in a ray transfer matrix for a focused system
+_MAXIMUM_FOCUS_DEVIATION = 0.0001
+
+
+def calculate_magnification(
+    eye: Eye,
+    camera: Camera,
+    distance_eye_camera: float = 0.05,
+    focus_lens_radius: float | None = None,
+    *,
+    suppress_warnings: bool = False,
+) -> tuple[float, float, Eye]:
+    """Calculate the total magnification of the eye - camera system.
+
+    A structure on the central retina is depicted `magnification` times larger
+    on the camera sensor.
+
+    Parameters
+    ----------
+    eye : Eye
+        Eye model.
+    camera : Camera
+        Camera model.
+    distance_eye_camera : float
+        Distance between eye and camera in meters, measured from the cornea front to
+        the camera lens front.
+    focus_lens_radius : float
+        Optional radius of curvature of the focus lens. If not specified, the focus lens
+        curvature is determined using `Camera.calculate_focus_lens_radius`.
+    suppress_warnings : bool
+        If `True`, no warning is issued if the calculated glasses power differs
+        significantly from `eye.spherical_equivalent`.
+
+    Returns
+    -------
+    magnification : float
+        Central magnification of the eye - camera system.
+    glasses_power : float
+        Power of the corrective lens required to correct for the eye's refraction, in
+        diopters.
+    eye_model : Eye
+        Eye model used to calculate the magnification.
+
+    Warnings
+    --------
+    When the calculated glasses power differs significantly from
+    `eye.spherical_equivalent`, a warning is displayed.
+    """
+    glasses_curvature, glasses_power = eye.calculate_refraction(display=False)
+
+    if not suppress_warnings and abs(glasses_power - eye.spherical_equivalent) > _MAXIMUM_REFRACTION_DEVIATION:
+        warn(
+            f"model refraction {glasses_power:.2f} not matching clinical refraction"
+            f" {eye.spherical_equivalent:.2f} for {eye.name}"
+        )
+
+    # For contact cameras such as the Panoret fundus camera, this refractive index (of air) needs to be changed to that
+    # of the medium between the eye and camera. This can be done by changing the use of uniform_medium() to
+    # medium_change().
+    system_matrix = camera.ray_transfer_matrix * uniform_medium(distance_eye_camera) * eye.evaluate_matrix()
+
+    if focus_lens_radius is None:
+        # system is in focus so B=0
+        solutions = list(sp.solve(system_matrix[0, 1] + 0.00001, camera.R_foc))
+        focus_lens_radius = solutions[np.argmax(np.abs(np.array(solutions) + camera.a1_value))]
+
+    focused_system_matrix = system_matrix.evalf(subs=({camera.R_foc: focus_lens_radius}))
+
+    magnification: float = focused_system_matrix[0, 0]
+
+    if abs(focused_system_matrix[0, 1]) > _MAXIMUM_FOCUS_DEVIATION:
+        warn(f"focused_system_matrix not in focus for patient {eye.name}")
+
+    return magnification, glasses_power, eye

paros-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.1
+Name: PAROS
+Version: 0.1.0
+Summary: PARaxial Optical fundus Scaling (PAROS)
+Author-email: "Lennart J. Pors" <l.j.pors@lumc.nl>, "Jan-Willem M. Beenakker" <j.w.m.beenakker@lumc.nl>, Corné Haasjes <c.haasjes@lumc.nl>
+License: MIT License
+        
+        Copyright (c) 2024 Lennart Pors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ophthalmology,paraxial optics
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: sympy
+Description-Content-Type: text/markdown
+
+# PARaxial Optical fundus Scaling (PAROS)
+
+Paros is a method to calculate the magnification of fundus images based on the optical characteristics of the patient's eye. The full method and validation are described in (article reference to be added upon acceptance)
+
+## License
+
+The code is provided as is, without any warranty, under the [MIT license](LICENSE). This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format. 
+
+## Basic usage
+
+A basic version of PAROS can most easily be run online here: [Basic version](https://mreye-lumc.github.io/PAROS)
+
+The full package is also available for download via PiP:
+
+```
+pip install PAROS
+``` 
+
+PAROS consists of two main functions: 
+
+- ‘fundus_camera_calibration.ipynb’: a method to calibrate camera using eye phantom measurements. 
+- ‘calculate_ocular_magnification.ipynb’: a method to calculate magnification fundus images of a subject. 
+
+## Implementation 
+
+The implementation of PAROS in this repository is functional for the camera in our center, and with the specific software used at our center. Both have impact on the calculated magnification. We therefore recommend calibration of the camera and software using the method described in the article mentioned below before implementation for quantitative purposes.
+
+## Camera constants
+
+Please find here a table of known camera calibration constants; this can be added upon by other contributors. 
+| Camera type     | CCD type | Condenser lens power (D) | First order calibration term |
+| --------------- | -------- | ------------------------ | ---------------------------- |
+| Topcon TRC-50DX |          | 38.0                     | -0.011                       |
+| Topcon TRC-50IX |          | 38.0                     | -0.012                       |
+
+## Referencing
+
+When publishing results obtained with this package, please cite the paper that describes the full method and validation: Pors, L.J., et al. (2023). "Correction method for optical scaling of fundoscopy images: development, validation and first implementation" in press.
+
+## Contributing
+
+Please read our [contribution guidelines](CONTRIBUTING.md) prior to opening a Pull Request.
+
+## Contact
+
+Feel free to contact us for any inquiries:
+
+- L.J. Pors ([email](mailto:l.j.pors@lumc.nl))
+- J.W.M. Beenakker ([email](mailto:j.w.m.beenakker@lumc.nl))

paros-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+PAROS/__init__.py,sha256=tDPXVwi1l7LKfd6ZxyuDcLCzs_mn64fEye2gIv1jQO4,386
+PAROS/eyephantom.py,sha256=YpsKcKeKWi6bvRRQdTQK7cE-VqiMXo6nKL0_AqSSFy8,6836
+PAROS/fundscale.py,sha256=ovYS3bzCcPuYyVyJJi6VGIOxKCr3uelOo6rOmng1zjM,23340
+PAROS/data/__init__.py,sha256=k2WEcTh10TvSqee1H5xmgpW8RnP91gKCtfXhuCVT0_s,1982
+PAROS/data/calibration/__init__.py,sha256=nHbgxHMZ76tUASGtaq18JeTs2TF9ATZHP118ppJAQ4A,37
+PAROS/data/calibration/Topcon/TRC_50DX.csv,sha256=mfCCaJqjb_CNrlWIl3l6s1Vb6j-QtJenOcRpYQPSc2c,1016
+PAROS/data/calibration/Topcon/TRC_50IX.csv,sha256=-GjlzBEufJVoQ2TekElZJKOwnOAfPAxm5MGB8J1Mu4o,1041
+PAROS/data/lenses/__init__.py,sha256=D9Afgofn4S5yRS_2IsMVsvgXDP4snT9ttpkEdITxJdw,23
+PAROS/data/lenses/phantom.csv,sha256=XpOnnU0gQiWO6ur_CMA3GaisAt7Y2hdRGt9vOLT1zjY,1000
+paros-0.1.0.dist-info/METADATA,sha256=2PbZhXIgUxQbNluL_YRWnhjijUV50X4i1VGvm1Q4Dvc,4327
+paros-0.1.0.dist-info/WHEEL,sha256=mRYSEL3Ih6g5a_CVMIcwiF__0Ae4_gLYh01YFNwiq1k,87
+paros-0.1.0.dist-info/licenses/LICENSE,sha256=bdHn5SWJdOrfnRkSGDabdWMbgvwLsv2I60Ygzta2ySA,1069
+paros-0.1.0.dist-info/RECORD,,

paros-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.21.0
+Root-Is-Purelib: true
+Tag: py3-none-any

paros-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lennart Pors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.