Cornean: Cornea Topography Analysis System, ver. 1.1
(c) J. S. Marron and N. Locantore, 1998
Department of Statistics, University of North Carolina



Summary:  Cornean is a software package for the analysis of corneal
shapes, as measured by the Keratron 2000.  Keratron data files can
be viewed directly in Cornean, but most analysis is done after 
first summarizing each image as a vector of Zernike coefficients.  
These vectors then form the basis for most of the analysis.  There 
are currently 4 types of analysis available:

I.  Individual Images, including display of the Keratron output
curvature file, Zernike decomposition, display of Zernike 
reconstruction.  The reconstruction can be modified by either 
smoothing (useful for handling edge effects), or by choosing any
combination of Zernike terms (with important ones highlighted by a 
term by term "power display" showing the relative contribution of 
each term to the image).

II.  Populations, where the focus is on lists of images.  Current
operations on these lists include Zernike decomposition, display 
of reconstructed images, and principal component analysis.

III.  Differences, where the focus is on pairs of images.  Current 
operation highlights differences in the two by a movie which morphs 
from one image to the other.

IV.  Individuals in Populations, where the focus is on 
understanding how an individual relates to a population.  This is 
done by showing where the individual lies with respect to the 
principal component analysis as in II.

    All programming was done in MATLAB, so a working version is 
required to use this software.  MATLAB runs in PC-Windows, Unix 
and Mac environments, and Cornean has been tested in PC-windows
and Unix.


&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&


Detailed Description of Menus and Features:

Main Menu:
  Has buttons:

  I.  Go to Individual Analysis Menu

  II.  Go to Population Analysis Menu

  III.  Go to Difference Analysis Menu

  IV.  Go to Individual in Population Menu


==================================================================


I.  Individual Analysis Menu
  Has buttons and data input fields

  Ia.  Input field for name of Keratron data files to work with.

  Ib.  Button to display directory with currently available 
             Keratron data files.

  Ic.  Button which displays help message about input files.

  Id.  Button to create display of raw data curvature map.  This 
             image includes shows the boundary of any missing 
             data points.

  ----------------------------------------------------------------

  Ie.  Input field for recentering coordinates (default is no
             recentering).

  If.  Button to do Zernike decomposition (result is saved both in
             an ASCII file with the same file suffix, and as a 
             MATLAB file, which allows simultaneously saving other
             parameters).

  ----------------------------------------------------------------

  Ig.  Button to go to Reconstruct Analysze Menu (see description
             below)


==================================================================


II.  Population Analysis Menu
  Has buttons and data input fields

  IIa.  Input field for name of list file to work with (these list
             can be created with an ASCII file editor, each line 
             should be an 8 character suffix of a Keratron data 
             file).

  IIb.  Button to display directory with currently available 
             list files.

  IIc.  Button which displays help message about input files.

  IId.  Button which does Zernike decomposition for all the data
             files in the list.

  IIe.  Button which displays a Zernike decomposition for all the
             data files in the list.

  IIf.  Button which generates a postscript file (for color
             printing), for the reconstructions in IIE.

  IIg.  Button which does a "Static" (no motion picture) 
             Principal Component Analysis.  This displays the 
             population mean, and shows variability about the 
             mean in terms of "directions of greatest 
             variability".  Directions are displayed by 
             showing extremes.  Additional population 
             properties, such as clustering, are shown by 
             displays of projections of images onto direction 
             vectors.

  IIh.  Button which generates a postscript file (for color
             printing), for the Principal Component Analysis 
             in IIG.

  IIi.  Button which generates a "Dynamic" (using motion 
             pictures for display).  This is the same analysis 
             as in IIG, but this type of display allows more 
             complete understanding of the variability in each
             direction through dynamic graphics.  This is done
             by a movie which morphs through images 
             representing that direction.  The movie also shows
             where in the population of projections the current
             image is.

  IIj.  Button which saves the current Dynamic Principal 
             Component Analysis images as MPEG files (this 
             works, but is not well tested, and probably needs
             some fine tuning).


==================================================================


III.  Difference Analysis Menu
  Has buttons and data input fields

  IIIa.  Input field for name of first Keratron data file.

  IIIb.  Input field for name of second Keratron data file.
 
  IIIc.  Button to display directory with currently available 
             Keratron data files.

  IIId.  Button which displays help message about input files.

  IIIe.  Button which makes a new movie that morphs between the
             two corneas.

  IIIf.  Button which reruns the movie created in IIIE (this
             is faster than recreating the movie).

  IIIg.  Button which saves the current Difference Analysis
             movie as an MPEG file (this works, but is not well 
             tested, and probably needs some fine tuning).


