Download and install BrainVISA

_images/cort_download.png

Detailed instructions

BrainVISA is composed of a set of software, freely distributed in software bundles. Starting from BrainVISA 5.0, the software is distributed using virtualization. It means that there is only one BrainVISA version running on Linux but, thanks to virtualization, it can be used on any system. There are BrainVISA images for two free and open source virtualization technologies :

  • Singularity: an operating-system-level virtualization (also known as containerization) technology well suited for high performance computing and for users without administration privileges (as compared to Docker, a more popular containerization technology).
  • VirtualBox: an hypervisor allowing to run virtual machines and available on main operating systems (Linux, Windows, MacOs).

Using virtualization allows to solve many porting and compatibility issues (especially packaging and distributing packages for many different operating systems). Now we only provide Linux containers for a single Linux system / version, which can be run on almost every host system.

But virtualization have 3 main drawbacks:

  • modularity is gone: virtual images are not designed to be modular, so we cannot install just parts of it. You get the whole BrainVISA distribution. But in practice we never heard about anyone installing just a part of the packages in the previous distrubtions.
  • Programs must always be run through the virtualization layer, and not natively on the system. It can add some overhead, but this is light in most cases.
  • 3D with hardware acceleration may not work out of the box. But it will, in most cases.

Plan:

To use BrainVISA on your system, first read the Prerequisites section. Then, if you just want to use the software, go to Install with Singularity or Install with VirtualBox section. But if you want to develop BrainVISA related software, go to the Developer environment installation section.

In other words:

Prerequisites

Prerequisite are the software that need to be installed on your computer in order to be able to install and use BrainVISA. They differ according to the virtualization technology you want to use (Singularity or VirtualBox). We recommend using Singularity for Linux and VirtualBox for Windows and MacOS. Some BrainVISA team members are using Singularity on Windows 10. It works well but is more complex to setup (explaination below). Note that we had mitigate experiences on MacOS using both VirtualBox or Singularity, even if both somewhat worked.

Prerequisites for Singularity on Linux

For Linux, two software must be installed : Python (version >= 2.7) and Singularity (version > 3.6). Most popular Linux distro come with Python already installed but if not, there are system package to install it. The name of the package to install is python. For example for Debian based distro:

sudo apt install python

At the time of this writing, no suitable version of Singularity is available as system package for Ubuntu (the most popular Linux distro). Therefore we decided to make our own packages for users who need a simple way to install Singularity. Look in the following table for a suitable package for your Linux distro. If found, download it and install it, either using a graphical tool, or the following commandline:

sudo dpkg -i singularity-container-*.deb
host systeminstallersizedate
linux mint-19.2singularity-ce_3.8.3~linuxmint-19.2_amd64.deb24.8 MB2021-09-08
linux mint-20.1singularity-ce_3.8.3~linuxmint-20.1_amd64.deb24.8 MB2021-09-08
ubuntu-18.04singularity-ce_3.8.3~ubuntu-18.04_amd64.deb24.8 MB2021-09-08
ubuntu-20.04singularity-ce_3.8.3~ubuntu-20.04_amd64.deb24.8 MB2021-09-08
ubuntu-16.04singularity-container-3.7.0-ubuntu-16.04.deb23.9 MB2021-02-04

If no package can be found for your system, then follow Singularity installation instructions

Prerequisites for VirtualBox

A recent version of VirtualBox ( >= 6.1) must be installed for the user of the system.

See the troubleshooting section, especially for Mac.

Prerequisites for Singularity on Windows 10

Using singularity on Windows works only with Windows 10 and requires a recent technology (deployed in late summer 2020, your system must have been updated afterward) allowing to run Linux in Windows. This technology, called Windows Subsystem For Linux 2 (WSL2) must be enabled on the system. Then a Linux distro must be installed from the Microsoft Store. Finally an X Windows server must be installed and started.

Once these steps are done, you will have a fully functionnal Linux running as a Windows 10 App. Therefore, you will have to follow the Prerequisites for Singularity on Linux section and then the Install with Singularity section.

