FRAT/Library

__NOTITLE__

(F)luid (R)egistration and (A)tlas (T)oolkit

Home Image Gallery Data and Publications For Users Installation Guide FRAT with Slicer For Developers libFRAT API Documentation Development Docs Contact Us

FRAT as a Library In addition to command line executables, FRAT provides a C++ library that can be used in external projects. Since FRAT is currently only available as source code, you must first follow the instructions in the Installation Guide to build FRAT. Using libFRAT in an External Project Once built, the steps for using FRAT in your own CMake project are: In your CMakeLists.txt file, find the FRAT project find_package(FRAT REQUIRED) if(FRAT_FOUND) include(${FRAT_USE_FILE}) else(FRAT_FOUND) message(FATAL_ERROR "FRAT not found. Please set FRAT_DIR.") endif(FRAT_FOUND) When building an executable or library that uses FRAT, make sure to link against the libraries in ${FRAT_LIBRARIES} add_library(bar bar.cxx) target_link_libraries(bar ${FRAT_LIBRARIES}) add_executable(foo foo.cxx) target_link_libraries(foo bar ${FRAT_LIBRARIES}) There is currently no installation system for FRAT, so you will most likely need to manually specify FRAT_DIR when configuring your project with CMake Basic Concepts in FRAT This section outlines some of the basics of the FRAT project so you can learn how to use libFRAT in your own project. Data Structures 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. VectorImageXD 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. To offer full compatibility with ITK images, FRAT images also carry a world coordinate origin and an direction matrix. These pieces of meta-data are used only to ensure that origin and direction are preserved between reading and writing. NOTE: All of the registration operations in FRAT assume that the images being registered are affinely pre-registered and thus have the same origin and direction. VectorFieldXD 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. VectorImageTimeSeriesXD The VectorImageTimeSeriesXD data structures act as container classes for the data computed during time series registration. Additionally, they provide functionality to use the computed velocity field to interpolate an image or displacement map at any time-point along the series trajectory. The important members of the data structure are: VSeries: The series of velocity fields between each known image in the time series ISet: The set of known images for the time series MapSet: The set of displacement maps used to initialize the transformations for each known image timeSet: The set of times associated with ISet and MapSet IPathSet: The paths to each of the known images. This is used when saving a time series object so that the images can be re-read later AlgParams: The parameters used to compute the time series Utility Functions FRAT has a collection of utility classes that contain static functions for operating on the data structures. These classes are divided based on the data structure they cater to. Additionally, a set of more advanced algorithmic parameters is provided in LDDMMUtils and a set of utilities for writing applications is provided in ApplicationUtils. The utility classes are: VectorImage2DUtils and VectorImage3DUtils: Basic utilities, including IO, for the VectorImageXD data structures VectorField2DUtils and VectorField3DUtils: Utilities specific to the displacement field nature of the VectorFieldXD data structures. Use VectorImageXDUtils for IO. TimeSeries2DUtils and TimeSeries3DUtils: IO utilities for the VectorImageTimeSeriesXD data structures. LDDMMUtils: Subroutines for LDDMM registration. ApplicationUtils: Front-end utilities such as string parsing and path verification for writing executables Algorithims FRAT implements a set of algorithms based on LDDMM registration. The lowest-level algorithms are: FlowAdvectionSemiLagrangian: Flow a volume using a provided velocity field. This implements a discrete solution to the advection equation and is a core component in the LDDMM registration algorithm. FlowScalarConsrvation: Flow a volume using a provided velocity field while conserving overall volume intensity. This implements a discrete solution to the scalar conservation equation and is a core component in the LDDMM registration algorithm. The higher-level algorithms are used to perform various registration tasks. Each algorithm is implemented first with a single-scale system and then augmented with a multiscale wrapper. These algorithms are: LDDMMAdjoint: Fluid registration from a source image to a target image AtlasBuilder: Cross-sectional atlas construction for a set of images TimeSeries: Fluid registration between a series of N time-point images GeometricMetamorphosis: Fluid registration between images with structural differences Finally, the LongitudinalAtlasBuilder algorithm uses TimeSeries and AtlasBuilder internally to create an average growth model for a longitudinal population of subjects.