What is this for?

This executable allows to perform retinal image registration through 3D eye modelling and pose estimation. It has been developed by Carlos Hernandez Matas during his Ph.D. studies at the University of Crete, and under the supervision of Xenophon Zabulis and Antonis A. Argyros. Scientific publications documenting the framework at different development stages are found at the bottom of this README.md file.

Contents

This zip file contains the following elements:

Contact

How to run

Double clicking on REMPE.exe will automatically run the program, loading the configuration file config.cfg

From the command line, it can be executed as:

REMPE.exe config.cfg

where config.cfg indicates the configuration file to be loaded.

Images will be saved inside the folder containing the images to register.

If using a CUDA compatible card, please ensure that the drivers are updated to the latest version.

Config file parameters

The following is a config file example. The parameters must be input following this order and structure

imageFolder "FIRE"
imageBodyName "S01_"
imageExtension "jpg"                        
initialTestImage 2                                
finalTestImage 2                                  
simultaneousTestImages 1                           
referenceImage 1                            
externalMasks 1                             
mask "mask.png"                             
externalFeatureMasks 1                      
featuremask "feature_mask.png"              
externalRegistrationPoints 0                
registrationPoints "keypoints"             
outputFolder ""                         
camera1FOV 45                               
camera2FOV 45                               
initialEyeRadii 12 12 12                          
lensToCorneaRefImg 45.7                     
angleStep 0.03                              
swarms 3                                
initialization 1                      
PSO-Stages 1                                
PSO-Generations 300                         
PSO-Particles 10000                         
searchSpaceRange 2 2 2 2 2 2 4 4 4 180 180 180 
objFuncPercentage 0.8                      
outputProjectedImage 1                      
outputSphereFloatingPoints 0                
outputImageFloatingPoints 0                 
outputIntermediateStuff 0                   
outputControlPoints 1                       
controlPoints1 "control_points"             
genericFolderName 0                               

Important

No spaces are allowed in the terms between quotation marks.

controlPoints1 "control_points"

is the correct way to write it, while

controlPoints1 "control points"

will cause errors and for the program to not run properly, possibly crash or give erroneous results.

Parameters

imageFolder

Indicates the relative path in which the images to register can be found

imageFolder "../FIRE"

imageBodyName

Indicates the body of the images, right up to the image number.

imageBodyName "S01_"

imageExtension

Indicates the image extension.

imageExtension "jpg"

initialTestImage

Indicates the first image of the range of images to be registered

initialTestImage 2

finalTestImage

Indicates the last image of the range of images to be registered

finalTestImage 2

simultaneousTestImages

Indicates the amount of test images to register simultaneously

simultaneousTestImages 1

referenceImage

Indicates the image that will be used as reference image

referenceImage 1

externalMasks

Indicates if the system should load external images for the image mask or if the system should attempt to create them itself.

.

externalMasks 0

mask

Indicates the name of the external mask to load.

If the name has the full name of the mask, including image extension, then that image will be used for all masks.

mask "mask.png"

If only the body of the name of the mask is indicated, the system will attempt to load a different mask for each image, following the format body + image number + .png.

mask "mask_"

externalFeatureMasks

Indicates if the system should load external images for the mask that indicates the ROI for feature selection, or if the system should attempt to create them itself.

.

externalFeatureMasks 0

featureMask

Indicates the name of the external feature mask to load.

If the name has the full name of the mask, including image extension, then that image will be used for all masks.

featureMask "feature_mask.png"

If only the body of the name of the mask is indicated, the system will attempt to load a different mask for each image, following the format body + image number + .png.

featureMask "feature_mask_"

externalRegistrationPoints

Indicates if the system should load external matches to use for performing the registration.

. externalRegistrationPoints 0

registrationPoints

Indicates the body of the file with the matches to load to use for registration

The filenames must follow the following format: registrationPoints + _ + imageBodyName + referenceImage + _ + testImage + .txt

registrationPoints "keypoints"

outputFolder

If a string is given, the result folder will be included inside the folder given by this parameter

outputFolder "output"

camera1FOV and camera2FOV

Indicate the camera field of view, for the reference image and for the image to register. Typically it's indicated in the camera's manual.

camera1FOV 45
camera2FOV 45

initialEyeRadii

Indicate the initial estimation for the eye radius. It requires a value for each of the three semi-axes.

initialEyeRadii 12 12 12

lensToCorneaRefImg

Indicates the value of the distance from the lens of the camera to the cornea. Typically it's indicated in the camera's manual. Default value 45.7

lensToCorneaRefImg 45.7

angleStep

Density of points for the 3D model. It effects the 2D projection also. Default value 0.04

angleStep 0.04

