/***************************************************
 These programs are free software; you can redistribute them and/or modify
 them under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.
***************************************************/

University of Chicago - Visual Science Laboratories - Chicago, IL - USA
            
This software determines the spectral power distribution of light on the retina, taking account of the optics of the eye, including chromatic aberration and wave aberrations.

TOPICS:
  1. Description
  2. The Program
  3. Warnings
  4. All the steps
  5. Manuals
  6. Downloads
  7. Links
  8. Contact me
  9. References


1. DESCRIPTION:
top
This software takes as input a two-dimensional image and determines the two-dimensional retinal image, taking into account the more important human optical factors affecting retinal image quality (including chromatic aberration and wave aberrations).
The input image is specified by the spectral distribution of the light at each point.
The software also can transform CRT images specified in RGB into the input image but this requires individual calibration of the CRT used to display the image (spectral power distribution of each phosphors and gamma correction).

Retinal image quality is based on the model "Indiana Eye".
For information about the human eye model used and the theoretical computation of the Point Spread Function (PSF), see (Thibos & Bradley 1999).
Alternatively have a look to Thibos's publications' : http://research.opt.indiana.edu/Researchers/Thibos/



2. THE PROGRAM:
top
Professor Thibos' MATLAB code is converted to C for faster execution. Calculation for larger images (512x512) and smaller wavelength steps (10 nm steps from 400 to 750 nm are used here) requires 3 minutes on a Macintosh G5 (1.6 MGHz, single processor).

Input images may either be given in terms of the the R, G, B components of a CRT display, or directly in l, s, Y chromaticity (lsY represents the relative L-cone to M-cone stimulation [l=L/L+M], relative S-cone stimulation [s=S/(L+M)] and luminance [Y=L+M] (MacLeod & Boynton 1979)).
The l, s, Y Chromaticity will be converted into percentage of red, green and blue guns (This option is set by the 'CONVERT_lsY2RGB' option in the Settings file ).
NOTE: To perform this lsY to RGB computation, the program needs to load the Monitor's Judd Specs.
The RGB Input image is converted into in a spectral power distribution at each point.
The model eye allows computation of a separate Point Spread Function (PSF) at each wavelength. The image is decomposed into a separate image at each wavelength (with 10 nm steps from 400 to 750 nm, there are 36 images.)
There is one convolution for each wavelength (that is, 36 convolutions).
This involves 72 Direct Fast Fourier Transform (FFT) and 36 Inverse Fast Fourier Transform, which can take a while.
After the retinal images is computed at each wavelength, standard trichromatic representation of the retinal image may be calculated, such as Judd(1951) X,Y,Z, or L,M,S cone excitation (based on the Smith & Pokorny cone fundamentals (Smith &Pokorny, 1975)).


P.S. Thanks to Paul Bourke, whose very efficient 2D FFT  source code is used here.



3. WARNINGS:  There are several critical steps to respect while using this software.
top
You will have to make sure the inputs parameters respect the following conditions:
  • The Spectral Power Distribution you are using (provided by your monitor) must correspond to the Judd Specs matrix.
  • The Zernike coefficients must match the defined pupil size.
  • The input displayed image must have the same spatial resolution as the computed PSF.


4. ALL THE STEPS:
top

Besides the input images, the software reads a Settings.cfg file, which defines about 50 options (Comments are given in this file for each of the 50 options).
The program also reads several intput text files: (located in the Params directory)
  1. The screen's Spectral Power distribution (SPD).
  2. The Judd51 color matching functions (, , ).
  3. The Judd Specs matrix.
  4. The Zernike coefficients modelling the wave aberration (Thibos et al. 2002).
  5. It can either load the Cones fundamentals or compute them from Judd51 , , .

There are three options for the software's input : (selected according to the 'CONVERT_lsY2RGB' and 'CRTorWAV' options in the Settings.cfg file)
  1. Three input images may represent for each pixel, the percentage of the monitor's guns R, G & B.
    • CONVERT_lsY2RGB option set to 0.
  2. Three input images may be characterized by relative L-cone to M-cone stimulation [l=L/L+M], relative S-cone stimulation [s=S/(L+M)] and luminance [Y=L+M] (MacLeod & Boynton 1979).
    • CONVERT_lsY2RGB option set to 1.
  3. The input images can also be wavelength images, i.e. for a start wavelength set to 400, a step of 10 and a final wavelength of 750, the software will read 36 wavelength images.
    • CRTorWAV option set to WAV
    • The images' names will be 'Name_1.tim', 'Name_2.tim', ... 'Name_36.tim'


You'll first have to download or create an image.
For testing purpose, we provide here two examples of stimulus files using calibration measurements for one of the Shevell lab's monitors:


RGB guns percentage: l,s,Y chromaticity:
TestImageR.tim.tgz
TestImageG.tim.tgz
TestImageB.tim.tgz

Download all three matrices,
which give for each
pixel the percentages of the
maximum light from
R, G and B guns of a particular CRT.
DC.512.O.LPl.tim.tgz
DC.512.O.LPs.tim.tgz
DC.512.O.LPY.tim.tgz

Download all three matrices, which give
at each pixel the l, s and Y chromaticity.


