pyrot.eye_modelling.clipbased_model#

Clip-based registration of the eye model to image and marker data.

This module provides functions to register an eye model to scleral clip positions and optic nerve/disk-related points of interest.

Functions#

`match_ellipse_with_pois`(eye_model_generators, ...)	Register the eye model to clip locations (on the sclera) and the optic disk location.
`calc_on_model_loc_patient`(geometry_generators, ...)	Determine the optic disk location for an eye model positioned at the origin.
`calc_residuals_for_registration_with_fitted_rotation`(...)	Calculate residuals for registration of an ellipsoid model with a fixed rotation.
`calc_ellipsoid_registration_with_fitted_rotation`(...)	Perform a least-squares optimization to register an ellipsoid to the provided clip data.
`calc_residuals_for_registration_with_calculated_rotation`(...)	Calculate residuals for registration by computing distances from clip points to an ellipsoid.
`calc_ellipsoid_registration_with_calculated_rotation`(...)	Register an ellipsoid model to clip POIs using least squares optimization.
`calc_roll_and_pitch_of_shifted_eyemodel`(...)	Calculate the roll and pitch angles to align a shifted eye model with the optic disc positions.

Module Contents#

pyrot.eye_modelling.clipbased_model.match_ellipse_with_pois(eye_model_generators, eye_model_parameters, structure_set, input_ellipse, poi_type_clips, poi_type_on, rotation_method)#

Rotation of the eye model is either determined by minimizing the distance to the optic disk POI, or by rotating the model such that the visual axis goes through the eye center and optic disk POI. In the first case, the eye center and rotation are fit parameters, while in the latter case the eye center is the only fitting parameter.

Parameters#

eye_model_generatorsobject: The eye model containing eye parameters
eye_model_parametersobject: Object containing specific parameters of the eye model, such as translation and rotation.
structure_setobject: Data structure containing the set of structures (e.g., ROIs, POIs) for the eye model.
input_ellipsestr: Specifies which ellipse radii to use for fitting (e.g., “sclera_radii”).
poi_type_clipsstr: The type of POIs representing the clip locations on the sclera.
poi_type_onstr: The type of POI representing the optic disk location.
rotation_methodstr: Method to determine rotation, either “minimize_distance” (fit rotation to minimize optic disk POI - optic disk center distance) or “fixed_gaze” (calculate rotation based on the location of the optic disk POI).

Raises#

ValueError: If there are multiple or no POIs of the specified optic disk type.
NotImplementedError: If the specified input_ellipse or rotation_method is not implemented.

Notes#

This function updates the eye model parameters (translation, rotation) in-place

pyrot.eye_modelling.clipbased_model.calc_on_model_loc_patient(geometry_generators, eye_model_parameters, on_model_loc_method)#

Determine the optic disk location for an eye model positioned at the origin.

([0, 0, 0]) with input angles [0, 0, 0] and sclera radii of [1, 1, 1]. This is necessary as the method where rotation is fitted relies on a methodology where all POIs are translated to the unity circle. Currently, only the “unity_circle_standard_model” method is implemented, which assumes the optic disk location within the eye model using RayOcular’s default values.

Parameters#

geometry_generatorsobject: An object containing geometry generation parameters, including eye laterality.
eye_model_parametersobject: An object containing parameters of the eye model, including optic nerve rotation.
on_model_loc_methodstr: The method used to determine the ON model location. Currently, only “unity_circle_standard_model” is supported.

Returns#

on_model_loc_patientnumpy.ndarray: The location of the optic nerve in the eye model, adjusted for eye laterality.

Raises#

AssertionError: If the optic nerve (and thus the optic disk) has been manually rotated within the eye model, violating fit assumptions.
NotImplementedError: If the specified on_model_loc_method is not implemented.

Notes#

The function assumes the optic disk location has not been manually changed within the eye model.
Validation and additional testing for different eye models are recommended (see TODOs in code).

pyrot.eye_modelling.clipbased_model.calc_residuals_for_registration_with_fitted_rotation(params, clip_data, optic_nerve_data, axes)#

Calculate residuals for registration of an ellipsoid model with a fixed rotation.

This function computes the residuals between a set of 3D points (clip_data) and a rotated, translated ellipsoid model, as well as the normalized squared distance between the predicted and observed optic nerve (ON) locations.

Parameters#

paramsarray-like, shape (6,)

Model parameters. The first three elements are the center coordinates (x0, y0, z0) of the ellipsoid. The fourth and sixth elements are the rotation angles (in degrees) around the x and z axes, respectively. The y-axis rotation is fixed to zero.

clip_datandarray, shape (N, 3)

Array of 3D points representing the data to be fitted to the ellipsoid model.

optic_nerve_datatuple of ndarray

Tuple containing:

on_model_loc: ndarray, shape (3,)
The expected location of the optic disk (should be on the unit ellipsoid, see the docstrings of calc_on_model_loc_patient).
on_image_loc: ndarray, shape (3,)
The observed location of the optic disk in the image data.

axesarray-like, shape (3,)

The semi-axes lengths of the eye model.

Returns#

residualsndarray, shape (N+1,)

Array containing:

The residuals for each point in clip_data (distance from the ellipsoid surface).
The normalized squared distance between the predicted and observed ON locations.

pyrot.eye_modelling.clipbased_model.calc_ellipsoid_registration_with_fitted_rotation(clip_data, on_model_loc, on_image_loc, axes, initial_guess=None)#

Perform a least-squares optimization to register an ellipsoid to the provided clip data.