==================================================================


IV.  Individual in Population Menu
  Has buttons and data input fields

  IVa.  Input field for name of Keratron data files to work with.

  IVb.  Button to display directory with currently available 
             Keratron data files.

  IVc.  Button which displays help message about input files.

  IVd.  Input field for name of the population list file (form as
             in IIA. above).

  IVe.  Button to display directory with currently available 
             list files.

  IVf.  Button which displays help message about input files.

  IVg.  Button which shows where the individual stands in the
             principal component analysis for the population.
             For each direction an image is displayed, which 
             shows the component of the individual in that
             direction, and also overlays the indiviuals 
             projection on that display.

  IVh.  Button which generates a postscript file (for color
             printing), for the Individual in Principal
             Component Analysis in IIG.


==================================================================


Ig.  Reconstruct Analysze Menu
  Has buttons and data input fields

  Ig1.  Button which does full Zernike Reconstruction of the 
             current image.  Also shows the boundary of any
             missing data.  

  Ig2.  Slider which which controls the mean (i.e. location) of 
             the smoothing function shown in Ig4.

  Ig3.  Slider which controls the standard deviation (i.e. spread)
             of the smoothing function shown in Ig4.

  Ig4.  Plot of the current smoothing function, which allows easy
             understanding of how much smoothing will be done in
             a smoothed reconstruction.

  Ig5.  Button to construct a smoothed reconstruction.  This is
             similar to the reconstruction in Ig1, but first the 
             Zernike coefficients are downweighted by the 
             smoothing function shown in Ig4.  This is a useful
             way to handle edge effects which can be caused by 
             missing data.

  Ig6.  Triangular array of pushbuttons, one for each type of 
             Zernike term.  This allows reconstructions with
             total user control over which terms are included.
             Click on a checkbox with the mouse to include 
             (exclude) that Zernike term.

  Ig7.  Button to do the reconstruction, using only the Zernike
             terms chosen in Ig6.  

  Ig8.  Button to show a "Power display".  This is triangular
             array of gray patches (same array as in Ig6), which
             shows the relative fraction of the "Power" (i.e. 
             part of the total sum of squares) that each Zernike
             term represents.  Lighter shades are use for more 
             those terms that contain a large part of the image.


&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&


Advanced Features:

    A number of control parameters can be adjusted by editing the
MATLAB program files.  (note:  it is recommended that these be 
changed by experienced MATLAB users only).
    The current value of these can also be reset using the MATLAB
prompt.  E.g. to set NMAX to 5, use:
            >>   NMAX = 5


Variable Name     Location                      Notes
            (where default is set)

ienviron          cornean.m         This allows for minimum resetting 
                                of control variables accross platforms.
                                Currently set up configurations
                                include:


NMAX              cornean.m         This is the number of Zernike terms
                                to use in decompositions.  For full
                                Zernike decompositions, default is 10,
                                which gave acceptable decompositions 
                                for a wide range of test corneas.  When
                                R0 = 4.2, NMAX = 10 has been well tested
                                on Normal, PRK and Kerataconic images.
                     

R0                cornean.m         Radius of analysis.  All images are
                                displayed as a circle with this radius.
                                Data outside this circle is truncated in
                                the Zernike decomposition.  4.2 has been
                                well tested on Normal, PRK and Kerataconic
                                images.  This sometimes admits large edge 
                                effects, so smaller values are probably
                                better in some cases.

screenfact        cornean.m         Controls size of sinlge image plots.
                                Set this bigger than one for higher 
                                resolution monitors.

NRPT              cornean.m         Number of times to replay movies, in
                                morphing analyses.

MATLABVER         cornean.m         Version of MATLAB.  Both versions 4
                                and 5 are supported (and this variable 
                                must be correct or there can be errors).

icut              coazdec.m         This controls cutoff of first two
                                "nondata points" generally created by
                                Keratron.  Default is 1, to cut these 
                                off.  Change this to 0 if input data 
                                files already have this cut off.

iasciiout         coazdec.m         This controls creation of an ASCII
                                file of Zernike coefficients when a 
                                single image Zernike decomposition is 
                                done.  Default is 1, to create ASCII
                                files.  Set this to 0 to stop
                                generation of ASCII files.

nframe            coadpca.m         Number of frames in Dynamic
                                Principal Component Analysis movies.
                                Setting this higher means the movies
                                are slower to generate, but look 
                                "smoother" (and run more slowly).
                                Default is 21, which seems like a
                                good tradeoff.
                                
