This is a reconstruction toolbox optimised for 3D non-cartesian MR images. There are many high quality MR recon toolboxes available, e.g. BART, but these are mostly optimised for 2D sequences. 3D non-cartesian sequences present unique challenges for efficient reconstruction, so we wrote our own.
This toolbox was presented at ISMRM 2020.
Tobias C Wood, Emil Ljungberg, Florian Wiesinger.
Pre-compiled executables are provided for Linux and Mac OS X in a .tar.gz
archive from http://github.com/spinicist/riesling/releases. Download the
archive and extract it with tar -xzf riesling-platform.tar.gz. Then, move the
resulting riesling executable to somewhere on your $PATH, for instance
/usr/local/bin. That's it.
- MacOS Catalina or higher users should use
curlto download the binary, i.e.curl -L https://github.com/spinicist/riesling/releases/download/v1.0/riesling-macos.tar.gz. This is because Safari now sets the quarantine attribute of all downloads, which prevents them being run as the binary is unsigned. It is possible to remove the quarantine flag withxattr, but downloading withcurlis more straightforward. - The Linux executable is compiled on Ubuntu 20.04 and a statically linked libstdc++. This means it will hopefully run on most modern Linux distributions. Let us know if it doesn't.
- The Mac executable is compiled with MacOS 14.
RIESLING comes as a single executable file with multiple commands, similar to
git or bart. Type riesling to see a list of all the available commands. If
you run a RIESLING command without any additional parameter RIESLING will output
all available options for the given command.
RIESLING uses HDF5 (.h5) files for input and output. Your input file will need to contain the non-cartesian data, the non-cartesian trajectory, and the image geometry/orientation information. Some helper functions are provided for creating a suitable .h5 file from Python or Matlab. These are in the repository but not included as part of the installation - you will need to download and install these yourself.
Once you have assembled the input dataset, the first command you should start
with is riesling recon-lsq. This will perform a least-squares reconstruction
of the data using a pre-conditioned iterative algorithm. If the resulting
image looks good, then the recon-rlsq command contains options for a
regularized least-squares reconstruction (e.g. Total Variation or Total
Generalized Variation).
To view the output images in .h5 format requires an HDF5 viewer, for instace
the H5Web plugin for VSCode. If you compile riesling yourself the montage
command can show images in your terminal. Otherwise the nii command will
convert from riesling format to Nifti.
A separate examples repository https://github.com/spinicist/riesling-examples contains Jupyter notebooks demonstrating most functionality.
Further documentation is available at https://riesling.readthedocs.io.
If you can't find an answer there or in the help strings, you can open an issue, or e-mail [email protected].
If you wish to compile RIESLING yourself, compilation should hopefully be
straightforward as long as you have access to a C++20 compiler (GCC 10 or
higher, Clang 7 or higher). RIESLING relies on vcpkg for dependency
management. To download and compile RIESLING, follow these steps:
Install the MacOS vcpkg dependencies.
- XCode from the AppStore
- Run
$ xcode-select --installin the terminal
You may also need to install pkg-config depending on your macOS version. This
is easily installed with Homebrew using
$ brew install pkg-config
Apple Silicon (M1) is supported.
Install the Linux vcpkg dependencies.
These include cmake, tar, curl, zip, unzip, pkg-config & build-essential.
You may be surprised by which distributions do not include these by default.
$ git clone https://github.com/spinicist/riesling
In the riesling folder execute
$ ./bootstrap.sh