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 installation from sources, also known as compiling.

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

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 build instructions, ?? for Mac OS X, 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 are optional and can be activated or not during the build process. See table 2.1 for the full list of dependencies.






Library

Web site

Mandatory

Minimum version





ITK

http://www.itk.org

yes

4.6.0





GDAL

http://www.gdal.org

yes

1.10





OSSIM

http://www.ossim.org

yes

r23537 recommended





Curl

http://www.curl.haxx.se

no

-





FFTW

http://www.fftw.org

no

-





libgeotiff

http://trac.osgeo.org/geotiff/

yes

-





OpenJPEG

http://code.google.com/p/openjpeg/

no

-





boost

http://www.boost.org

yes

-





openthreads

http://www.openscenegraph.org

yes

-





Mapnik

http://www.mapnik.org

no

-





tinyXML

http://www.grinninglizard.com/tinyxml

yes

-





6S

http://6s.ltdri.org

no

-





SiftFast

http://libsift.sourceforge.net

no

-





MuParser

http://www.muparser.sourceforge.net

no

-





MuParserX

http://muparserx.beltoforion.de

no

3.0.5





libSVM

http://www.csie.ntu.edu.tw/~cjlin/libsvm

no

2.0





Qt

http://qt-_project.org/

no

4





OpenCV

http://opencv.org

no

2






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, compile and install 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_LOCATION=~/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.

During the configuration step, the SuperBuild will detect any existing dependencies installed as systems libraries. Wheter to use them can be controlled via the USE_SYSTEM_XXX (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 usefull if you wish to bypass a proxy, intend to compile OTB without an internet conection, or other network constraint. You can find a complete bundle with all dependencies sources on the Orfeo ToolBox website (pick the ’SuperBuild-archives’ corresponding to the OTB version you want to build) :

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

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

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

$ make install

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_OPENCV OTBOpenCV




OTB_USE_MUPARSERXOTBMuParserX

OTBMathParserX OTBAppMathParserX




OTB_USE_OPENJPEG OTBOpenJPEG

OTBIOJPEG2000




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_LIBSVM OTBLibSVM

OTBSVMLearning




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.