REMPE Configuration Instructions
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:
- readme.html: Readme webpage.
- web: A folfer containing the support files for the readme web.
- REMPE.exe: The registration method executable.
- config.cfg: A sample config file.
- license.txt: The REMPE executable license file.
- libraries_README.txt: Relevant information regarding the libraries utilized.
- FIRE: A folder containing one image pair, as well as control points and masks of the FIRE dataset, which is publicly available at http://www.ics.forth.gr/cvrl/fire/
Contact
- Code implementation: Carlos Hernandez Matas carlos@hernandez.im
- Research advisor: Xenophon Zabulis zabulis@ics.forth.gr
- Research advisor: Antonis Argyros argyros@ics.forth.gr
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.
0: Create mask
1: Load external mask
.
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.
0: Create mask
1: Load external mask
.
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.
0: Use internal points
1: Load external mask
. 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.
0: No initialization
1: RANSAC
2: POSEST
.
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:
0: No control point output.
1: External control point output.
2: Automatic control point 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