FRAT/Library

From KitwarePublic
Jump to navigationJump to search

__NOTITLE__


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


Home




For Users




For Developers




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

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
  • VectorImage3DUtils
  • VectorField2DUtils
  • VectorField3DUtils
  • TimeSeries2DUtils
  • TimeSeries3DUtils
  • LDDMMUtils
  • ApplicationUtils