Install WSL2 and Linux

We recommend that you install Ubuntu 20.04. Follow the installation steps defined in Windows Subsystem for Linux Installation Guide for Windows 10.

Install an X Windows server

Linux is an old system with many programs using text-based user interface an no graphical user interface (GUI). For now, it is necessary to install a third-party App to run any Linux App with a GUI, but Microsoft announced on //build 2020 that they will release soon an improvement that will not require any third-party component to run Linux GUI Apps on Windows Desktop (source). The graphical interface for Linux is based on a technology called X Windows and the App to install is an X Windows server.

There exists many X Windows servers for Windows. For a free and open source one, we recommend VcXsrv. On its web page, click on the Download button to get an installer program. Once installed, you can run X Launch to configure and start the server. The following images shows the options we recommend for the various steps of the setup. On the last step, you can save the configuration in a file that will allow to quickly restart the server by just double clicking on the saved file.

_images/vcxsrv_launch_1.png _images/vcxsrv_launch_2.png _images/vcxsrv_launch_3.png _images/vcxsrv_launch_4.png

Prerequisites for Singularity for MacOS

Python

Python is already installed on MacOS systems.

Singularity

At the time this document is written, there is no official Singularity final release available for MacOS. However a beta is available for more than a year (but with no updates or fixes since then):

Singularity for Mac

Officially this beta does not fully support the new .sif format of Singularity 3.6. However it appears to work… with a few issues, see the troubleshooting notes.

X server

On Mac XQuartz is part of the system but needs some setup: see also this doc.

Install with Singularity

  • Create an installation directory:

    mkdir $HOME/brainvisa-5.0.0
    
  • Download the BrainVISA image found below into this new directory. It’s a .sif file, for instance brainvisa-5.0.0.sif.

fileversionsizedatemetadata (md5)
brainvisa-5.0.3.sif5.0.33.6 GB2021-10-14metadata
brainvisa-5.0.2.sif5.0.23.6 GB2021-06-29metadata
brainvisa-5.0.1.sif5.0.13.6 GB2021-03-25metadata
  • Run Singularity using this image, with an option to tell it to run its setup procedure. The installation directory should be passed:

    singularity run -B $HOME/brainvisa-5.0.0:/casa/setup $HOME/brainvisa-5.0.0/brainvisa-5.0.0.sif
    
  • set the bin/ directory of the installation directory in the PATH environment variable of your host system config, typically in $HOME/.bashrc or $HOME/.bash_profile if you are using a Unix Bash shell:

    export PATH="$HOME/brainvisa-5.0.0/bin:$PATH"
    
  • Optionally, you may want to run the configuration GUI, through the bv program. Since BrainVISA is running in a container, it cannot access your computer directories unless you make them available to the container. Adding directories is done graphically, simply using the following command:

    bv
    
  • Installation is finished, you can run programs from the container.

    There are several ways actually:

    1. The simplest way, call commands directly from the above PATH like if they were on the host machine:

      # run programs
      AimsFileInfo --info
      anatomist
      brainvisa
      
    1. Using bv interface to containers or casa_distro:

    The bv program is found in each install directory into bin subdirectory in order to be always compatible with this installed environment (thus you can install and use several BrainVISA version at the same time).

    • bv accepts an executable program name as sub-command, it allows to run programs installed inside the container, for instance:

      bv brainvisa
      bv anatomist
      bv AimsFileInfo -h
      

      or to open an interactive shell in the container:

      bv bash
      

      More options may be used. See the complete documentation of the bv command.

  • If you are using BrainVISA using Singularity or Docker containers, graphical software need to run the containers with a graphical “bridge”: a X server has to be running on the host system, and 3D display may or may not work. The options gui=yes and opengl of the bv command try to handle common cases, possibly using Nvidia proprietary OpenGL implementation and drivers from the host system.

    Note that the option gui=yes is now the default, thus it is not needed.

  • see the troubleshooting section, especially the OpenGL troubleshooting, Singularity on Mac and Singularity on Windows subsections.

  • See also the OpenGL troubleshooting section for if you experience problems using 3D rendering.

