ncigt-fil
Quick Start Guide

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.

Prerequisites

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.

Setup

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 file demos

Build the MEX files

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:

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:

addpath <igt_fil_basepath>/source_code/matlab
addpath <igt_fil_basepath>/source_code/matlab/mex

The remaining portion of this section presents each the MEX demos in turn.

Loading the Demo Data

all of the MEX demos use the same raw data. This can be read into Matlab via readnd

k = readnd('phantom.dat');

This should provide 8-channels of k-space data for a resolution phantom (acquired at 1.5T using a fast spin echo sequence).

Zero-pad k-space Demo (util_demo.m)

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.

Yo = [ vec(1:2:256) ones(128,1) ];

This sampling pattern is then passed to the kstretch function via

ko = kstretch( Yo, squeeze(k(:,Yo(:,1),1)), [256 256 1] );

ko should now be a zero-padded version of the subsampled k data. This can be visualized using the following Matlab command:

pltcmplx( k(:,:,1), ko(:,:,1) );

Partial Fourier Demo (pF_demo.m)

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 :

Y = 1:146; % specify the lines to use
k0 = correct_pF( k(:,Y,1), [ 256 256 ], 1 ); % perform the correction
im(k0); % visualize the result

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.

Parallel Imaging Demo (pmri_demo.m)

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.

k = readnd('phantom.dat');
N = 256;
k = k( (size(k,1)-N)/2+(1:N), (size(k,1)-N)/2+(1:N), : );
% form a variable density sampling pattern, 4x-2x-1x, with 3x total
% acceleration (suitable for self-referenced reconstructions)
Z = zeros(N,1);
Z( 2:4:end) = 1;
Z( (N/2) + (-(N/8-2):2:(N/8)) ) = 1;
Z( (N/2) + (-(N/32-2):(N/32)) ) = 1;
Y = find(Z);

Next, coil sensitivity maps are generated from the subsampled data set:

% generate the coil sensitivity maps
W = geyser( k(Y,:,:), Y(:), [N N 8] );

Finally, images are formed from the subsampled data using various reconstruction algorithms.

UNFOLD Demo (unfold_demo.m)

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

a = readnd('zoomed.dat');

and all processing is done within the MEX file

z = unfold(a);
im([ a squeeze(z)]);

Important Details

Indexing

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.

Data Ordering

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

  1. self_ref_b1_via_geyser
  2. grappa
  3. all sprip_ functions, such as sprip_lsqr_recon

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.

Anatomy of a MEX file

Here we describe how the MEX files are structured, using unfold.c as an example.

C test files

DICOM editing demo

The code included in

demos/dicom_demo/

demonstrates how to edit the value associated with a specific DICOM tag in a file, and write out the new DICOM image file.

.nd to .png Demo

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

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.

Demo for simple display, using ImLib

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

./demos/display/

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.]