BART documentation¶
Contents:
Introduction¶
Overview¶
BART is a free and open-source image-reconstruction framework for Computational Magnetic Resonance Imaging. It consists of a programming library and a toolbox of command-line programs.
This documentation is meant to be a guide for BART usage and development. Since this is hand-written rather than machine generated, some code snippets might be outdated by the time you read them. However, the general idea should remain the same.
If you have any questions about the implementation details or find errors in this documentation, please send them to our mailing list https://lists.eecs.berkeley.edu/sympa/info/mrirecon.
List of Features¶
- Basic features
- support for Linux, Mac OS X, and Windows (with Cygwin)
- multi-dimensional operations on arrays
- fast non-uniform Fourier Transform (nuFFT)
- multi-dimensional (divergence-free) wavelet transform
- parallel computation on multiple cores and with Graphical Processing Units (GPU)
- Iterative methods
- Conjugate Gradients (CG)
- (Fast) Iterative Soft-Thresholding Algorithm (ISTA and FISTA)
- Alternating Direction Method of Multipliers (ADMM)
- Iteratively Regularized Gauss-Newton Method (IRGNM)
- Calibration methods for parallel MRI
- direct calibration from k-space center
- Walsh’s method
- ESPIRiT
- Reconstruction methods for MRI
- iterative parallel imaging reconstruction: POCSENSE, SENSE
- compressed sensing and parallel imaging
- non-linear inverse reconstruction: NLINV (blind multi-channel deconvolution)
- calibration-less parallel imaging: SAKE (structured low-rank matrix completion)
- Regularization (in arbitrary dimensions)
- Tikhonov
- total variation
- l1-wavelet
- (multi-scale) low-rank
Resources for BART¶
There are many resources for getting started with BART.
For tutorial-style code demos, please visit the github repository:
The material was presented at the 2016 ISMRM Workshop on Data Sampling & Image Reconstruction as a software demo.
Examples of using BART in MATLAB is available at:
Please direct all questions or comments to our public mailing list:
Note: This list has a public archive! Please do not send any confidential information.
Updates and further information can be found here:
License¶
The tools in BART implement various reconstruction algorithms for Magnetic Resonance Imaging. The software is intended for research use only and NOT FOR DIAGNOSTIC USE. It comes without any warranty (see LICENSE for details).
Please cite the corresponding articles when using these tools. Some references can be found at the end of this file. The source code might provide more detailed references, e.g. for specific iterative algorithms.
Installation¶
Prerequisites¶
BART requires the GCC compiler, the FFTW library, the BLAS/LAPACK library and optionally CUDA for NVIDIA GPU computing. (see Optional: Turn on GPU acceleration)
The software can be used in combination with Matlab, python or octave.
There is limited support for reading Cartesian data encoded with the ISMRM Raw Data format when linking with the ISMRMRD library (version 0.5.2) (http://ismrmrd.sourceforge.net/).
In the following, the symbol $
indicates a shell prompt.
Please do not type $
when entering commands.
Linux¶
BART should run on any recent Linux distribution.
To install the required libraries on Debian and Ubuntu run:
$ sudo apt-get install gcc make libfftw3-dev liblapacke-dev
Mac OS X¶
Xcode command line tools are required and can be installed by running:
$ xcode-select --install
Mac installation with Macports¶
Follow the instruction at https://www.macports.org/install.php to install Macports.
To install the required libraries, run:
$ sudo port install fftw-3-single gcc6 openblas
Mac installation with Homebrew¶
To install Homebrew (http://brew.sh), run:
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
To install BART, run
$ brew install homebrew/science/bart
Windows¶
You can use BART on Windows using Cygwin:
Install Cygwin and select the following packages:
Devel: gcc, make
Math: fftw3, fftw3-doc, libfftw3-devel, libfftw3_3
Math: liblapack-devel, liblapack-doc, liblapack0
Then use the cygwin shell to compile BART as described below.
An alternative to using Cygwin is a virtual machine with Linux.
Download and Compilation¶
If you are a git user, you can simply clone our public repository:
$ git clone https://github.com/mrirecon/bart
Otherwise, please download the latest version as a zip file from Github:
and unpack it somewhere on your computer.
Open a terminal window and enter the bart directory (the top-level directory with the Makefile in it). To build the reconstruction tools type:
$ make
If you have installed the ISMRMRD library version 0.5.2, you can also build the ISMRM raw data import tool:
$ make ismrmrd
Data Format¶
BART’s data format consists of a pair of files: one header file (.hdr) and one raw complex float data file (.cfl).
The header file (.hdr) is a simple text readable file that describes the dimensions of the data. Any line that starts with # is regarded as comments. For example, a valid data header for a 192-by-128 dataset is:
# Dimensions
192 128 1 1 1 1
The raw data file (.cfl) is a binary file containing a single contiguous block of array data of dimensions described in the header stored in column-major order (first index is sequential). The raw data file is complex float (32 bit real + 32 bit imaginary, IEEE 747 binary32 little-endian).
MATLAB functions to read and write our data files may be found in the folder matlab (readcfl.m and writecfl.m). Python functions to read and write our data files may be found in folder`python <https://github.com/mrirecon/bart/tree/master/python>`_ (cfl.py).
Cartesian Datasets¶
For Cartesian MRI data and images, the dimensions are usually assigned in the following order:
Dimension Usage 0 readout 1 phase-encoding dimension 1 2 phase-encoding dimension 2 3 receive channels 4 ESPIRiT maps
(more dimensions are defined in src/misc/mri.h)
Undersampled data is stored with zeros in the unsampled positions.
Non-Cartesian Datasets¶
Non-Cartesian datasets are stored in two separate BART datafiles: one kspace coordinates dataset and one non-Cartesian samples dataset . Each datafile consists of a header and a raw data file.
The k-space coordinates for each sample are stored along dimension 0 which must have size equal to three. Dimension 1 stores the samples along a single readout windows while dimension 2 may be used to differentiate between different lines (e.g. radial spokes). Channel (3) and map (4) dimensions must not be used (i.e. have size one), while other dimensions can be used as for Cartesian data.
The first five dimensions for the kspace coordinates are usually assigned in the following order:
Dimension Usage 0 number of dimension (set to 3) 1 readout dimension 2 number of TRs 3 not used (set to 1) 4 not used (set to 1)
The unit of measurement for kspace trajectory is 1/FOV. For example, a valid kspace trajectory for a 192-by-128 image should be scaled such that the x-coordinates cover the range of -192/2 to 192/2 and y-coordinates cover the range of -128/2 to 128/2.
Non-Cartesian samples are stored in a similar way as trajectories except that dimension 0 is not used (i.e. has size one). The channel dimension can be used for different receiver coils as usual.
The first five dimensions for the kspace samples are usually assigned in the following order:
Dimension Usage 0 not used (set to 1) 1 readout dimension 2 number of TRs 3 number of coils 4 not used (set to 1)
Tool Interfaces¶
BART tools can be access through multiple interfaces: command-line, Matlab, and Python. All interfaces accept the same arguments.
Command-line¶
Matlab¶
Python¶
Tools¶
This section focuses on a few main reconstruction tools in BART and details their usage and design.
ecalib¶
The ecalib tool estimates coil sensitivies using the ESPIRiT calibration method. It takes a Cartesian kspace data with fully-sampled calibration region as input and outputs ESPIRiT sensitivity maps with the same image dimensions as the input kspace. ecalib usage can be as simple as follows:
bart ecalib kspace sensitivity
The calibration region does not have to be centered in the kspace array. ecalib estimates the center of kspace by looking at the maximum kspace amplitude and extracts the surrounding region as the calibration region.
Non-Cartesian kspace data must first be gridded onto a Cartesian grid and passed to ecalib. For details about gridding, please see the nufft section.
pics¶
The pics tool performs general parallel imaging and compressed sensing reconstruction. For Cartesian imaging, it takes kspace data and sensitivity maps as inputs and outputs an image dataset. By default, pics performs a SENSE reconstruction using conjugate gradient and can be used as simple as:
bart pics kspace sensitivity image
For non-Cartesian imaging, the trajectory file must be supplied with the flag -t
. For example:
bart pics -t trajectory kspace sensitivity image
nufft¶
The nufft tool performs non-uniform fast Fourier transform operations.
Viewers¶
There are multiple ways of viewing BART datasets and images. If you are using the Matlab interface, A Matlab-based image viewer which works well with BART is arrayShow by Tilman Sumpf.
If you have Python installed, you can view BART datasets using the bartview.py script in the folder python to view the images. The simplest way to use it is to install python through Anaconda. To use the script to view a dataset img (with files img.cfl and img.hdr), type the following in the command line:
$ python bartview.py img
Developer API¶
This section describes the API available for reconstruction researchers to develop their custom reconstruction methods. The three main abstractions are:
Iterative Algorithms¶
Implementation of the operators is separated from the implementation of the iterative algorithm itself and passed as a function pointer. A similar stategy called supermarionation has been described in Murphy et al.
iter interfaces¶
There are three iter interfaces that allow simplified access of the algorithms: iter, iter2, and iter3. The iter interfaces use the linop interface and operator_p interface.
The iter interface considers the problem \(\min_x \frac{1}{2} \| Ax - y \|_2^2 + g(x)\). It requires \(A^\top A\), \(A^\top y\), and \(\text{prox}_g\) as inputs and outputs x. The iter interface supports cg, ist, fista and admm. \(\text{prox}_g\) has to be NULL for cg.
The iter2 interface considers the problem \(\min_x \frac{1}{2} \| Ax - y \|_2^2 + \sum_i f_i (G_i x)\). It requires \(A^\top A\), \(A^\top y\), \(\text{prox}_{f_i}\), and \(G_i\) linops as inputs and outputs x. The iter2 interface supports cg, ist, fista and admm. \(\text{prox}_{f_i}\) has to be NULL for cg. For ist and fista, the number of \(\text{prox}_{f_i}\) has to be one.
The iter3 interface contains the rest of the algorithms without a unifying interface.
cg¶
cg implements the conjugate gradient method. It solves for:
Parameters:
Regularization \(\lambda\) and number of iterations
Input:
\(A^\top A\), and \(A^\top y\)
Ouput:
\(x\)
Iteration steps:
ist¶
ist implements the iterative soft threshold method, also known as the proximal gradient method. It solves for:
where \(g(x)\) is simple, that is the proximal of g(x) can be computed easily.
Parameters:
Step-size \(\tau\) and number of iterations
Input:
\(A^\top A\), \(A^\top y\), and \(\text{prox}_g\)
Ouput:
\(x\)
Iteration steps:
fista¶
fista implements the fast iterative soft threshold method, also known as the accelerated proximal gradient method. It solves for:
where \(g(x)\) is simple, that is the proximal of g(x) can be computed easily.
Parameters:
Step-size \(\tau\) and number of iterations
Input:
\(A^\top A\), \(A^\top y\), and \(\text{prox}_g\)
Ouput:
\(x\)
Iteration steps:
admm¶
admm implements the alternating direction method of multipliers. It solves for:
where \(f_i\) s are simple, that is the proximal of each f_i can be computed easily.
Parameters:
Convergence parameter \(\rho\), and number of iterations
Input:
\(A^\top A\), \(A^\top y\), \(\text{prox}_{f_i}\), \(G_i\), \(G_i^\top\), \(G_i^\top G_i\), and \(b_i\)
Ouput:
\(x\)
Iteration steps:
Linear Operators¶
linop interface¶
The linop interface provides an abstraction for linear operators. For each linop \(A\), it supports forward operation \(x \rightarrow A(x)\), adjoint operation \(x \rightarrow A^\top(x)\) and normal operation \(x \rightarrow A^\top A(x)\).
linop_chain¶
The linop_chain function is arguably the most powerful feature of the linop interface. Given two linops \(A\) and \(B\), the composite linear operator \(A(B)\) can be created by doing:
AB = linop_chain(A, B)
This automatically chains the forward operation, adjoint operation, and normal operation.
fft¶
fft implements the fast Fourier transform using the FFTW library for CPU and cudaFFT for GPU.
nufft¶
sense¶
wavelet¶
finite_diff¶
Software Implementation¶
Memory-mapped Input/Output¶
Input and output is performed using memory-mapped files. This allows efficient access to small parts of a large file, e.g. a slice of a 3D data set.
The use of memory-mapped input/output allows simple processing of extremely large data sets. While all data can be accessed simply, either directly with points or using the functions of the library, only the parts of the data which are actually accessed are loaded into memory.
It is also possible to access data during long-running computations or debugging stops.
Multi-Dimensional Arrays¶
Multi-dimensional arrays are part of almost every framework for image reconstruction. A set of functions is provided for basic addressing/indexing, mathematical operations, and some transforms. It offers simple but powerful interfaces for many operations on multi-dimensional arrays, e.g. to access slices of an array or to apply an FFT along selected dimensions.
GPU Acceleration¶
Most operations can be transparently accelerated using GPUs. Data can be allocated on the GPU using:
The generic copy function md_copy
can be used to copy data
from on to the GPU. Basic operations, FFT, ... are
implemented for the CPU and GPU. The library keeps track
of all allocated memory regions and automatically
uses the right function.
Unit Tests¶
Procedures to add unit tests for particular file:
- add test under bart/src/utests
- include “utest.h” in testfile
- add “UTARGET += test_file” under the appropriate rule files under “bart/src/rules”
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line