Installation#

Overview#

omni is a hybrid Python/C++17 library designed for developing image preprocessing algorithms.

System Requirements#

A linux system is required to run omni. Currently, the recommended linux OS to use is Ubuntu 20.04.

It is recommended that your system has at least 32 GB of RAM to run omni. Actual memory usage will depend on the size of the images, and the models that you are using.

omni currently relies on programs from FSL, AFNI, and ANTs for some functionality. The list below are the known versions for each package known to work with omni:

# Newer/Older versions may still work, but have not been tested.
FSL 6.0.4
AFNI 20.0.18
ANTs 15a6861

To install these packages, refer to each package’s respective documenation.

Installing omni#

omni has a PyPI package available here. To install it, you can use pip:

Warning

The PyPI package for omni is called omnineuro. The omni package on PyPI refers to an unrelated package. Take care to install the correct package!

# base installation of omni package
pip install omnineuro

# OR

# if you want to use SpaceTimeRealign (Simultaneous Slice Time/Motion Correction)
# you need to install the extra packages
pip install omnineuro[extra]

# post installation
omni_affine -h
# should run successfully and give you the help text for the omni_affine script
# note that on first run, it may take some time due to python generating bytcode files

Building and installing omni from source#

While the omni package is available on PyPI, you may have reason to build and install omni directory from source. In this case, you will need to install a few system dependencies to compile the C++ modules.

System Dependencies#

You will need python >=3.6, pip >= 19.1, gcc >=8, gfortran >=8, openblas, hdf5, and fftw3 Example package manager commands are below:

Ubuntu and Debian#

# this was tested on Ubuntu 20.04 and 18.04
apt-get install -y python3 python3-dev python3-distutils python3-pip build-essential \
gfortran libopenblas-dev liblapack-dev libhdf5-dev libfftw3-dev

Centos#

# this was tested on Centos 7

# add the epel repo
yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

# dependencies
yum -y install python3-devel openblas-devel lapack-devel hdf5-devel fftw3-devel

# pip version on Centos is old, so we use pip to update itself
pip3 install pip -U

# install devtoolset for gcc/gfortran 8
yum -y install centos-release-scl && yum -y install devtoolset-8

# this enables the gcc/gfortran toolset
source /opt/rh/devtoolset-8/enable

Compiling and installing omni#

To compile and install omni, you have two options:

  1. Install the sdist package from PyPI.

You can install the sdist package from PyPI by running:

# installs the sdist package from PyPI
pip install omnineuro --no-binary omnineuro

  1. Install the package from the git repo.

This involves cloning the git repo and using pip to install the package:

# clone the git repo
git clone https://gitlab.com/vanandrew/omni.git

# install omni package
pip install [path/to/the/cloned/omni/directory]

If you are running into compilation issues, it is helpful to use pip’s verbose option -v to see what is happening.

Running omni on Docker#

It is also possible to run omni on Docker. A pre-built Docker image can be found at DockerHub.

# The first argument to the docker image is the command to run
# Note that unlike the local install, commands are called without the
# ``omni_`` prefix.
docker run -it --rm vanandrew/omni affine -h

# Running the image without any arguments will give you a list of
# available commands.
docker run -it --rm vanandrew/omni

For Developers#

If you are a developer, it may be convenient to install omni in editable mode for making code modifications and testing. This will allow you to directly work out of the cloned git repo (instead of modifying files in whatever location pip installs omni into).

You will need to follow all the same steps as in Building and installing omni from source.

git clone https://gitlab.com/vanandrew/omni.git
pip install -e [path/to/the/cloned/omni/directory]

What’s next?#

After downloading and installing, you may want to read the Walkthrough: Field map-lessly correcting distortion in an example data set. Over the course of that tutorial, you learn how to test and validate the success of your installation by using the script, omni_pipeline to preprocess the included example data set. Reading through this section will help you understand how omni preprocessing scripts organize their outputs, the purposes of the various intermediary files they produce, and give you a sense of where to begin when troubleshooting registration issues, if they happen to crop up.