nframe            coamn.m           Number of frames in Difference
                                Analysis movies.  Setting this
                                higher means the movies are slower 
                                to generate, but look "smoother"
                                (and run more slowly).  Default is 
                                21, which seems like a good
                                tradeoff.

(mpeg parameters) coadpcas.m        Parameters that control the
                  coams.m       creation of mpage files, for saving
                                movies.  These are neither
                                implemented nor fine tuned yet.



Note:  There are a number of other variables, such as defaults for paths,
and filenames that first appear in the input windows, which are also set 
(and can be reset) in the file cornean.m.  

CAUTION:  There are also many other variables that are not intended to 
be changed (and can cause erratic behavior if they are changed).





&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&


Directory Structure:

The main directory for Cornean is intended to be:

\matlab\cornean

The main program files are intended to reside there.  As long as
this is the current MATLAB directory, this does not need to be in
the "MATLAB path".


Subdirectories are:


\matlab\cornean\indata

where the Keratron data files are assumed to reside.  These have 8
character suffixes, and 3 character endings:

.xla       (contains radii)
.zla       (contians heights)
.tla       (contians curvatures)

For the raw data display, the .xla and .tla files must be present 
or there will be an error messge (and no display constructed).  For
Zernike decomposition, the .xla and .zla files must be present or
there will be an error message (and no decomposition done).


\matlab\cornean\zfm

Where the Zernike feature matrices, and the file lists are stored
(see discussion below about these).


\matlab\cornean\outputs

Where outputs are stored.  Current output types are:

1.  .asc files, ASCII files of Zernike feature vectors (put out by
              single image decompositions).  These appear in the
              order:       n   m
                           0   0               Piston
                           1   1       cos     Tilt
                           1   1       sin     Tilt
                           2   0               Spheric 
                           2   2       cos     Astigmatic 3
                           2   2       sin     Astigmatic 3
                           3   1       cos     Coma 3
                           3   1       sin     Coma 3
                           3   3       cos
                           3   3       sin
                           4   0               Spheric 3
                           4   2       cos     Astigmatic 5
                           4   2       sin     Astigmatic 5
                           4   4       cos
                           4   4       sin
              etc. as in Webb (1992) "Zernike polynomial description
              of opthalmic surfaces", Ophthalmic and Visual Optics,
              Vol. 3 of OSA Technical Digest series, 38-41.

2.  .ps files, postscript files for convenient color printing, of:
          a.  Listwise Reconstructions.
          b.  Static Principal Component Analyses.
          c.  Individual in Population Analyses.

3.  .mpg files, movie storage in mpeg format.  This can be easily
          ported to non-Matlab users, and is also a very compact
          form for saving movies.



&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&



Notes About File Saving and Reading:

1.  Zernike Decompositions:  These are stored as .mat files.  The
  suffix of these files is the SAME as the suffix of the
  corresponding Keratron data files.  These .mat files allow
  convenient simultaneous storage of several entities.  Currently, 
  when a decomposition is done, the .mat file stores:
          a.  the vector of Zernike coefficients
          b.  NMAX   (highest Zernike level in this decomp.)
          c.  R0     (radius of this analysis)
          d.  the radius and angle of the amount of recentering
          e.  the boundary of the nonmissing data points.
  To avoid problems with clashing values of these variables, they
  are all reset to the value in the file, when one of these gets
  loaded.
  CAUTION:  the ascii file that is saved during individual
  decompositions contains ONLY the vector of Zernike coefficients.
  
2.  List files:  These have a suffix indicating what they are about,
and the suffix .lst.  They are intended to be created with an ASCII
file editor (e.g. Windows "Notepad"), and each line line should be 
the 8 character suffix of Keratron data files.  These are used for:
         a.  Listwise Zernike decomposition (Population menu)
                 This reads through the entire list, and does a
                 Zernike decomposition for each image in the list.
         b.  Listwise Zernike image display (Population Menu)
                 This does a reconstruction, from existing Zernike 
                 decompositions, of the images, putting 20 on a
                 single page (more pages if needed).  For this, NMAX
                 and R0 need to be the same for each Zernike
                 decomposition in the list.  If not, this will be
                 aborted.  Fix this easily by doing a listwise
                 decomposition as in a.
         c.  Population Analyses (Pop'n and Individ. in Pop'n Menus)
                 These also load the Zernike feature vectors for
                 the entire list, and again NMAX and R0 needs to be
                 same for all (and will abort, but can be easily 
                 fixed as above).
   




