ncigt-fil
|
The goal of this guide is to get a new user of the Fast Imaging Library (FIL) up and running as quickly as possible, using provided demo programs.
Currently [release 2.0], the library is available on Linux (both 64-bit and 32-bit), Windows (MSWin64), and Mac OS X (darwin-intel).
The library provides a binary file for the processing functions, with MEX files to call the functions from Matlab. Thus, a C compiler is required. The library has been tested with gcc
on Linux and Mac OS X, and MS Visual Studio 2008 on Windows.
First, extract the library into a working directory. Below, we will refer to this directory as the [igt_fil_basepath]
. This should create a directory tree that includes ./demos
, ./include
, ./lib
, and ./source_code/matlab
paths.
MEX files are C programs that are callable from Matlab. The FIL distribution contains a number of examples in the source_code/matlab/mex
directory. To set up MEX file use, do the following:
[igt_fil_basepath]/source_code/matlab/mex
buildall.m
Examples of how to use the MEX functions are located in [igt_fil_basepath]/demos/mex_demo/
After a cd
to this directory, be certain to add both the matlab script and the path MEX paths to the matlab path:
The remaining portion of this section presents each the MEX demos in turn.
all of the MEX demos use the same raw data. This can be read into Matlab via readnd
This should provide 8-channels of k-space data for a resolution phantom (acquired at 1.5T using a fast spin echo sequence).
The file util_demo.m
provides a simple example on how to zero-pad an accelerated k-space data set. First, a sampling pattern is generated. The input sampling pattern is structured with each row containing a ky-z
coordinate location. Since there is only one slice here, all of the z
coordiantes are the same. ky
is subsampled by 2, capturing all 'odd' lines.
This sampling pattern is then passed to the kstretch function via
ko
should now be a zero-padded version of the subsampled k
data. This can be visualized using the following Matlab command:
The library includes functions to perform homodyne detection/syncronization for partial-Fourier data sets (as per Noll, Nishimura, and Macovski. IEEE Trans Medical Imaging. 10(2):154-163, 1991). The MEX file correct_pF
performs this process by calling the partial_Fourier :
The 3rd argument of the MEX function can be used to switch between a (0) step filter or a (1) ramp filter. The step filter carries better SNR, while the ramp filter is more tolerant of k-space that is off-center.
Three parallel imaging algorithms are included in the library: SENSE, GRAPPA, and SPACE RIP (see Parallel Imaging Algorithms for more details). This demo demonstrates each of them on the same data set. First, the data is loaded and a subsampling pattern is generated.
Next, coil sensitivity maps are generated from the subsampled data set:
Finally, images are formed from the subsampled data using various reconstruction algorithms.
SPACE RIP, using the LSQR-Hybrid algorithm to perform automatic regularization.
GRAPPA
Ig2
here is the root-sum-of-squares image. If phase needs to be retained, reconstruct the image using coil sensitivity maps instead:
RLS-GRAPPA
This algorithm performs the GRAPPA reconstruction in hybrid-space (ky-x) and employs an RLS adaptive filter to rapidly compute the reconstruction parameters. In certain cases, it is significantly faster than standard GRAPPA.
standard Cartesian SENSE
and Variable Density SENSE
Finally, the results are displayed
UNFOLD employs temporal variations in the sampling pattern to encode aliasing artifacts and then filters the results to suppress the encoded artifacts.
This demo uses a temporal data set
and all processing is done within the MEX file
To keep with standard C convention, all indexing in the library starts at zero. This is particularly important in regards to specifying which phase-encode lines are acquired. So, if in Matlab the phase encode list runs from [ 1 .. M ], the same phase encode list in the library would run from [0 .. (M-1) ]. The MEX functions provided with the library perform this transition automatically to give a transparent interface to Matlab.
Except for certain parallel imaging functions, all of the data is ordered as kx-ky-z-timeframe-coil
The parallel imaging algorithms that do not follow this convention include
which are ordered ky-kx-coil
for historical reasons. In short, if a function call does not include a temporal and/or Z component as an argument, then the data should be short-ordered, with the subsampled ky
data as the first dimension.
Here we describe how the MEX files are structured, using unfold.c
as an example.
The code included in
demonstrates how to edit the value associated with a specific DICOM tag in a file, and write out the new DICOM image file.
This function is designed to convert the FIL .nd output data files into an image viewable on any platform. It uses the PNG and ZLIB libraries to accomplish this. These libraries are standard on Linux and Mac OS X, but may need to be installed on Windows. To build them them on Windows, do the following
C:\src
) nmake -f win32\Makefile.msc
nmake -f lpng/scripts/makefile.vcwin32
Once the libraries are built, modify the Makefile.win32
file in the display directory to point to the location of the ZLIB and LIBPNG library and header files. nd2png
should then build properly.
ImLib is a general image loading and rendering library, designed to simplify the generating drawable in X-Windows systems. It is included by default in many Linux distributions. Source code for ImLib can be found here: ftp://ftp.gnome.org/pub/GNOME/sources/imlib/1.9/
This demo code included in the
directory uses ImLib to load data from a file stored in the ND-data format, and displays the data in a simple viewer.
The display demos use an "X Server" for data display. This is available by default on Linux and Mac. For Windows, a free version is available here: http://xming.sourceforge.net/
Code is also included that links to ImageMagick to display a set of images. This code works on both Linux and Windows. To setup ImageMagick on Windows, either (1) download the latest binary version along with the MSVC 2008 Portability Pack, or (2) download the source and compile. [ImageMagick binarys are currently compiled with MSVC 2008, which uses 'manifests' to manage DLL linking order. VC++ 6 doesn't have this, so programs compiled in VC++ 6 but linked to the ImageMagick DLL's will show an "R6034 error" everytime the program runs.]