README 11.7 KB
Newer Older
Martin Uecker's avatar
Martin Uecker committed
1

Martin Uecker's avatar
Martin Uecker committed
2 3 4
0. License
==========

Martin Uecker's avatar
Martin Uecker committed
5 6 7 8 9
See LICENSE file for licensing information.

-------------------------------------------------------------------------------


10 11 12 13 14 15
The tools in this software 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.
Martin Uecker's avatar
Martin Uecker committed
16 17 18 19
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.


Martin Uecker's avatar
Martin Uecker committed
20 21

1. Help
Martin Uecker's avatar
Martin Uecker committed
22
=======
Martin Uecker's avatar
Martin Uecker committed
23

24 25 26 27 28 29 30 31 32 33 34 35 36 37
Please direct all questions or comments to the public mailing list:

	mrirecon@lists.eecs.berkeley.edu

	https://lists.eecs.berkeley.edu/sympa/info/mrirecon


Note: This list has a public archive! Please do not send
any confidential information.



Updates and further information can be found here:

Martin Uecker's avatar
Martin Uecker committed
38
	http://mrirecon.github.io/bart/
Martin Uecker's avatar
Martin Uecker committed
39 40 41 42




Martin Uecker's avatar
Martin Uecker committed
43
2. Installation
Martin Uecker's avatar
Martin Uecker committed
44
===============
Martin Uecker's avatar
Martin Uecker committed
45

Martin Uecker's avatar
Martin Uecker committed
46
2.1. Prerequisites
47
------------------
Martin Uecker's avatar
Martin Uecker committed
48

Martin Uecker's avatar
Martin Uecker committed
49 50
GCC compiler, the FFTW library, and optionally CUDA.
(see recon/Makefile to turn options on or off)
Martin Uecker's avatar
Martin Uecker committed
51

52 53 54
The minimum GCC supported is 5.0. It should also be possible
to use the clang compiler, but older version before version
4.0 are known to cause problems.
Martin Uecker's avatar
Martin Uecker committed
55

Martin Uecker's avatar
Martin Uecker committed
56 57 58
The software can be used in combination with Matlab or octave.


