This section describes the process for installing OTB on your system. OTB is a toolbox, and as such, once it is installed in your computer, it provides by default a set of useful libraries. You can use these libraries to build your own applications based on it. What OTB does provide, besides the toolbox, is a large set of test files and examples that will introduce you to OTB concepts and will show you how to use OTB in your own projects.
Since the release 3.12, OTB embeds a specific framework to generate applications in a more user-friendly way. OTB provides for each application one shared library (also known as plugin). This plugin can be auto-loaded into appropriate tools without recompiling, and is able to fully describe its own parameters, behavior and documentation.
The tools to use these plugins can be extended, but OTB is shipped with the following:
Based on a visualization framework which used FLTK libraries, Orfeo ToolBox team provides an integrated application which giving graphical access to a lot of OTB functionalities: Monteverdi. Since mid-2013, we also provide a new graphical application based on Qt: Monteverdi2. This new application used the OTB-Applications tools as processing framework.
There are two ways to install OTB library on your system: installing from a binary distribution or compiling from sources. The choice depends on your system, and on what you intend to do. If you intend compiling from source, OTB team provides the SuperBuild feature, which is designed to provide an easy access to OTB and its dependencies. SuperBuild is available since the release 5.0 (revision c20055670b36 / Tue, 24 Mar 2015 18:22:06).
You can find all information about the installation of binary packages for OTB-Applications, Monteverdi and Monteverdi2 (if they are available on your platform) into the OTB-Cookbook.
The binary packages for OTB library are only available on:
Currently, no OSGeo4W package is available for the OTB library, you need to build from source to use it on windows platform. However you can find binary packages for Monteverdi, Monteverdi2 and OTB-Applications (command-line, QT based and python ones).
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:
Given the advanced usage of C++ features in the toolbox, some compilers may have difficulties processing the code. If you are currently using an outdated compiler this may be an excellent excuse for upgrading this old piece of software!
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 generates Makefiles under UNIX systems and generates Visual Studio workspaces under Windows (and appropriate build files for other compilers like Borland). 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.
CMake can be downloaded at no cost from
OTB requires at least CMake version 2.8.6. You can download binary versions for most of the popular platforms including Windows, Solaris, IRIX, HP, Mac and Linux. Alternatively you can download the source code and build CMake on your system. Follow the instructions in the CMake Web page for downloading and installing the software.
CMake runs in an interactive mode in that you iteratively select options and configure according to these options. The iteration proceeds until no more options remain to be selected. At this point, a generation step produces the appropriate build files for your configuration.
This interactive configuration process can be better understood if you imagine that you are walking through a decision tree. Every option that you select introduces the possibility that new, dependent options may become relevant. These new options are presented by CMake at the top of the options list in its interface. Only when no new options appear after a configuration iteration can you be sure that the necessary decisions have all been made. At this point build files are generated for the current configuration.
As the following figures display it, CMake has a different interface according to your systems.
Running CMake initially requires that you provide three pieces of information:
These are referred to as the source directory, the binary directory and the install directory. We recommend setting the binary directory to be different than the source directory (an out-of-source build), but OTB will still build if they are set to a directory inside the source directory (an in-source build).
The OTB needs some external libraries to work (see table 2.1 below).
Library | Web site | Mandatory | Minimum version |
ITK | yes | 4.5.0 |
|
GDAL | yes | 1.10 |
|
OSSIM | yes | 1.8.6 |
|
Curl | no | - |
|
FFTW | no | - |
|
libgeotiff | yes | - |
|
OpenJPEG | no | - |
|
boost | yes | - |
|
openthreads | yes | - |
|
Mapnik | no | - |
|
tinyXML | yes | - |
|
6S | no | - |
|
SiftFast | no | - |
|
MuParser | no | - |
|
MuParserX | no | 3.0.5 |
|
libSVM | no | 2.0 |
|
Qt | no | 4 |
|
OpenCV | no | - |
|
To manage correctly and easily the dependencies of OTB (especially under Windows) we strongly recommend to use the SuperBuild feature (see next subsection 2.2.2). Once the dependencies are built, OTB can finally be compiled :
Compilation awarness The build process will typically take anywhere from 15 to 30 minutes depending on the performance of your system. If you decide to enable testing as part of the normal build process, about 2500 small tests programs will be compiled. This will verify that the basic components of OTB have been correctly built on your system.
Set the CMake variables BUILD_TESTING and BUILD_EXAMPLES to ON will activate the compilation of the examples and the tests and slow down the build process. The examples distributed with the toolbox are a helpful resource for learning how to use OTB components but are not essential for the use of the toolbox itself. The testing section includes a large number of small programs that exercise the capabilities of OTB classes. Due to the large number of tests, enabling the testing option will considerably increase the build time. It is not desirable to enable this option for a first build of the toolbox.
The CMake variable OTB_BUILD_DEFAULT_MODULES activates all usual modules. This is required to build the examples. If you want to reduce the set of enabled modules, in order to produce a smaller OTB or to avoid some third parties, you have two methods :
Note 1: Those who want to avoid using the SuperBuild (even partially) or to use additional dependencies not provided by the SuperBuild, should refer to the subsection 2.2.3.
Note 2: Please note that even if this section only describes how to compile OTB library and applications from sources, Monteverdi1 and Monteverdi2 can be compiled in a similar way.
For Monteverdi, in addition to OTB, FLTK is required (http://www.fltk.org) as an external dependency. Therefore, you need to install it from your package manager or build it from source. For windows users, you can find it through the OSGeo4W installer.
For Monteverdi2, in addition to OTB, Qt4 (http://qt-_project.org/) and Qwt5 (http://qwt.sourceforge.net/) are required as external dependencies. Therefore, you need to install them from your package manager or build them from source. For windows users, you can find them through the OSGeo4W installer.
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.
The purpose is to provide an easy way to get OTB and its dependencies, whatever the platform (among Linux, MacOSX and Windows).
There are few requirements to use the SuperBuild :
There are optional requirements depending on OTB features you want to enable :
The SuperBuild is made like a standard CMake-type project. You should then prepare three directories (for source, build and install) : OTB_SOURCE_DIR, OTB_BINARY_DIR, OTB_INSTALL_DIR.
This section details the libraries that are not fully supported by SuperBuild depending on the target platform.
Windows MSVC 2010
The libraries not handled by SuperBuild are :
Note : there is a limitation on the absolute path length for the source directory and build directory : it should not exceed 50 characters. In fact, this limitation is not related to the SuperBuild but comes with OTB.
MacOSX 10.10
The libraries not handled by SuperBuild are :
Linux
The libraries not handled by SuperBuild are :
A wiki page is also available here : http://wiki.orfeo-_toolbox.org/index.php/SuperBuild.
To manage the dependencies of OTB under Windows without SuperBuild, users should install the OSGeo4W tool. This software will provide you with all the necessary dependencies in 32 bit and 64 bit mode. Please follow these steps:
Create a directory, where you have write access, to store your work. Download the OTB sources (see subsection 1.3.1) : OTB_SOURCE_DIR. Create the two other usual directories OTB_BINARY_DIR and OTB_INSTALL_DIR.
We will describe here how to compile and install the library with the main functionalities in Release and ReleaseWithDebugInfo mode. Create an OTB.bat file into your MyOTBDir and copy paste the following lines:
Into a OSGEo4W shell, run the OTB.bat with the right arguments: full path to the OTB src directory, full path to the OTB build directory, full path to the place where install OTB. Take a break, you made it: OTB is installed in your install directory. If you want test: into an OSGeo4W shell, go to the bin directory of the install directory and run HelloWorld.exe. If you want build OTB in Release config, into the OSGeo4W shell, open the OTB.sln and select this configuration from the configuration selector and build the solution.
If you want use more recent MS-compiler please change the path to vsvars32.bat file and change the generator used by cmake line. OTB should support compilation under Visual Studio 2012 and 2013.
That should be all! Otherwise, subscribe to otb-users@googlegroups.com and you will get some help.
Manual installation of OTB dependencies can easily be done under unix platforms, either directly by package managers (be sure to also install libraries headers, which are mandatory to build OTB) or by compiling from sources (follow the build instructions for each particular dependence).
However, special precautions are necessary concerning Gdal.
Gdal is a very rich data abstraction library, and there are many compilation time options in Gdal that will impact Gdal and therefore OTB libraries capabilities. There are also options and dependencies that could limit or prevent Orfeo ToolBox from working properly. On linux systems, there are a lot of Gdal binary packages with different configurations. It is therefore very important to know exactly your Gdal configuration before proceeding to the next step.
Here are the things to check:
If you already have a Gdal in your system (either from the official package manager of your distribution or from your own build), here is how to check if it qualifies for Orfeo ToolBox.
Gdal version can be checked using the following command:
If version is lower than 1.10.0, you should build or install an up-to-date Gdal library.
If you have several versions of Gdal installed in your system, be sure to run this command for the version you intend to. You can check this with:
Next step is to check if the Gdal library leaks any Tiff or Geotiff symbol. First you need to locate gdal library. If it has been installed system wide, the library will most probably be located in /usr/lib. Otherwise, you need to find where is libgdal.so.
Once you found it, run:
This should show either nothing, or the following:
If the command outputs the following:
It means that your Gdal library leaks Tiff and Geotiff symbols. Depending on your system, this might cause random crashes in Orfeo ToolBox when reading or writing Tiff images. In this case it is advised to build or retrieve a Gdal library that does not exhibit this issue.
Last, it might be important for you to be able to read and write Tiff files of more than 4 Gb with Orfeo ToolBox. To check for BigTiff file support, choose an image on your computer and run:
If this fails, your Gdal library or the Tiff library it is linked to does not support BigTiff files. In this case it is advised to build or retrieve a Gdal library.
Distributions and binary packages repositories known to distribute a qualified Gdal
Among the different distributions and packages repositories that distribute a qualified Gdal, one can cite:
Building your own qualified Gdal
If do not yet have a Gdal library or suspect that the library you have will not qualify, you can build your own library. After downloading the latest version of gdal source code, run:
The GDAL_INSTALL_DIR environment variable allows to choose where you will install your Gdal library. It is NOT advised to install it system wide. It is recommended to choose a dedicated directory in your home folder. The configuration options will ensure that Gdal will build internal Tiff and Geotiff libraries that supports BigTiff files, while renaming their symbols so that they will not be leaked outside of the library. Depending on your need, feel free to enable more Gdal configuration options.
Once this is done, be sure to update your environment variables:
Also note that with this Gdal configuration, you will still need to have Tiff and Geotiff libraries and headers available on your system to build OTB (due to third parties requiring them). However, you can use the system packages for those.
COMPONENTS Since OTB is modularized, it is possible to only build some modules instead of the whole set. You can deactivate each module (and the ones that depend on it) one by one from the cmake interface. You just have to switch off the cmake variable OTB_BUILD_DEFAULT_MODULES, press Configure, and then switch off each Module_module_name variable (). To provide an overview on how things work, the otion 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.
Some of the OTB capabilities are considered as optional, and you can deactivate the related modules thanks to the following cmake variables: OTB_USE_LIBKML, OTB_USE_QT4, OTB_USE_OPENCV, OTB_USE_MUPARSERX, OTB_USE_OPENJPEG, OTB_USE_CURL, OTB_USE_MUPARSER, OTB_USE_LIBSVM, OTB_USE_MAPNIK, OTB_USE_6S, OTB_USE_SIFTFAST. It is very important to notice that these variable override the variable OTB_BUILD_DEFAULT_MODULES.
The table below shows which modules are deactivated when switching off these variables:
Cmake variable | Modules |
OTB_USE_LIBKML | OTBlibkml OTBKMZWriter OTBIOKML OTBAppKMZ |
OTB_USE_QT4 | OTBQt4 OTBQtWidget |
OTB_USE_OPENCV | OTBOpenCV |
OTB_USE_MUPARSERX | OTBMuParserX 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 |
Every cmake variable mentionned in this subsection are set to ON by default, except OTB_USE_MAPNIK; this means that, by default, all the modules are built except OTBMapnik and OTBVectorDataRendering.
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.
The simplest way to create a new project with OTB is to create a new directory somewhere in your disk and create two files in it. The first one is a CMakeLists.txt file that will be used by CMake to generate a Makefile (if you are using UNIX) or a Visual Studio workspace (if you are using MS-Windows). The second file is an actual C++ program that will exercise some of the large number of classes available in OTB. The details of these files are described in the following section. Under Windows, we provide a specifc example to show you how to proceed.
For Unix users, once both files are in your directory you can run CMake in order to configure your project. Under UNIX, you can cd to your newly created directory and type “ccmake .”. Note the “.” in the command line for indicating that the CMakeLists.txt file is in the current directory. The curses interface will require you to provide the directory where OTB was built. This is the same path that you indicated for the OTB_BINARY_DIR variable at the time of configuring OTB. Then CMake will require you to provide the path to the binary directory where OTB was built. The OTB binary directory will contain a file named OTBConfig.cmake generated during the configuration process at the time OTB was built. From this file, CMake will recover all the information required to configure your new OTB project.
This section is dedicated to Unix or Linux or MacOsX users, the next section provide specific information for Windows users.
Here is the content of the two files to write in your new project. These two files can be found in the OTB/Examples/Installation directory. The CMakeLists.txt file contains the following lines:
The first line defines the name of your project. The second line loads a CMake file with a predefined strategy for finding OTB 1 . If the strategy for finding OTB fails, CMake will prompt you for the directory where OTB is installed in your system. In that case you will write this information in the OTB_DIR variable. The line INCLUDE(${USE_OTB_FILE}) loads the UseOTB.cmake file to set all the configuration information from OTB.
The line ADD_EXECUTABLE defines as its first argument the name of the executable that will be produced as result of this project. The remaining arguments of ADD_EXECUTABLE are the names of the source files to be compiled and linked. Finally, the TARGET_LINK_LIBRARIES line specifies which OTB libraries will be linked against this project.
The source code for this example can be found in the file
Examples/Installation/HelloWorld.cxx.
The following code is an implementation of a small OTB program. It tests including header files and linking with OTB libraries.
This code instantiates an image whose pixels are represented with type unsigned short. The image is then constructed and assigned to a itk::SmartPointer . Although later in the text we will discuss SmartPointer’s in detail, for now think of it as a handle on an instance of an object (see section 3.2.4 for more information). The itk::Image class will be described in Section 5.1.
At this point you have successfully installed and compiled OTB, and created your first simple program. If you have difficulties, please join the otb-users mailing list (Section 1.4.1 on page 15) and post questions there.
Create a directory (with write access) where to store your work (for example at C:\path\to\MyFirstCode). Organize your repository as it :
Follow the following steps: