README

0. License
==========

See LICENSE file for licensing information.

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


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



1. Help
=======

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:

	http://mrirecon.github.io/bart/




2. Installation
===============

2.1. Packages
-------------

The easiest way to install BART on Debian or Ubuntu is to install the
BART package.

    $ sudo apt-get install bart bart-view

You can also try the package built with CUDA support:

    $ sudo apt-get install bart-cuda bart-view


Note, if you need Matlab / Python integration, want to use BART on Mac, Windows, or
other Linux distributions, or if you need a very recent version or BART, you
may need to compile BART yourself. Please see then follow the instructions
below.


The recommended way to use BART on Windows is with the Windows Subsystem for
Linux (WSL2) which is available for Windows 10.

Once you have installed WSL2 you can follow the steps for Linux given above
to install the BART packages, or compile it yourself as described below.


2.2. Prerequisites
------------------

GCC compiler, the FFTW library, and optionally CUDA.
(see recon/Makefile to turn options on or off)

The minimum GCC supported is 11. It should also be possible
to use the clang compiler.

The software can be used in combination with Matlab or octave.


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


In the following, the symbol '`$`' indicates a shell prompt.
Do not type '`$`' when entering commands.

For more build information, check docs/building.txt



### 2.1.1. Linux

The software tools 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 libpng-dev libopenblas-dev gfortran

    (optional)
    $ sudo apt-get install octave

    (optional)
    install version 0.5.2 of the ISMRMRD library


To install the required libraries on Redhat / Centos run:

    $ sudo yum install atlas-devel fftw3-devel libpng-devel lapack-devel

It may be required to install support for software collections (for Centos):

    $ sudo yum install centos-release-scl devtoolset-8

To enable gcc 8 and start a bash shell run:

    $ scl enable devtoolset-8 bash


### 2.1.2. Mac OS X

BART is supported on Intel-based and ARM-based Macs. Xcode is also required. For
ARM-based Macs, it is recommended to use gcc12 or higher.

Using MacPorts (http://www.macports.org/):

    $ sudo port install fftw-3-single
    $ sudo port install gcc12
    $ sudo port install libpng
    $ sudo port install openblas
    $ sudo port install flock

    (optional)
    $ sudo port install octave

    (optional)
    install version 0.5.2 of the ISMRMRD library

    Select gcc as the compiler when building:
    $ CC=gcc-mp-12 make

Using HomeBrew (https://brew.sh):

    $ brew install --cask gcc-arm-embedded
    $ brew install libpng
    $ brew install fftw
    $ brew install openblas

    Select gcc as the compiler when building:
    $ CC=gcc make

### 2.2.3 Windows

BART is supported through WSL 2 which is avaialable on Windows 10. The instructions are
similar to installing on Linux.

Step-by-step instructions are available on the website at:
	https://mrirecon.github.io/bart/installation_windows.html

First follow the instructions for Debian/Ubuntu in Section 2.1.1 to install reqiured libraries.
Next follow the instructions in Section 2.2 to download and compile bart

2.2.3.1. Using BART with Matlab outside of WSL

To use BART outside of WSL, e.g. with Matlab, it is recommended to soft link
the bart binary to /usr/local/bin. Assuming bart is installed in
the ${BART_TOOLBOX_PATH} directory, execute the following command in WSL:

    $ sudo ln -s ${BART_TOOLBOX_PATH}/bart /usr/local/bin/bart

Outside of WSL, copy the files from ${BART_TOOLBOX_PATH}/matlab to a local folder
and add the folder to the Matlab path.



2.2. Downloading 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:

	http://github.com/mrirecon/bart/releases/latest

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








2.3. Getting Started
--------------------

### 2.3.1. Organization


    .			main directory / built software tools
    Makefile		makefile
    Makefiles/		directory for custom makefiles
    matlab/		Matlab helper scripts
    python/		Python helper functions
    doc/		documentation
    pkg/		packaging for Fedora
    rules/		more built-related files
    scripts/		various helper scripts and examples
    src/		source code
    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
    src/moba/		source code for model-based reconstruction
    src/networks/	source code for neural networks
    src/wavelet/	source code for wavelets
    src/dfwavelet/	source code for divergence-free wavelets
    src/lowrank/	source code for low-rank regularization
    src/simu/		source code for MRI simulation
    src/noncart/	source code for non-uniform FFT
    src/iter/		library of iterative algorithms
    src/linops/		library of linear operators
    src/nlops/		library of nonlinear operators
    src/nn/		library for neural networks
    src/geom/		library for geometric computations
    src/num/		base library with numerical functions
    src/misc/		miscellaneous (e.g. I/O)
    src/lapacke/	copy of a part of LAPACKE
    src/grecon/		helper functions for generic reconstructions
    src/ismrm/		support for ISMRM raw data format
    src/python/		support for Python
    src/win/		support for Windows
    tests/		system tests
    utests/		unit tests
    lib/		built software libraries


### 2.3.2. Terminal

When using the toolbox commands from a UNIX shell, it is recommended
to set the BART_TOOLBOX_PATH to the base directory and to add it to
the PATH variable. You can do this by running the following command:

    $ . startup.sh

Note: The dot or 'source' command is needed so that the variables
are imported into the current shell.


### 2.3.3. Matlab

You can set the BART_TOOLBOX_PATH to the base directory and to add it
to the Matlab path by running the following command in the
bart directory:

    >> startup

(Note: The '>>' indicates the shell prompt. Do not type '>>'
when entering commands.)



You can use Matlab to read and visualize/process files. To write
a data file 'xyz' from Matlab you can run:

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

To read the data file 'xyz' back into Matlab use:

    >> A = readcfl('xyz');


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

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



Download and unpack the examples which demonstrate interoperability
with Matlab. Go to the examples directory and run:

    >> examples


### 2.3.4. Python

You can set the BART_TOOLBOX_PATH to the base directory and start a
Python interactively as follows:

    $ python3 -i startup.py

To avoid doing the above everytime, it is recommended to update your
PYTHONPATH environment. For example, in Linux, assuming your 
BART_TOOLBOX_PATH is set, add the below line to your bashrc file.

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

After doing so, we can simply import as needed.

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

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.

To read the data file 'xyz' back into Python use:

    >>> 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:

    >>> <outputs> = bart(<nargout>, <command>, <arguments>, ...)

To use BART in a script, please follow the steps in the
startup.py file.


3. Data Format
==============

3.1. Generic
------------

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 754 binary32 little-endian).

Convenience methods to read and write our data files using Matlab may
be found in the matlab/ directory (readcfl.m and writecfl.m). Similar
methods for Python may be found in the python/ directory (cfl.py).



3.2. Magnetic Resonance Imaging Data
------------------------------------

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

    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.



3.3. Non-Cartesian Trajectories and Samples
-------------------------------------------

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




4. Command-line Tools
=====================

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.


For example, an inverse Fourier transform of first three dimensions can
be performed with the following command:


    $ bart fft -i 7 kspace volume


More information about each command can be found using the
help option '-h' or in the 'doc/commands.txt' file that can
be generated using 'make doc/commands.txt'.



5. Information for Contributors
===============================

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.



6. Troubleshooting
==================

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 BART_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):

* What system you are using (Linux, Mac OS X, Windows)
  and whether you use Matlab/Python wrappers.

* 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
=============

* 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

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

* 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


References related to implemented methods and algorithms can be
found in the file 'doc/references.txt'.