Configuration of BrainVisa in a Singularity container

Please read this document.

Install with VirtualBox

To use BrainVISA with VirtualBox, the procedure is roughly the same on Linux, Windows and Mac machines.

  • VirtualBox must be installed for the user of the system.

  • Download a VirtualBox image foud in the following table.

    Note that you don’t need to download an image built for your host system, the virtualization allows precisely to run, for instance, an Ubuntu-18.04 image, on any host system (Linux, Windows, or Mac).

    Available VirtualBox BrainVisa images:

    fileversionsizedatemetadata (md5)
    brainvisa-5.0.3.ova5.0.37.1 GB2021-10-14metadata
    brainvisa-5.0.2.ova5.0.28.0 GB2021-06-29metadata
    brainvisa-5.0.1.ova5.0.17.1 GB2021-03-25metadata
  • start virtualbox

  • in VirtualBox, import the downloaded image - some configuration (memory, CPU, video, sound etc) may be useful for it in VirtualBox.

  • some mount points to the host filesystem can be added to see the host filesystem directories from the VM.

  • start it

  • in the running Linux virtual machine, BrainVISA is installed and configured. You can open a terminal and type:

    AimsFileInfo -h
    brainvisa
    anatomist
    

The virtual machine has a configured user named “brainvisa”, with the password “brainvisa”, which has sudo (admin) permissions.

Developer environment installation

The requirements are the same as for user installs. The main difference is that developers will get source code from source repositories, and compile the whole code. To do that, we have published “developer images” which contain all the required development tools and libraries. To date, we only support development environments using Singularity. But we plan to provide image and instruction for VirtualBox too.

If you want to develop software using the BrainVISA environment, you are advised to read the developer section of the Casa-Distro project.