swarms 1

Amount of independent swarms (parallel ransac and pso processes) to be executed independently

swarms 1

initialization

Indicates what type of initialization should be used in the registration process.

.

initialization 1

PSO-stages

Indicates the amount of PSO stages to be used. It can range from 0 to a maximum of 3. For each PSO-Stage, a set of parameters scoreMethod, PSO-Generations, PSO-Particles and searchSpaceRange have to be defined.

PSO-Stages 1

PSO-Generations

Amount of generations for the PSO process.

 PSO-Generations 300

PSO-Particles

Amount of particles per generation

PSO-Particles 10000

searchSpaceRange

Definition of the search space. Requires 12 parameters, that define {t, R, A, Q} as {tx, ty, tz, Rx, Ry, Rz, a, b, c, rotA, rotB, rotC}. t and A are in mm. R and Q are in degrees.

searchSpaceRange 2 2 2 2 2 2 4 4 4 180 180 180

objFuncPercentage

Percentage of keypoints utilized by the objective function. Should be 0.8

objFuncPercentage 0.8

outputProjectedImage

Indicates if the projected 2D images should be output. Binary value.

outputProjectedImage 1

outputSphereFloatingPoints

Indicates if the 3D point clouds of the images on the ellipsoidal model should be output. Binary value.

outputSphereFloatingPoints 0

outputImageFloatingPoints 0

Indicates if the 2D point cloud of the images should be output. Binary value.

outputImageFloatingPoints 0

outputIntermediateStuff

Indicates if a number of intermediate data, such as image processing and warpings and point clouds should be output. Binary value.

outputIntermediateStuff 0

outputControlPoints

Indicates which type of control points to be output:

.

outputControlPoints 1

controlPoints

Indicates the name of the control point file to read if outputControlPoints is set to 1

The filenames must follow the following format: controlPoints + _ + imageBodyName + referenceImage + _ + testImage + .txt

controlPoints "control_points"

genericFolderName

Indicates if the result files should be output to a dynamic name generated folder, or to a "Results" folder. If the program is used within another software (i.e. for the Thessaloniki doctors), it is recommended to set the value to 1. Otherwise, it should be set to 0. Binary value.

genericFolderName 0

Config file example for image registration with the parameters used in the PhD thesis.

imageFolder "FIRE"
imageBodyName "S01_"
imageExtension "jpg"                        
initialTestImage 2                                
finalTestImage 2                                  
simultaneousTestImages 1                           
referenceImage 1                            
externalMasks 1                             
mask "mask.png"                             
externalFeatureMasks 1                      
featuremask "feature_mask.png"              
externalRegistrationPoints 0                
registrationPoints "keypoints"             
outputFolder ""                         
camera1FOV 45                               
camera2FOV 45                               
initialEyeRadii 12 12 12                          
lensToCorneaRefImg 45.7                     
angleStep 0.03                              
swarms 3                                
ransacInitialization 1                      
PSO-Stages 1                                
PSO-Generations 300                         
PSO-Particles 10000                         
searchSpaceRange 2 2 2 2 2 2 4 4 4 180 180 180 
objFuncPercentage 0.8                      
outputProjectedImage 1                      
outputSphereFloatingPoints 0                
outputImageFloatingPoints 0                 
outputIntermediateStuff 0                   
outputControlPoints 1                       
controlPoints1 "control_points"             
genericFolderName 0                         

Config file example for image registration with 2 PSO stages per swarm.

imageFolder "FIRE"
imageBodyName "S01_"
imageExtension "jpg"                        
initialTestImage 2                                
finalTestImage 2                                  
simultaneousTestImages 1                           
referenceImage 1                            
externalMasks 0                             
mask "mask_"                             
externalFeatureMasks 0                      
featuremask "mask_"              
externalRegistrationPoints 0                
registrationPoints "keypoints"             
outputFolder ""                         
camera1FOV 45                               
camera2FOV 45                               
initialEyeRadii 12 12 12                          
lensToCorneaRefImg 45.7                     
angleStep 0.03                              
swarms 3                                
ransacInitialization 1                      
PSO-Stages 2                                
PSO-Generations 150                         
PSO-Particles 10000                         
searchSpaceRange 4 4 4 4 4 4 8 8 8 360 360 360
PSO-Generations 150                         
PSO-Particles 10000                         
searchSpaceRange 2 2 2 2 2 2 4 4 4 180 180 180 
objFuncPercentage 0.8                      
outputProjectedImage 1                      
outputSphereFloatingPoints 0                
outputImageFloatingPoints 0                 
outputIntermediateStuff 0                   
outputControlPoints 0                       
controlPoints1 "control_points"             
genericFolderName 0