Surface Registration Toolkit
		----------------------------

This package contains a library and tools for registering surfaces
generated by the MNI ASP software.


		Installation
		------------

REQUIRED software

* CGAL - Computational Geometry Algorithms Library (www.cgal.org)
* Boost - High-quality C++ libraries (www.boost.org)
* GSL - The GNU Scientific Library (http://sources.redhat.com/gsl/)
* MINC, bicpl, conglomerate, and mni-perllib from MNI (www.bic.mni.mcgill.ca)
* perl version 5


OPTIONAL software

* doxygen: enables documentation generation
* dot: enhanced doxygen-generated documentation with graphs
* cppunit: enables unit tests


Building the source package comprises the following steps.

0. Ensure the required software is built and installed correctly.
   (optional software is optional)
1. Create a symbolic link named "cgal_makefile" in the current directory
   to the correct makefile in directory "makefile" of the CGAL sources.
2. Run configure per directions in file INSTALL.
3. Run "make" and "make install".


		Usage
		-----

	Single Registration
	-------------------

The two surfaces to be registered must each be an instance of the traditional
BIC mesh, such as generated by ASP.

There are two steps to registering a pair of surfaces.  


The first step is to generate the feature data value for each surface.  This
data is used to drive the matching.  The first version of this feature is
generated in the following manner

    surface-data-term-1 surface_A.obj surface_A.vv

This reads the file "surface_A.obj" and generates the output
in a new file "surface_A.vv".  

The final step in computing the surface data term is a distance
transform from the "seed" vertices along the gyrii.  This computation
uses an approximation that depends on inserting a number of extra
vertices along each mesh edge.  The default (5 extra vertices) was
chosen for use with 80k polygons.  For larger polygons, you may need
to reduce this number or face running out of memory.  Use the option
"-dt_extra"; e.g. "-dt_extra 3" for a 320k polygon.

NB:  This data-term computation uses parameter values that were selected 
     for working on the inner surface, i.e., the white/gray interface.
     These values may not produce acceptable results on the outer
     surface.

Alternatively, one of the surface curvature estimates produced by
"surface-curvature" may be used.


The second step is the registration itself.  Assuming that files
"surface_A.vv" and "surface_B.vv" were generated in the first
step (from files "surface_A.obj" and "surface_B.obj", respectively),
the command

    sphere-register surface_A.vv surface_B.vv map_AB.sm

generates a surface map file "map_AB.sm".  This map takes points
FROM surface A TO surface B.


	Resampling Data
	---------------

Suppose we have obtained "map_AB.sm" by registering surface A to B,
as above.  We may have additional data associated with each surface,
say in the files "thickness_A.vv" and "thickness_B.vv".  Each of
these files contains a single value per vertex, listed one value
per line in the traditional BIC vertex ordering.

In order to compare the thickness at matching locations, we can resample
dataset associated with surface B to the mesh or "space" of surface A.

  NOTA BENE: Mapping from A --> B is used to resample the data
             of surface B to the space of surface A.

This is accomplished by the command

    surface-resample surface_A.obj surface_B.obj surface_B.vv \
	map_AB.sm thickness_resB.vv

producing the output file "thickness_resB.vv".  This file contains the
thickness values from surface B at the points corresponding to each
vertex of surface A.  The data in files "thickness_A.vv" and
"thickness_resB.vv" can be compared, vertex-by-vertex.



	Spatial Normalization
	---------------------

By spatial normalization, we mean mapping a population of surfaces
into a standardized space.  The standardized space is defined by
a template surface.  

Let S0.obj be the template surface, and S1.obj, S2.obj, ..., SN.obj
be N surfaces in the population.

The goal of spatial normalization is to put some associated data of
surfaces S1, ..., SN into a common space.  Since the resampling takes
data in the direction opposite of the spatial mapping, the registrations
must be FROM the template surface to each individual.  That is, we
perform the registrations

    S0 --> S1   ==> mapping map_01.sm
    S0 --> S2   ==> mapping map_02.sm
       ...
    S0 --> SN   ==> mapping map_0N.sm

Then resample all the data onto the space of S0 using

    surface-resample S0.obj S1.obj S1.vv map_01.sm S1_std.vv 
    surface-resample S0.obj S2.obj S2.vv map_02.sm S2_std.vv 
	...
    surface-resample S0.obj SN.obj SN.vv map_0N.sm SN_std.vv 

Producing the resampled data in files S1_std.vv, ..., SN_std.vv.


	  Surface Library
	  ---------------

The library is built on an existing, high-quality computational
geometry library (CGAL).  The CGAL Polyhedron_3 data type is used
to represent surfaces in 3D, e.g., the cortical surface.  Thus,
familiarity with CGAL::Polyhedron_3 is required to work with this
library.  See the manual on www.cgal.org.