Chapter 2
Compiling OTB from source

There are two ways to install OTB library on your system: installing from a binary distribution or compiling from sources. You can find information about the installation of binary packages for OTB and Monteverdi in the OTB-Cookbook.

This chapter covers compilation of OTB library from source. Note that it covers also the compilation of Monteverdi which is integrated as an OTB module since version 5.8.

OTB has been developed and tested across different combinations of operating systems, compilers, and hardware platforms including Windows, Linux and Mac OSX. It is known to work with the following compilers in 32/64 bit:

Since release version 6.2.0, OTB is compiled using the C++14 standard by default.

The challenge of supporting OTB across platforms has been solved through the use of CMake, a cross-platform, open-source build system. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it supports complex environments requiring system configuration, compiler feature testing, and code generation.

CMake supports several generators to produce the compilation scripts, dependending on the platform and compiler. It can use :

The information used by CMake is provided by CMakeLists.txt files that are present in every directory of the OTB source tree. These files contain information that the user provides to CMake at configuration time. Typical information includes paths to utilities in the system and the selection of software options specified by the user.

There are (at least) two ways to use CMake :

As shown in figure 2.1, CMake has a different interfaces according to your system. Refer to section 2.1 for Linux and Mac OS X build instructions and 2.2 for Windows.


PIC PIC

Figure 2.1: CMake interface. Top) ccmake, the UNIX version based on curses. Bottom) CMakeSetup, the MS-Windows version based on MFC.


For more information on CMake, check :

http://www.cmake.org

OTB depends on a number of external libraries. Some are mandatory, meaning that OTB cannot be compiled without them, while others (the majority) are optional and can be activated or not during the build process. See table 2.1 for the full list of dependencies.



Table 2.1: External libraries used in OTB.

2.1 Linux and Mac OS X

2.1.1 Setting up the build environment

The first thing to do is to create a directory for working with OTB. This guide will use ~/OTB but you are free to choose something else. In this directory, there will be three locations:

To setup this structure, the following commands can be used:

$ mkdir ~/OTB  
$ cd ~/OTB  
$ git clone https://git@git.orfeo-toolbox.org/git/otb.git  
$ mkdir build  
$ mkdir install

The OTB project uses a git branching model where develop is the current development version. It contains the latest patches and represents the work in progress towards the next release. For more information on OTB and git, including how to decide which branch to want to compile, please see the OTB wiki page at http://wiki.orfeo-_toolbox.org/index.php/Git.

Checkout the relevant branch now:

$ cd ~/OTB/otb  
$ git checkout develop

Now you must decide which build method you will use. There are two ways of compiling OTB from sources, depending on how you want to manage dependencies. Both methods rely on CMake.

If you do not know which method to use and just want to compile OTB with all its modules, use SuperBuild.




CMake variable

Value



CMAKE_INSTALL_PREFIX

Installation directory, target for make install

BUILD_EXAMPLES

Activate compilation of OTB examples

BUILD_TESTING

Activate compilation of the tests

OTB_BUILD_DEFAULT_MODULES

Activate all usual modules, required to build the examples

OTB_USE_XXX

Activate module XXX

OTBGroup_XXX

Enable modules in the group XXX

OTB_DATA_ROOT

otb-data repository

OTB_WRAP_PYTHON

Enable Python wrapper

OTB_WRAP_JAVA

Enable Java wrapper



SuperBuild only

DOWNLOAD_LOCATION

Location to download dependencies

USE_SYSTEM_XXX

Use the system’s XXX library




Table 2.2: Important CMake configuration variables in OTB

2.1.2 SuperBuild: Build OTB and all dependencies

The SuperBuild is a way of compiling dependencies to a project just before you build the project. Thanks to CMake and its ExternalProject module, it is possible to download a source archive, configure and compile it when building the main project. This feature has been used in other CMake-based projects (ITK, Slicer, ParaView,...). In OTB, the SuperBuild is implemented with no impact on the library sources : the sources for SuperBuild are located in the ’OTB/SuperBuild’ subdirectory. It is made of CMake scripts and source patches that allow to compile all the dependencies necessary for OTB. Once all the dependencies are compiled and installed, the OTB library is built using those dependencies.

OTB’s compilation is customized by specifying configuration variables. The most important configuration variables are shown in table 2.2. The simplest way to provide configuration variables is via the command line -D option:

$ cd ~/OTB/build  
$ cmake -D CMAKE_INSTALL_PREFIX=~/OTB/install ../otb/SuperBuild

