Fluid Registration and Atlas Toolkit (FRAT)
0.1
FRAT provides c++ libraries and applications for performing fluid registration based operations on 2D and 3D images. The registration method is based on the large displacement diffeomorphic mapping (LDDM) registration method and implements discretized fluid registration. This registration method is then applied to time series analysis, cross-sectional atlas building, and longitudinal atlas building. The individual tool components are:
LDDM: Fluid registration between two images.
TimeSeries: Time series analysis of longitudinal data for a single subject.
AtlasBuilder: Cross-sectional atlas building for a population of images.
LongitudinalAtlasBuilder: Longitudinal atlas building for a population of subjects, each with a longitudinal data set.
FRATUtils: A colleciton of utilitiy functions for working with volumes and time seried files
FRAT is currently a work in progress. To install the latest version, follow the instructions below.
FRAT requires a full setup of the Insight Toolkit (ITK), the GenerateCLP module from Slicer3, and a working FFTW setup. The easiest way to get CMake, ITK, and GenerateCLP is to do a complete install of Slicer3. For build instructions, go here. For FFTW installation instructions, go here.
Create the directory into which you plan to install FRAT and download the source code from the svn repository using
svn checkout https://www.nitrc.org/svn/frat
the sake of clarity, we'll refer to the base installation directory FRAT_DIR.
FRAT is designed for an in-source build with CMake. Change directory to the trunk directory (FRAT_DIR/trunk) and execute
ccmake . (including the period)
This will present you with the command line configuration utility for CMake. The initial screen will inform you that the cache is empty. Press 'c' to initialize the configuration. Once the initial configuration is done, will be presented with a number of options and variables that must be set.
options present are COMPILE_APPLICATIONS, COMPILE_TESTING, and BUILD_DOCUMENTATION. Each switch toggles the build of the primary executables, the testing executables, and a local copy of this documentation respectively. All will begin in the OFF setting. To enable a build component, switch it to ON and press 'c' to re-configure. If you wish to compile only a subset of the applications or tests, switch the appropriate option flag to ON and then use the 't' key to view the advanced options. In the advanced options there will be an individual flag for each application and each test (“compile_{application name}”). With the primary applications or testing flag on, these individual flags can be used to toggle the specific build components. If a compile flag is switched off, all of the corresponding individual component flags will be switched off.
primary variables to be set are those that link to ITK, GenerateCLP, and FFTW. Some of these may be automatically retrieved during configuration. A sample configuration using a Slicer3 install looks like:
FFTW_LIB /usr/local/lib/libfftw3.a
FFTW_PATH /usr/local/include
ITK_DIR /playpen/Slicer3-lib/Insight-build
GenerateCLP_DIR /playpen/Slicer3-build/Libs/GenerateCLP
The paths on your system may vary depending on how you have the libraries set up. Also, the GenerateCLP_DIR option will not show up until COMPILE_APPLICATIONS is turned on. Once any variables ore options have been changed, press 'c' to re-configure the build.
Once all variables and options have been set correctly, the generate option will appear at the bottom of the console. It can be activated by pressing the 'g' key. This will generate the appropriate make files and exit CMake.
The last step is simply to build the project with make. From the trunk directory, just execute
make
The project will build and the executables will be placed in FRAT_DIR/trunk/bin. If you set BUILD_DOCUMENTATION to ON during the configuration step, you also need to execute
make doc
to build your local copy of the documentation.
FRAT provides libraries for working with both 2D and 3D vector-valued images. Most functions and algorithms are implemented for both 2D and 3D, so for the sake of brevity, we'll use XD in place of 2D or 3D. At this time, FRAT is not generalized to arbitrary dimensionality.
The base data classes in FRAT are the VectorArrayXD classes. These templated classes store XD vector-valued data of any type. Throughout the code, they are used only as the superclass for the float-based VectorImageXD and VectorFieldXD classes.
The VectorImage2D and VectorImage3D classes offer basic vector-value XD image functionality with float type pixels. The following trivial example shows a simple operation using the VectorImage2D type and then deletes the image. In this case it simply sets the value of each pixel to the value of the x index times the value of the y index.
unsigned int szX = 100;
unsigned int szY = 50;
unsigned int dim = 1;
VectorImage2D* im = new VectorImage2D(szX, szY, dim);
for (unsigned int y = 0; y < szY; y++) {
for (unsigned int x = 0; x < szX; x++) {
for (unsigned int d = 0; d < dim; d++) {
im->setValue(x,y,d, x*y);
}
}
}
delete im;
The key elements in this example are the use of the setValue(x,y,d, val) method and the use of the inverted loop structure. FRAT stores the image array in row-major format, so using the y-dimension in 2D or the z-dimension in 3D as the outer loop is more efficient. The setValue(x,y,d, val) method used here simply sets d'th vector component of the pixel at location x,y to val. The pixel can then be accessed using getValue(x,y,d).
In addition to image size (szX, szY) and vector dimensionality (dim), the VectorImageXD classes support the notion of anisotropic pixel spacing (spX, spY). A spacing scale factor (spFct) can also be employed to change the units on the space in order to adjust derivative behavior. For example:
unsigned int szX = 100;
unsigned int szY = 50;
unsigned int dim = 1;
float spX = 0.1;
float spY = 0.2;
float spFct = 0.01;
VectorImage2D* im = new VectorImage2D(szX, szY, dim, spX, spY, spFct);
If the space factor is not set for an image, it will default to having a factor of 0.01 (found to be the best default experimentally). If the spacing is not specified, it will default to 1 for each axis. The size, dimensionality spacing, and space factor can be get and set after instantiation using methods such as getSizeX(), getDim(), getSpaceX(), getSpaceFactor(), and similar set methods.
The other primary data type used in FRAT is vector fields, implemented in the VectorField2D and VectorField3D classes. In practice these classes are simply subclasses of the VectorImageXD classes where the vector size is specified as 2 for 2D fields and 3 for 3D fields. In theory, however, these classes should be thought of as separate entities from the VectorImageXD classes. To access vector components, these classes provide axis specific get and set methods such as getX(x,y,d) and setX(x,y,d, val). Since the dimensionality is fixed for vector fields, a dim value cannot be included when instantiating a field. For example:
unsigned int szX = 100;
unsigned int szY = 50;
float spX = 0.1;
float spY = 0.2;
float spFct = 0.01;
VectorField2D* fld = new VectorField2D(szX, szY, spX, spY, spFct);
When using VectorFieldXD objects in conjunction with VectorImageXD objects, it is important that the fields use the same spacings and space factor as the images.
Generated on Thu May 20 11:56:42 2010 for Fluid Registration and Atlas Toolkit (FRAT) by
1.4.7