Installing a Singularity developer environment

  • follow the Prerequisites section as for users.

  • Create an installation directory:

    mkdir -p $HOME/casa_distro/brainvisa-opensource-master
    

    (note that we are using a slightly different directories organization from the user case, because the images here can be reused and shared betwen several development configurations - but this organization is not mandatory, it will just make things simpler for the management tool casa_distro if it is used later)

  • Download the casa-dev image found here (https://brainvisa.info/download/), preferably into the $HOME/casa_distro directory. It’s a .sif file, for instance casa-dev-5.0.sif.

    Note that you don’t need to download an image built for your host system, the virtualization allows precisely to run, for instance, an Ubuntu-18.04 image, on any host system (Linux, Windows, or Mac).

imagesizedatebase systemmetadata (md5)
casa-dev-5.1-3.sif2.3 GB2021-11-24ubuntu-20.04casa-dev-5.1-3.sif.json
casa-dev-5.0-7.sif3.2 GB2021-11-24ubuntu-18.04casa-dev-5.0-7.sif.json
casa-dev-5.0-6.sif3.2 GB2021-11-19ubuntu-18.04casa-dev-5.0-6.sif.json
casa-dev-5.0-5.sif3.2 GB2021-10-08ubuntu-18.04casa-dev-5.0-5.sif.json
casa-dev-5.0-4.sif3.2 GB2021-06-30ubuntu-18.04casa-dev-5.0-4.sif.json
casa-dev-5.0-3.sif3.1 GB2021-06-02ubuntu-18.04casa-dev-5.0-3.sif.json
casa-dev-5.0-1.sif3.0 GB2021-03-17ubuntu-18.04casa-dev-5.0-1.sif.json
casa-dev-5.0.sif3.1 GB2021-04-28ubuntu-18.04casa-dev-5.0.sif.json
  • Execute the container image using Singularity, with an option to tell it to run its setup procedure. The installation directory should be passed, and it will require additional parameters to specify the development environment characteristics. Namely a distro argument will tell which projects set the build will be based on (valid values are opensource, brainvisa, cea etc.), a branch argument will be master, latest_release etc., and other arguments are optional:

    singularity run -B $HOME/casa_distro/brainvisa-opensource-master:/casa/setup $HOME/casa_distro/casa-dev-5.0.sif branch=master distro=opensource
    
  • set the bin/ directory of the installation directory in the PATH environment variable of your host system config, typically in $HOME/.bashrc or $HOME/.bash_profile if you are using a Unix Bash shell:

    export PATH="$HOME/casa_distro/brainvisa-opensource-master/bin:$PATH"
    
  • Optionally, you may want to run the configuration GUI, through the bv program: as programs are actually running in a container or a virtual machine (transparently), the user may have to configure additional mount points to actually see his data and working directories from his host machine in the container. This is done graphically, simply using:

    bv
    
  • The development system is ready in the container, and BrainVISA build system (brainvisa-cmake) is available. You may need to configure the projects you want to retreive / build, and set the login / passwords in the sources repositories for non-public sources, if needed.

    • You can open a terminal using:

      bv bash
      

      then build from within the terminal:

      bv_maker
      
    • or start it from outside the container:

      bv_maker
      

      (this will run the bv program wich will call commands inside the container)

  • Technically, bv is a simplified version of casa_distro which is contained inside a single environment (distribution installation) and only allows to run and configure this environment. See the doc of casa-distro for more details.

Installing a VirtualBox developer environment

  • Download the casa-dev VirtualBox image:
imagesizedatebase systemmetadata (md5)
casa-dev-5.0-1.ova6.9 GB2021-03-05ubuntu-18.04casa-dev-5.0-1.ova.json
  • import the image and configure it in VirtualBox just like the BrainVisa users images
  • inside the image, edit, check or complete the config files, especially /casa/conf/svn.secret and /casa/conf/bv_maker.cfg
  • the develper tools and directories are already setup. The bv_maker command is available.

Getting started

Three main programs, brainvisa, anatomist, and morphologist are available directly in the bin directory of the installed software. A lot of other programs are also present here.

anatomist is the interactive 3D visualization software.

morphologist is the new user interface for the main Morphologist pipeline.

brainvisa is the user interface to Axon, which will generally be the entry point to all other applications and toolboxes. You may also have access to morphologist and anatomist from the brainvisa program.

Once started, brainvisa will need a bit of configuration: go to the “BrainVISA / Preferences” menu, and setup especially paths to external software such as Matlab, SPM, FSL or Freesurfer if you have installed them.

BrainVISA is working with files and directories organizations, and local databases, more generally regrouped under the term “databases”. You will have to setup at least one to make it work in optimal conditions. At the beginning a database is a new, empty directory, where BrainVISA will import unprocessed data and write processed data.

Before running processing, raw data thus has to be imported in such a database: use the “Data management” tools, “import” to do so. For T1 MRI processing (using Morphologist), you will typically use the “Import T1 MRI” process, or the “Import DICOM T1 MRI” process. Appropriate import processes are generally also found in processing toolboxes.

_images/importt1.png

More information may be found in the Axon tutorial and, more generally in the Axon documentation.

Licences

Globally, it is free for a non-profit usage.

As the whole set of software contains several sub-packages, each may have its specific licencing policy. See individual modules for licence information.

Some are “really” free and open source (CeCILL-B, BSD-like licence), some are CeCILL-v2 (GPL-compatible), and some are closed source with free binary distribution for non-profit usage.

The core is as free as possible: CeCILL-B when possible, or CeCILL-v2 when using PyQt which is GPL:

  • Axon is CeCILL-v2
  • Anatomist is CeCILL-B, with some additional python plugins which are bound to GPL.
  • AIMS (image processing tools) is CeCILL-B

CeCILL licences are compatible with their GPL or BSD equivalent, but with additional legal precisions for french laws. See http://www.cecill.info/index.en.html

This basically leaves the possibility for toolboxes developers to choose the licence which suits them (open or closed), with some PyQt (GUI) parts which have to be GPL-compatible.

  • Morphologist, BrainRAT, cortical_surface and some other toolboxes also include closed-source code in their algorithmic parts. They can be used freely for non-profit usage.
    • Typically academic research applications are OK.
    • Commercial applications of these toolboxes should contact their authors before proceeding.