-
Notifications
You must be signed in to change notification settings - Fork 16
Installation help
The general steps to install OMEGA are as follows:
-
Install a C++-compiler if one is not already installed
-
(Optional) Install OpenCL, ArrayFire, ROOT, drivers/runtimes, OpenMP and/or CUDA
-
Obtain OMEGA and add the necessary folders to the MATLAB/Octave path
-
Run
install_mexin MATLAB or Octave
This section specifies the necessary installation information when using OMEGA on Windows.
Simply download and install MATLAB for Windows. Any version from 2009b and up should work, but the latest version is always recommended. If you are using an older version, however, you should use 64-bit version as 32-bit version is not supported.
Image processing toolbox and parallel computing toolbox are used for some specific features. However, (slower) fallback alternatives are used if these toolboxes are not found in most cases. The only function that requires image processing toolbox is the anisotropic diffusion MRP prior when using either implementation 1 or 4. Due to this, it does not work on Octave. A warning is produced if AD-MRP prior is used without the toolbox.
Simply download the binary installer for Octave and install the software (Windows-64, though the large data version should work as well). io, image, and statistics packages are required for some features, but are easy to install with the following commands in the Octave user interface:
pkg install -forge io
pkg install -forge image
pkg install -forge statistics
after which you need to load the statistics and image packages
pkg load statistics
pkg load image
Anisotropic diffusion MRP prior when using either implementation 1 or 4 does not work on Octave. A warning is produced if AD-MRP prior is used.
You need a C++11 compiler to compile the necessary MEX-files on MATLAB. For a list of supported compilers for each version of MATLAB, see here. On Octave the built-in compiler is sufficient (implementation 2 is not supported).
On MATLAB, however, Visual Studio is highly recommended. Depending on your MATLAB version, you might need an older version. To configure the C++ MEX-compiler you can use the command mex -setup C++ which will show the currently selected compiler, list all available compilers and show the necessary commands to switch the compiler.
If you use Visual studio, OMEGA only requires "Desktop development with C++". No additional features need to be installed.
MATLAB allows the use of MinGW++, but when using this compiler ArrayFire (implementation 2) will not work unless ArrayFire is built from the source with MinGW.
If you have a Nvidia GPU, then CUDA toolkit is recommended. Both Development and Runtime libraries are required, especially if CUDA support is desired.
If you have Intel GPU/CPU, you should use the Intel OpenCL SDK. When using a CPU you might need to install the runtimes as well.
If you are using AMD GPUs, it is recommended to download and install OCL-SDK. Additionally, you should install official drivers.
For AMD CPUs you should first install the OCL-SDK and then either the Intel CPU runtimes from above or build POCL on Windows (download). If you are using a newer version of Visual Studio, you need to do some modification to the POCL Windows script (setup_and_build_win64.sh). For Visual Studio 2019 you need to change the following sections on lines 29 and 38 "Visual Studio 12 Win64" to "Visual Studio 16" -A x64. For older Visual Studios, simply replace the number 12 with the version you are using (see e.g. Wikipedia).
Note that if you are using Octave and want to use implementation 2, there are some special requirements for OpenCL location. See the ArrayFire section below for a link to the guide page.
These instructions are for MATLAB ONLY (when using Visual Studio):
On Windows simply download the Windows binary from ArrayFire and install it. For more help on installing ArrayFire on Windows see here.
These instructions are for Octave and for MATLAB when using Mingw-w64:
You’ll need to build ArrayFire manually in order to get it to work. Furthermore, only OpenCL is supported. For details see here.
Download either a release version from releases, clone the current master with e.g. GitHub desktop or download an archive of the master-branch. If you downloaded either a release or master branch archive, you need to extract the contents to the folder of your choosing. Alternatively, if you are using MATLAB, you can download the mltbx package (OMEGA.-.Open-source.MATLAB.emission.tomography.software.mltbx) from the releases and simply run it in which case all the necessary folders will be automatically added to the MATLAB path.
Unless the MATLAB package was used, you need to add the source and mat-files folders to the MATLAB/Octave path (biograph-folder should be added if you intend to use mCT or Vision list-mode data files). In MATLAB you can do this by simply right clicking the folders and selecting "Add to path → Selected folders" by selecting the OMEGA folder itself and selecting "Add to path → Selected folders and subfolders". Alternatively, if you are using for example Octave, you can add the paths with addpath('C:\path\to\OMEGA\source') and addpath('C:\path\to\OMEGA\mat-files') or simply with addpath(genpath('C:\path\to\OMEGA\')). On MATLAB you can also add these folders to the list of folders in "Set path".
To build all the necessary mex-files, simply run install_mex.
In case you have trouble compiling the mex-files, you can also try using the precompiled files on the releases page (MATLAB only).
This section specifies the necessary installation information when using OMEGA on Linux distributions.
Simply download and install MATLAB for Linux. Any version from 2009b and up should work, but the latest version is always recommended. If you are using an older version, however, you should use 64-bit version as 32-bit version is not supported.
Image processing toolbox and parallel computing toolbox are used for some specific features. However, (slower) fallback alternatives are used if these toolboxes are not found in most cases. The only function that requires image processing toolbox is the anisotropic diffusion MRP prior when using either implementation 1 or 4. Due to this, it does not work on Octave. A warning is produced if AD-MRP prior is used without the toolbox.
There are several different ways to install Octave on Linux systems. For instructions on how to install Octave on variety of Linux distributions see the Octave wiki. You also need to install the Octave development files (e.g. liboctave-dev on Debian/Ubuntu). Alternatively, you can use distribution independent methods or just build from source.
io, image and statistics packages are required for some features, but are easy to install with the following commands in the Octave user interface:
pkg install -forge io
pkg install -forge image
pkg install -forge statistics
after which you need to load the statistics and image packages
pkg load statistics
pkg load image
Anisotropic diffusion MRP prior when using either implementation 1 or 4 does not work on Octave. A warning is produced if AD-MRP prior is used.
A C++ compiler should already be included, but GCC/G++ is recommended. Any version 4.7 or up should be sufficient. It is recommended to use the G++ version supported by your MATLAB version whenever possible, though newer versions should work almost all the time. The only exception is MATLAB R2017b and earlier using G++ 5.1 or newer, as that will most likely lead to errors. See OMEGA section below for more details. List of supported compilers is available here.
Octave should be fine in all cases.
On Ubuntu, you can install g++ with e.g. sudo apt install build-essential.
If you are using any GPU on Linux, it should be sufficient to simply download the OpenCL libraries and headers
Debian/Ubuntu: sudo apt-get install ocl-icd-opencl-dev opencl-headers ocl-icd-libopencl1
as well as the official drivers.
Alternatively, if you have a Nvidia GPU, then CUDA toolkit can be used. Both Development and Runtime libraries are required, especially if CUDA support is desired.
AMD GPUs should work with only the drivers. If that doesn’t work, you can try using ROCm OpenCL runtimes.
If you have Intel GPU/CPU, you can use the Intel OpenCL SDK. When using a CPU you might need to install the runtimes as well. The runtimes, however, might not anymore support your current OS version.
Alternatively, and especially when using AMD CPUs, POCL is recommended (download). Note that if you use the default installation path, you need to move /usr/local/etc/OpenCL/vendors/pocl.icd to /etc/OpenCL/vendors/.
A useful, but not necessary, program is clinfo that should be available as a package (e.g. sudo apt-get install clinfo). clinfo displays all the available OpenCL platforms, the devices available and various other features. A short list of OpenCL platforms and devices can be obtained in OMEGA with the OpenCL_device_info() function.
Simply download the Linux binary from ArrayFire and install it. For more help on installing ArrayFire on Linux see here. Note, however, that, if you are using the official binary, you should install it to the default location in /opt and secondly that you should rename, or simply delete if you are not using ArrayFire’s graphic features (not used in OMEGA), all the libforge files in /opt/arrayfire/lib64 to something else (e.g. libforge.so.old). Alternatively, you can use a "no-GL" version, but it is an older version that should, nevertheless, work. Leaving the libforge.so files with their original names will most likely lead to crashes as of AF 3.7.2 and earlier (except the no-gl versions).
Alternatively, you can build from source. If you are building ArrayFire from source, it is recommended to disable Forge (set AF_BUILD_FORGE to OFF), otherwise you might get unstable behavior.
Download either a release version from releases, clone the current master with e.g. git clone https://github.com/villekf/OMEGA.git or download an archive of the master-branch. If you downloaded either a release or master branch archive, you need to extract the contents to the folder of your choosing. Alternatively, if you are using MATLAB, you can download the mltbx package (OMEGA.-.Open-source.MATLAB.emission.tomography.software.mltbx) from the releases and simply run it in which case all the necessary folders will be automatically added to the MATLAB path.
Unless the MATLAB package was used, you need to add the source and mat-files folders to the MATLAB/Octave path (biograph-folder should be added if you intend to use mCT or Vision list-mode data files). In MATLAB you can do this by simply right clicking the folders and selecting "Add to path → Selected folders" by selecting the OMEGA folder itself and selecting "Add to path → Selected folders and subfolders". Alternatively, if you are using for example Octave, you can add the paths with addpath('/path/to/OMEGA/source') and addpath('/path/to/OMEGA/mat-files') or simply with addpath(genpath('/path/to/OMEGA/')). On MATLAB you can also add these folders to the list of folders in "Set path".
To build all the necessary mex-files, simply run install_mex.
In case you have trouble compiling the mex-files, you can also try using the precompiled files on the releases page (MATLAB only).
If you are using MATLAB R2017b or EARLIER, you will most likely encounter problems when running the mex-files. The same can also happen if you use the latest gcc/g++ with MATLAB 2020a or earlier. One alternative is to install the supported compiler of the MATLAB version in use (see here) and then re-run install_mex (the supported compiler is used if available). Alternatively, you can try one of solutions presented here or try the precompiled mex-files from releases. In short there are mainly three possibilities:
1) Install the compiler that MATLAB supports. If you are using, for example, Ubuntu 20, you can install older g++ as outlined here. Note that you need to install g++ (e.g. sudo apt install g++-6). If you are using R2017b or earlier, see here. Then simply re-run install_mex.
2) Locate the system version of libstdc++.so.6 and create an alias in .bashrc for MATLAB to use this one, for example:
alias matlab='LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 /path/to/MATLAB/bin/matlab -desktop'. Or simply run MATLAB with the same LD_PRELOAD.
3) Rename the libstdc++.so.6 file that ships with MATLAB, located in /path/to/MATLAB/sys/os/glnxa64/
e.g. sudo mv /path/to/MATLAB/sys/os/glnxa64/libstdc++.so.6 /path/to/MATLAB/sys/os/glnxa64/libstdc++.so.6.old.
When importing ROOT data, you might run into errors (the crashes with R2018b and earlier can be fixed by running MATLAB with matlab -nojvm, however, errors can still occur after this). These occur if you are using ROOT 6.16 or later and are using MATLAB (Octave is unaffected). R2020b (and probably newer ones later) is unaffected. These errors can be fixed by similar methods as above with two additional possibilities:
1) Locate the ROOT version of libtbb.so.2 and create an alias in .bashrc for MATLAB to use this one, for example:
alias matlab='LD_PRELOAD=/opt/root/lib/libtbb.so.2 /path/to/MATLAB/bin/matlab -desktop'. Or simply run MATLAB with the same LD_PRELOAD.
2) Rename the libtbb.so.2 file that ships with MATLAB, located in /path/to/MATLAB/bin/glnxa64/
e.g. sudo mv /path/to/MATLAB/bin/glnxa64/libtbb.so.2 /path/to/MATLAB/bin/glnxa64/libtbb.so.2.old. This is not recommended if the system is used by other users who use the same MATLAB.
3) Install ROOT 6.14 or earlier.
4) Use Octave for ROOT data import.
This section specifies the necessary installation information when using OMEGA on MacOS.
|
Note
|
Mac build of OMEGA hasn’t been tested so far. Compilation has been tested on MATLAB ONLY. |
Simply download and install MATLAB for Windows. Any version from 2009b and up should work, but the latest version is always recommended. If you are using an older version, however, you should use 64-bit version as 32-bit version is not supported.
Image processing toolbox and parallel computing toolbox are used for some specific features. However, (slower) fallback alternatives are used if these toolboxes are not found in most cases. The only function that requires image processing toolbox is the anisotropic diffusion MRP prior when using either implementation 1 or 4. Due to this, it does not work on Octave. A warning is produced if AD-MRP prior is used without the toolbox.
To install Octave on Mac, see their wiki for instructions.
io, image and statistics packages are required for some features, but are easy to install with the following commands in the Octave user interface:
pkg install -forge io
pkg install -forge image
pkg install -forge statistics
after which you need to load the statistics and image packages
pkg load statistics
pkg load image
Anisotropic diffusion MRP prior when using either implementation 1 or 4 does not work on Octave. A warning is produced if AD-MRP prior is used.
You should install Xcode from the app store. Furthermore, if you wish to use implementations 1 and/or 4 with OpenMP (parallel computing) support, you might need to install OpenMP. This is most easily achieved with Homebrew:
brew install libomp
On MATLAB, you do not need to do any changes. On Octave, you need to make sure that both the library and header (omp.h) can be found on path. This might also be the case on MATLAB if the header is installed in non-standard location. If OpenMP support could NOT be applied, you should see a warning message(s) of the like …built WITHOUT OpenMP (parallel) support.
OpenCL should already be included with your Mac installation. If running OpenCL functions fails, make sure that /System/Library/Frameworks/OpenCL.framework is included in the library path.
Simply download the Mac binary from ArrayFire and install it. For more help on installing ArrayFire on Mac see here.
Alternatively, you can build from source.
Download either a release version from releases, clone the current master with e.g. git clone https://github.com/villekf/OMEGA.git or download an archive of the master-branch. If you downloaded either a release or master branch archive, you need to extract the contents to the folder of your choosing. Alternatively, if you are using MATLAB, you can download the mltbx package (OMEGA.-.Open-source.MATLAB.emission.tomography.software.mltbx) from the releases and simply run it in which case all the necessary folders will be automatically added to the MATLAB path.
Unless the MATLAB package was used, you need to add the source and mat-files folders to the MATLAB/Octave path (biograph-folder should be added if you intend to use mCT or Vision list-mode data files). In MATLAB you can do this by simply right clicking the folders and selecting "Add to path → Selected folders" by selecting the OMEGA folder itself and selecting "Add to path → Selected folders and subfolders". Alternatively, if you are using for example Octave, you can add the paths with addpath('/path/to/OMEGA/source') and addpath('/path/to/OMEGA/mat-files') or simply with addpath(genpath('/path/to/OMEGA/')). On MATLAB you can also add these folders to the list of folders in "Set path".
To build all the necessary mex-files, simply run install_mex.
This section describes the optional software that can be used in OMEGA, but which are not required for any of the core functions.
If you wish to use NIfTI data or save data as NIfTI format, on MATLAB you’ll need EITHER image processing toolbox OR Tools for NIfTI and ANALYZE image. For Octave, only Tools for NIfTI and ANALYZE image can be used, though it hasn’t been tested.
For Analyze data, you’ll need the above Tools for NIfTI and ANALYZE image in all cases.
For DICOM data, you’ll need image processing toolbox on MATLAB and dicom package on Octave (untested).
For 3D volumetric visualization, there is built-in support for vol3d in visualize_pet.m.
For random subset sampling (subset_type = 3), it is recommended to use Shuffle as it is both faster and more memory efficient than the built-in function. Note that you need to enable this by setting options.shuffle = true in MISC SETTINGS in RECONSTRUCTION PROPERTIES.
If you NEED to use implementation 1 WITHOUT precomputation (not recommended), then for Octave and MATLAB R2019b and EARLIER, it is recommended to download and build fsparse. Note that you need to enable this by setting options.fsparse = true in MISC SETTINGS in RECONSTRUCTION PROPERTIES.
- Home
- Installation help
- Getting started
- PET Tutorials
- CT Tutorials
- Useful information
- Function help
- Visualization
- Using GATE PET data
- Using GATE CT data
- Extracting GATE scatter, randoms and trues data
- Computing the forward and/or backward projections
- Using non-cylindrical PET scanners
- Custom detector coordinates and/or list mode reconstruction
- Using TOF data
- Extracting the system matrix
- Using Inveon PET data
- Using Inveon CT data
- Using Biograph PET data
- Using custom gradient-based priors
- Adding custom built-in algorithms
- Toolbox overview
- Contributing code to OMEGA
- Contact