Warning: For the first stimulus, the 'CONVERT_lsY2RGB' parameter should be set to 0 in the Settings.cfg file (the stimulus is already given in terms of RGB guns percentage), whereas for the second stimulus, it should be set to 1 (the program must convert the lsY values onto RGB guns percentage).
We recommend the NIH's ImageJ software to read and write such images:  http://rsb.info.nih.gov/ij/
('ImageJ' can import and save Text Images, i.e. matrices without header, it can also split or merge RGB Images, see the README file for more details).


All input images will have to be in the RetImg/build directory.
The 'SAVE_WAV_FILES' option in the Settings.cfg file allows storing the whole set of wavelength images obtained while converting from lsY or RGB images.

Note:  The stimulus size (in degrees of visual angle) depends on both its size in pixels and on the pupil size.
  • A 512x512 stimulus with a 3.0mm diameter pupil provides an image size of: 1.956 degrees square.
  • A 512x512 stimulus with a 4.5mm diameter pupil provides an image size of: 1.304 degrees square.
  • A 512x512 stimulus with a 6.0mm diameter pupil provides an image size of: 0.978 degrees square.
The FFT source code used here only supports square images of size 2^n (i.e. 256x256, 512x512 or 1024x1024 pixels).
We recommend using a 512x512 pixels stimulus as 1024x1024 uses far more computing resources and requires a huge amount of hard disk space to store outputs.

 Mac OS X instructions: (if you want to modify the code, we suggest using XCode)

  1. Open a Terminal window (Terminal usually is in the Utilities folder of the Application folder)
  2. Download and unzip the Ret-Img.tgz package in your Applications folder
      • tar -xvzf ~/Applications/Ret-Img.tgz
  3. Download and unzip the above TestImages in the build directory of the Ret-Img folder
      • tar -xvzf ~/Applications/Ret-Img/build/TestImageR.tim.tgz
      • tar -xvzf ~/Applications/Ret-Img/build/TestImageG.tim.tgz
      • tar -xvzf ~/Applications/Ret-Img/build/TestImageB.tim.tgz
  4. Go to the Ret-Img/build directory
      • cd ~/Applications/Ret-Img/build/
  5. Compile the package : 
      • > gcc -o Ret-Img ../main.cpp -lstdc++
  6. Launch the program : 
    • You can specify up to 9 parameters in the command line:
      •  > ./Ret-Img <imageName> <imageSize> <StartWavelength> <Steps> <EndWavelength> <PupilSize> <FocusWavelength> <Frequency(For Sinewaves)> <ZernikeCoefficients>
          • Exemple:

      •  > ./Ret-Img TestImage 512 400 10 750 3.0 550 0 ZernikeCoefs_3.0
    • Or the software will read default input parameters from the Settings.cfg file by launching the program without arguments:
      • > ./Ret-Img
Linux/Unix instructions:
Instructions are the same. You probably know where the terminal is, and you surely have gcc installed.
You can use an Integrated Development environment (IDE) such as Kdevelop or Anjuta or you can use whatever text editor you want and compile with a command line as given above.

Windows (98/2000/XP):

Either import these .cpp and .h files into commercial software such as Microsoft Visual c++, use some free software which runs gcc, (such as devc++, check here), or use gcc with Cygwin.



5. MORE DETAILS:
top
  • Readme.Software (Ret-Img)
  • Check out the main Formulas
  • Readme.Software (CreateStimulus)
  • For a few of the other softwares given in the Downloads section, the command line argument -h may provide the arguments.
            ( i.e. >./FitOnSquare -h ) If the images quality is poor, check out the PDF (Note however that this file is pretty big ! ~9 MBytes).



6. DOWNLOADS:

top

Retinal image software

Mac OS X: (Xcode)

Windows: (Dev-cpp)



Linux: (kdevelop)


Related Code      Readme

Mac OS X:

Parameters used in the Shevell Lab. :    Readme


Alternate parameters:



7. LINKS:
top



8. QUESTIONS OR SUGGESTIONS:
top


9. REFERENCES:


Thibos & Bradley, Modeling the Refractive and Neuro-Sensor Systems of the Eye, Chapter 4 of VISUAL INSTRUMENTATION: Optical Design and Engineering Principles In: Mouroulis, P. (Ed.), Optical Design for Visual Instrumentation New York: McGraw-Hill (pp. 101-159), 1999.

Smith, V. C. & Pokorny, J. (1975). Spectral sensitivity of the foveal cone photopigments between 400 and 500 nm. Vision Research, 15, 161-171.

MacLeod, D. I. A. & Boynton, R. M. (1979). Chromaticity diagram showing cone excitation by stimuli of equal luminance. Journal of the Optical Society of America, 69. 1183-1185.

Thibos, L. N., Hong, X., Bradley, A. Cheng, X. (2002). Statistical variation of aberration structure and image quality in a normal population of healthy eyes. Journal of the Optical Society of America A, 19(12), 2329-2348.


/***************************************************
-------------------
Last modification : March 10th 2005
Florent Autrusseau
email : Florent.Autrusseau@univ-nantes.fr
-------------------
***************************************************/








Polytech'Nantes
IRCCyN