CompilingOTBFromSource.rst 23 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
Compiling OTB from source
=========================

This section covers the compilation of OTB from source code using `CMake
<http://www.cmake.org>`_. If you just need to install OTB and Monteverdi, follow
instructions from the :doc:`Installation` section.

OTB is known to work on:

* Visual Studio 2015 on Windows

* GCC 4.x, 5.x or Clang 3.x on GNU/Linux

* AppleClang on macOS (10.8 or higher)

The C++14 standard is required since version 6.2.0.

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:

.. table:: External libraries used in OTB
    :widths: 50 20 30
    :align: center

    +------------------------------------------------------------------+-----------------------+--------------------------+
    | **Library**                                                      | **Mandatory**         | **Minimum version**      |
    +==================================================================+=======================+==========================+
    | `ITK <http://www.itk.org>`_                                      | Yes                   | 4.6.0                    |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `GDAL <http://www.gdal.org>`_                                    | Yes                   | 2.0                      |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `OSSIM <http://www.ossim.org>`_                                  | Yes                   | 1.8.20-3                 |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `libgeotiff <http://trac.osgeo.org/geotiff/>`_                   | Yes                   |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `boost <http://www.boost.org>`_                                  | Yes                   |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `openthreads <http://www.openscenegraph.org>`_                   | Yes                   |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `tinyXML <http://www.grinninglizard.com/tinyxml>`_               | Yes                   |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `6S <http://6s.ltdri.org>`_                                      | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `Curl <http://www.curl.haxx.se>`_                                | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `FFTW <http://www.fftw.org>`_                                    | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `GLEW <http://glew.sourceforge.net/>`_                           | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `GLFW <http://www.glfw.org/>`_                                   | No                    | 3                        |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `GLUT <https://www.opengl.org/resources/libraries/glut/>`_       | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `libKML <https://github.com/google/libkml>`_                     | No                    | 1.2                      |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `libSVM <http://www.csie.ntu.edu.tw/~cjlin/libsvm>`_             | No                    | 2.0                      |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `MPI <https://www.open-mpi.org/>`_                               | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `MuParser <http://www.muparser.sourceforge.net>`_                | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `MuParserX <http://muparserx.beltoforion.de>`_                   | No                    | 4.0.7                    |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `OpenCV <http://opencv.org>`_                                    | No                    | 2 (3.x also supported)   |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `OPENGL <https://www.opengl.org/>`_                              | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `Qt <https://www.qt.io/developers/>`_                            | No                    | 5                        |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `QWT <http://qwt.sourceforge.net>`_                              | No                    | 6                        |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `Shark <http://image.diku.dk/shark/>`_                           | No                    | 3.1                      |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `SiftFast <http://libsift.sourceforge.net>`_                     | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+
    | `SPTW <https://github.com/remicres/sptw.git>`_                   | No                    |                          |
    +------------------------------------------------------------------+-----------------------+--------------------------+

GNU/Linux and macOS
-------------------

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:

*  ``~/OTB/otb`` for the source git repository

*  ``~/OTB/build`` for the intermediate build objects, CMake specific
   files, libraries and binaries.

*  ``~/OTB/install``, the installation directory for OTB once it is
   built. A system location (``/usr/local`` for example) can also be
   used, but installing locally is more flexible and does not require
   root access.

::

    $ mkdir ~/OTB
    $ cd ~/OTB
    $ git clone https://gitlab.orfeo-toolbox.org/orfeotoolbox/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. ``master`` is the latest stable release.

Checkout the branch you want to build now:

::

    $ cd ~/OTB/otb
    $ git checkout develop

Now, there are two ways of compiling OTB from source, depending on how you want
to manage dependencies. Both methods rely on CMake.

* **SuperBuild**: All OTB dependencies are automatically downloaded and
  compiled.  This method is the easiest to use and provides a complete OTB with
  minimal effort.

* **Normal build**: OTB dependencies must already be compiled and available on
  your system. This method requires more work but provides more flexibility.

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

Important CMake configuration variables:

* ``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

SuperBuild only:

* ``DOWNLOAD_LOCATION``: Location to download dependencies
* ``USE_SYSTEM_XXX``: Use the system’s *XXX* library

SuperBuild: Build OTB and all dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

OTB’s compilation is customized by specifying configuration variables.
The most important configuration variables are shown in the
table above. 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

You can also 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 `OFF`. 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 OTB build. So we enable geotiff (with proj4 support),
openjpeg, geos in GDAL build.

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 constraints. You can find an archive with sources
of all our dependencies on `the Orfeo ToolBox website
<https://www.orfeo-toolbox.org/packages>`_ (pick the ’SuperBuild-archives’
corresponding to the OTB version you want to build).

**Notes about Qt:** Unlike other dependencies, building Qt5 on all platforms is
not a trivial task but OTB SuperBuild does its best to facilitate this for the
user. 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 5 documentation
<https://doc.qt.io/qt-5/linux-requirements.html>`_ for the list of packages that
need to be installed before starting SuperBuild.

For example for a Debian 8.1 system, all Qt5 dependencies can be installed with the
following ’apt-get install’ command:

::

    apt-get install libx11-dev libxext-dev libxt-dev libxi-dev libxrandr-dev libgl-dev libglu-dev libxinerama-dev libxcursor-dev

You can also deactivate Qt5 and skip this by passing
``-DOTB_USE_QT=OFF`` to CMake, but this will install OTB without
Monteverdi, Mapla and the GUI application launchers.

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 ``CMAKE_INSTALL_PREFIX/bin/`` directory:

::

    ~/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.

In order to ensure access to your OTB build from anywhere within your
system, we recommend setting the following environment variables.
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 part of OTB module and is compiled by the SuperBuild if 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

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 above for the list of CMake variables.

OTB is modular. 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.

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``. The table below 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\_QT**          | OTBQt                  | 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 OTBRoadExtraction OTBRCC8 OTBCCOBIA OTBMeanShift   |
+---------------------------+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **OTB\_USE\_MUPARSERX**   | OTBMuParserX           | 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\_6S**          | OTB6S                  | OTBOpticalCalibration OTBAppOpticalCalibration OTBSimulation                                                                                                              |
+---------------------------+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **OTB\_USE\_SIFTFAST**    | OTBSiftFast            |                                                                                                                                                                           |
+---------------------------+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Table: Third parties and related modules.

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

Known issues
------------

Please check `our gitlab tracker <https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues?label_name%5B%5D=bug>`_ for a list of open bugs.
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376

Tests
-----

There are more than 2500 tests for OTB. It can take from 20 minutes to 3
hours to run them all, depending on compilation options
(release mode does make a difference) and hardware.

To run the tests, first make sure to set the option
``BUILD_TESTING`` to ``ON`` before building the library.

For some of the tests, you also need the test data and the baselines (~1GB):

::

    git clone https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb-data.git

Once OTB is built with the tests, you just have to go to the binary
directory where you built OTB and run ``ctest -N`` to have a list of all
the tests. Just using ``ctest`` will run all the tests. To select a
subset, you can do ``ctest -R Kml`` to run all tests related to kml
files or ``ctest -I 1,10`` to run tests from 1 to 10.