A pre-load script can also be used with the -C options (see https://cmake.org/cmake/help/v3.4/manual/cmake.1.html#options). Another option is to set variables manually with cmake-gui or ccmake.

Please note that the CMAKE_INSTALL_PREFIX variable is important because the SuperBuild will install some targets during the compilation step. Therefore this directory will be used even if you don’t use make install target. In fact there is no make install target for the SuperBuild. Also note that if not specified to cmake, a default install dir will be used, located in ../superbuild_install.

By default, SuperBuild will not use any of libraries installed on system. All USE_SYSTEM_XXX are set to FALSE. This is our recommended way of using SuperBuild. You are however free to use a system library if you want!. You must be very much aware of dependencies of those libraries you use from system. For example, if libjpeg is not used from superbuild then you should not use zlib from superbuild because zlib is a dependency of libjpeg. Here SuperBuild will NOT set USE_SYSTEM_ZLIB=FALSE. One must re-run cmake with -DUSE_SYSTEM_ZLIB=FALSE. Above example of libjpeg-zlib dependency is so simple. Imagine the case for GDAL which depends on zlib, libjpeg, libtiff(with big tiff support), geotiff, sqlite, curl, geos, libkml, openjpeg. This is one of the reasons we recommend to use SuperBuild exclusively.

All dependencies are configured and built in a way that help us to get an efficient build OTB. So we enable geotiff (with proj4 support), openjpeg, geos in GDAL build.

(see table 2.2).

SuperBuild downloads dependencies into the DOWNLOAD_LOCATION directory, which will be ~/OTB/build/Downloads in our example. Dependencies can be downloaded manually into this directory before the compilation step. This can be useful if you wish to bypass a proxy, intend to compile OTB without an internet connection, or other network constraint. You can find an archive with sources of all our dependencies on the Orfeo ToolBox website (pick the ’SuperBuild-archives’ corresponding to the OTB version you want to build) :

https://www.orfeo-_toolbox.org/packages

Qt library: Unlike other dependencies building Qt4 on all platform is not trivial task but OTB SuperBuild makes best effort to make it easier for you. So there is still some additional package installation, one has to do as a pre-requistie for SuperBuild On a GNU/Linux you must have Qt X11 dependencies installed. See Qt 4.8 documentation for list of packages that needs to be installed before starting superbuild. http://doc.qt.io/qt-4.8/requirements-x11.html For a debian 8.1 systeme, I installed all Qt4 dependencies with below ’apt-get install’ apt-get install libx11-dev libxext-dev libxt-dev libxi-dev libxrandr-dev libgl-dev libglu-dev

You can also deactivate QT4 and skip this by passing -DOTB_USE_QT4=OFF to cmake. This will give you OTB install without monteverdi, mapla and gui application launchers.

For Mac OSX you need to install XCode and Windows 7,8.1,10 requires MSVC 2015 or higher.

You are now ready to compile OTB! Simply use the make command (other targets can be generated with CMake’s -G option):

$ cd ~/OTB/build  
$ make

Applications will be located in the bin/ directory in CMAKE_INSTALL_PREFIX directory, which in our case is  /OTB/install/bin/. For example:

~/OTB/install/bin/otbcli_ExtractROI

will launch the command line version of the ExtractROI application, while:

./OTB/install/bin/otbgui_ExtractROI

will launch the graphical version.

To be able to use your OTB build from everywhere, we recommend the following. First, add bin/ directory to your PATH for easy access:

export PATH=$PATH:~/OTB/install/bin

Second, add the lib/ directory to your LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=~/OTB/install/lib:$LD_LIBRARY_PATH

Monteverdi is integrated as an OTB module since release 5.8 and it is compiled by the SuperBuild (as long as GLEW, GLUT, OPENGL, Qt and QWT modules are activated).

To use OTB applications from within Monteverdi you will need to define the OTB_APPLICATION_PATH environment variable.

export OTB_APPLICATION_PATH=~/OTB/install/lib/otb/applications  
monteverdi

A wiki page detailing the status of SuperBuild on various platforms is also available here: http://wiki.orfeo-_toolbox.org/index.php/SuperBuild.

2.1.3 Normal build: Build only OTB

Once all OTB dependencies are availables on your system, use CMake to generate a Makefile:

$ cd ~/OTB/build  
$ cmake -C configuration.cmake ../otb

The script configuration.cmake needs to contain dependencies location if CMake cannot find them automatically. This can be done with the XXX_DIR variables containing the directories which contain the FindXXX.cmake scripts, or with the XXX_INCLUDEDIR and XXX_LIBRARY variables.

Additionally, decide which module you wish to enable, together with tests and examples. Refer to table 2.2 for the list of CMake variables.

Since OTB is modularized, it is possible to only build some modules instead of the whole set. To deactivate a module (and the ones that depend on it) switch off the CMake variable OTB_BUILD_DEFAULT_MODULES, configure, and then switch off each Module_module_name variable. To provide an overview on how things work, the option COMPONENTS of the CMake command find_package is used in order to only load the requested modules. This module-specific list prevent CMake from performing a blind search; it is also a convienent way to monitor the dependencies of each module.

find_package(OTB COMPONENTS OTBCommon OTBTransform [...])

Some of the OTB capabilities are considered as optional, and you can deactivate the related modules thanks to a set of CMake variables starting with OTB_USE_XXX. Table 2.3 shows which modules are associated to these variables. It is very important to notice that these variable override the variable OTB_BUILD_DEFAULT_MODULES.

You are now ready to compile OTB! Simply use the make command (other targets can be generated with CMake’s -G option):

$ make

The installation target will copy the binaries and libraries to the installation location:

$ make install





CMake variable 3rd party module

Modules depending on it




OTB_USE_LIBKML OTBlibkml

OTBKMZWriter OTBIOKML OTBAppKMZ




OTB_USE_QT4 OTBQt4

OTBQtWidget




OTB_USE_QWT OTBQwt

OTBMonteverdiGUI OTBMonteverdi




OTB_USE_GLEW OTBGlew

OTBIce OTBMonteverdiGUI OTBMonteverdi




OTB_USE_OPENGL OTBOpenGL

OTBIce OTBMonteverdiGUI OTBMonteverdi




OTB_USE_CURL OTBCurl




OTB_USE_MUPARSER OTBMuParser

OTBMathParser OTBDempsterShafer OTBAppClassification OTBAppMathParser OTBAppStereo OTBAppProjection OTBAppSegmentation OTBAppClassification OTBRoadExtraction OTBRCC8 OTBCCOBIA OTBAppSegmentation OTBMeanShift OTBAppSegmentation OTBMeanShift OTBAppSegmentation




OTB_USE_MUPARSERXOTBMuParserX

OTBMathParserX OTBAppMathParserX




OTB_USE_LIBSVM OTBLibSVM

optional for OTBSupervised OTBAppClassification




OTB_USE_OPENCV OTBOpenCV

optional for OTBSupervised OTBAppClassification




OTB_USE_SHARK OTBShark

optional for OTBSupervised OTBAppClassification




OTB_USE_MAPNIK OTBMapnik

OTBVectorDataRendering




OTB_USE_6S OTB6S

OTBOpticalCalibration OTBAppOpticalCalibration OTBSimulation




OTB_USE_SIFTFAST OTBSiftFast





Table 2.3: Third parties and related modules.

2.2 Windows

Everything that is needed for OTB development on Windows, including compiling from source, is covered in details on the OTB wiki at:

http://wiki.orfeo-_toolbox.org/index.php/OTB_development_on_Windows

2.3 Known issues

It is important to know that the OpenJpeg library doesn’t support name mangling since version 2.0. As a consequence, if other libraries linked by your project already contain OpenJpeg, there may be a symbol conflict at run-time. For instance, this was observed with OTB build on a recent ITK version (ver. 4). The ITK library already had a version of OpenJpeg in libitkopenjpeg-*.so, which contained the OpenJpeg symbols un-wrapped. These symbols were also loaded by the GDAL driver but only the first ones were used, which caused a crash.

Hopefully, thanks to the modular architecture of ITK, the library libitkopenjpeg-*.so is not imported anymore inside OTB. However the OpenJPEG headers may be present in ITK include directory. As the current architecture doesn’t allow to tune include order between modules, the OpenJPEG header from ITK can be included before your own OpenJPEG install. There are two ways to avoid this situation :

More information can be found here : http://wiki.orfeo-_toolbox.org/index.php/JPEG2000_with_GDAL_OpenJpeg_plugin

Another issue is related to the official package of libkml under Ubuntu 12.4. Until this problem is addressed, users of this plateform should disable the option OTB_USE_KML, so that OTB won’t be built with this third-party.