Both the center and rotation angles are optimized based on the clip locations and the optic disk POI. The optimization minimizes the residuals between the transformed model and the observed data.

Parameters#

clip_datanp.ndarray: An (N, 3) array of 3D points representing the data to fit.
on_model_locnp.ndarray: A (3,) array specifying the location of the optic disk model.
on_image_locnp.ndarray: A (3,) array specifying the location of the optic disk POI (based on the MR image).
axesnp.ndarray: A (3,) array representing the axes lengths of the ellipsoid.
initial_guessnp.ndarray or None, optional: Initial guess for the optimization parameters (center and rotation angles). If None, the center is initialized to the mean of clip_data and angles to zero.

Returns#

fitted_centernp.ndarray: A (3,) array representing the estimated center of the ellipsoid.
fitted_anglesnp.ndarray: A (3,) array of rotation angles (in degrees) fitted to the data.

Notes#

This function relies on calc_residuals_for_registration_with_fitted_rotation for computing

the residuals and uses scipy.optimize.least_squares for optimization. - The y-axis rotation is fixed to 0.

pyrot.eye_modelling.clipbased_model.calc_residuals_for_registration_with_calculated_rotation(params, clip_data, optic_nerve_data, axes, vitreous_body_center, eye_rotation_in, eye_translation_input)#

Calculate residuals for registration by computing distances from clip points to an ellipsoid.

This function translates the clip data according to the provided eye center parameters, computes the necessary rotation to align the model with the observed optic nerve location, applies the rotation, and then calculates the residuals (distance to the ellipsoid surface) for each clip POI.

Parameters#

paramsarray-like, shape (3,)

The center coordinates (x0, y0, z0) of the eye model in image space

clip_datandarray, shape (N, 3)

The 3D coordinates of the clip POIs.

optic_nerve_datatuple of array-like

Tuple containing (on_model_loc, on_image_loc), where:

on_model_locarray-like, shape (3,): The optic disk location in the model.
on_image_locarray-like, shape (3,): The optic disk location in the image (clicked point of interest).

axesarray-like, shape (3,)

The ellipsoid axes lengths (rl_axis, is_axis, ap_axis).

vitreous_body_centerarray-like, shape (3,)

The center of the vitreous body in the image space.

eye_rotation_indict

Dictionary containing the current eye rotation angles in degrees, with keys “x” and “z” (“y” is not used and should be set to 0).

eye_translation_inputarray-like, shape (3,)

The initial translation/ center location of the eye model.

Returns#

residuals_clipsndarray, shape (N,): The residuals for each clip point, representing the distance to the ellipsoid surface. Values close to zero indicate points lying on the ellipsoid.

pyrot.eye_modelling.clipbased_model.calc_ellipsoid_registration_with_calculated_rotation(clip_data, on_model_loc, on_image_loc, axes, vitreous_body_center, eye_rotation_in, eye_translation_in, initial_guess=None)#

The optimization incorporates calculated eye rotation and translation. Rotation is based purely on the location of the optic disk, while translation is based on the clip location. For each evaluated center translation, the corresponding rotation is calculated and thereafter, the residuals are calculated.

Parameters#

clip_datanp.ndarray: Array of 3D points representing the clip POIs to which the eye model is registered.
on_model_locnp.ndarray: 3D coordinates of the optic disk model center.
on_image_locnp.ndarray: 3D coordinates of the clicked POI of the optic disk on the MR image.
axesnp.ndarray: The axes lengths of the ellipsoid model.
vitreous_body_centernp.ndarray: The center coordinates of the vitreous body (which corresponds to the center of the eye/sclera ellipsoid).
eye_rotation_innp.ndarray: Initial eye rotation parameters.
eye_translation_innp.ndarray: Initial eye translation parameters.
initial_guessnp.ndarray, optional: Initial guess for the optimizer. If None, the mean of clip_data is used.

Returns#

np.ndarray: Optimized parameters resulting from the registration process.

Notes#

This function uses scipy.optimize.least_squares to minimize the residuals computed by calc_residuals_for_registration_with_calculated_rotation.

pyrot.eye_modelling.clipbased_model.calc_roll_and_pitch_of_shifted_eyemodel(retina_center_location, axes, on_model_loc, on_image_loc, eye_translation_before_shift, eye_translation_after_shift)#

Calculate the roll and pitch angles to align a shifted eye model with the optic disc positions.

This function computes the roll and pitch corrections for an eye model after a translational shift, based on the locations of the retina center, retina axes, optic disc model center, and the optic disc point of interest (POI) as clicked on the MRI image.

Parameters#

retina_center_locationarray-like, shape (3,): The (x, y, z) coordinates of the retina center in the original eye model.
axesarray-like, shape (3,): The axes of the retina, typically representing the orientation in (x, y, z).
on_model_locarray-like, shape (3,): The (x, y, z) coordinates of the optic disc on the eye model.
on_image_locarray-like, shape (3,): The (x, y, z) coordinates of the optic disc POI as clicked on the MRI image.
eye_translation_before_shiftarray-like, shape (3,): The translation vector of the eye center before the shift.
eye_translation_after_shiftarray-like, shape (3,): The translation vector of the eye center after the shift.

Returns#

roll_angle_degfloat: The roll angle (in degrees) required to align the model with the observed optic disc position.
pitch_angle_degfloat: The pitch angle (in degrees) required to align the model with the observed optic disc position.

Notes#

Coordinates are assumed to be in the (x, y, z) or (RL, AP, IS) convention. The function corrects for translational shifts before calculating the required rotations.