59 60
There is limited support for reading Cartesian data encoded with
the ISMRM Raw Data format when linking with the ISMRMRD library
61
(http://ismrmrd.sourceforge.net/).
62 63


Martin Uecker's avatar
Martin Uecker committed
64 65
In the following, the symbol '`$`' indicates a shell prompt.
Do not type '`$`' when entering commands.
Martin Uecker's avatar
Martin Uecker committed
66

Martin Uecker's avatar
Martin Uecker committed
67

Martin Uecker's avatar
Martin Uecker committed
68

Martin Uecker's avatar
Martin Uecker committed
69
### 2.1.1. Linux
Martin Uecker's avatar
Martin Uecker committed
70 71 72 73 74

The software tools in recon should run on any recent Linux distribution.

To install the required libraries on Debian and Ubuntu run:

75
    $ sudo apt-get install gcc make libfftw3-dev liblapacke-dev libpng-dev libopenblas-dev gfortran
Martin Uecker's avatar
Martin Uecker committed
76

77 78
    (optional)
    $ sudo apt-get install octave
Martin Uecker's avatar
Martin Uecker committed
79

80 81
    (optional)
    install version 0.5.2 of the ISMRMRD library
Martin Uecker's avatar
Martin Uecker committed
82 83 84



Martin Uecker's avatar
Martin Uecker committed
85
### 2.1.2. Mac OS X
Martin Uecker's avatar
Martin Uecker committed
86 87

Xcode is required and it is recommended to install a newer version 
Martin Uecker's avatar
Martin Uecker committed
88
of gcc from MacPorts (http://www.macports.org/).
Martin Uecker's avatar
Martin Uecker committed
89 90


91
    $ sudo port install fftw-3-single
Martin Uecker's avatar
Martin Uecker committed
92
    $ sudo port install gcc6
93
    $ sudo port install libpng
94
    $ sudo port install openblas
Martin Uecker's avatar
Martin Uecker committed
95

96 97
    (optional)
    $ sudo port install octave
Martin Uecker's avatar
Martin Uecker committed
98

99 100
    (optional)
    install version 0.5.2 of the ISMRMRD library
Martin Uecker's avatar
Martin Uecker committed
101 102 103



Martin Uecker's avatar
Martin Uecker committed
104
### 2.1.3. Windows
105

Martin Uecker's avatar
Martin Uecker committed
106 107 108 109 110
Note that Windows is currently not supported. Nevertheless, many people
use BART on Windows. If you have trouble to get it to work, you may
want to try an older version (e.g. version 4.00).


111
The recommended way to use BART on Windows is with the Windows Subsystem for
Martin Uecker's avatar
Martin Uecker committed
112
Linux (WSL) which is available for Windows 10. If you use WSL, you need to
113
either use the clang compiler or gcc with the NOEXEC_STACK option.
114 115


Martin Uecker's avatar
Martin Uecker committed
116
BART should also work with Cygwin:
117 118 119

https://www.cygwin.com/

Martin Uecker's avatar
Martin Uecker committed
120 121
Install Cygwin and select the following packages:

122 123 124
    Devel: gcc, make
    Math: fftw3, fftw3-doc, libfftw3-devel, libfftw3_3
    Math: liblapack-devel, liblapack-doc, liblapack0
Martin Uecker's avatar
Martin Uecker committed
125
    Libs: libpng, libpng-devel
Martin Uecker's avatar
Martin Uecker committed
126 127 128 129 130


Then use the cygwin shell to compile BART as described below.


Martin Uecker's avatar
Martin Uecker committed
131 132
An alternative to using the Windows Subsystem for Linux or Cygwin
is a virtual machine with Linux installed.
133 134


Martin Uecker's avatar
Martin Uecker committed
135

Martin Uecker's avatar
Martin Uecker committed
136
2.2. Downloading and Compilation
137
--------------------------------
Martin Uecker's avatar
Martin Uecker committed
138 139 140

If you are a git user, you can simply clone our public repository:

141
    $ git clone https://github.com/mrirecon/bart
Martin Uecker's avatar
Martin Uecker committed
142 143 144 145 146


Otherwise, please download the latest version as a zip file
from Github:

Martin Uecker's avatar
Martin Uecker committed
147
	http://github.com/mrirecon/bart/releases/latest
Martin Uecker's avatar
Martin Uecker committed
148 149 150 151 152 153 154 155

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:

156
    $ make
Martin Uecker's avatar
Martin Uecker committed
157 158 159



160
If you have installed the ISMRMRD library version 0.5.2, you can also
Martin Uecker's avatar
Martin Uecker committed
161 162
build the ISMRM raw data import tool:

163
    $ make ismrmrd
Martin Uecker's avatar
Martin Uecker committed
164 165 166 167 168 169 170 171 172








2.3. Getting Started
173
--------------------
Martin Uecker's avatar
Martin Uecker committed
174

Martin Uecker's avatar
Martin Uecker committed
175
### 2.3.1. Organization
Martin Uecker's avatar
Martin Uecker committed
176 177


178 179
    .           main directory / built software tools
    Makefile    Makefile
180 181 182 183 184 185
    matlab/	Matlab helper scripts
    python/	Python helper functions
    doc/	documentation
    rules/	more built-related files
    scripts/	various helper scripts and examples
    src/	source code
186 187 188 189
    src/calib 	source code for sensitivity calibration
    src/sense	source code for SENSE or ESPIRiT reconstruction
    src/noir	source code for nonlinear inversion
    src/sake	source code for SAKE reconstruction
190 191
    src/wavelet	source code for wavelets
    src/num	base library with numerical functions
192 193
    src/iter	iterative algorithms
    src/linops	library of linear operators
194
    src/nlops   library of nonlinear operators
195 196
    src/misc	miscellaneous (e.g. I/O)
    src/ismrm	support for ISMRM raw data format
197 198 199 200 201
    src/simu	source code for simulation
    src/noncart	source code for non-uniform FFT
    tests/	system tests
    utests/	unit tests
    lib/	built software libraries
Martin Uecker's avatar
Martin Uecker committed
202 203 204 205




Martin Uecker's avatar
Martin Uecker committed
206
### 2.3.2. Terminal
Martin Uecker's avatar
Martin Uecker committed
207

Martin Uecker's avatar
Martin Uecker committed
208
When using the toolbox commands from a UNIX shell, it is recommended
Martin Uecker's avatar
Martin Uecker committed
209
to set the TOOLBOX_PATH to the base directory and to add it to
Martin Uecker's avatar
Martin Uecker committed
210
the PATH variable. You can do this by running the following command:
Martin Uecker's avatar
Martin Uecker committed
211

212
    $ . startup.sh
Martin Uecker's avatar
Martin Uecker committed
213

Martin Uecker's avatar
Martin Uecker committed
214 215
Note: The dot or 'source' command is needed so that the variables
are imported into the current shell.
Martin Uecker's avatar
Martin Uecker committed
216 217


Martin Uecker's avatar
Martin Uecker committed
218
### 2.3.3. Matlab
Martin Uecker's avatar
Martin Uecker committed
219

Martin Uecker's avatar
Martin Uecker committed
220
You can set the TOOLBOX_PATH to the base directory and to add it
Martin Uecker's avatar
Martin Uecker committed
221 222
to the Matlab path by running the following command in the
bart directory:
Martin Uecker's avatar
Martin Uecker committed
223

224
    >> startup
Martin Uecker's avatar
Martin Uecker committed
225

Martin Uecker's avatar
Martin Uecker committed
226 227
(Note: The '>>' indicates the shell prompt. Do not type '>>'
when entering commands.)
Martin Uecker's avatar
Martin Uecker committed
228 229 230



Martin Uecker's avatar
Martin Uecker committed
231 232
You can use Matlab to read and visualize/process files. To write
a data file 'xyz' from Matlab you can run:
Martin Uecker's avatar
Martin Uecker committed
233

234
    >> writecfl('xyz', A);
Martin Uecker's avatar
Martin Uecker committed
235 236


Martin Uecker's avatar
Martin Uecker committed
237 238
Note, that the name 'xyz' is used without filename extension.
See below for more information about the file format used in BART.
Martin Uecker's avatar
Martin Uecker committed
239

Martin Uecker's avatar
Martin Uecker committed
240
To read the data file 'xyz' back into Matlab use:
Martin Uecker's avatar
Martin Uecker committed
241

242
    >> A = readcfl('xyz');
Martin Uecker's avatar
Martin Uecker committed
243 244


Martin Uecker's avatar
Martin Uecker committed
245 246
To call a BART tool (e.g. ecalib) from Matlab, you can use the
'bart' command:
Martin Uecker's avatar
Martin Uecker committed
247

248
    >> sensitivities = bart('ecalib', kspace);
Martin Uecker's avatar
Martin Uecker committed
249 250 251



252
Download and unpack the examples which demonstrate interoperability
Martin Uecker's avatar
Martin Uecker committed
253
with Matlab. Go to the examples directory and run:
Martin Uecker's avatar
Martin Uecker committed
254

255
    >> examples
Martin Uecker's avatar
Martin Uecker committed
256 257


Martin Uecker's avatar
Martin Uecker committed
258
### 2.3.4. Python
Martin Uecker's avatar
Martin Uecker committed
259

260 261
You can set the TOOLBOX_PATH to the base directory and start a
Python interactively as follows:
Martin Uecker's avatar
Martin Uecker committed
262

263
    $ python -i startup.py
Martin Uecker's avatar
Martin Uecker committed
264

265 266 267 268 269 270 271 272 273 274 275
To avoid doing the above everytime, it is recommended to update your
PYTHONPATH environment. For example, in Linux, assuming your 
TOOLBOX_PATH is set, add the below line to your bashrc file.

    $ export PYTHONPATH="${TOOLBOX_PATH}/python:$PYTHONPATH"

After doing so, we can simply import as needed.

    >>> from bart import bart
    >>> import cfl

276 277 278 279 280 281 282 283
You can use Python to read and visualize/process files. To write
a data file 'xyz' from Python you can run:

    >>> cfl.writecfl('xyz', A);

Note, that the name 'xyz' is used without filename extension.
See below for more information about the file format used in BART.

Martin Uecker's avatar
Martin Uecker committed
284
To read the data file 'xyz' back into Python use:
285 286 287 288 289 290 291 292 293 294

    >>> A = cfl.readcfl('xyz');

To call a BART tool (e.g. ecalib) from Python, you can use the
'bart' command:

    >>> sensitivities = bart(1, 'ecalib', kspace);

The bart function expects the following signature:

Martin Uecker's avatar
Martin Uecker committed
295 296 297
    >>> <outputs> = bart(<nargout>, <command>, <arguments>, ...)

To use BART in a script, please follow the steps in the
298
startup.py file.
Martin Uecker's avatar
Martin Uecker committed
299

Martin Uecker's avatar
Martin Uecker committed
300 301

3. Data Format
Martin Uecker's avatar
Martin Uecker committed
302
==============
Martin Uecker's avatar
Martin Uecker committed
303

Martin Uecker's avatar
Martin Uecker committed
304
3.1. Generic
305
------------
Martin Uecker's avatar
Martin Uecker committed
306

Martin Uecker's avatar
Martin Uecker committed
307 308 309 310 311 312 313 314 315
The input and output datasets are each stored in a pair of files: one
header (*.hdr) and one raw data (*.cfl). The header is a simple text
readable file that describes the dimensions of the data. The raw data
file 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).

Convenience methods to read and write our data files using Matlab may
Jon Tamir's avatar
Jon Tamir committed
316 317
be found in the matlab/ directory (readcfl.m and writecfl.m). Similar
methods for Python may be found in the python/ directory (cfl.py).
Martin Uecker's avatar
Martin Uecker committed
318 319 320



Martin Uecker's avatar
Martin Uecker committed
321
3.2. Magnetic Resonance Imaging Data
322
------------------------------------
Martin Uecker's avatar
Martin Uecker committed
323 324 325 326

For MRI data and images, the dimensions are usually assigned in
the following order:

327 328 329 330 331 332 333
    0 readout
    1 phase-encoding dimension 1
    2 phase-encoding dimension 2
    3 receive channels
    4 ESPIRiT maps
    ...
    ...
Martin Uecker's avatar
Martin Uecker committed
334

335
    (more dimensions are defined in src/misc/mri.h)
Martin Uecker's avatar
Martin Uecker committed
336 337


Jon Tamir's avatar
Jon Tamir committed
338
Undersampled data is stored with zeros in the unsampled
Martin Uecker's avatar
Martin Uecker committed
339 340 341 342 343
positions.



3.3. Non-Cartesian Trajectories and Samples
344
-------------------------------------------
Martin Uecker's avatar
Martin Uecker committed
345 346 347 348 349 350 351 352 353 354 355 356 357

The k-space coordinates for each sample are stored along dimension 0
which must have size equal to three. The unit of measurement is 1/FOV.
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. Non-Cartesian samples are stored in a similar
way as trajectories except that dimension 0 is not used. The channel
dimension can be used for different receiver coils as usual.



Martin Uecker's avatar
Martin Uecker committed
358

Martin Uecker's avatar
Martin Uecker committed
359
4. Command-line Tools
Martin Uecker's avatar
Martin Uecker committed
360
=====================
Martin Uecker's avatar
Martin Uecker committed
361 362 363 364 365 366

All tools operate on the simple file format given above. Indices and
dimensions run from 0 to N-1. Sometimes a set of dimensions is given
as a bitmask where the lowest bit corresponds to the 0st dimension.


367
For example, an inverse Fourier transform of first three dimensions can
368
be performed with the following command:
Martin Uecker's avatar
Martin Uecker committed
369 370


Martin Uecker's avatar
Martin Uecker committed
371
    $ bart fft -i 7 kspace volume
Martin Uecker's avatar
Martin Uecker committed
372 373


374
More information about each command can be found in 'doc/commands.txt'.
Martin Uecker's avatar
Martin Uecker committed
375 376 377



378 379
5. Information for Contributors
===============================
Martin Uecker's avatar
Martin Uecker committed
380

381 382 383 384 385 386 387 388
Thank you for helping to improve BART! In order for us to be able
to accept your contribution, it has to be released under the BSD
license used by BART (see LICENSE file). By submitting patches to
us it is understood that you agree to these terms and that you
confirm that you hold all necessary rights yourself or have
permission from the copyright holder. Please also add the name of
the copyright holder and name and email of the author(s) to the
copyright headers in all new or changed files.
Martin Uecker's avatar
Martin Uecker committed
389

390 391


392 393
6. Troubleshooting
==================
394

395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437
6.1. Installation Problems
--------------------------

When problems occur after updating BART or changing build
variables, it may help to clean the build environment and
to recompile BART:

    $ make allclean
    $ make


Make sure the PATH and TOOLBOX_PATH environment variables
are set correctly. Sometimes, several versions of BART
are installed and the wrong version is used accidentally.


6.2. Reporting Problems
-----------------------

Please report problems to our mailing list and include
the following information (as applicable):

* The output of the 'version' command:

    $ bart version -V

* The exact BART command-line that caused the problem.

* The specific error message.

* Information about the data files used when the problem occured
  (please provide atleast the dimensions of all input files).



6.3. Debugging
--------------

See 'doc/debugging.txt' for details.



7. References
Martin Uecker's avatar
Martin Uecker committed
438
=============
Martin Uecker's avatar
Martin Uecker committed
439

Martin Uecker's avatar
Martin Uecker committed
440 441 442 443
* Tamir JI, Ong F, Cheng JY, Uecker M, Lustig M,
  Generalized Magnetic Resonance Image Reconstruction using
  The Berkeley Advanced Reconstruction Toolbox, ISMRM Workshop
  on Data Sampling and Image Reconstruction, Sedona 2016
Martin Uecker's avatar
Martin Uecker committed
444

Martin Uecker's avatar
Martin Uecker committed
445
* Uecker M, Ong F, Tamir JI, Bahri D, Virtue P, Cheng JY, Zhang T, Lustig M,
446 447
  Berkeley Advanced Reconstruction Toolbox, Annual Meeting ISMRM, Toronto 2015
  In: Proc Intl Soc Mag Reson Med 23:2486
Martin Uecker's avatar
Martin Uecker committed
448

449 450 451 452
* Uecker M, Virtue P, Ong F, Murphy MJ, Alley MT, Vasanawala SS, Lustig M,
  Software Toolbox and Programming Library for Compressed Sensing and
  Parallel Imaging, ISMRM Workshop on Data Sampling and Image
  Reconstruction, Sedona 2013
453 454


Martin Uecker's avatar
Martin Uecker committed
455 456
References related to implemented methods and algorithms can be
found in the file 'doc/references.txt'.
Martin Uecker's avatar
Martin Uecker committed
457 458