pyrot.eye_modelling.clipbased_model =================================== .. py:module:: pyrot.eye_modelling.clipbased_model .. autoapi-nested-parse:: 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 --------- .. autoapisummary:: pyrot.eye_modelling.clipbased_model.match_ellipse_with_pois pyrot.eye_modelling.clipbased_model.calc_on_model_loc_patient pyrot.eye_modelling.clipbased_model.calc_residuals_for_registration_with_fitted_rotation pyrot.eye_modelling.clipbased_model.calc_ellipsoid_registration_with_fitted_rotation pyrot.eye_modelling.clipbased_model.calc_residuals_for_registration_with_calculated_rotation pyrot.eye_modelling.clipbased_model.calc_ellipsoid_registration_with_calculated_rotation pyrot.eye_modelling.clipbased_model.calc_roll_and_pitch_of_shifted_eyemodel Module Contents --------------- .. py:function:: match_ellipse_with_pois(eye_model_generators, eye_model_parameters, structure_set, input_ellipse, poi_type_clips, poi_type_on, rotation_method) Register the eye model to clip locations (on the sclera) and the optic disk location. 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_generators : object The eye model containing eye parameters eye_model_parameters : object Object containing specific parameters of the eye model, such as translation and rotation. structure_set : object Data structure containing the set of structures (e.g., ROIs, POIs) for the eye model. input_ellipse : str Specifies which ellipse radii to use for fitting (e.g., "sclera_radii"). poi_type_clips : str The type of POIs representing the clip locations on the sclera. poi_type_on : str The type of POI representing the optic disk location. rotation_method : str 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 .. py:function:: 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_generators : object An object containing geometry generation parameters, including eye laterality. eye_model_parameters : object An object containing parameters of the eye model, including optic nerve rotation. on_model_loc_method : str The method used to determine the ON model location. Currently, only "unity_circle_standard_model" is supported. Returns ------- on_model_loc_patient : numpy.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). .. py:function:: 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 ---------- params : array-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_data : ndarray, shape (N, 3) Array of 3D points representing the data to be fitted to the ellipsoid model. optic_nerve_data : tuple 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. axes : array-like, shape (3,) The semi-axes lengths of the eye model. Returns ------- residuals : ndarray, 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. .. py:function:: 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_data : np.ndarray An (N, 3) array of 3D points representing the data to fit. on_model_loc : np.ndarray A (3,) array specifying the location of the optic disk model. on_image_loc : np.ndarray A (3,) array specifying the location of the optic disk POI (based on the MR image). axes : np.ndarray A (3,) array representing the axes lengths of the ellipsoid. initial_guess : np.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_center : np.ndarray A (3,) array representing the estimated center of the ellipsoid. fitted_angles : np.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. .. py:function:: 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 ---------- params : array-like, shape (3,) The center coordinates (x0, y0, z0) of the eye model in image space clip_data : ndarray, shape (N, 3) The 3D coordinates of the clip POIs. optic_nerve_data : tuple of array-like Tuple containing (on_model_loc, on_image_loc), where: on_model_loc : array-like, shape (3,) The optic disk location in the model. on_image_loc : array-like, shape (3,) The optic disk location in the image (clicked point of interest). axes : array-like, shape (3,) The ellipsoid axes lengths (rl_axis, is_axis, ap_axis). vitreous_body_center : array-like, shape (3,) The center of the vitreous body in the image space. eye_rotation_in : dict 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_input : array-like, shape (3,) The initial translation/ center location of the eye model. Returns ------- residuals_clips : ndarray, 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. .. py:function:: 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) Register an ellipsoid model to clip POIs using least squares optimization. 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_data : np.ndarray Array of 3D points representing the clip POIs to which the eye model is registered. on_model_loc : np.ndarray 3D coordinates of the optic disk model center. on_image_loc : np.ndarray 3D coordinates of the clicked POI of the optic disk on the MR image. axes : np.ndarray The axes lengths of the ellipsoid model. vitreous_body_center : np.ndarray The center coordinates of the vitreous body (which corresponds to the center of the eye/sclera ellipsoid). eye_rotation_in : np.ndarray Initial eye rotation parameters. eye_translation_in : np.ndarray Initial eye translation parameters. initial_guess : np.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`. .. py:function:: 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_location : array-like, shape (3,) The (x, y, z) coordinates of the retina center in the original eye model. axes : array-like, shape (3,) The axes of the retina, typically representing the orientation in (x, y, z). on_model_loc : array-like, shape (3,) The (x, y, z) coordinates of the optic disc on the eye model. on_image_loc : array-like, shape (3,) The (x, y, z) coordinates of the optic disc POI as clicked on the MRI image. eye_translation_before_shift : array-like, shape (3,) The translation vector of the eye center before the shift. eye_translation_after_shift : array-like, shape (3,) The translation vector of the eye center after the shift. Returns ------- roll_angle_deg : float The roll angle (in degrees) required to align the model with the observed optic disc position. pitch_angle_deg : float 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.