Up to Build Environment.

The easiest way to set up a working build environment for open_iA in an automated fashion is through our superbuild. In contrast, this document provides detailed instructions on how to manually set up a build environment for open_iA on Ubuntu, for example on 20.04. For older versions of Ubuntu you might have to adapt the names of the packages to install, for other Linux distributions you might have to use completely different commands to install packages and the package names might also differ; please consult the manuals of the respective distribution! A leading $ in code-formatted parts denotes commands to be executed on the shell (don't type the '$' character).

• Compiler: Gnu C++ >= 4.8 / clang >= 6
• git
• CMake (>= 3.0)
• Build Tool (e.g. make or ninja)
• OpenGL
• OpenCL SDK
• Qt, VTK, ITK (installation/build described below)
• optional: ASTRA Toolbox, boost, eigen, HDF5 (also described below), an IDE with CMake support such as QtCreator; OpenVR / OpenXR (untested under Linux, therefore no detailed description available here)

For the libraries below, we usually try to support the latest versions. If those don't work for you, check our list of supported operating systems, library versions and tools!

Either g++ or clang are required:

• g++: $ sudo apt install g++
• clang: $ sudo apt install clang

Either make or ninja are required:

• $ sudo apt install make OR
• $ sudo apt install ninja-build

Install via $ sudo apt install git

Install via $ sudo apt install cmake-qt-gui

Install OpenGL and X11 Xt development library and headers: $ sudo apt install libgl1-mesa-dev libxt-dev

Required for some GPU-accelerated filters in ITK and open_iA. See the Build Instructions OpenCL.

We recommend to install the version (of Qt 5 or Qt 6) included in the distribution's repository.

• For Qt 5 for example, install via $ sudo apt install qtbase5-dev libqt5x11extras5-dev qttools5-dev qt5-default libxt-dev libqt5opengl5-dev libqt5svg5-dev libqt5charts5-dev

If you want to build Qt yourself, see Qt build from source for our recommended build procedure.

See Build Instructions VTK.

See Build Instructions ITK.

• Optional; only used in RandomWalker algorithm in Segmentation module, and optional there
• Download a suitable version from http://eigen.tuxfamily.org to /workspace/. Note: Use a 3.3.x version of eigen
• Open a command line in /workspace.
• Extract: $ tar xf 3.3.9.tar.bz2
• $ rm 3.3.9.tar.bz2
• No build is required, eigen is a header-only library.

• Optional; required if you want to be able to read arbitrary HDF5 files.

• Go to the HDF5 group download page, click on the version you want to use (e.g., 1.12.2, assumes for the rest of these instructions, replace if using a different version), and download the respective CMake source bundle (e.g. CMake-hdf5-1.12.2.tar.gz).

• Extract the archive.

• Change the options to build static libraries. For that, you need to uncomment one line in HDF5options.cmake; change

  #set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF")

  to

  set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF")

• You could also disable the testing build, by changing

  #set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_TESTING:BOOL=OFF")

  to

  set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_TESTING:BOOL=OFF")

  but not that this also requires adding --no-tests=ignore to the ctest options in build-VS2019-64.bat

• Execute build-unix.sh to build

• For more information, see the CMake build instructions of the HDF5 group

• After the build has finished, run the created file "HDF5-1.12.2-Linux.sh"

• Choose a location of your choice as installation destination

• If you want to shorten the path, only the content of the 1.12.2 directory under HDF_Group/HDF5 is required, you can move it to a shorter path (e.g. /workspace/hdf5-1.12.2, such that you have the directories /workspace/hdf5-1.12.2/bin, /workspace/hdf5-1.12.2/lib, etc...)

• In the open_iA build, specify HDF5_DIR as the share/cmake/hdf5 subdirectory of the install location, e.g. /workspace/hdf5-1.12.2/share/cmake/hdf5

• Optional; required for the AstraReconstruction module
• Building this library requires several other libraries:
  • NVidia CUDA SDK (install from repositories, e.g. $ sudo apt install nvidia-cuda-dev, or download installer from https://developer.nvidia.com/cuda-downloads. Note: You will also have to make sure CUDA is set up properly, see e.g. http://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html)
  • Boost (install from repositories: $ sudo apt install libboost-dev)
  • Automake/Autoconf and libtool (install with $ sudo apt install automake libtool)
• Download an archive of the latest version from https://github.com/astra-toolbox/astra-toolbox to /workspace/astra, and open a command line there
• Extract archive
• Follow the build instructions for python on the ASTRA Toolbox homepage. In the configure step, use the following command instead of the one shown there: ./configure --with-cuda=/usr/local/cuda[-8.0] --prefix=/workspace/astra[-versionsuffix]

• Optional; required for ASTRA Toolbox (see above, no version restrictions), as well as for VR module (needs to be boost >= 1.70 for open_iA >= 2021.07)
• Typically included in distribution repositories, e.g. $ sudo apt install libboost-dev

• Create a folder for open_iA, e.g. /workspace/open_iA
• Open a terminal window in that folder
• Clone the open_iA project into the src subfolder: $ git clone https://github.com/3dct/open_iA.git src
• You will have to decide which version you want to build. In case you want to build the latest stable release, then you can stay on the default branch (main). In case you want to build the latest development version (potentially containing some new features and/or bugfixes, but potentially also less stable than main), you can check out the develop branch: git checkout develop
• Open CMake GUI and set:
  • Source: /workspace/open_iA/src
  • Binaries: /workspace/open_iA/bin
  • Click on the "Configure" button.
  • Say "Yes" when asked whether the build directory should be created.
  • In the dialog opening next, chose the "generator" - the build system (and IDE) you want to use: Depending on whether you installed make or ninja-build above, choose either "Unix Makefiles" or "Ninja" (or the respective option with IDE, for example, to create an eclipse CDT project with the ninja build system, choose "Eclipse CDT4 - Ninja").
  • "Use default native compilers" should be selected in the radio buttons below the geberator selection, leave it like it is.
  • Confirm the build system choice by pressing the "Finish" button.
  • Wait for the configure run to finish.
  • There will be some errors. Set the following configuration:
  • Set CMAKE_BUILD_TYPE to the same value you used for VTK and ITK.
  • Set ITK_DIR: /workspace/ITK/bin-5.2.1
  • In case you want to enable HDF5 support, set HDF5_DIR to the HDF_Group/HDF5/1.12.2/share/cmake subdirectory of where you extracted the HDF5 build files.
  • Enable the modules you want to build (by enabling any of the Module_[ModuleName] options, or by enabling openiA_BUILD_ALL_MODULES to automatically enable all modules)
  • Click "Configure" again.
  • When CMake does not report errors anymore when Configuring, click "Generate".
• Open a command line in /workspace/open_iA/bin
• Build open_iA If you chose the make build system, run $ make -j 8, for ninja run $ ninja

See Build Options open_iA.

For more potential problems, see the troubleshooting section of our superbuild

Problem: Some of our modules are using OpenMP, and when using e.g. the clang compiler, this might require the installation of additional packages.

Solution: Install the package containing the LLVM OpenMP library; e.g. on Ubuntu, do sudo apt install libomp-dev

Problem: The open_iA build fails with "[...]dreamcaster.h:25:30: fatal error: ui_dream_caster4.h: File or directory not found"

Workaround: Run cmake once more. Note - this should be fixed in recent versions of open_iA (>= 2018.11). If you still get it, please let us know (e.g. via an issue).

Problem: The build fails with an error complaining about a missing CL/cl.hpp. This is due to open_iA currently still requiring an 1.x version of OpenCL, while newer versions of Linux come only with the 2.x headers (cl2.hpp) - substitution is unfortunately not easily possible, it would require some code rewrite.

Workaround: Use the OpenCL-ICD library possibly included in the package repository of your distribution, build it from source, as described in the OpenCL build instructions, or use an older OpenCL implementation, e.g. the one included in the CUDA SDK; in CMake, specify /usr/local/cuda/include as OPENCL_INCLUDE_DIRS and /usr/local/cuda/lib64/libOpenCL.so as OPENCL_LIBRARIES (when the CUDA SDK, e.g. version 8.0, is installed in /usr/local/cuda).

If you get error messages like this during a ninja build:

{standard input}: Assembler messages:
{standard input}:2211035: Warning: File end is not at the end of a line; added new line
{standard input}:2211222: Error: unknown pseudo-op: `.uleb12'
{standard input}:2211219: Error: invalid operands (*AND* and .gcc_except_table sections) for `-'
g++: fatal error: Killed signal terminated program cc1plus
compilation terminated.

or similar messages, your build probably runs out of memory. Either just restart the ninja, but this might terminate again in a similar fashion, so you might have to restart it multiple times), or restrict the number of compilations running in parallel via the -j <NumOfProcesses> option (by default, ninja starts a lot of parallel processes, which can lead to using more than 32GB RAM).

When compiling on very recent versions of Linux (gcc >= 9 / clang >= 10), you might receive errors such as this:

In file included from /usr/include/cuda_runtime.h:83,
                 from <command-line>:
/usr/include/crt/host_config.h:138:2: error: #error -- unsupported GNU version! gcc versions later than 8 are not supported!
  138 | #error -- unsupported GNU version! gcc versions later than 8 are not supported!

In this case, set the CUDA_HOST_COMPILER to a lower version of your compiler, e.g. /usr/bin/gcc-8.

We mostly build open_iA on Windows; there are some issues that occur on Linux but are not an issue on Windows. We do run daily builds on Linux, so at least in the develop branch there shouldn't be any such issues, but with other branchs, such issues might occur:

• Wrong case in includes. e.g. #include <qButton>. Linux is case-sensitive regarding files, and thus requires #include <QButton>
• Missing includes e.g. for size_t datatype. size_t requires #include <cstddef> under Linux.
• Missing typename keyword. Visual Studio (< 2017 15.6, and again for VS 2019 somehow) does some simpler template evaluation scheme and therefore does not require the typename keyword for dependent types (e.g. a typedef defined inside a class defined as template, such as if you declare typedef itk::Image<T, 3> ImageType; and then say somewhwere ImageType::Pointer xyz;. Under Linux, you need to write typename ImageType::Pointer.