Installation on macOS and Linux

Shimming Toolbox can be used either from the Terminal or from a graphical user interface (GUI) as a plugin for FSLeyes.

Dependencies

Optional dependencies:

If you would like to use prelude for phase unwrapping and/or bet for brain extraction, you need to install FSL.
If you would like to use sct_deepseg_sc for spinal cord segmentation, you need to install SCT.

Installation Procedure for macOS and Linux

Note

The installer will install Shimming Toolbox, FSLeyes and dcm2niix into an isolated environment. They will not interfere if you already have FSLeyes or dcm2niix installed. If you have previously installed FSLeyes, that version will not support the GUI.

Open a Terminal and run the following commands.

First, download the FSLeyes plugin:

git clone https://github.com/shimming-toolbox/fsleyes-plugin-shimming-toolbox.git

Next, run the installer:

cd fsleyes-plugin-shimming-toolbox
make install

You will be prompted to source your .*shrc file. For example:

source ~/.bashrc

Note

You can restart your terminal or open a new tab to source your .*shrc file automatically.

The shimming-toolbox command launches FSLeyes with GUI support.

shimming-toolbox

To launch our plugin, go to:

Settings --> OrthoView --> Shimming Toolbox

The plugin should open as a panel.

Test the Installation

This step is optional but it's a good measure to ensure Shimming Toolbox is properly installed on your system.

Comprehensive Test

To run the entire testing suite, run pytest from the cloned shimming-toolbox directory:

cd ~/shimming-toolbox/shimming-toolbox
source $HOME/shimming-toolbox/python/etc/profile.d/conda.sh
conda activate ~/shimming-toolbox/python/
pytest

See https://docs.pytest.org/ for more options.

If all tests pass, Shimming Toolbox is properly installed.

Testing subsets of soft dependencies

prelude is a soft dependencies, so you may wish to run the parts of the testing suite that do not depend on it.

To test shimming-toolbox without prelude:

cd ~/shimming-toolbox/shimming-toolbox
source $HOME/shimming-toolbox/python/etc/profile.d/conda.sh
conda activate ~/shimming-toolbox/python/
pytest -m "not prelude"

To test only the parts of shimming-toolbox dependent on prelude, the corresponding -m argument is "prelude"

For Developers

Developers have options to start developing Shimming Toolbox. A quick setup is available for those who want to quickly start coding. While a more permanent setup is available for those who want to contribute to the project more substantially.

Quick setup

To quickly develop Shimming Toolbox, you can clone/fork the repository and run the installer.

git clone https://github.com/shimming-toolbox/shimming-toolbox.git
cd shimming-toolbox
make install

You will be prompted to source your .*shrc file. For example:

source ~/.bashrc

You can then activate the shimming-toolbox environment and start coding!

source $HOME/shimming-toolbox/python/etc/profile.d/conda.sh
conda activate ~/shimming-toolbox/python

Any changes you make in the cloned Shimming Toolbox repository should automatically be reflected in the shimming-toolbox environment. You can test that by making a change to the code and running the right CLI command.

Permanent setup

For more permanent developers, we recommend following this guide to set up a development environment.