diff --git a/Documentation/Cookbook/rst/Applications.rst b/Documentation/Cookbook/rst/Applications.rst
index 046e3cf2e2f5b14c2e4060053a8044f10e93b97a..007a8f8bcad1392baa8bb90449cf049c487728cc 100644
--- a/Documentation/Cookbook/rst/Applications.rst
+++ b/Documentation/Cookbook/rst/Applications.rst
@@ -1,9 +1,14 @@
Applications
============
+This chapter is the reference documentation for applications delivered
+with . It provides detailed description of the application behaviour and
+parameters, as well as python and bash snippets to use them
+applications. For a general introduction on applications delivered with
+, please read chapter[chap:otb-applications], page .
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
Applications/Image_Manipulation.rst
Applications/Vector_Data_Manipulation.rst
diff --git a/Documentation/Cookbook/rst/CookBook.rst b/Documentation/Cookbook/rst/CookBook.rst
new file mode 100644
index 0000000000000000000000000000000000000000..89ed542148d096681d92156b2848e395e8bf0c96
--- /dev/null
+++ b/Documentation/Cookbook/rst/CookBook.rst
@@ -0,0 +1,43 @@
+[t][10cm][b] |image|
+
+| *The ORFEO Toolbox is not a black box.*
+
+Ch.D.
+
+Foreword
+========
+
+Since 2006, the **Orfeo ToolBox**has become a rich library used in many
+remote sensing context, from research work to operational systems. The
+**OTB Applications**and more recently the Monteverdi tool has helped to
+broaden the audience of the library, giving access to its
+functionalities to non-developers.
+
+Meanwhile, the `OTB Software
+Guide <http://orfeo-toolbox.org/SoftwareGuide/>`__has grown to more than
+700 pages of documented code examples, which, combined with the class
+documentation with the `Doxygen <http://orfeo-toolbox.org/doxygen/>`__,
+allows developer users to find their way through the **Orfeo ToolBox**so
+as to write code suiting their needs.
+
+Yet, the documentation available for non-developers users, using
+Monteverdi and **OTB Applications**to perform everyday remote sensing
+tasks, has been almost inexistent for all these years, and these users
+had to learn the software by themselves or ask for help from more
+experienced users. This cookbook aims at fulfilling the need for an
+appropriate documentation of the applications built upon the **Orfeo
+ToolBox**: **Monteverdi**, and **OTB Applications**, which are now
+integrated into the main **Orfeo ToolBox**package and provide several
+access mode (command-line, QT interface, QGis plugins, other languages
+…).
+
+A general introduction to these tools is first presented, along with
+installation instructions. Rather than describing all modules and
+applications in an exhaustive way, we then decided to focus on very
+common remote sensing tasks, detailing how they can be achieved with
+either **Monteverdi**or an application.
+
+For more information on the **Orfeo ToolBox**, please feel free to visit
+the `Orfeo ToolBox website <http://orfeo-toolbox.org>`__.
+
+.. |image| image:: ../Art/logoVectoriel.pdf
diff --git a/Documentation/Cookbook/rst/Monteverdi.rst b/Documentation/Cookbook/rst/Monteverdi.rst
index 0b022ad8128bdd66f3da42c0f86c82bdf24c47d7..e16f275b3581366d3e8f46f0b7f700637cc52ee6 100644
--- a/Documentation/Cookbook/rst/Monteverdi.rst
+++ b/Documentation/Cookbook/rst/Monteverdi.rst
@@ -1,5 +1,5 @@
-A brief tour of
-================
+A brief tour of Monteverdi
+==========================
Introduction
------------
diff --git a/Documentation/Cookbook/rst/OTB-Applications.rst b/Documentation/Cookbook/rst/OTB-Applications.rst
index fb78ed7743fabc8281fd2c34cd175e73c4414d01..cb91b4c6ef75e6f0d1ea75598de445642055e2b6 100644
--- a/Documentation/Cookbook/rst/OTB-Applications.rst
+++ b/Documentation/Cookbook/rst/OTB-Applications.rst
@@ -89,7 +89,7 @@ To facilitate the use of these tools and applications, they will now be
shipped with the standard **Orfeo Toolbox** package. It means that the
former **OTB-Applications** package has entered its maintenance cycle :
no new feature will be pushed there, and all development is done
-directly inside the **Orfeo Toolbox** paackage.
+directly inside the **Orfeo Toolbox** package.
The **OTB Applications** are now rich of more than 40 tools, which are
listed in the the applications reference documentation, presented in
@@ -98,62 +98,176 @@ chapter [chap:apprefdoc], page .
Installation
------------
-We provide different binary packages for OTB-Applications:
+We provide different standalone binary packages for OTB-Applications:
-- for Windows platform (XP/Seven) through OsGeo4W installer (32/64bit)
+- for Windows platform (7 or higher)
-- for Ubuntu 12.04 and higher
+- for 64bit Linux distribution
-- for OpenSuse 12.X and higher
+- for MacOS X
-- for MacOSX through MacPorts software
+Other binaries can be available as packages (OSGeo packages,
+Debian/Ubuntu packages, OpenSuse packages), however be advised that they
+may not be up-to-date nor delivered with full features. If you want to
+build from source or if we don’t provide packages for your system, some
+informations are available into the , in the section **(**\ Building
+from Source)
-If you want build from source or if we don’t provide packages for your
-system, some informations are available into the `OTB Software
-Guide <http://orfeo-toolbox.org/SoftwareGuide>`_ , in the section
-**(**\ Building from Source)
+Windows
+~~~~~~~
+
+We provide for Windows Seven and later through standalone packages. They
+are cross-compiled with MinGW, for 32bit and 64bit platforms. They
+contain all and their launchers (both command line and graphical
+launchers are provided). Check the download page : `OTB Download
+page <https://www.orfeo-toolbox.org/download>`__
+
+There is a 32bit and a 64bit version. They contain the same directory
+structure:
+
+- ``monteverdi.bat`` : A launcher script for
-Windows XP/Seven
-~~~~~~~~~~~~~~~~
+- ``mapla.bat`` : A launcher script for Mapla
-Since version 3.12, we provide OTB Applications packages through OSGeo4W
-for Windows XP/Seven users:
+- ``otbenv.bat`` : A script to initialize the environment for OTB
+ executables
-- **otb-bin** for command line and QT applications
+- ``bin`` : A folder containing application launchers (otbcli.bat,
+ otbgui.bat) and the DLLs.
-- **otb-python** for python applications
+- ``lib`` : A folder containing application DLLs.
-Follow the instructions in the installer and select the packages you
-want to add. The installer will proceed with the installation of
-selected packages and all their dependencies. For the **otb-bin**
-packages, it will be available directly in the OSGeo4W shell, for
-example run
+The applications can be launched from the Mapla launcher. If you want to
+use the otbcli and otbgui launchers, you can initialize a command prompt
+with ``otbenv.bat``.
+
+Linux 64bit
+~~~~~~~~~~~
+
+We provide for Linux 64bit OS through standalone packages. They contain
+all OTB Applications and their launchers (both command line and
+graphical launchers are provided). Check the download page : `OTB
+Download page <https://www.orfeo-toolbox.org/download>`__
+
+This package is a self-extractible archive. You may uncompress it with a
+double-click on the file, or with the command line :
::
- otbgui_BandMath.
+ > chmod +x OTB-&\otbversion&-Linux64.run
+ > ./OTB-&\otbversion&-Linux64.run
+
+Please note that the resulting installation is not meant to be moved,
+you should uncompress the archive in its final location. Once the
+archive is extracted, the directory structure is made of :
-For the **otb-python** packages, you can simply check from an OSGeo4W
-shell the list of available applications:
+- ``monteverdi.sh`` : A launcher script for
+
+- ``mapla.sh`` : A launcher script for Mapla
+
+- ``otbenv.profile`` : A script to initialize the environment for OTB
+ executables
+
+- ``bin`` : A folder containing application launchers (otbcli.sh,
+ otbgui.sh), Monteverdi and Mapla.
+
+- ``lib`` : A folder containing all shared libraries and OTB
+ applications.
+
+- ``share`` : A folder containing common resources and copyright
+ mentions.
+
+In order to run the command line launchers, this package doesn’t require
+any special library that is not present in most modern Linux
+distributions. The graphical executable (otbgui launchers, Monteverdi
+and Mapla) use the X11 libraries, which are widely used in a lot of
+distributions :
::
- python
- import otbApplication
- print str( otbApplication.Registry.GetAvailableApplications() )
+ libx11-6 libxext6 libxau6 libxxf86vm1 libxdmcp6 libdrm2
+
+Monteverdi also requires the standard graphics libraries **libgl1** and
+**libglu1**. Make sure you have at least one version of them installed
+in your system.
+
+The applications can be launched from the Mapla launcher. If you want to
+use the otbcli and otbgui launchers, you can initialize your environment
+with ``source otbenv.profile``.
MacOS X
~~~~~~~
-OTB Applications are now available on
-`MacPorts <http://http://www.macports.org/>`_ . The port name is called
-orfeotoolbox. You can follow the `MacPorts
-documentation <http://guide.macports.org/>`_ to install MacPorts
-first, then install the orfeotoolbox port. After the installation, you
-can used directly on your system, the OTB applications.
+We provide for MacOS X through a standalone package. This package is a
+self-extractible archive, quite similar to the Linux one. You may
+uncompress it with the command line :
+
+::
+
+ > chmod +x OTB-&\otbversion&-Darwin64.run
+ > ./OTB-&\otbversion&-Darwin64.run
+
+Once the archive is extracted, you can see OTB--Darwin64 directory in
+the same direcrtory along with OTB--Darwin64.run
+
+Contents of OTB--Darwin64 is briefly listed below:
+
+- ``Monteverdi.app`` : A Mac OSX .app for Monteverdi
+
+- ``Mapla.app`` : A Mac OSX .app for Mapla.
+
+- ``bin`` : A folder containing application launchers (otbcli.sh,
+ otbgui.sh), monteverdi and mapla binaries.
+
+- ``lib`` : A folder containing all shared libraries and OTB
+ applications.
+
+- ``share`` : A folder containing common resources and copyright
+ mentions.
+
+Notes:
+
+- If you want to use the otbcli and otbgui launchers, you must access
+ them via a terminal prompt.
+
+- The OSX .app are provided for monteverdi (viewer) and mapla
+ (application browser).
+
+- You must use monteverdi and mapla through their .app files only.
+
+- You are allowed to move these .app files and refrain from moving or
+ deleting OTB--Darwin64 after extraction. In case you need to have OTB
+ installed in some other directory. Extract the .run file there.
+
+Other packages
+~~~~~~~~~~~~~~
+
+**Warning !** These packages may not be up-to-date with latest OTB
+releases. In addition, some features of the library may not be available
+on every platform. Some of these are not maintained by OTB-team. If you
+want to get involved in the packaging of OTB for your favourite
+platform, please contact us through the developer’s mailing list :
+otb-developers@googlegroups.com.
+
+Debian
+^^^^^^
+
+There are OTB packages for Debian (unstable) since version 5.2.0. OTB
+Applications packages may be available as Debian packages through APT
+repositories:
+
+- **otb-bin** for command line applications
+
+- **otb-bin-qt** for Qt applications
+
+- **python-otb** for python applications
+
+Due to license issues, the OTB package built in Debian doesn’t contain
+6S. As a consequence, the package does not contain the
+OpticalCalibration application.
Ubuntu 12.04 and higher
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
For Ubuntu 12.04 and higher, OTB Applications packages may be available
as Debian packages through APT repositories:
@@ -165,9 +279,12 @@ as Debian packages through APT repositories:
- **python-otb** for python applications
Since release 3.14.1, OTB Applications packages are available in the
-`ubuntugis-unstable <https://launchpad.net/~ubuntugis/+archive/ubuntugis-unstable>`_
+`ubuntugis-unstable <https://launchpad.net/~ubuntugis/+archive/ubuntugis-unstable>`__
repository.
+Since release 5.2.0, the Ubuntu packages derive from the Debian
+packages.
+
You can add it by using these command-lines:
::
@@ -185,7 +302,7 @@ If you are using *Synaptic*, you can add the repositories, update and
install the packages through the graphical interface.
For further informations about Ubuntu packages go to
-`ubuntugis-unstable <https://launchpad.net/~ubuntugis/+archive/ubuntugis-unstable>`_
+`ubuntugis-unstable <https://launchpad.net/~ubuntugis/+archive/ubuntugis-unstable>`__
launchpad page and click on **Read about installing**.
**apt-add-repository** will try to retrieve the GPG keys of the
@@ -197,7 +314,7 @@ about a signature problem. This warning won’t prevent you from
installing the packages.
OpenSuse 12.X and higher
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
For OpenSuse 12.X and higher, OTB Applications packages are available
through *zypper*.
@@ -224,7 +341,7 @@ Now run:
Alternatively you can use the One-Click Installer from the `openSUSE
Download
-page <http://software.opensuse.org/search?q=Orfeo&baseproject=openSUSE%3A11.4&lang=en&include_home=true&exclude_debug=true>`_
+page <http://software.opensuse.org/search?q=Orfeo&baseproject=openSUSE%3A11.4&lang=en&include_home=true&exclude_debug=true>`__
or add the above repositories and install through Yast Package
Management.
@@ -243,29 +360,38 @@ following repositories with these command-lines:
and then add the OTB packages as shown above.
+MacPort
+^^^^^^^
+
+OTB Applications are now available on
+`MacPorts <http://http://www.macports.org/>`__. The port name is called
+’orfeotoolbox’. You can follow the `MacPorts
+documentation < http://guide.macports.org/>`__ to install MacPorts
+first, then install the ’orfeotoolbox’ port. After the installation, you
+can used directly on your system, the OTB applications.
+
Using the applications
----------------------
-Using the new **OTB Applications** framework is slightly more complex
-than launching a command-line tool. This section describes all the ways
-to launch the new applications. Apart from the simplified access, which
-is similar to the former access to **OTB Applications** , you will need
-to know the application name and optionally the path where the
-applications plugins are stored. For applications shipped with **Orfeo
-Toolbox** , the name of each application can be found in
+Using the new framework is slightly more complex than launching a
+command-line tool. This section describes all the ways to launch the new
+applications. Apart from the simplified access, which is similar to the
+former access to , you will need to know the application name and
+optionally the path where the applications plugins are stored. For
+applications shipped with , the name of each application can be found in
chapter [chap:apprefdoc], page .
Simplified use
~~~~~~~~~~~~~~
-All standard applications delivered in with **Orfeo Toolbox** comes with
-simplified scripts in the system path, allowing to launch the
-command-line and graphical user interface versions of the application in
-the same simple way we used to launch the old applications. The
-command-line interface is prefixed by ``otbcli_``, while the Qt
-interface is prefixed by ``otbgui_``. For instance, calling
-``otbcli_Convert`` will launch the command-line interface of the
-**Convert** application, while ``otbgui_Convert`` will launch its GUI.
+All standard applications delivered in with comes with simplified
+scripts in the system path, allowing to launch the command-line and
+graphical user interface versions of the application in the same simple
+way we used to launch the old applications. The command-line interface
+is prefixed by ``otbcli_``, while the Qt interface is prefixed by
+``otbgui_``. For instance, calling ``otbcli_Convert`` will launch the
+command-line interface of the **Convert** application, while
+``otbgui_Convert`` will launch its GUI.
Passing arguments to the command-line version (prefixed by ``otbcli_``)
is explained in next sub-section.
@@ -280,7 +406,7 @@ results in the following help to be displayed:
::
- $ otbApplicationLauncherCommandLine
+ $ otbApplicationLauncherCommandLine
Usage : ./otbApplicationLauncherCommandLine module_name [MODULEPATH] [arguments]
The ``module_name`` parameter corresponds to the application name. The
@@ -289,21 +415,21 @@ a path where the shared library (or plugin) corresponding to
``module_name`` is.
It is also possible to set this path with the environment variable
-``ITK_AUTOLOAD_PATH``, making the ``[MODULEPATH]`` optional. This
+``OTB_APPLICATION_PATH``, making the ``[MODULEPATH]`` optional. This
variable is checked by default when no ``[MODULEPATH]`` argument is
-given. When using multiple paths in ``ITK_AUTOLOAD_PATH``, one must make
-sure to use the standard path separator of the target system, which is
-``:`` on Unix, and ``;`` on Windows.
+given. When using multiple paths in ``OTB_APPLICATION_PATH``, one must
+make sure to use the standard path separator of the target system, which
+is ``:`` on Unix, and ``;`` on Windows.
An error in the application name (i.e. in parameter ``module_name``)
will make the ``otbApplicationLauncherCommandLine`` lists the name of
all applications found in the available path (either ``[MODULEPATH]``
-and/or ``ITK_AUTOLOAD_PATH``).
+and/or ``OTB_APPLICATION_PATH``).
To ease the use of the applications, and try avoiding extensive
environment customization, ready-to-use scripts are provided by the OTB
installation to launch each application, and takes care of adding the
-standard application installation path to the ``ITK_AUTOLOAD_PATH``
+standard application installation path to the ``OTB_APPLICATION_PATH``
environment variable.
These scripts are named ``otbcli_<ApplicationName>`` and do not need any
@@ -325,37 +451,37 @@ example with the **OrthoRectification** application:
NAME: OrthoRectification
DESCRIPTION: This application allows to ortho-rectify optical images from supported sensors.
- EXAMPLE OF USE:
+ EXAMPLE OF USE:
otbcli_OrthoRectification -io.in QB_TOULOUSE_MUL_Extract_500_500.tif -io.out QB_Toulouse_ortho.tif
DOCUMENTATION: http://www.orfeo-toolbox.org/Applications/OrthoRectification.html
======================= PARAMETERS =======================
- -progress <boolean> Report progress
- MISSING -io.in <string> Input Image
+ -progress <boolean> Report progress
+ MISSING -io.in <string> Input Image
MISSING -io.out <string> [pixel] Output Image [pixel=uint8/int8/uint16/int16/uint32/int32/float/double]
-map <string> Output Map Projection [utm/lambert2/lambert93/transmercator/wgs/epsg]
- MISSING -map.utm.zone <int32> Zone number
- -map.utm.northhem <boolean> Northern Hemisphere
- -map.transmercator.falseeasting <float> False easting
- -map.transmercator.falsenorthing <float> False northing
- -map.transmercator.scale <float> Scale factor
- -map.epsg.code <int32> EPSG Code
+ MISSING -map.utm.zone <int32> Zone number
+ -map.utm.northhem <boolean> Northern Hemisphere
+ -map.transmercator.falseeasting <float> False easting
+ -map.transmercator.falsenorthing <float> False northing
+ -map.transmercator.scale <float> Scale factor
+ -map.epsg.code <int32> EPSG Code
-outputs.mode <string> Parameters estimation modes [auto/autosize/autospacing]
- MISSING -outputs.ulx <float> Upper Left X
- MISSING -outputs.uly <float> Upper Left Y
- MISSING -outputs.sizex <int32> Size X
- MISSING -outputs.sizey <int32> Size Y
- MISSING -outputs.spacingx <float> Pixel Size X
- MISSING -outputs.spacingy <float> Pixel Size Y
- -outputs.isotropic <boolean> Force isotropic spacing by default
- -elev.dem <string> DEM directory
- -elev.geoid <string> Geoid File
- -elev.default <float> Average Elevation
+ MISSING -outputs.ulx <float> Upper Left X
+ MISSING -outputs.uly <float> Upper Left Y
+ MISSING -outputs.sizex <int32> Size X
+ MISSING -outputs.sizey <int32> Size Y
+ MISSING -outputs.spacingx <float> Pixel Size X
+ MISSING -outputs.spacingy <float> Pixel Size Y
+ -outputs.isotropic <boolean> Force isotropic spacing by default
+ -elev.dem <string> DEM directory
+ -elev.geoid <string> Geoid File
+ -elev.default <float> Average Elevation
-interpolator <string> Interpolation [nn/linear/bco]
- -interpolator.bco.radius <int32> Radius for bicubic interpolation
- -opt.rpc <int32> RPC modeling (points per axis)
- -opt.ram <int32> Available memory for processing (in MB)
- -opt.gridspacing <float> Resampling grid spacing
+ -interpolator.bco.radius <int32> Radius for bicubic interpolation
+ -opt.rpc <int32> RPC modeling (points per axis)
+ -opt.ram <int32> Available memory for processing (in MB)
+ -opt.gridspacing <float> Resampling grid spacing
For a detailed description of the application behaviour and parameters,
please check the application reference documentation presented
@@ -381,11 +507,11 @@ This launcher needs the same two arguments as the command line launcher
$ otbApplicationLauncherQt module_name [MODULEPATH]
-The application paths can be set with the ``ITK_AUTOLOAD_PATH``
+The application paths can be set with the ``OTB_APPLICATION_PATH``
environment variable, as for the command line launcher. Also, as for the
command-line application, a more simple script is generated and
installed by OTB to ease the configuration of the module path : to
-launch the *Rescale* graphical user interface, one will start the
+launch the graphical user interface, one will start the
``otbgui_Rescale`` script.
The resulting graphical application displays a window with several tabs:
@@ -406,15 +532,15 @@ In this interface, every optional parameter has a check box that you
have to tick if you want to set a value and use this parameter. The
mandatory parameters cannot be unchecked.
-The interface of the application *Rescale* is shown here as an example.
+The interface of the application is shown here as an example.
-|image1| [fig:rescaleParam]
+|image| [fig:rescaleParam]
-|image2| [fig:rescaleLogs]
+|image| [fig:rescaleLogs]
-|image3| [fig:rescaleProgress]
+|image| [fig:rescaleProgress]
-|image4| [fig:rescaleDocumentation]
+|image| [fig:rescaleDocumentation]
Using the Python interface
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -439,12 +565,12 @@ In this module, two main classes can be manipulated :
interact with an application instance created by the ``Registry``
As for the command line and GUI launchers, the path to the application
-modules needs to be properly set with the ``ITK_AUTOLOAD_PATH``
+modules needs to be properly set with the ``OTB_APPLICATION_PATH``
environment variable. The standard location on Unix systems is
``/usr/lib/otb/applications``. On Windows, the applications are
available in the ``otb-bin`` OSGeo4W package, and the environment is
configured automatically so you don’t need to tweak
-``ITK_AUTOLOAD_PATH``.
+``OTB_APPLICATION_PATH``.
Here is one example of how to use Python to run the ``Smoothing``
application, changing the algorithm at each iteration.
@@ -519,7 +645,7 @@ time
::
- otbcli_BandMath -inxml saved_applications_parameters.xml
+ otbcli_BandMath -inxml saved_applications_parameters.xml
-exp "(im1b1 - im2b1)"
In this cas it will use as mathematical expression “(im1b1 - im2b1)â€
@@ -536,7 +662,36 @@ the application name. Use in this case:
It will retrieve the application name and related parameters from the
input xml file and launch in this case the BandMath applications.
-.. |image1| image:: ./Art/QtImages/rescale_param.png
-.. |image2| image:: ./Art/QtImages/rescale_logs.png
-.. |image3| image:: ./Art/QtImages/rescale_progress.png
-.. |image4| image:: ./Art/QtImages/rescale_documentation.png
+Using OTB from QGIS
+~~~~~~~~~~~~~~~~~~~
+
+The processing toolbox
+^^^^^^^^^^^^^^^^^^^^^^
+
+OTB applications are available from QGIS. Use them from the processing
+toolbox, which is accessible with Processing :math:`\rightarrow`
+Toolbox. Switch to “advanced interface†in the bottom of the application
+widget and OTB applications will be there.
+
+|image| [fig:otb-qgis]
+
+Using a custom OTB
+^^^^^^^^^^^^^^^^^^
+
+If QGIS cannot find OTB, the “applications folder†and “binaries folderâ€
+can be set from the settings in the Processing :math:`\rightarrow`
+Settings :math:`\rightarrow` “service providerâ€.
+
+|image| [fig:otb-qgis-settings]
+
+On some versions of QGIS, if an existing OTB installation is found, the
+textfield settings will not be shown. To use a custom OTB instead of the
+existing one, you will need to replace the otbcli, otbgui and library
+files in QGIS installation directly.
+
+.. |image| image:: ../Art/QtImages/rescale_param.png
+.. |image| image:: ../Art/QtImages/rescale_logs.png
+.. |image| image:: ../Art/QtImages/rescale_progress.png
+.. |image| image:: ../Art/QtImages/rescale_documentation.png
+.. |image| image:: ../Art/QtImages/qgis-otb.png
+.. |image| image:: ../Art/QtImages/qgis-otb-settings.png
diff --git a/Documentation/Cookbook/rst/Recipes.rst b/Documentation/Cookbook/rst/Recipes.rst
index 17d7c68fc834672961ac35ab34b4111429aeb52c..9176933737d34b1598b1b27d5c15362e31193aaf 100644
--- a/Documentation/Cookbook/rst/Recipes.rst
+++ b/Documentation/Cookbook/rst/Recipes.rst
@@ -1,12 +1,19 @@
Recipes
=======
+This chapter presents guideline to perform various remote sensing and
+image processing tasks with either , or both. Its goal is not to be
+exhaustive, but rather to help the non-developper user to get familiar
+with these two packages, so that he can use and explore them for his
+future needs.
+
.. toctree::
:maxdepth: 6
recipes/pleiades.rst
recipes/optpreproc.rst
+ recipes/sarprocessing.rst
recipes/residual_registration.rst
recipes/improc.rst
recipes/pbclassif.rst
diff --git a/Documentation/Cookbook/rst/WrappedApplications.rst b/Documentation/Cookbook/rst/WrappedApplications.rst
new file mode 100644
index 0000000000000000000000000000000000000000..18eed90466b292f7df0c9e98fc8a79269bc48e6e
--- /dev/null
+++ b/Documentation/Cookbook/rst/WrappedApplications.rst
@@ -0,0 +1,112 @@
+Using OTB applications
+======================
+
+Introduction
+------------
+
+The package (see [chap:otb-applications]) has brought a nice set of
+applications, along with several tools to launch them (command line,
+Qt,…). As for the future of these applications, it has been decided to
+integrate them inside the library. This migration has been an
+opportunity to enhance all the framework around the applications: not
+only new features have been added, but the interface with the developer
+has also been simplified. The new framework has inherited the wrappers
+from , and new ones have been added. The development philosophy behind
+these applications is to provide users with modular functional blocs for
+remote sensing, ready to be integrated in any environment.
+
+Because the applications are now a part of the library, their
+installation doesn’t require much effort: when building the library, you
+can activate the applications with the CMake boolean option .
+
+List of applications
+--------------------
+
+The documentation of the available applications is accessible
+`here <http://orfeo-toolbox.org/Applications>`__. Most of the old
+applications have been migrated. They are sorted by categories.
+
+Available wrappers
+------------------
+
+Command line
+~~~~~~~~~~~~
+
+By default, the applications can be called with the command line
+launcher. This launcher is built in your directory. It needs at least
+two arguments: the application name and the path to the directory. Any
+additional argument will be given to the application itself. You can ask
+the application to print its help message:
+
+::
+
+ otbApplicationLauncherCommandLine Rescale OTB_DIR/bin -help
+
+The help message (but also the
+`documentation <http://orfeo-toolbox.org/Applications>`__) will give you
+the list of available parameters. Each parameter must be set by giving
+the corresponding key followed by its value:
+
+::
+
+ otbApplicationLauncherCommandLine Rescale OTB_DIR/bin -in QB_Toulouse_Ortho_PAN.tif -out QB_Toulouse_rescaled.tif -outmin 0 -outmax 255
+
+An other way to launch your application is to use the auto-generated
+scripts located in the directory. There is one for each application,
+their name is the same as the application, prefixed with :
+
+::
+
+ otbcli_Rescale -in QB_Toulouse_Ortho_PAN.tif -out QB_Toulouse_rescaled.tif -outmin 0 -outmax 255
+
+If the application has sub-parameters (i.e. parameters contained in
+other parameters), their keys must be prefixed by their full tree path.
+For instance, the application has a paramater for bicubic interpolation
+radius whose key is . This parameter should be called with the path .
+
+Note that some types of parameters allow you to give several values
+after the key (they must be separated with whitespaces).
+
+For example an *InputImageList* key, which can be followed by one or
+several filenames :
+
+::
+
+ otbApplicationLauncherCommandLine ConcatenateImages OTB_DIR/bin -il GomaAvant.png GomaApres.png -out otbConcatenateImages.tif
+
+Other wrappers
+~~~~~~~~~~~~~~
+
+If you want to use the other available wrappers, you have to activate
+the corresponding CMake options when building the library:
+
+- Enable to build a Qt application launcher. It opens a GUI which
+ allows you to set the parameters and execute the application. This
+ launcher only needs the same two arguments as the command line:
+
+ ::
+
+ otbApplicationLauncherQt Rescale OTB_DIR/bin
+
+
+ There are also auto-generated scripts, similar to command line ones:
+
+ ::
+
+ otbgui_Rescale
+
+
+ It displays a window with several tabs. **[Parameters]** is where you
+ set the parameters and execute the application. **[Logs]** is where
+ you see the informations given by the application during its
+ execution. **[Progress]** is where you see a progress bar of the
+ execution (not available for all applications). **[Documentation]**
+ is where you find a summary of the application documentation.
+
+- : **TODO**
+
+- : **TODO**
+
+- : **TODO**
+
+
diff --git a/Documentation/Cookbook/rst/bandmathx.rst b/Documentation/Cookbook/rst/bandmathx.rst
deleted file mode 100644
index 3b5e39c8448e68778a94c509ab09670c5b3b64ba..0000000000000000000000000000000000000000
--- a/Documentation/Cookbook/rst/bandmathx.rst
+++ /dev/null
@@ -1,292 +0,0 @@
-BandMathX application (based on muParserX)
-==========================================
-
-This section describes how to use the BandMathX application.
-
-Syntax : first elements
------------------------
-
-The default prefix name for variables related to the ith input is
-*im(i+1)* (note the indexing from 1 to N, for N inputs). The user has
-the possibility to change this default behaviour by setting its own
-prefix.
-
-In this document, we will keep the default convention. Following list
-summaries the available variables for input #0 (and so on for every
-input).
-
-\|\|l\|l\|l\|\| **Variables & **Description & **Type
-im1 & a pixel from first input, made of n components/bands (first image
-is indexed by 1) & Vector
-im1bj & jth component of a pixel from first input (first band is indexed
-by 1) & Scalar
-im1bjNkxp & a neighbourhood (“Nâ€) of pixels of the jth component from
-first input, of size kxp & Matrix
-im1bjMini & global statistic : minimum of the jth band from first input
-& Scalar
-im1bjMaxi & global statistic : maximum of the jth band from first input
-& Scalar
-im1bjMean & global statistic : mean of the jth band from first input &
-Scalar
-im1bjSum & global statistic : sum of the jth band from first input &
-Scalar
-im1bjVar & global statistic : variance of the jth band from first input
-& Scalar
-im1PhyX and im1PhyY & spacing of first input in X and Y directions &
-Scalar
-******
-
-[variables]
-
-Moreover, we also have the generic variables idxX and idxY that
-represent the indices of the current pixel (scalars).
-
-For instance, the following formula (addition of two pixels)
-
-.. math:: im1+im2
-
-[firstequation]
-
-is correct only if the two first inputs have the same number of bands.
-In addition, the following formula is not consistent even if im1
-represents a pixel of an image made of only one band:
-
-.. math:: im1+1
-
-A scalar can’t be added to a vector. The right formula is instead (one
-can notice the way that muParserX allows to define vectors on the fly):
-
-.. math:: im1+\{ 1 \}
-
-or
-
-.. math:: im1 + \{1,1,1,...,1\}
-
-if im1 is made of n components.
-
-On the other hand, the variable im1b1 for instance is represented as a
-scalar; so we have the following different possibilities:
-
-\|\|c\|c\|\| **Expression & **Status
-im1b1 + 1 & correct
-{im1b1} + {1} & correct
-im1b1 + {1} & incorrect
-{im1b1} + 1 & incorrect
-im1 + {im2b1,im2b2} & correct if im1 represents a pixel of two
-components (equivalent to im1 + im2)
-****
-
-[correctness]
-
-Similar remarks can be made for the multiplication/division; for
-instance, the following formula is incorrect:
-
-.. math:: \{im2b1,im2b2\} * \{1,2\}
-
-whereas this one is correct:
-
-.. math:: \{im2b1,im2b2\} * \{1,2\}'
-
-or in more simple terms (and only if im2 contains two components):
-
-.. math:: im2* \{1,2\}'
-
-Concerning division, this operation is not originally defined between
-two vectors (see next section “New operators and functionsâ€
--[ssec:operators]-).
-
-Now, let’s go back to the first formula: this one specifies the addition
-of two images band to band. With muParserX lib, we can now define such
-operation with only one formula, instead of many formulas (as many as
-the number of bands). We call this new functionality the **batch mode**,
-which directly arises from the introduction of vectors within muParserX
-framework.
-
-Finally, let’s say a few words about neighbourhood variables. These
-variables are defined for each particular input, and for each particular
-band. The two last numbers, kxp, indicate the size of the neighbourhood.
-All neighbourhoods are centred: this means that k and p can only be odd
-numbers. Moreover, k represents the dimension in the x direction (number
-of columns), and p the dimension in the y direction (number of rows).
-For instance, im1b3N3x5 represents the following neighbourhood:
-
-+-----+-----+-----+
-| . | . | . |
-+=====+=====+=====+
-| . | . | . |
-+-----+-----+-----+
-| . | . | . |
-+-----+-----+-----+
-| . | . | . |
-+-----+-----+-----+
-| . | . | . |
-+-----+-----+-----+
-
-[correctness]
-
-Fundamentally, a neighbourhood is represented as a matrix inside the
-muParserX framework; so the remark about mathematically well-defined
-formulas still stands.
-
-New operators and functions
----------------------------
-
-New operators and functions have been implemented within BandMathX
-application. These ones can be divided into two categories.
-
-- adaptation of existing operators/functions, that were not originally
- defined for vectors and matrices (for instance cos, sin, ...). These
- new operators/ functions keep the original names to which we add the
- prefix “v†for vector (vcos, vsin, ...) .
-
-- truly new operators/functions.
-
-Concerning the last category, here is a list of implemented operators or
-functions (they are all implemented in otbParserXPlugins.h/.cxx files
--OTB/Code/Common-):
-
-**Operators div and dv** The first operator allows the definition of an
-element-wise division of two vectors (and even matrices), provided that
-they have the same dimensions. The second one allows the definition of
-the division of a vector/matrix by a scalar (components are divided by
-the same unique value). For instance:
-
-.. math:: im1 ~ div ~ im2
-
-.. math:: im1 ~ dv ~ 2.0
-
-**Operators mult and mlt** These operators are the duals of the previous
-ones. For instance:
-
-.. math:: im1 ~ mult ~ im2
-
-.. math:: im1 ~ mlt ~ 2.0
-
-Note that the operator ’\*’ could have been used instead of ’pw’ one.
-But ’pw’ is a little bit more permisive, and can tolerate
-one-dimensional vector as right element.
-
-**Operators pow and pw** The first operator allows the definition of an
-element-wise exponentiation of two vectors (and even matrices), provided
-that they have the same dimensions. The second one allows the definition
-of the division of a vector/matrix by a scalar (components are
-exponentiated by the same unique value). For instance:
-
-.. math:: im1 ~ pow ~ im2
-
-.. math:: im1 ~ pw ~ 2.0
-
-**Function bands** This function allows to select specific bands from an
-image, and/or to rearrange them in a new vector; for instance:
-
-.. math:: bands(im1,\{1,2,1,1\})
-
-produces a vector of 4 components made of band 1, band 2, band 1 and
-band 1 values from the first input. Note that curly brackets must be
-used in order to select the desired band indices.
-
-**Function dotpr ** This function allows the dot product between two
-vectors or matrices (actually in our case, a kernel and a neighbourhood
-of pixels):
-
-.. math:: \sum_{(i,j)} m_1(i,j)*m_2(i,j)
-
-For instance:
-
-.. math:: dotpr(kernel1,im1b1N3x5)
-
-is correct provided that kernel1 and im1b1N3x5 have the same dimensions.
-The function can take as many neighbourhoods as needed in inputs.
-
-**Function mean** This function allows to compute the mean value of a
-given vector or neighborhood (the function can take as many inputs as
-needed; one mean value is computed per input). For instance:
-
-.. math:: mean(im1b1N3x3,im1b2N3x3,im1b3N3x3,im1b4N3x3)
-
-Note: a limitation coming from muparserX itself makes impossible to pass
-all those neighborhoods with a unique variable.
-
-**Function var** This function allows to compute the variance of a given
-vector or neighborhood (the function can take as many inputs as needed;
-one var value is computed per input). For instance:
-
-.. math:: var(im1b1N3x3)
-
-**Function median** This function allows to compute the median value of
-a given vector or neighborhood (the function can take as many inputs as
-needed; one median value is computed per input). For instance:
-
-.. math:: median(im1b1N3x3)
-
-**Function corr** This function allows to compute the correlation
-between two vectors or matrices of the same dimensions (the function
-takes two inputs). For instance:
-
-.. math:: corr(im1b1N3x3,im1b2N3x3)
-
-**Function maj** This function allows to compute the most represented
-element within a vector or a matrix (the function can take as many
-inputs as needed; one maj element value is computed per input). For
-instance:
-
-.. math:: maj(im1b1N3x3,im1b2N3x3)
-
-**Function vmin and vmax** These functions allow to compute the min or
-max value of a given vector or neighborhood (only one input). For
-instance:
-
-.. math:: (vmax(im3b1N3x5)+vmin(im3b1N3x5)) ~ div ~ \{2.0\}
-
-**Function cat** This function allows to concatenate the results of
-several expressions into a multidimensional vector, whatever their
-respective dimensions (the function can take as many inputs as needed).
-For instance:
-
-.. math:: cat(im3b1,vmin(im3b1N3x5),median(im3b1N3x5),vmax(im3b1N3x5))
-
-Note: the user should prefer the use of semi-colons (;) when setting
-expressions, instead of directly use this function. The application will
-call the function ’cat’ automatically.
-
-**Function ndvi** This function implements the classical normalized
-difference vegetation index; it tkaes two inputs. For instance:
-
-.. math:: ndvi(im1b1,im1b4)
-
-First argument is related to the visible red band, and the second one to
-the near-infrareds band.
-
-The table below summarises the different functions and operators.
-
-\|\|l\|l\|\| **Variables & **Remark
-ndvi & two inputs
-bands & two inputs; length of second vector input gives the dimension of
-the output
-dotptr & many inputs
-cat & many inputs
-mean & many inputs
-var & many inputs
-median & many inputs
-maj & many inputs
-corr & two inputs
-div and dv & operators
-mult and mlt & operators
-pow and pw & operators
-vnorm & adapation of an existing function to vectors : one input
-vabs & adapation of an existing function to vectors : one input
-vmin & adapation of an existing function to vectors : one input
-vmax & adapation of an existing function to vectors : one input
-vcos & adapation of an existing function to vectors : one input
-vsin & adapation of an existing function to vectors : one input
-vtan & adapation of an existing function to vectors : one input
-vtanh & adapation of an existing function to vectors : one input
-vsinh & adapation of an existing function to vectors : one input
-vcosh & adapation of an existing function to vectors : one input
-vlog & adapation of an existing function to vectors : one input
-vlog10 & adapation of an existing function to vectors : one input
-vexp & adapation of an existing function to vectors : one input
-vsqrt & adapation of an existing function to vectors : one input
-****
-
-[bandmathOperators]
diff --git a/Documentation/Cookbook/rst/featextract.rst b/Documentation/Cookbook/rst/featextract.rst
deleted file mode 100644
index 3f92e0280fc26ce80174f6c4c852fb51e56a2b4b..0000000000000000000000000000000000000000
--- a/Documentation/Cookbook/rst/featextract.rst
+++ /dev/null
@@ -1,524 +0,0 @@
-Feature extraction
-==================
-
-As described in the OTB Software Guide, the term *Feature Extraction*
-refers to techniques aiming at extracting added value information from
-images. These extracted items named *features* can be local statistical
-moments, edges, radiometric indices, morphological and textural
-properties. For example, such features can be used as input data for
-other image processing methods like *Segmentation* and *Classification*.
-
-Local statistics extraction
----------------------------
-
-This application computes the 4 local statistical moments on every pixel
-in the selected channel of the input image, over a specified
-neighborhood. The output image is multi band with one statistical moment
-(feature) per band. Thus, the 4 output features are the Mean, the
-Variance, the Skewness and the Kurtosis. They are provided in this exact
-order in the output image.
-
-The application has the following input parameters:
-
-- ``-in`` the input image to compute the features on
-
-- ``-channel`` the selected channel index in the input image to be
- processed (default value is 1)
-
-- ``-radius`` the computational window radius (default value is 3
- pixels)
-
-- ``-out`` the output image containing the local statistical moments
-
-The application can be used like this:
-
-::
-
- otbcli_LocalStatisticExtraction -in InputImage
- -channel 1
- -radius 3
- -out OutputImage
-
-Edge extraction
----------------
-
-This application Computes edge features on every pixel in the selected
-channel of the input image.
-
-The application has the following input parameters:
-
-- ``-in`` the input image to compute the features on
-
-- ``-channel`` the selected channel index in the input image to be
- processed (default value is 1)
-
-- | ``-filter`` the choice of edge detection method
- (gradient/sobel/touzi) (default value is gradient) Â Â
-
-- ``(-filter.touzi.xradius)`` the X Radius of the Touzi processing
- neighborhood (only if filter==touzi) (default value is 1 pixel)
-
-- | ``(-filter.touzi.yradius)`` the Y Radius of the Touzi processing
- neighborhood (only if filter==touzi) (default value is 1 pixel) Â Â
-
-- ``-out`` the output mono band image containing the edge features
-
-The application can be used like this:
-
-::
-
- otbcli_EdgeExtraction -in InputImage
- -channel 1
- -filter sobel
- -out OutputImage
-
-or like this if filter==touzi:
-
-::
-
- otbcli_EdgeExtraction -in InputImage
- -channel 1
- -filter touzi
- -filter.touzi.xradius 2
- -filter.touzi.yradius 2
- -out OutputImage
-
-Radiometric indices extraction
-------------------------------
-
-This application computes radiometric indices using the channels of the
-input image. The output is a multi band image into which each channel is
-one of the selected indices.
-
-The application has the following input parameters:
-
-- ``-in`` the input image to compute the features on
-
-- ``-out`` the output image containing the radiometric indices
-
-- ``-channels.blue`` the Blue channel index in the input image (default
- value is 1)
-
-- ``-channels.green`` the Green channel index in the input image
- (default value is 1)
-
-- ``-channels.red`` the Red channel index in the input image (default
- value is 1)
-
-- ``-channels.nir`` the Near Infrared channel index in the input image
- (default value is 1)
-
-- ``-channels.mir`` the Mid-Infrared channel index in the input image
- (default value is 1)
-
-- ``-list`` the list of available radiometric indices (default value is
- Vegetation:NDVI)
-
-The available radiometric indices to be listed into -list with their
-relevant channels in brackets are:
-
-::
-
- Vegetation:NDVI - Normalized difference vegetation index (Red, NIR)
- Vegetation:TNDVI - Transformed normalized difference vegetation index (Red, NIR)
- Vegetation:RVI - Ratio vegetation index (Red, NIR)
- Vegetation:SAVI - Soil adjusted vegetation index (Red, NIR)
- Vegetation:TSAVI - Transformed soil adjusted vegetation index (Red, NIR)
- Vegetation:MSAVI - Modified soil adjusted vegetation index (Red, NIR)
- Vegetation:MSAVI2 - Modified soil adjusted vegetation index 2 (Red, NIR)
- Vegetation:GEMI - Global environment monitoring index (Red, NIR)
- Vegetation:IPVI - Infrared percentage vegetation index (Red, NIR)
-
- Water:NDWI - Normalized difference water index (Gao 1996) (NIR, MIR)
- Water:NDWI2 - Normalized difference water index (Mc Feeters 1996) (Green, NIR)
- Water:MNDWI - Modified normalized difference water index (Xu 2006) (Green, MIR)
- Water:NDPI - Normalized difference pond index (Lacaux et al.) (MIR, Green)
- Water:NDTI - Normalized difference turbidity index (Lacaux et al.) (Red, Green)
-
- Soil:RI - Redness index (Red, Green)
- Soil:CI - Color index (Red, Green)
- Soil:BI - Brightness index (Red, Green)
- Soil:BI2 - Brightness index 2 (NIR, Red, Green)
-
-The application can be used like this, which leads to an output image
-with 3 bands, respectively with the Vegetation:NDVI, Vegetation:RVI and
-Vegetation:IPVI radiometric indices in this exact order:
-
-::
-
- otbcli_RadiometricIndices -in InputImage
- -out OutputImage
- -channels.red 3
- -channels.green 2
- -channels.nir 4
- -list Vegetation:NDVI Vegetation:RVI
- Vegetation:IPVI
-
-or like this, which leads to a single band output image with the
-Water:NDWI2 radiometric indice:
-
-::
-
- otbcli_RadiometricIndices -in InputImage
- -out OutputImage
- -channels.red 3
- -channels.green 2
- -channels.nir 4
- -list Water:NDWI2
-
-Morphological features extraction
----------------------------------
-
-Morphological features can be highlighted by using image filters based
-on mathematical morphology either on binary or gray scale images.
-
-Binary morphological operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This application performs binary morphological operations (dilation,
-erosion, opening and closing) on a mono band image with a specific
-structuring element (a ball or a cross) having one radius along X and
-another one along Y. NB: the cross shaped structuring element has a
-fixed radius equal to 1 pixel in both X and Y directions.
-
-The application has the following input parameters:
-
-- ``-in`` the input image to be filtered
-
-- ``-channel`` the selected channel index in the input image to be
- processed (default value is 1)
-
-- ``-structype`` the choice of the structuring element type
- (ball/cross) (default value is ball)
-
-- ``(-structype.ball.xradius)`` the ball structuring element X Radius
- (only if structype==ball) (default value is 5 pixels)
-
-- ``(-structype.ball.yradius)`` the ball structuring element Y Radius
- (only if structype==ball) (default value is 5 pixels)
-
-- ``-filter`` the choice of the morphological operation
- (dilate/erode/opening/closing) (default value is dilate)
-
-- ``(-filter.dilate.foreval)`` the foreground value for the dilation
- (idem for filter.erode/opening/closing) (default value is 1)
-
-- ``(-filter.dilate.backval)`` the background value for the dilation
- (idem for filter.erode/opening/closing) (default value is 0)
-
-- ``-out`` the output filtered image
-
-The application can be used like this:
-
-::
-
- otbcli_BinaryMorphologicalOperation -in InputImage
- -channel 1
- -structype ball
- -structype.ball.xradius 10
- -structype.ball.yradius 5
- -filter opening
- -filter.opening.foreval 1.0
- -filter.opening.backval 0.0
- -out OutputImage
-
-Gray scale morphological operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This application performs morphological operations (dilation, erosion,
-opening and closing) on a gray scale mono band image with a specific
-structuring element (a ball or a cross) having one radius along X and
-another one along Y. NB: the cross shaped structuring element has a
-fixed radius equal to 1 pixel in both X and Y directions.
-
-The application has the following input parameters:
-
-- ``-in`` the input image to be filtered
-
-- ``-channel`` the selected channel index in the input image to be
- processed (default value is 1)
-
-- ``-structype`` the choice of the structuring element type
- (ball/cross) (default value is ball)
-
-- ``(-structype.ball.xradius)`` the ball structuring element X Radius
- (only if structype==ball) (default value is 5 pixels)
-
-- ``(-structype.ball.yradius)`` the ball structuring element Y Radius
- (only if structype==ball) (default value is 5 pixels)
-
-- ``-filter`` the choice of the morphological operation
- (dilate/erode/opening/closing) (default value is dilate)
-
-- ``-out`` the output filtered image
-
-The application can be used like this:
-
-::
-
- otbcli_GrayScaleMorphologicalOperation -in InputImage
- -channel 1
- -structype ball
- -structype.ball.xradius 10
- -structype.ball.yradius 5
- -filter opening
- -out OutputImage
-
-Textural features extraction
-----------------------------
-
-Texture features can be extracted with the help of image filters based
-on texture analysis methods like Haralick and structural feature set
-(SFS).
-
-Haralick texture features
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This application computes Haralick, advanced and higher order texture
-features on every pixel in the selected channel of the input image. The
-output image is multi band with a feature per band.
-
-The application has the following input parameters:
-
-- ``-in`` the input image to compute the features on
-
-- ``-channel`` the selected channel index in the input image to be
- processed (default value is 1)
-
-- ``-texture`` the texture set selection [simple/advanced/higher]
- (default value is simple)
-
-- ``-parameters.min`` the input image minimum (default value is 0)
-
-- ``-parameters.max`` the input image maximum (default value is 255)
-
-- ``-parameters.xrad`` the X Radius of the processing neighborhood
- (default value is 2 pixels)
-
-- ``-parameters.yrad`` the Y Radius of the processing neighborhood
- (default value is 2 pixels)
-
-- ``-parameters.xoff`` the :math:`\Delta`\ X Offset for the
- co-occurrence computation (default value is 1 pixel)
-
-- ``-parameters.yoff`` the :math:`\Delta`\ Y Offset for the
- co-occurrence computation (default value is 1 pixel)
-
-- ``-parameters.nbbin`` the number of bin per axis for histogram
- generation (default value is 8)
-
-- ``-out`` the output multi band image containing the selected texture
- features (one feature per band)
-
-The available values for -texture with their relevant features are:
-
-- ``-texture=simple:`` In this case, 8 local Haralick textures features
- will be processed. The 8 output image channels are: Energy, Entropy,
- Correlation, Inverse Difference Moment, Inertia, Cluster Shade,
- Cluster Prominence and Haralick Correlation. They are provided in
- this exact order in the output image. Thus, this application computes
- the following Haralick textures over a neighborhood with user defined
- radius. To improve the speed of computation, a variant of Grey Level
- Co-occurrence Matrix(GLCM) called Grey Level Co-occurrence Indexed
- List (GLCIL) is used. Given below is the mathematical explanation on
- the computation of each textures. Here :math:` g(i, j) ` is the
- frequency of element in the GLCIL whose index is i, j. GLCIL stores a
- pair of frequency of two pixels taken from the given offset and the
- cell index (i, j) of the pixel in the neighborhood window. :(where
- each element in GLCIL is a pair of pixel index and it’s frequency,
- :math:` g(i, j) ` is the frequency value of the pair having index is
- i, j).
-
- “Energy†:math:` = f_1 = \sum_{i, j}g(i, j)^2 `
-
- “Entropy†:math:` = f_2 = -\sum_{i, j}g(i, j) \log_2 g(i, j)`, or 0
- if :math:`g(i, j) = 0`
-
- “Correlationâ€
- :math:` = f_3 = \sum_{i, j}\frac{(i - \mu)(j - \mu)g(i, j)}{\sigma^2} `
-
- “Inverse Difference Momentâ€
- :math:`= f_4 = \sum_{i, j}\frac{1}{1 + (i - j)^2}g(i, j) `
-
- “Inertia†:math:` = f_5 = \sum_{i, j}(i - j)^2g(i, j) ` (sometimes
- called “contrastâ€)
-
- “Cluster Shadeâ€
- :math:` = f_6 = \sum_{i, j}((i - \mu) + (j - \mu))^3 g(i, j) `
-
- “Cluster Prominenceâ€
- :math:` = f_7 = \sum_{i, j}((i - \mu) + (j - \mu))^4 g(i, j) `
-
- “Haralick’s Correlationâ€
- :math:` = f_8 = \frac{\sum_{i, j}(i, j) g(i, j) -\mu_t^2}{\sigma_t^2} `
- where :math:`\mu_t` and :math:`\sigma_t` are the mean and standard
- deviation of the row (or column, due to symmetry) sums. Above,
- :math:` \mu = ` (weighted pixel average)
- :math:` = \sum_{i, j}i \cdot g(i, j) = \sum_{i, j}j \cdot g(i, j) `
- (due to matrix symmetry), and :math:` \sigma = ` (weighted pixel
- variance)
- :math:` = \sum_{i, j}(i - \mu)^2 \cdot g(i, j) = \sum_{i, j}(j - \mu)^2 \cdot g(i, j) `
- (due to matrix symmetry).
-
-- ``-texture=advanced:`` In this case, 10 advanced texture features
- will be processed. The 10 output image channels are: Mean, Variance,
- Dissimilarity, Sum Average, Sum Variance, Sum Entropy, Difference of
- Entropies, Difference of Variances, IC1 and IC2. They are provided in
- this exact order in the output image. The textures are computed over
- a sliding window with user defined radius.
-
- To improve the speed of computation, a variant of Grey Level
- Co-occurrence Matrix(GLCM) called Grey Level Co-occurrence Indexed
- List (GLCIL) is used. Given below is the mathematical explanation on
- the computation of each textures. Here :math:` g(i, j) ` is the
- frequency of element in the GLCIL whose index is i, j. GLCIL stores a
- pair of frequency of two pixels taken from the given offset and the
- cell index (i, j) of the pixel in the neighborhood window. :(where
- each element in GLCIL is a pair of pixel index and it’s frequency,
- :math:` g(i, j) ` is the frequency value of the pair having index is
- i, j).
-
- “Mean†:math:` = \sum_{i, j}i g(i, j) `
-
- “Sum of squares: Varianceâ€
- :math:` = f_4 = \sum_{i, j}(i - \mu)^2 g(i, j) `
-
- “Dissimilarity†:math:` = f_5 = \sum_{i, j}(i - j) g(i, j)^2 `
-
- “Sum average†:math:` = f_6 = -\sum_{i}i g_{x+y}(i) `
-
- “Sum Variance†:math:` = f_7 = \sum_{i}(i - f_8)^2 g_{x+y}(i) `
-
- “Sum Entropy†:math:`= f_8 = -\sum_{i}g_{x+y}(i) log (g_{x+y}(i)) `
-
- “Difference variance†:math:` = f_10 = variance of g_{x-y}(i) `
-
- “Difference entropyâ€
- :math:` = f_11 = -\sum_{i}g_{x-y}(i) log (g_{x-y}(i)) `
-
- “Information Measures of Correlation IC1â€
- :math:` = f_12 = \frac{f_9 - HXY1}{H} `
-
- “Information Measures of Correlation IC2â€
- :math:` = f_13 = \sqrt{1 - \exp{-2}|HXY2 - f_9|} `
-
- Above, :math:` \mu = ` (weighted pixel average)
- :math:` = \sum_{i, j}i \cdot g(i, j) = \sum_{i, j}j \cdot g(i, j) `
- (due to matrix summetry), and
-
- :math:` g_{x+y}(k) = \sum_{i}\sum_{j}g(i) ` where :math:` i+j=k `
- and :math:` k = 2, 3, .., 2N_{g} ` and
-
- :math:` g_{x-y}(k) = \sum_{i}\sum_{j}g(i) ` where :math:` i-j=k `
- and :math:` k = 0, 1, .., N_{g}-1 `
-
-- ``-texture=higher:`` In this case, 11 local higher order statistics
- texture coefficients based on the grey level run-length matrix will
- be processed. The 11 output image channels are: Short Run Emphasis,
- Long Run Emphasis, Grey-Level Nonuniformity, Run Length
- Nonuniformity, Run Percentage, Low Grey-Level Run Emphasis, High
- Grey-Level Run Emphasis, Short Run Low Grey-Level Emphasis, Short Run
- High Grey-Level Emphasis, Long Run Low Grey-Level Emphasis and Long
- Run High Grey-Level Emphasis. They are provided in this exact order
- in the output image. Thus, this application computes the following
- Haralick textures over a sliding window with user defined radius:
- (where :math:` p(i, j) ` is the element in cell i, j of a normalized
- Run Length Matrix, :math:`n_r` is the total number of runs and
- :math:`n_p` is the total number of pixels):
-
- “Short Run Emphasisâ€
- :math:` = SRE = \frac{1}{n_r} \sum_{i, j}\frac{p(i, j)}{j^2} `
-
- “Long Run Emphasisâ€
- :math:` = LRE = \frac{1}{n_r} \sum_{i, j}p(i, j) * j^2 `
-
- “Grey-Level Nonuniformityâ€
- :math:` = GLN = \frac{1}{n_r} \sum_{i} \left( \sum_{j}{p(i, j)} \right)^2 `
-
- “Run Length Nonuniformityâ€
- :math:` = RLN = \frac{1}{n_r} \sum_{j} \left( \sum_{i}{p(i, j)} \right)^2 `
-
- “Run Percentage†:math:` = RP = \frac{n_r}{n_p} `
-
- “Low Grey-Level Run Emphasisâ€
- :math:` = LGRE = \frac{1}{n_r} \sum_{i, j}\frac{p(i, j)}{i^2} `
-
- “High Grey-Level Run Emphasisâ€
- :math:` = HGRE = \frac{1}{n_r} \sum_{i, j}p(i, j) * i^2 `
-
- “Short Run Low Grey-Level Emphasisâ€
- :math:` = SRLGE = \frac{1}{n_r} \sum_{i, j}\frac{p(i, j)}{i^2 j^2} `
-
- “Short Run High Grey-Level Emphasisâ€
- :math:` = SRHGE = \frac{1}{n_r} \sum_{i, j}\frac{p(i, j) * i^2}{j^2} `
-
- “Long Run Low Grey-Level Emphasisâ€
- :math:` = LRLGE = \frac{1}{n_r} \sum_{i, j}\frac{p(i, j) * j^2}{i^2} `
-
- “Long Run High Grey-Level Emphasisâ€
- :math:` = LRHGE = \frac{1}{n_r} \sum_{i, j} p(i, j) i^2 j^2 `
-
-The application can be used like this:
-
-::
-
- otbcli_HaralickTextureExtraction -in InputImage
- -channel 1
- -texture simple
- -parameters.min 0
- -parameters.max 255
- -out OutputImage
-
-SFS texture extraction
-~~~~~~~~~~~~~~~~~~~~~~
-
-This application computes Structural Feature Set textures on every pixel
-in the selected channel of the input image. The output image is multi
-band with a feature per band. The 6 output texture features are
-SFS’Length, SFS’Width, SFS’PSI, SFS’W-Mean, SFS’Ratio and SFS’SD. They
-are provided in this exact order in the output image.
-
-It is based on line direction estimation and described in the following
-publication. Please refer to Xin Huang, Liangpei Zhang and Pingxiang Li
-publication, Classification and Extraction of Spatial Features in Urban
-Areas Using High-Resolution Multispectral Imagery. IEEE Geoscience and
-Remote Sensing Letters, vol. 4, n. 2, 2007, pp 260-264.
-
-The texture is computed for each pixel using its neighborhood. User can
-set the spatial threshold that is the max line length, the spectral
-threshold that is the max difference authorized between a pixel of the
-line and the center pixel of the current neighborhood. The adjustement
-constant alpha and the ratio Maximum Consideration Number, which
-describes the shape contour around the central pixel, are used to
-compute the :math:`w - mean` value.
-
-The application has the following input parameters:
-
-- ``-in`` the input image to compute the features on
-
-- ``-channel`` the selected channel index in the input image to be
- processed (default value is 1)
-
-- ``-parameters.spethre`` the spectral threshold (default value is 50)
-
-- ``-parameters.spathre`` the spatial threshold (default value is 100
- pixels)
-
-- ``-parameters.nbdir`` the number of directions (default value is 20)
-
-- ``-parameters.alpha`` the alpha value (default value is 1)
-
-- ``-parameters.maxcons`` the ratio Maximum Consideration Number
- (default value is 5)
-
-- ``-out`` the output multi band image containing the selected texture
- features (one feature per band)
-
-The application can be used like this:
-
-::
-
- otbcli_SFSTextureExtraction -in InputImage
- -channel 1
- -out OutputImage
-
diff --git a/Documentation/Cookbook/rst/improc.rst b/Documentation/Cookbook/rst/improc.rst
deleted file mode 100644
index 7265657371aaf0b4d088b3743ba8fd348eb8717a..0000000000000000000000000000000000000000
--- a/Documentation/Cookbook/rst/improc.rst
+++ /dev/null
@@ -1,380 +0,0 @@
-Image processing and information extraction
-===========================================
-
-Simple calculus with channels
------------------------------
-
-The application provides a simple and efficient way to perform band
-operations. The command line application and the corresponding
-Monteverdi module (shown in the section [Band:sub:`m`\ ath module]) are
-based on the same standards. It computes a band wise operation according
-to a user defined mathematical expression. The following code computes
-the absolute difference between first bands of two images:
-
-::
-
- otbcli_BandMath -il input_image_1 input_image_2
- -exp "abs(im1b1 - im2b1)"
- -out output_image
-
-The naming convention “im[x]b[y]†designates the yth band of the xth
-input image.
-
-The application embeds built-in operators and functions (listed
-`here <http://muparser.sourceforge.net/mup_features.html#idDef2>`__),
-allowing a vast choice of possible operations.
-
-Images with no-data values
---------------------------
-
-Image files can contain a no-data value in their metadata. It represents
-a special pixel value that should be treated as “no data available for
-this pixelâ€. For instance, SRTM tiles use a particular no-data value of
--32768 (usually found on sea areas).
-
-On multiband images, the no-data values are handled independently for
-each band. The case of an image with no-data values defined only for a
-subset of its bands is supported.
-
-This metadata is now handled by OTB image readers and writer (using the
-GDAL driver). The no-data value can be read from an image files and
-stored in the image metadata dictionary. It can also be exported by
-image writers. The OTB filters that produce a no-data value are able to
-export this value so that the output file will store it.
-
-An application has been created to manage the no-data value. The
-application has the following features :
-
-- Build a mask corresponding to the no-data pixels in the input image :
- it gives you a binary image of the no-data pixels in your input
- image.
-
-- Change the no-data value of the input image : it will change all
- pixels that carry the old no-data value to the new one and update the
- metadata
-
-- Apply an external mask to the input image as no-data : all the pixels
- that corresponds have a null mask value are flagged as no-data in the
- output image.
-
-For instance, the following command converts the no-data value of the
-input image to the default value for DEM (which is -32768) :
-
-::
-
- otbcli_ManageNoData -in input_image.tif
- -out output_image.tif
- -mode changevalue
- -mode.changevalue.newv -32768
-
-The third mode “apply†can be useful if you apply a formula to the
-entire image. This will likely change the values of pixels flagged as
-no-data, but the no-data value in the image metadata doesn’t change. If
-you want to fix all no-data pixels to their original value, you can
-extract the mask of the original image and apply it on the output image.
-For instance:
-
-::
-
- otbcli_ManageNoData -in input_image.tif
- -out mask.tif
- -mode buildmask
-
- otbcli_BandMath -il input_image.tif
- -out filtered_image.tif
- -exp "2*im1b1-4"
-
- otbcli_ManageNoData -in filtered_image.tif
- -out output_image.tif
- -mode apply
- -mode.apply.mask mask.tif
-
-Segmentation
-------------
-
-Segmenting objects across a very high resolution scene and with a
-controlled quality is a difficult task for which no method has reached a
-sufficient level of performance to be considered as operational.
-
-Even if we leave aside the question of segmentation quality and consider
-that we have a method performing reasonably well on our data and objects
-of interest, the task of scaling up segmentation to real very high
-resolution data is itself challenging. First, we can not load the whole
-data into memory, and there is a need for on the flow processing which
-does not cope well with traditional segmentation algorithms. Second, the
-result of the segmentation process itself is difficult to represent and
-manipulate efficiently.
-
-The experience of segmenting large remote sensing images is packed into
-a single in .
-
-You can find more information about this application
-`here <http://blog.orfeo-toolbox.org/preview/coming-next-large-scale-segmentation>`__.
-
-Large-Scale Mean-Shift (LSMS) segmentation
-------------------------------------------
-
-LSMS is a segmentation workflow which allows to perform tile-wise
-segmentation of very large image with theoretical guarantees of getting
-identical results to those without tiling.
-
-It has been developed by David Youssefi and Julien Michel during David
-internship at CNES.
-
-For more a complete description of the LSMS method, please refer to the
-following publication, *J. Michel, D. Youssefi and M. Grizonnet, “Stable
-Mean-Shift Algorithm and Its Application to the Segmentation of
-Arbitrarily Large Remote Sensing Images,†in IEEE Transactions on
-Geoscience and Remote Sensing, vol. 53, no. 2, pp. 952-964, Feb. 2015.*
-
-The workflow consists in chaining 3 or 4 dedicated applications and
-produces a GIS vector file with artifact-free polygons corresponding to
-the segmented image, as well as mean and variance of the radiometry of
-each band for each polygon.
-
-Step 1: Mean-Shift Smoothing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The first step of the workflow is to perform Mean-Shift smoothing with
-the application:
-
-::
-
- otbcli_MeanShiftSmoothing -in input_image
- -fout filtered_range.tif
- -foutpos filtered_spat.tif
- -ranger 30
- -spatialr 5
- -maxiter 10
- -modesearch 0
-
-Note that the *modesearch* option should be disabled, and that the
-*foutpos* parameter is optional: it can be activated if you want to
-perform the segmentation based on both spatial and range modes.
-
-This application will smooth large images by streaming them, and
-deactivating the *modesearch* will guarantee that the results will not
-depend on the streaming scheme. Please also note that the *maxiter* is
-used to set the margin to ensure these identical results, and as such
-increasing the *maxiter* may have an additional impact on processing
-time.
-
-Step 2: Segmentation
-~~~~~~~~~~~~~~~~~~~~
-
-The next step is to produce an initial segmentation based on the
-smoothed images produced by the application. To do so, the will process
-them by tiles whose dimensions are defined by the *tilesizex* and
-*tilesizey* parameters, and by writing intermediate images to disk, thus
-keeping the memory consumption very low throughout the process. The
-segmentation will group together adjacent pixels whose range distance is
-below the *ranger* parameter and (optionally) spatial distance is below
-the *spatialr* parameter.
-
-::
-
- otbcli_LSMSSegmentation -in filtered_range.tif
- -inpos filtered_spatial.tif
- -out segmentation.tif uint32
- -ranger 30
- -spatialr 5
- -minsize 0
- -tilesizex 256
- -tilesizey 256
-
-Note that the final segmentation image may contains a very large number
-of segments, and the *uint32* image type should therefore be used to
-ensure that there will be enough labels to index those segments. The
-*minsize* parameter will filter segments whose size in pixels is below
-its value, and their labels will be set to 0 (nodata).
-
-Please note that the output segmented image may look patchy, as if there
-were tiling artifacts: this is because segments are numbered
-sequentially with respect to the order in which tiles are processed. You
-will see after the result of the vectorization step that there are no
-artifacts in the results.
-
-The application will write as many intermediate files as tiles needed
-during processing. As such, it may require twice as free disk space as
-the final size of the final image. The *cleanup* option (active by
-default) will clear the intermediate files during the processing as soon
-as they are not needed anymore. By default, files will be written to the
-current directory. The *tmpdir* option allows to specify a different
-directory for these intermediate files.
-
-Step 3 (optional): Merging small regions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The application allows to filter out small segments. In the output
-segmented image, those segments will be removed and replaced by the
-background label (0). Another solution to deal with the small regions is
-to merge them with the closest big enough adjacent region in terms of
-radiometry. This is handled by the application, which will output a
-segmented image where small regions have been merged. Again, the
-*uint32* image type is advised for this output image.
-
-::
-
- otbcli_LSMSSmallRegionsMerging -in filtered_range.tif
- -inseg segementation.tif
- -out segmentation_merged.tif uint32
- -minsize 10
- -tilesizex 256
- -tilesizey 256
-
-The *minsize* parameter allows to specify the threshold on the size of
-the regions to be merged. Like the application, this application will
-process the input images tile-wise to keep resources usage low, with the
-guarantee of identical results. You can set the tile size using the
-*tilesizex* and *tilesizey* parameters. However unlike the application,
-it does not require to write any temporary file to disk.
-
-Step 4: Vectorization
-~~~~~~~~~~~~~~~~~~~~~
-
-The last step of the LSMS workflow consists in the vectorization of the
-segmented image into a GIS vector file. This vector file will contain
-one polygon per segment, and each of these polygons will hold additional
-attributes denoting the label of the original segment, the size of the
-segment in pixels, and the mean and variance of each band over the
-segment. The projection of the output GIS vector file will be the same
-as the projection from the input image (if input image has no
-projection, so does the output GIS file).
-
-::
-
- otbcli_LSMSVectorization -in input_image
- -inseg segmentation_merged.tif
- -out segmentation_merged.shp
- -tilesizex 256
- -tilesizey 256
-
-This application will process the input images tile-wise to keep
-resources usage low, with the guarantee of identical results. You can
-set the tile size using the *tilesizex* and *tilesizey* parameters.
-However unlike the application, it does not require to write any
-temporary file to disk.
-
-Dempster Shafer based Classifier Fusion
----------------------------------------
-
-This framework is dedicated to perform cartographic validation starting
-from the result of a detection (for example a road extraction), enhance
-the results fiability by using a classifier fusion algorithm. Using a
-set of descriptor, the processing chain validates or invalidates the
-input geometrical features.
-
-Fuzzy Model (requisite)
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The application performs the fuzzy model estimation (once by use case:
-descriptor set / Belief support / Plausibility support). It has the
-following input parameters :
-
-- ``-psin`` a vector data of positive samples enriched according to the
- “Compute Descriptors†part
-
-- ``-nsin`` a vector data of negative samples enriched according to the
- “Compute Descriptors†part
-
-- ``-belsup`` a support for the Belief computation
-
-- ``-plasup`` a support for the Plausibility computation
-
-- ``-desclist`` an initialization model (xml file) or a descriptor name
- list (listing the descriptors to be included in the model)
-
-The application can be used like this:
-
-::
-
- otbcli_DSFuzzyModelEstimation -psin PosSamples.shp
- -nsin NegSamples.shp
- -belsup "ROADSA"
- -plasup "NONDVI" "ROADSA" "NOBUIL"
- -desclist "NONDVI" "ROADSA" "NOBUIL"
- -out FuzzyModel.xml
-
-The output file ``FuzzyModel.xml`` contains the optimal model to perform
-informations fusion.
-
-First Step: Compute Descriptors
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The first step in the classifier fusion based validation is to compute,
-for each studied polyline, the choosen descriptors. In this context, the
-application can be used for a large range of descriptors. It has the
-following inputs :
-
-- ``-in`` an image (of the sudied scene) corresponding to the choosen
- descriptor (NDVI, building Mask…)
-
-- ``-vd`` a vector data containing polyline of interest
-
-- ``-expr`` a formula (“b1 >0.4â€, “b1 == 0â€) where b1 is the standard
- name of input image first band
-
-- ``-field`` a field name corresponding to the descriptor codename
- (NONDVI, ROADSA...)
-
-The output is a vector data containing polylines with a new field
-containing the descriptor value. In order to add the “NONDVI†descriptor
-to an input vector data (“inVD.shpâ€) corresponding to the percentage of
-pixels along a polyline that verifies the formula “NDVI >0.4†:
-
-::
-
- otbcli_ComputePolylineFeatureFromImage -in NDVI.TIF
- -vd inVD.shp
- -expr "b1 > 0.4"
- -field "NONDVI"
- -out VD_NONDVI.shp
-
-``NDVI.TIF`` is the NDVI mono band image of the studied scene. This step
-must be repeated for each choosen descriptor:
-
-::
-
- otbcli_ComputePolylineFeatureFromImage -in roadSpectralAngle.TIF
- -vd VD_NONDVI.shp
- -expr "b1 > 0.24"
- -field "ROADSA"
- -out VD_NONDVI_ROADSA.shp
-
-::
-
- otbcli_ComputePolylineFeatureFromImage -in Buildings.TIF
- -vd VD_NONDVI_ROADSA.shp
- -expr "b1 == 0"
- -field "NOBUILDING"
- -out VD_NONDVI_ROADSA_NOBUIL.shp
-
-Both ``NDVI.TIF`` and ``roadSpectralAngle.TIF`` can be produced using
-feature extraction capabilities, and ``Buildings.TIF`` can be generated
-using rasterization module. From now on, ``VD_NONDVI_ROADSA_NOBUIL.shp``
-contains three descriptor fields. It will be used in the following part.
-
-Second Step: Feature Validation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The final application () will validate or unvalidate the studied samples
-using `the Dempster-Shafer
-theory <http://en.wikipedia.org/wiki/Dempster%E2%80%93Shafer_theory>`__
-. Its inputs are :
-
-- ``-in`` an enriched vector data “VD\_NONDVI\_ROADSA\_NOBUIL.shpâ€
-
-- ``-belsup`` a support for the Belief computation
-
-- ``-plasup`` a support for the Plausibility computation
-
-- ``-descmod`` a fuzzy model FuzzyModel.xml
-
-The output is a vector data containing only the validated samples.
-
-::
-
- otbcli_VectorDataDSValidation -in extractedRoads_enriched.shp
- -descmod FuzzyModel.xml
- -out validatedSamples.shp
-
diff --git a/Documentation/Cookbook/rst/index.rst b/Documentation/Cookbook/rst/index.rst
index 4459a0c85319222623361758396a2e9bf69b9e91..b08bd480ad53075401f85bac73ec741c80bbafe8 100644
--- a/Documentation/Cookbook/rst/index.rst
+++ b/Documentation/Cookbook/rst/index.rst
@@ -9,15 +9,13 @@ Welcome to OTB CookBook's documentation!
.. toctree::
:maxdepth: 3
+ CookBook
OTB-Applications
Monteverdi
- Monteverdi2
Recipes
+ WrappedApplications
Applications
-
-
-
Indices and tables
==================
diff --git a/Documentation/Cookbook/rst/optpreproc.rst b/Documentation/Cookbook/rst/optpreproc.rst
deleted file mode 100644
index 1e595c8f556a53b5409b0cada132e6c63de86496..0000000000000000000000000000000000000000
--- a/Documentation/Cookbook/rst/optpreproc.rst
+++ /dev/null
@@ -1,767 +0,0 @@
-From raw image to calibrated product
-====================================
-
-This section presents various pre-processing tasks that are presented in
-a classical order to obtain a calibrated, pan-sharpened image.
-
-Optical radiometric calibration
--------------------------------
-
-In remote sensing imagery, pixel values are called DN (for Digital
-Numbers) and can not be physically interpreted and compared: they are
-influenced by various factors such as the amount of light flowing trough
-the sensor, the gain of the detectors and the analogic to numeric
-converter.
-
-Depending on the season, the light and atmospheric conditions, the
-position of the sun or the sensor internal parameters, these DN can
-drastically change for a given pixel (apart from any ground change
-effects). Moreover, these effects are not uniform over the spectrum: for
-instance aerosol amount and type has usually more impact on the blue
-channel.
-
-Therefore, it is necessary to calibrate the pixel values before any
-physical interpretation is made out of them. In particular, this
-processing is mandatory before any comparison of pixel spectrum between
-several images (from the same sensor), and to train a classifier without
-dependence to the atmospheric conditions at the acquisition time.
-
-Calibrated values are called surface reflectivity, which is a ratio
-denoting the fraction of light that is reflected by the underlying
-surface in the given spectral range. As such, its values lie in the
-range :math:`[0,1]`. For convenience, images are often stored in
-thousandth of reflectivity, so that they can be encoded with an integer
-type. Two levels of calibration are usually distinguished:
-
-- The first level is called *Top Of Atmosphere (TOA)* reflectivity. It
- takes into account the sensor gain, sensor spectral response and the
- solar illumination.
-
-- The second level is called *Top Of Canopy (TOC)* reflectivity. In
- addition to sensor gain and solar illumination, it takes into account
- the optical thickness of the atmosphere, the atmospheric pressure,
- the water vapor amount, the ozone amount, as well as the composition
- and amount of aerosol gasses.
-
-This transformation can be done either with or with . Sensor-related
-parameters such as gain, date, spectral sensitivity and sensor position
-are seamlessly read from the image metadata. Atmospheric parameters can
-be tuned by the user. Supported sensors are :
-
-- Pleiades,
-
-- SPOT5,
-
-- QuickBird,
-
-- Ikonos,
-
-- WorldView-1,
-
-- WorldView-2,
-
-- Formosat.
-
-Optical calibration with
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The application allows to perform optical calibration. The mandatory
-parameters are the input and output images. All other parameters are
-optional. By default the level of calibration is set to TOA (Top Of
-Atmosphere). The output images are expressed in thousandth of
-reflectivity using a 16 bits unsigned integer type.
-
-A basic TOA calibration task can be performed with the following command
-:
-
-::
-
- otbcli_OpticalCalibration -in input_image -out output_image
-
-A basic TOC calibration task can be performed with the following command
-:
-
-::
-
- otbcli_OpticalCalibration -in input_image -out output_image -level toc
-
-Optical calibration with
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-These transformations can also be done in .
-
-The 6S model needs atmospheric parameters to be able to compute
-radiative terms to estimate the atmospheric contributions on the input
-signal. Default parameters are available in the module. For atmospheric
-parameters, it is possible to indicate AERONET file. The AERONET
-(AErosol RObotic NETwork) program is a federation of ground-based remote
-sensing aerosol networks established by NASA and PHOTONS (Univ. of Lille
-1, CNES, and CNRS-INSU) and is greatly expanded by collaborators from
-national agencies, institutes, universities, individual scientists, and
-partners. The program provides accessible public domain database of
-aerosol optical, mircrophysical and radiative properties.
-
-The module produces four outputs:
-
-- Luminance image.
-
-- TOA reflectance image.
-
-- TOC reflectance image.
-
-- Difference TOA-TOC image, which allows to get the estimation of
- atmospheric contribution.
-
-|image| [fig:opticalcalibration]
-
-|image| [fig:opticalcalibrationoutput]
-
-Pan-sharpening
---------------
-
-Because of physical constrains on the sensor design, it is difficult to
-achieve high spatial and spectral resolution at the same time : a better
-spatial resolution means a smaller detector, which in turns means lesser
-optical flow on the detector surface. On the contrary, spectral bands
-are obtained through filters applied on the detector surface, that
-lowers the optical flow, so that it is necessary to increase the
-detector size to achieve an acceptable signal to noise ratio.
-
-For these reasons, many high resolution satellite payload are composed
-of two sets of detectors, which in turns delivers two different kind of
-images :
-
-- The multi-spectral (XS) image, composed of 3 to 8 spectral bands
- containing usually blue, green, red and near infra-red bands at a
- given resolution (usually from 2.8 meters to 2 meters).
-
-- The panchromatic (PAN) image, which is a grayscale image acquired by
- a detector covering a wider part of the light spectrum, which allows
- to increase the optical flow and thus to reduce pixel size.
- Therefore, resolution of the panchromatic image is usually around 4
- times lower than the resolution of the multi-spectral image (from 46
- centimeters to 70 centimeters).
-
-It is very frequent that those two images are delivered side by side by
-data providers. Such a dataset is called a bundle. A very common remote
-sensing processing is to fuse the panchromatic image with the
-multi-spectral one so as to get an image combining the spatial
-resolution of the panchromatic image with the spectral richness of the
-multi-spectral image. This operation is called pan-sharpening.
-
-This fusion operation requires two different steps :
-
-#. The multi-spectral (XS) image is zoomed and registered to the
- panchromatic image,
-
-#. A pixel-by-pixel fusion operator is applied to the co-registered
- pixels of the multi-spectral and panchromatic image to obtain the
- fused pixels.
-
-Using either or modules from , it is possible to perform both steps in a
-row, or step-by-step fusion, as described in the above sections.
-
-Pan-sharpening with
-~~~~~~~~~~~~~~~~~~~~
-
-The application allows to perform both steps in a row. Seamless sensor
-modelling is used to perform zooming and registration of the
-multi-spectral image on the panchromatic image. In the case of a
-Pléiades bundle, a different approach is used : an affine transform is
-used to zoom the multi-spectral image and apply a residual translation.
-This translation is computed based on metadata about the geometric
-processing of the bundle. This zooming and registration of the
-multi-spectral image over the panchromatic image can also be performed
-by the application.
-
-After the registration step, a simple pan-sharpening is applied,
-according to the following formula:
-
-.. math:: PXS(i,j) = \frac{PAN(i,j)}{PAN_{smooth}(i,j)} \cdot XS(i,j)
-
-Where :math:`i` and :math:`j` are pixels indices, :math:`PAN` is the
-panchromatic image, :math:`XS` is the multi-spectral image and
-:math:`PAN_{smooth}` is the panchromatic image smoothed with a kernel to
-fit the multi-spectral image scale.
-
-Here is a simple example of how to use the application:
-
-::
-
- otbcli_BundleToPerfectSensor -inp pan_image -inxs xs_image -out output_image
-
-There are also optional parameters that can be useful for this tool:
-
-- The ``-elev`` option allows to specify the elevation, either with a
- DEM formatted for OTB (``-elev.dem`` option, see section [ssec:dem])
- or with an average elevation (``-elev.default`` option). Since
- registration and zooming of the multi-spectral image is performed
- using sensor-models, it may happen that the registration is not
- perfect in case of landscape with high elevation variation. Using a
- DEM in this case allows to get better registration.
-
-- The ``-lmSpacing`` option allows to specify the step of the
- registration grid between the multi-spectral image and panchromatic
- image. This is expressed in amount of panchromatic pixels. A lower
- value gives a more precise registration but implies more computation
- with the sensor models, and thus increase the computation time.
- Default value is 10 pixels, which gives sufficient precision in most
- of the cases.
-
-- The ``-mode`` option allows to select the registration mode for the
- multi-spectral image. The ``default`` mode uses the sensor model of
- each image to create a generic “MS to Pan†transform. The ``phr``
- mode uses a simple affine transform (which doesn’t need an elevation
- source nor a registration grid).
-
-Pan-sharpening is a quite heavy processing requiring a lot of system
-resource. The ``-ram`` option allows you to limit the amount of memory
-available for the computation, and to avoid overloading your computer.
-Increasing the available amount of RAM may also result in better
-computation time, seems it optimises the use of the system resources.
-Default value is 256 Mb.
-
-Pan-sharpening with
-~~~~~~~~~~~~~~~~~~~~
-
-allows to perform step-by-step fusion. The followings screenshots
-highlight operations needed to perform Pan-Sharpening.
-
-- Open panchromatic and multispectral images in monteverdi using the
- module or using the ``-il`` option of the executable.
-
-- The module is used to zoomed and registered the multispectral on the
- panchromatic image. As a result, we get a multispectral dataset with
- the same geographic extension and the same resolution as the
- panchromatic image, cf  [fig:qbmulsuper].
-
- |image| |image| [fig:qbmulsuper]
-
-- Now the module can be used using the panchromatic and the
- multispectral images as inputs. It produces a multispectral image
- with the same resolution and geographic extension (cf
- Â [fig:pansharpen]).
-
- |image| [fig:pansharpen]
-
-Please also note that since registration and zooming of the
-multi-spectral image with the panchromatic image relies on sensor
-modelling, this tool will work only for images whose sensor models is
-available in (see section [ssec:ortho] for a detailed list). It will
-also work with ortho-ready products in cartographic projection.
-
-Digital Elevation Model management
-----------------------------------
-
-A Digital Elevation Model (DEM) is a georeferenced image (or collection
-of images) where each pixel corresponds to a local elevation. DEM are
-useful for tasks involving sensor to ground and ground to sensor
-coordinate transforms, like during ortho-rectification (see
-section [ssec:ortho]). These transforms need to find the intersection
-between the line of sight of the sensor and the earth geoid. If a simple
-spheroid is used as the earth model, potentially high localisation
-errors can be made in areas where elevation is high or perturbed. Of
-course, DEM accuracy and resolution have a great impact on the precision
-of these transforms.
-
-Two main available DEM, free of charges, and with worldwide cover, are
-both delivered as 1 degree by 1 degree tiles:
-
-- `The Shuttle Radar topographic Mission
- (SRTM) <http://www2.jpl.nasa.gov/srtm/>`__ is a 90 meters resolution
- DEM, obtained by radar interferometry during a campaign of the
- Endeavour space shuttle from NASA in 2000.
-
-- The `Advanced Spaceborne Thermal Emission and Reflection Radiometer
- (ASTER) <http://www.ersdac.or.jp/GDEM/E/2.html>`__ is a 30 meters
- resolution DEM obtained by stereoscopic processing of the archive of
- the ASTER instrument.
-
-The relies on capabilities for sensor modelling and DEM handling. Tiles
-of a given DEM are supposed to be located within a single directory.
-General elevation support is also supported from GeoTIFF files.
-
-Whenever an application or module requires a DEM, the option
-**elev.dem** allows set the DEM directory. This directory must contains
-the DEM tiles, either in DTED or SRTM format, either as GeoTIFF files.
-Subdirectories are not supported.
-
-Depending on the reference of the elevation, you also need to use a
-geoid to manage elevation accurately. For this, you need to specify a
-path to a file which contains the geoid. Geoid corresponds to the
-equipotential surface that would coincide with the mean ocean surface of
-the Earth (see `) <http://en.wikipedia.org/wiki/Geoid>`__. We provide
-one geoid in the OTB-Data repository available
-`here <http://hg.orfeo-toolbox.org/OTB-Data/file/4722d9e672c6/Input/DEM/egm96.grd>`__.
-
-In all applications, the option **elev.geoid** allows to manage the path
-to the geoid. Finally, it is also possible to use an average elevation
-in case no DEM is available by using the **elev.default** option.
-
-Ortho-rectification and map projections
----------------------------------------
-
-There are several level of products available on the remote sensing
-imagery market. The most basic level often provide the geometry of
-acquisition (sometimes called the raw geometry). In this case, pixel
-coordinates can not be directly used as geographical positions. For most
-sensors (but not for all), the different lines corresponds to different
-acquisition times and thus different sensor positions, and different
-rows correspond to different cells of the detector.
-
-The mapping of a raw image so as to be registered to a cartographic grid
-is called ortho-rectification, and consist in inverting the following
-effects (at least):
-
-- In most cases, lines are orthogonal to the sensor trajectory, which
- is not exactly (and in some case not at all) following a north-south
- axis,
-
-- Depending on the sensor, the line of sight may be different from a
- Nadir (ground position of the sensor), and thus a projective warping
- may appear,
-
-- The variation of height in the landscape may result in severe warping
- of the image.
-
-Moreover, depending on the area of the world the image has been acquired
-on, different map projections should be used.
-
-The ortho-rectification process is as follows: once an appropriate map
-projection has been defined, a localisation grid is computed to map
-pixels from the raw image to the ortho-rectified one. Pixels from the
-raw image are then interpolated according to this grid in order to fill
-the ortho-rectified pixels.
-
-Ortho-rectification can be performed either with or . Sensor parameters
-and image meta-data are seamlessly read from the image files without
-needing any user interaction, provided that all auxiliary files are
-available. The sensor for which supports ortho-rectification of raw
-products are the following:
-
-- Pleiades,
-
-- SPOT5,
-
-- Ikonos,
-
-- Quickbird,
-
-- GeoEye,
-
-- WorldView.
-
-In addition, GeoTiff and other file format with geographical information
-are seamlessly read by , and the ortho-rectification tools can be used
-to re-sample these images in another map projection.
-
-Beware of “ortho-ready†products
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are some image products, called “ortho-readyâ€, that should be
-processed carefully. They are actual products in raw geometry, but their
-metadata also contains projection data :
-
-- a map projection
-
-- a physical origin
-
-- a physical spacing
-
-- and sometimes an orientation angle
-
-The purpose of this projection information is to give an approximate map
-projection to a raw product. It allows you to display the raw image in a
-GIS viewer at the (almost) right location, without having to reproject
-it. Obviously, this map projection is not as accurate as the sensor
-parameters of the raw geometry. In addition, the impact of the elevation
-model can’t be observed if the map projection is used. In order to
-perform an ortho-rectification on this type of product, the map
-projection has to be hidden from .
-
-You can see if a product is an “ortho-ready†product by using tools such
-as ``gdalinfo`` or (see [app:ReadImageInfo]), and check if the product
-verifies the 2 following conditions :
-
-- The product is in raw geometry : you should expect the presence of
- RPC coefficients and a non-empty OSSIM keywordlist.
-
-- The product has a map projection : you should see a projection name
- with physical origin and spacing.
-
-In that case, you can hide the map projection from the by using
-*extended* filenames. Instead of using the plain input image path, you
-append a specific key at the end :
-
-::
-
- "path_to_image?&skipcarto=true"
-
-The double quote can be necessary for a successful parsing. More details
-about the extended filenames can be found
-`here <http://wiki.orfeo-toolbox.org/index.php/ExtendedFileName>`__, and
-also in the .
-
-Ortho-rectification with
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The application allows to perform ortho-rectification and map
-re-projection. The simplest way to use it is the following command:
-
-::
-
- otbcli_OrthoRectification -io.in input_image -io.out output_image
-
-In this case, the tool will automatically estimates all the necessary
-parameters:
-
-- The map projection is set to UTM (a worldwide map projection) and the
- UTM zone is automatically estimated,
-
-- The ground sampling distance of the output image is computed to fit
- the image resolution,
-
-- The region of interest (upper-left corner and size of the image) is
- estimated so as to contain the whole input image extent.
-
-In order to use a Digital Elevation Model (see section [ssec:dem]) for
-better localisation performances, one can pass the directory containing
-the DEM tiles to the application:
-
-::
-
- otbcli_OrthoRectification -io.in input_image
- -io.out output_image
- -elev.dem dem_dir
-
-If one wants to use a different map projection, the *-map* option may be
-used (example with *lambert93* map projection):
-
-::
-
-
- otbcli_OrthoRectification -io.in input_image
- -io.out output_image
- -elev.dem dem_dir
- -map lambert93
-
-Map projections handled by the application are the following (please
-note that the ellipsoid is always WGS84):
-
-- | UTM : ``-map utm``
- | The UTM zone and hemisphere can be set by the options
- ``-map.utm.zone`` and ``-map.utm.northhem``.
-
-- Lambert 2 etendu: ``-map lambert2``
-
-- Lambert 93: ``-map lambert93``
-
-- | TransMercator: ``-map transmercator``
- | The related parameters (false easting, false northing and scale
- factor) can be set by the options
- ``-map.transmercator.falseeasting``,
- ``-map.transmercator.falsenorthing`` and ``-map.transmercator.scale``
-
-- WGS : ``-map wgs``
-
-- | Any map projection system with an EPSG code : ``-map epsg``
- | The EPSG code is set with the option ``-map.epsg.code``
-
-The group ``outputs`` contains parameters to set the origin, size and
-spacing of the output image. For instance, the ground spacing can be
-specified as follows:
-
-::
-
-
- otbcli_OrthoRectification -io.in input_image
- -io.out output_image
- -elev.dem dem_dir
- -map lambert93
- -outputs.spacingx spx
- -outputs.spacingy spy
-
-Please note that since the y axis of the image is bottom oriented, the y
-spacing should be negative to avoid switching north and south direction.
-
-A user-defined region of interest to ortho-rectify can be specified as
-follows:
-
-::
-
-
- otbcli_OrthoRectification -io.in input_image
- -io.out output_image
- -elev.dem dem_dir
- -map lambert93
- -outputs.spacingx spx
- -outputs.spacingy spy
- -outputs.ulx ul_x_coord
- -outputs.uly ul_y_coord
- -outputs.sizex x_size
- -outputs.sizey y_size
-
-Where the ``-outputs.ulx`` and ``-outputs.uly`` options allow to specify
-the coordinates of the upper-left corner of the output image. The
-``-outputs.sizex`` and ``-outputs.sizey`` options allow to specify the
-size of the output image.
-
-A few more interesting options are available:
-
-- The ``-opt.rpc`` option allows to use an estimated RPC model instead
- of the rigorous SPOT5 model, which speeds-up the processing,
-
-- The ``-opt.gridspacing`` option allows to define the spacing of the
- localisation grid used for ortho-rectification. A coarser grid
- results in speeding-up the processing, but with potential loss of
- accuracy. A standard value would be 10 times the ground spacing of
- the output image.
-
-- The ``-interpolator`` option allows to change the interpolation
- algorithm between nearest neighbor, linear and bicubic. Default is
- nearest neighbor interpolation, but bicubic should be fine in most
- cases.
-
-- The ``-opt.ram`` option allows to specify the amount of memory
- available for the processing (in Mb). Default is 256 Mb. Increasing
- this value to fit the available memory on your computer might
- speed-up the processing.
-
-Residual registration
----------------------
-
-Image registration is a fundamental problem in image processing. The aim
-is to align two or more images of the same scene often taken at
-different times, from different viewpoints, or by different sensors. It
-is a basic step for orthorectification, image stitching, image fusion,
-change detection…But this process is also critical for stereo
-reconstruction process to be able to obtain an accurate estimation of
-epipolar geometry.
-
-Sensor model is generally not sufficient to provide image registrations.
-Indeed, several sources of geometric distortion can be contained in
-optical remote sensing images including earth rotation, platform
-movement, non linearity…
-
-They result in geometric errors on scene level, image level and pixel
-level. It is critical to rectify the errors before a thematic map is
-generated, especially when the remote sensing data need to be integrated
-together with other GIS data.
-
-This figure illustrates the generic workflow in the case of image series
-registration:
-
-[scale=0.15] (-1,-12) rectangle (75,17); in 5,...,1 (,) rectangle
-+(4,4); (InputSeries) at (4,-1) Input series; (9,5) – +(3,0); (12.2,3)
-rectangle +(6,4); (SensorModel) at (15,5) Sensor Model; (1,-10)
-rectangle +(4,4); (DEM) at (5,-11) DEM; (3,-5.5) – ++(0,3) – ++(12,0) –
-++(0,5); (18.5,5) – +(3,0); in 5,...,1 (,) rectangle +(4,4);
-(GeoRefSeries) at (28,-1) Geo-referenced Series;
-
-(25.5,8.5) – +(0,3);
-
-(22,12) rectangle +(8.5,4); (HomPoExtr) at (27,14) Homologous Points;
-
-(21.5,14) – +(-2.5,0);
-
-(11,12) rectangle +(8,4); (BBAdj) at (15.5,14) Bundle-block Adjustement;
-
-(15,11.5) – +(0,-4);
-
-(30,5) – +(3,0); (33.2,2.5) rectangle +(6,4.5); (FineRegistration) at
-(36,4.9) Fine Registration;
-
-(39.5,5) – +(3,0); in 5,...,1 (,) rectangle +(4,4); (RegistSeries) at
-(47,-1) Registered Series; (36,2) – ++(0,-10) – ++(-30,0);
-
-(52,5) – +(3,0); (55.2,2.5) rectangle +(6,4.5); (CartoProjection) at
-(57.5,4.9) Map Projection;
-
-(61.5,5) – +(3,0); in 5,...,1 (,) rectangle +(4,4); (CartoSeries) at
-(68,-1) Cartographic Series;
-
-We will now illustrate this process by applying this workflow to
-register two images. This process can be easily extended to perform
-image series registration.
-
-The aim of this example is to describe how to register a Level 1
-QuickBird image over an orthorectify Pleiades image over the area of
-Toulouse, France.
-
-|image| |image| [fig:InputImagesRegistration]
-
-Extract metadata from the image reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We first dump geometry metadata of the image we want to refine in a text
-file. In OTB, we use the extension *.geom* for this type of file. As you
-will see the application which will estimate a refine geometry only
-needs as input this metadata and a set of homologous points. The
-refinement application will create a new *.geom* file containing refined
-geometry parameters which can be used after for reprojection for
-example.
-
-The use of external *.geom* file is available in OTB since release
-:math:`3.16`. See
-`here <http://wiki.orfeo-toolbox.org/index.php/ExtendedFileName>`__ for
-more information.
-
-::
-
-
- otbcli_ReadImageInfo -in slave_image
- -outkwl TheGeom.geom
-
-Extract homologous points from images
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The main idea of the residual registration is to estimate an second
-transformation (after the application of sensors model).
-
-The homologous point application use interest point detection method to
-get a set of point which match in both images.
-
-The basic idea is to use this set of homologous points and estimate with
-them a residual transformation between the two images.
-
-There is a wide variety of keypoint detector in the literature. They
-allow to detect and describe local features in images. These algorithms
-provide for each interesting point a “feature descriptionâ€. This
-descriptor has the property to be invariant to image translation,
-scaling, and rotation, partially invariant to illumination changes and
-robust to local geometric distortion. keypoints. Features extracted from
-the input images are then matched against each other. These
-correspondences are then used to create the homologous points.
-
-`SIFT <http://en.wikipedia.org/wiki/Scale-invariant_feature_transform>`__
-or `SURF <http://en.wikipedia.org/wiki/SURF>`__ keypoints can be
-computed in the application. The band on which keypoints are computed
-can be set independently for both images.
-
-The application offers two modes :
-
-- the first is the full mode where keypoints are extracted from the
- full extent of both images (please note that in this mode large image
- file are not supported).
-
-- The second mode, called *geobins*, allows to set-up spatial binning
- so as to get fewer points spread across the entire image. In this
- mode, the corresponding spatial bin in the second image is estimated
- using geographical transform or sensor modeling, and is padded
- according to the user defined precision.
-
-Moreover, in both modes the application can filter matches whose
-co-localization in the first image exceed this precision. Last, the
-elevation parameters allow to deal more precisely with sensor modelling
-in case of sensor geometry data. The *outvector* option allows to create
-a vector file with segments corresponding to the localization error
-between the matches.
-
-Finally, with the *2wgs84* option, you can match two sensor geometry
-images or a sensor geometry image with an ortho-rectified reference. In
-all cases, you get a list of ground control points spread all over your
-image.
-
-::
-
-
-
- otbcli_HomologousPointsExtraction -in1 slave_image
- -in2 reference_image
- -algorithm surf
- -mode geobins
- -mode.geobins.binstep 512
- -mode.geobins.binsize 512
- -mfilter 1
- -precision 20
- -2wgs84 1
- -out homologous_points.txt
- -outvector points.shp
- -elev.dem dem_path/SRTM4-HGT/
- -elev.geoid OTB-Data/Input/DEM/egm96.grd
-
-Note that for a proper use of the application, elevation must be
-correctly set (including DEM and geoid file).
-
-Geometry refinement using homologous points
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now that we can use this set of tie points to estimate a residual
-transformation.For this we use the dedicated application called
-**RefineSensorModel**. This application make use of OSSIM capabilities
-to align the sensor model.
-
-It reads the input geometry metadata file (*.geom*) which contains the
-sensor model information that we want to refine and the text file
-(homologous\_points.txt) containing the list of ground control point. It
-performs a least-square fit of the sensor model adjustable parameters to
-these tie points and produces an updated geometry file as output (the
-extension which is always use is *.geom*)
-
-The application can provide as well an optional ground control points
-based statistics file and a vector file containing residues that you can
-display in a GIS software.
-
-Please note again that for a proper use of the application, elevation
-must be correctly set (including DEM and geoid file). The map parameters
-allows to choose a map projection in which the accuracy will be
-estimated (in meters).
-
-Accuracy values are provided as output of the application (computed
-using tie points location) and allow also to control the precision of
-the estimated model.
-
-::
-
-
- otbcli_RefineSensorModel -elev.dem dem_path/SRTM4-HGT/
- -elev.geoid OTB-Data/Input/DEM/egm96.grd
- -ingeom slave_image.geom
- -outgeom refined_slave_image.geom
- -inpoints homologous_points.txt
- -outstat stats.txt
- -outvector refined_slave_image.shp
-
-Orthorecrtify image using the affine geometry
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now we will show how we can use this new sensor model. In our case we’ll
-use this sensor model to orthorectify the image over the Pléiades
-reference. offers since version 3.16 the possibility to use
-hrefhttp://wiki.orfeo-toolbox.org/index.php/ExtendedFileNameextend image
-path to use different metadata file as input. That’s what we are going
-to use there to orthorectify the QuickBird image using the *.geom* file
-obtained by the **RefineSensorModel** applications. over the first one
-using for the second image estimated sensor model which take into
-account the original sensor model of the slave and which also fit to the
-set of tie points.
-
-::
-
-
- otbcli_OrthoRectification -io.in slave_image?&geom=TheRefinedGeom.geom
- -io.out ortho_slave_image
- -elev.dem dem_path/SRTM4-HGT/
- -elev.geoid OTB-Data/Input/DEM/egm96.grd
-
-
-As a result, if you’ve got enough homologous points in images and
-control that the residual error between the set of tie points and the
-estimated sensor model is small, you must achieve a good registration
-now between the 2 rectified images. Normally far better than ’only’
-performing separate orthorectification over the 2 images.
-
-This methodology can be adapt and apply in several cases, for example :
-
-- register stereo pair of images and estimate accurate epipolar
- geometry
-
-- registration prior to change detection
-
-.. |image| image:: ../Art/MonteverdiImages/monteverdi_optical_calibration.png
-.. |image| image:: ../Art/MonteverdiImages/monteverdi_optical_calibration_outputs.png
-.. |image| image:: ../Art/MonteverdiImages/monteverdi_QB_PAN_ROI.png
-.. |image| image:: ../Art/MonteverdiImages/monteverdi_QB_MUL_Superimpose.png
-.. |image| image:: ../Art/MonteverdiImages/monteverdi_QB_XS_pan-sharpened.png
-.. |image| image:: ../Art/MonteverdiImages/registration_pleiades_ql.png
-.. |image| image:: ../Art/MonteverdiImages/registration_quickbird_ql.png
diff --git a/Documentation/Cookbook/rst/pbclassif.rst b/Documentation/Cookbook/rst/pbclassif.rst
deleted file mode 100644
index f458f0f7402053fab3bb40db805cf94b90c3c18a..0000000000000000000000000000000000000000
--- a/Documentation/Cookbook/rst/pbclassif.rst
+++ /dev/null
@@ -1,616 +0,0 @@
-Classification
-==============
-
-Pixel based classification
---------------------------
-
-The classification in the application framework provides a supervised
-pixel-wise classification chain based on learning from multiple images,
-and using one specified machine learning method like SVM, Bayes, KNN,
-Random Forests, Artificial Neural Network, and others...(see application
-help of for further details about all the available classifiers). It
-supports huge images through streaming and multi-threading. The
-classification chain performs a training step based on the intensities
-of each pixel as features. Please note that all the input images must
-have the same number of bands to be comparable.
-
-Statistics estimation
-~~~~~~~~~~~~~~~~~~~~~
-
-In order to make these features comparable between each training images,
-the first step consists in estimating the input images statistics. These
-statistics will be used to center and reduce the intensities (mean of 0
-and standard deviation of 1) of samples based on the vector data
-produced by the user. To do so, the tool can be used:
-
-::
-
- otbcli_ComputeImagesStatistics -il im1.tif im2.tif im3.tif
- -out images_statistics.xml
-
-This tool will compute each band mean, compute the standard deviation
-based on pooled variance of each band and finally export them to an XML
-file. The features statistics XML file will be an input of the following
-tools.
-
-Building the training data set
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As the chain is supervised, we first need to build a training set with
-positive examples of different objects of interest. These polygons must
-be saved in OGR vector format supported by GDAL like ESRI shapefile for
-example.
-
-Please note that the positive examples in the vector data should have a
-\`\`Class\`\` field with a label value higher than 1 and coherent in
-each images.
-
-You can generate the vector data set with software for example and save
-it in an OGR vector format supported by (ESRI shapefile for example).
-should be able to transform the vector data into the image coordinate
-system.
-
-Performing the learning scheme
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once images statistics have been estimated, the learning scheme is the
-following:
-
-#. For each input image:
-
- #. Read the region of interest (ROI) inside the shapefile,
-
- #. Generate validation and training data within the ROI,
-
- #. Add vectors respectively to the training samples set and the
- validation samples set.
-
-#. Increase the size of the training samples set and balance it by
- generating new noisy samples from the previous ones,
-
-#. Perform the learning with this training set
-
-#. Estimate performances of the classifier on the validation samples set
- (confusion matrix, precision, recall and F-Score).
-
-Let us consider a SVM classification. These steps can be performed by
-the command-line using the following:
-
-::
-
- otbcli_TrainImagesClassifier -io.il im1.tif im2.tif im3.tif
- -io.vd vd1.shp vd2.shp vd3.shp
- -io.imstat images_statistics.xml
- -classifier svm (classifier_for_the_training)
- -io.out model.svm
-
-Additional groups of parameters are also available (see application help
-for more details):
-
-- ``-elev`` Handling of elevation (DEM or average elevation)
-
-- ``-sample`` Group of parameters for sampling
-
-- ``-classifier`` Classifiers to use for the training, and their
- corresponding groups of parameters
-
-Using the classification model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once the classifier has been trained, one can apply the model to
-classify pixel inside defined classes on a new image using the
-application:
-
-::
-
- otbcli_ImageClassifier -in image.tif
- -imstat images_statistics.xml
- -model model.svm
- -out labeled_image.tif
-
-You can set an input mask to limit the classification to the mask area
-with value >0.
-
-Validating the classification model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The performance of the model generated by the application is directly
-estimated by the application itself, which displays the precision,
-recall and F-score of each class, and can generate the global confusion
-matrix as an output \*.CSV file.
-
-With the application, it is also possible to estimate the performance of
-a model from a classification map generated with the application. This
-labeled image is compared to positive reference samples (either
-represented as a raster labeled image or as a vector data containing the
-reference classes). It will compute the confusion matrix and precision,
-recall and F-score of each class too, based on the
-`ConfusionMatrixCalculator <http://www.orfeo-toolbox.org/doxygen-current/classotb_1_1ConfusionMatrixCalculator.html>`__
-class.
-
-::
-
- otbcli_ComputeConfusionMatrix -in labeled_image.tif
- -ref vector
- -ref.vector.in vectordata.shp
- -ref.vector.field Class (name_of_label_field)
- -out confusion_matrix.csv
-
-Fancy classification results
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Color mapping can be used to apply color transformations on the final
-graylevel label image. It allows to get an RGB classification map by
-re-mapping the image values to be suitable for display purposes. One can
-use the application. This tool will replace each label with an 8-bits
-RGB color specified in a mapping file. The mapping file should look like
-this :
-
-::
-
- # Lines beginning with a # are ignored
- 1 255 0 0
-
-In the previous example, 1 is the label and 255 0 0 is a RGB color (this
-one will be rendered as red). To use the mapping tool, enter the
-following :
-
-::
-
- otbcli_ColorMapping -in labeled_image.tif
- -method custom
- -method.custom.lut lut_mapping_file.txt
- -out RGB_color_image.tif
-
-Other look-up tables (LUT) are available : standard continuous LUT,
-optimal LUT, and LUT computed over a support image.
-
-Example
-~~~~~~~
-
-We consider 4 classes: water, roads, vegetation and buildings with red
-roofs. Data is available in the OTB-Data
-`repository <http://hg.orfeo-toolbox.org/OTB-Data/file/0fed8f4f035c/Input/Classification>`__
-and this image is produced with the commands inside this
-`file <http://hg.orfeo-toolbox.org/OTB-Applications/file/3ce975605013/Testing/Classification/CMakeLists.txt>`__.
-
-|image| |image| |image| [fig:MeanShiftVectorImageFilter]
-
-Fusion of classification maps
------------------------------
-
-After having processed several classifications of the same input image
-but from different models or methods (SVM, KNN, Random Forest,...), it
-is possible to make a fusion of these classification maps with the
-application which uses either majority voting or the Demspter Shafer
-framework to handle this fusion. The Fusion of Classifications generates
-a single more robust and precise classification map which combines the
-information extracted from the input list of labeled images.
-
-The application has the following input parameters :
-
-- ``-il`` list of input labeled classification images to fuse
-
-- ``-out`` the output labeled image resulting from the fusion of the
- input classification images
-
-- ``-method`` the fusion method (either by majority voting or by
- Dempster Shafer)
-
-- ``-nodatalabel`` label for the no data class (default value = 0)
-
-- ``-undecidedlabel`` label for the undecided class (default value = 0)
-
-The input pixels with the nodata class label are simply ignored by the
-fusion process. Moreover, the output pixels for which the fusion process
-does not result in a unique class label, are set to the undecided value.
-
-Majority voting for the fusion of classifications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the Majority Voting method implemented in the application, the value
-of each output pixel is equal to the more frequent class label of the
-same pixel in the input classification maps. However, it may happen that
-the more frequent class labels are not unique in individual pixels. In
-that case, the undecided label is attributed to the output pixels.
-
-The application can be used like this:
-
-::
-
- otbcli_FusionOfClassifications -il cmap1.tif cmap2.tif cmap3.tif
- -method majorityvoting
- -nodatalabel 0
- -undecidedlabel 10
- -out MVFusedClassificationMap.tif
-
-Let us consider 6 independent classification maps of the same input
-image (Cf. left image in Fig. [fig:MeanShiftVectorImageFilter])
-generated from 6 different SVM models. The Fig.
-[fig:ClassificationMapFusionApplication] represents them after a color
-mapping by the same LUT. Thus, 4 classes (water: blue, roads: gray,
-vegetation: green, buildings with red roofs: red) are observable on each
-of them.
-
-|image| |image| |image| |image| |image| |image|
-[fig:ClassificationMapFusionApplication]
-
-As an example of the application by *majority voting*, the fusion of the
-six input classification maps represented in Fig.
-[fig:ClassificationMapFusionApplication] leads to the classification map
-illustrated on the right in Fig.
-[fig:ClassificationMapFusionApplicationMV]. Thus, it appears that this
-fusion highlights the more relevant classes among the six different
-input classifications. The white parts of the fused image correspond to
-the undecided class labels, i.e. to pixels for which there is not a
-unique majority voting.
-
-|image| |image| [fig:ClassificationMapFusionApplicationMV]
-
-Dempster Shafer framework for the fusion of classifications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The application, handles another method to compute the fusion: the
-Dempster Shafer framework. In the `Dempster-Shafer
-theory <http://en.wikipedia.org/wiki/Dempster-Shafer_theory>`__, the
-performance of each classifier resulting in the classification maps to
-fuse are evaluated with the help of the so-called *belief function* of
-each class label, which measures the degree of belief that the
-corresponding label is correctly assigned to a pixel. For each
-classifier, and for each class label, these belief functions are
-estimated from another parameter called the *mass of belief* of each
-class label, which measures the confidence that the user can have in
-each classifier according to the resulting labels.
-
-In the Dempster Shafer framework for the fusion of classification maps,
-the fused class label for each pixel is the one with the maximal belief
-function. In case of multiple class labels maximizing the belief
-functions, the output fused pixels are set to the undecided value.
-
-In order to estimate the confidence level in each classification map,
-each of them should be confronted with a ground truth. For this purpose,
-the masses of belief of the class labels resulting from a classifier are
-estimated from its confusion matrix, which is itself exported as a
-\*.CSV file with the help of the application. Thus, using the Dempster
-Shafer method to fuse classification maps needs an additional input list
-of such \*.CSV files corresponding to their respective confusion
-matrices.
-
-The application can be used like this:
-
-::
-
- otbcli_FusionOfClassifications -il cmap1.tif cmap2.tif cmap3.tif
- -method dempstershafer
- -method.dempstershafer.cmfl
- cmat1.csv cmat2.csv cmat3.csv
- -nodatalabel 0
- -undecidedlabel 10
- -out DSFusedClassificationMap.tif
-
-As an example of the application by *Dempster Shafer*, the fusion of the
-six input classification maps represented in Fig.
-[fig:ClassificationMapFusionApplication] leads to the classification map
-illustrated on the right in Fig.
-[fig:ClassificationMapFusionApplicationDS]. Thus, it appears that this
-fusion gives access to a more precise and robust classification map
-based on the confidence level in each classifier.
-
-|image| |image| [fig:ClassificationMapFusionApplicationDS]
-
-Recommendations to properly use the fusion of classification maps
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In order to properly use the application, some points should be
-considered. First, the ``list_of_input_images`` and
-``OutputFusedClassificationImage`` are single band labeled images, which
-means that the value of each pixel corresponds to the class label it
-belongs to, and labels in each classification map must represent the
-same class. Secondly, the undecided label value must be different from
-existing labels in the input images in order to avoid any ambiguity in
-the interpretation of the ``OutputFusedClassificationImage``.
-
-Majority voting based classification map regularization
--------------------------------------------------------
-
-Resulting classification maps can be regularized in order to smoothen
-irregular classes. Such a regularization process improves classification
-results by making more homogeneous areas which are easier to handle.
-
-Majority voting for the classification map regularization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The application performs a regularization of a labeled input image based
-on the Majority Voting method in a specified ball shaped neighborhood.
-For each center pixel, Majority Voting takes the more representative
-value of all the pixels identified by the structuring element and then
-sets the output center pixel to this majority label value. The ball
-shaped neighborhood is identified by its radius expressed in pixels.
-
-Handling ambiguity and not classified pixels in the majority voting based regularization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Since, the Majority Voting regularization may lead to not unique
-majority labels in the neighborhood, it is important to define which
-behavior the filter must have in this case. For this purpose, a Boolean
-parameter (called ip.suvbool) is used in the application to choose
-whether pixels with more than one majority class are set to Undecided
-(true), or to their Original labels (false = default value).
-
-Moreover, it may happen that pixels in the input image do not belong to
-any of the considered class. Such pixels are assumed to belong to the
-NoData class, the label of which is specified as an input parameter for
-the regularization. Therefore, those NoData input pixels are invariant
-and keep their NoData label in the output regularized image.
-
-The application has the following input parameters :
-
-- ``-io.in`` labeled input image resulting from a previous
- classification process
-
-- ``-io.out`` output labeled image corresponding to the regularization
- of the input image
-
-- ``-ip.radius`` integer corresponding to the radius of the ball shaped
- structuring element (default value = 1 pixel)
-
-- ``-ip.suvbool`` boolean parameter used to choose whether pixels with
- more than one majority class are set to Undecided (true), or to their
- Original labels (false = default value). Please note that the
- Undecided value must be different from existing labels in the input
- image
-
-- ``-ip.nodatalabel`` label for the NoData class. Such input pixels
- keep their NoData label in the output image (default value = 0)
-
-- ``-ip.undecidedlabel`` label for the Undecided class (default value =
- 0).
-
-The application can be used like this:
-
-::
-
- otbcli_ClassificationMapRegularization -io.in labeled_image.tif
- -ip.radius 3
- -ip.suvbool true
- -ip.nodatalabel 10
- -ip.undecidedlabel 7
- -io.out regularized.tif
-
-Recommendations to properly use the majority voting based regularization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In order to properly use the application, some points should be
-considered. First, both ``InputLabeledImage`` and ``OutputLabeledImage``
-are single band labeled images, which means that the value of each pixel
-corresponds to the class label it belongs to. The ``InputLabeledImage``
-is commonly an image generated with a classification algorithm such as
-the SVM classification. Remark: both ``InputLabeledImage`` and
-``OutputLabeledImage`` are not necessarily of the same datatype.
-Secondly, if ip.suvbool == true, the Undecided label value must be
-different from existing labels in the input labeled image in order to
-avoid any ambiguity in the interpretation of the regularized
-``OutputLabeledImage``. Finally, the structuring element radius must
-have a minimum value equal to 1 pixel, which is its default value. Both
-NoData and Undecided labels have a default value equal to 0.
-
-Example
-~~~~~~~
-
-Resulting from the application presented in section
-[ssec:classificationcolormapping], and illustrated in Fig.
-[fig:MeanShiftVectorImageFilter], the Fig.
-[fig:ClassificationMapRegularizationApplication] shows a regularization
-of a classification map composed of 4 classes: water, roads, vegetation
-and buildings with red roofs. The radius of the ball shaped structuring
-element is equal to 3 pixels, which corresponds to a ball included in a
-7 x 7 pixels square. Pixels with more than one majority class keep their
-original labels.
-
-|image| |image| |image| [fig:ClassificationMapRegularizationApplication]
-
-Regression
-----------
-
-The machine learning models in OpenCV and LibSVM also support a
-regression mode : they can be used to predict a numeric value (i.e. not
-a class index) from an input predictor. The workflow is the same as
-classification. First, the regression model is trained, then it can be
-used to predict output values. The applications to do that are and .
-
-Input datasets
-~~~~~~~~~~~~~~
-
-The input data set for training must have the following structure :
-
-- *n* components for the input predictors
-
-- one component for the corresponding output value
-
-The application supports 2 input formats :
-
-- An image list : each image should have components matching the
- structure detailed earlier (*n* feature components + 1 output value)
-
-- A CSV file : the first *n* columns are the feature components and the
- last one is the output value
-
-If you have separate images for predictors and output values, you can
-use the application.
-
-::
-
- otbcli_ConcatenateImages -il features.tif output_value.tif
- -out training_set.tif
-
-Statistics estimation
-~~~~~~~~~~~~~~~~~~~~~
-
-As in classification, a statistics estimation step can be performed
-before training. It allows to normalize the dynamic of the input
-predictors to a standard one : zero mean, unit standard deviation. The
-main difference with the classification case is that with regression,
-the dynamic of output values can also be reduced.
-
-The statistics file format is identical to the output file from
-application, for instance :
-
-::
-
- <?xml version="1.0" ?>
- <FeatureStatistics>
- <Statistic name="mean">
- <StatisticVector value="198.796" />
- <StatisticVector value="283.117" />
- <StatisticVector value="169.878" />
- <StatisticVector value="376.514" />
- </Statistic>
- <Statistic name="stddev">
- <StatisticVector value="22.6234" />
- <StatisticVector value="41.4086" />
- <StatisticVector value="40.6766" />
- <StatisticVector value="110.956" />
- </Statistic>
- </FeatureStatistics>
-
-In the application, normalization of input predictors and output values
-is optional. There are 3 options :
-
-- No statistic file : normalization disabled
-
-- Statistic file with *n* components : normalization enabled for input
- predictors only
-
-- Statistic file with *n+1* components : normalization enabled for
- input predictors and output values
-
-If you use an image list as training set, you can run application. It
-will produce a statistics file suitable for input and output
-normalization (third option).
-
-::
-
- otbcli_ComputeImagesStatistics -il training_set.tif
- -out stats.xml
-
-Training
-~~~~~~~~
-
-Initially, the machine learning models in OTB only used classification.
-But since they come from external libraries (OpenCV and LibSVM), the
-regression mode was already implemented in these external libraries. So
-the integration of these models in OTB has been improved in order to
-allow the usage of regression mode. As a consequence , the machine
-learning models have nearly the same set of parameters for
-classification and regression mode.
-
-The regression mode is currently supported for :
-
-- Support Vector Machine (LibSVM and OpenCV)
-
-- Decision Trees
-
-- Gradient Boosted Trees
-
-- Neural Network
-
-- Random Forests
-
-- K-Nearest Neighbors
-
-The behaviour of application is very similar to . From the input data
-set, a portion of the samples is used for training, whereas the other
-part is used for validation. The user may also set the model to train
-and its parameters. Once the training is done, the model is stored in an
-output file.
-
-::
-
- otbcli_TrainRegression -io.il training_set.tif
- -io.imstat stats.xml
- -io.out model.txt
- -sample.vtr 0.5
- -classifier knn
- -classifier.knn.k 5
- -classifier.knn.rule median
-
-Prediction
-~~~~~~~~~~
-
-Once the model is trained, it can be used in application to perform the
-prediction on an entire image containing input predictors (i.e. an image
-with only *n* feature components). If the model was trained with
-normalization, the same statistic file must be used for prediction. The
-behavior of with respect to statistic file is identical to :
-
-- no statistic file : normalization off
-
-- *n* components : input only
-
-- *n+1* components : input and output
-
-The model to use is read from file (the one produced during training).
-
-::
-
- otbcli_PredictRegression -in features_bis.tif
- -model model.txt
- -imstat stats.xml
- -out prediction.tif
-
-Samples selection
------------------
-
-Since release 5.4, new functionalities related to the handling of the
-vectors from the training data set (see also [sssec:building]) were
-added to OTB.
-
-The first improvement was provided by the application
-PolygonClassStatistics. This application processes a set of training
-geometries, and outputs statistics about the sample distribution in the
-input geometries (in the form of a xml file) :
-
-- number of samples per class
-
-- number of samples per geometry
-
-Supported geometries are polygons, lines and points; depending on the
-geometry type, this application behaves differently :
-
-- polygon : select pixels whose center is inside the polygon
-
-- lines : select pixels intersecting the line
-
-- points : select closest pixel to the provided point
-
-The application also takes as input a support image, but the values of
-its pixels are not used. The purpose is rather to define the image grid
-that will later provide the samples. The user can also provide a raster
-mask, that will be used to discard pixel positions.
-
-A simple use of the application PolygonClassStatistics could be as
-follows :
-
-::
-
- otbcli_PolygonClassStatistics -in support_image.tif
- -vec variousTrainingVectors.sqlite
- -field class
- -out polygonStat.xml
-
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_fusion.jpg
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif.jpg
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C1_CM.png
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C2_CM.png
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C3_CM.png
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C4_CM.png
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C5_CM.png
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C6_CM.png
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_MV_C123456_CM.png
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
-.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_DS_V_P_C123456_CM.png
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_CMR_input.png
-.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_CMR_3.png
diff --git a/Documentation/Cookbook/rst/recipes/improc.rst b/Documentation/Cookbook/rst/recipes/improc.rst
index 9a133b5deaa3da4fcd80edeedd7e88cecf52530b..a2141d15e65ffeb4e8d43ad1deedd36a88932c9d 100644
--- a/Documentation/Cookbook/rst/recipes/improc.rst
+++ b/Documentation/Cookbook/rst/recipes/improc.rst
@@ -18,12 +18,82 @@ two images.
-exp "abs(im1b1 - im2b1)"
-out output_image
-The naming convention “im[x]b[y]†designates the y\ :sup:`th` band of the x\ :sup:`th` input image.
+The naming convention “im[x]b[y]†designates the yth band of the xth
+input image.
The *BandMath* application embeds built-in operators and functions
listed in `muparser documentation <http://muparser.sourceforge.net/mup_features.html#idDef2>`_ thus
allowing a vast choice of possible operations.
+Images with no-data values
+--------------------------
+
+Image files can contain a no-data value in their metadata. It represents
+a special pixel value that should be treated as “no data available for
+this pixelâ€. For instance, SRTM tiles use a particular no-data value of
+-32768 (usually found on sea areas).
+
+On multiband images, the no-data values are handled independently for
+each band. The case of an image with no-data values defined only for a
+subset of its bands is supported.
+
+This metadata is now handled by OTB image readers and writer (using the
+GDAL driver). The no-data value can be read from an image files and
+stored in the image metadata dictionary. It can also be exported by
+image writers. The OTB filters that produce a no-data value are able to
+export this value so that the output file will store it.
+
+An application has been created to manage the no-data value. The
+application has the following features :
+
+- Build a mask corresponding to the no-data pixels in the input image :
+ it gives you a binary image of the no-data pixels in your input
+ image.
+
+- Change the no-data value of the input image : it will change all
+ pixels that carry the old no-data value to the new one and update the
+ metadata
+
+- Apply an external mask to the input image as no-data : all the pixels
+ that corresponds have a null mask value are flagged as no-data in the
+ output image.
+
+For instance, the following command converts the no-data value of the
+input image to the default value for DEM (which is -32768) :
+
+::
+
+ otbcli_ManageNoData -in input_image.tif
+ -out output_image.tif
+ -mode changevalue
+ -mode.changevalue.newv -32768
+
+The third mode “apply†can be useful if you apply a formula to the
+entire image. This will likely change the values of pixels flagged as
+no-data, but the no-data value in the image metadata doesn’t change. If
+you want to fix all no-data pixels to their original value, you can
+extract the mask of the original image and apply it on the output image.
+For instance:
+
+::
+
+ otbcli_ManageNoData -in input_image.tif
+ -out mask.tif
+ -mode buildmask
+
+ otbcli_BandMath -il input_image.tif
+ -out filtered_image.tif
+ -exp "2*im1b1-4"
+
+ otbcli_ManageNoData -in filtered_image.tif
+ -out output_image.tif
+ -mode apply
+ -mode.apply.mask mask.tif
+
+You can also use this “apply†mode with an additional parameter
+“mode.apply.ndvalâ€. This parameter allow to set the output nodata value
+applying according to your input mask.
+
Segmentation
------------
@@ -43,17 +113,25 @@ manipulate efficiently.
The experience of segmenting large remote sensing images is packed into
a single *Segmentation* in **OTB Applications** .
-You can find more information about this application in this `blog <http://blog.orfeo-toolbox.org/preview/coming-next-large-scale-segmentation>`_ .
+You can find more information about this application
+`here <http://blog.orfeo-toolbox.org/preview/coming-next-large-scale-segmentation>`__.
Large-Scale Mean-Shift (LSMS) segmentation
------------------------------------------
LSMS is a segmentation workflow which allows to perform tile-wise
segmentation of very large image with theoretical guarantees of getting
-identical results to those without tiling. It has been developed by
-David Youssefi and Julien Michel during David internship at CNES and is
-to be published soon.
+identical results to those without tiling.
+
+It has been developed by David Youssefi and Julien Michel during David
+
+internship at CNES.
+For more a complete description of the LSMS method, please refer to the
+following publication, *J. Michel, D. Youssefi and M. Grizonnet, “Stable
+Mean-Shift Algorithm and Its Application to the Segmentation of
+Arbitrarily Large Remote Sensing Images,†in IEEE Transactions on
+Geoscience and Remote Sensing, vol. 53, no. 2, pp. 952-964, Feb. 2015.*
The workflow consists in chaining 3 or 4 dedicated applications and
produces a GIS vector file with artifact-free polygons corresponding to
the segmented image, as well as mean and variance of the radiometry of
diff --git a/Documentation/Cookbook/rst/recipes/pbclassif.rst b/Documentation/Cookbook/rst/recipes/pbclassif.rst
index 43a6524c9d867b653878c6b34a3cca74dc7c32fe..33419237bcbb9c65ae6b8e68ba5831c3feddf179 100644
--- a/Documentation/Cookbook/rst/recipes/pbclassif.rst
+++ b/Documentation/Cookbook/rst/recipes/pbclassif.rst
@@ -1,8 +1,6 @@
Classification
==============
-.. _section4:
-
Pixel based classification
--------------------------
@@ -40,25 +38,18 @@ Building the training data set
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As the chain is supervised, we first need to build a training set with
-positive examples of different objects of interest. This can be done
-with Monteverdi Vectorization module (`Figure 1`). These polygons must be saved in
-OGR vector format supported by GDAL like ESRI shapefile for example.
-
-This operation will be reproduced on each image used as input of the
-training function.
+positive examples of different objects of interest. These polygons must
+be saved in OGR vector format supported by GDAL like ESRI shapefile for
+example.
Please note that the positive examples in the vector data should have a
-*Class* field with a label value higher than 1 and coherent in
+\`\`Class\`\` field with a label value higher than 1 and coherent in
each images.
-.. figure:: ../Art/MonteverdiImages/monteverdi_vectorization_module_for_classification.png
-
-Figure 1: A training data set builded with the vectorization monteverdi module.
-
-You can generate the vector data set with `Quantum GIS <http://www.qgis.org/>`_
-software for example and save it in an OGR vector format supported by `GDAL <http://www.gdal.org/>`_
-(ESRI sphapefile for example). **OTB Applications** should be able to
-transform the vector data into the image coordinate system.
+You can generate the vector data set with software for example and save
+it in an OGR vector format supported by (ESRI shapefile for example).
+should be able to transform the vector data into the image coordinate
+system.
Performing the learning scheme
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -421,44 +412,112 @@ NoData and Undecided labels have a default value equal to 0.
Example
~~~~~~~
-Resulting from the *ColorMapping* application presented in section
-:ref:`section4` and illustrated in `Figure 2`.
-The `Figure 6` shows a regularization of a classification map composed
-of 4 classes: water, roads, vegetation and buildings with red roofs.
-The radius of the ball shaped structuring element is equal to 3 pixels,
-which corresponds to a ball included in a 7 x 7 pixels square.
-Pixels with more than one majority class keep their original labels.
+Resulting from the application presented in section
+[ssec:classificationcolormapping], and illustrated in Fig.
+[fig:MeanShiftVectorImageFilter], the Fig.
+[fig:ClassificationMapRegularizationApplication] shows a regularization
+of a classification map composed of 4 classes: water, roads, vegetation
+and buildings with red roofs. The radius of the ball shaped structuring
+element is equal to 3 pixels, which corresponds to a ball included in a
+7 x 7 pixels square. Pixels with more than one majority class keep their
+original labels.
+
+|image| |image| |image| [fig:ClassificationMapRegularizationApplication]
+
+Regression
+----------
+
+The machine learning models in OpenCV and LibSVM also support a
+regression mode : they can be used to predict a numeric value (i.e. not
+a class index) from an input predictor. The workflow is the same as
+classification. First, the regression model is trained, then it can be
+used to predict output values. The applications to do that are and .
|image15| |image16| |image17|
Figure 6: From left to right: Original image, fancy colored classified image and regularized classification map with radius equal to 3 pixels.
-.. |image1| image:: ../Art/MonteverdiImages/monteverdi_vectorization_module_for_classification.png
-.. |image2| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
- :scale: 88%
+The input data set for training must have the following structure :
-.. |image3| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_fusion.jpg
- :scale: 88%
+- *n* components for the input predictors
-.. |image4| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif.jpg
- :scale: 88%
+- one component for the corresponding output value
-.. |image5| image:: ../Art/MonteverdiImages/QB_1_ortho_C1_CM.png
- :scale: 88%
+The application supports 2 input formats :
-.. |image6| image:: ../Art/MonteverdiImages/QB_1_ortho_C2_CM.png
- :scale: 88%
+- An image list : each image should have components matching the
+ structure detailed earlier (*n* feature components + 1 output value)
-.. |image7| image:: ../Art/MonteverdiImages/QB_1_ortho_C3_CM.png
- :scale: 88%
+- A CSV file : the first *n* columns are the feature components and the
+ last one is the output value
-.. |image8| image:: ../Art/MonteverdiImages/QB_1_ortho_C4_CM.png
- :scale: 88%
+If you have separate images for predictors and output values, you can
+use the application.
-.. |image9| image:: ../Art/MonteverdiImages/QB_1_ortho_C5_CM.png
- :scale: 88%
+::
+
+ otbcli_ConcatenateImages -il features.tif output_value.tif
+ -out training_set.tif
-.. |image10| image:: ../Art/MonteverdiImages/QB_1_ortho_C6_CM.png
- :scale: 88%
+Statistics estimation
+~~~~~~~~~~~~~~~~~~~~~
+
+As in classification, a statistics estimation step can be performed
+before training. It allows to normalize the dynamic of the input
+predictors to a standard one : zero mean, unit standard deviation. The
+main difference with the classification case is that with regression,
+the dynamic of output values can also be reduced.
+
+The statistics file format is identical to the output file from
+application, for instance :
+
+::
+
+ <?xml version="1.0" ?>
+ <FeatureStatistics>
+ <Statistic name="mean">
+ <StatisticVector value="198.796" />
+ <StatisticVector value="283.117" />
+ <StatisticVector value="169.878" />
+ <StatisticVector value="376.514" />
+ </Statistic>
+ <Statistic name="stddev">
+ <StatisticVector value="22.6234" />
+ <StatisticVector value="41.4086" />
+ <StatisticVector value="40.6766" />
+ <StatisticVector value="110.956" />
+ </Statistic>
+ </FeatureStatistics>
+
+In the application, normalization of input predictors and output values
+is optional. There are 3 options :
+
+- No statistic file : normalization disabled
+
+- Statistic file with *n* components : normalization enabled for input
+ predictors only
+
+- Statistic file with *n+1* components : normalization enabled for
+ input predictors and output values
+
+If you use an image list as training set, you can run application. It
+will produce a statistics file suitable for input and output
+normalization (third option).
+
+::
+
+ otbcli_ComputeImagesStatistics -il training_set.tif
+ -out stats.xml
+
+Training
+~~~~~~~~
+
+Initially, the machine learning models in OTB only used classification.
+But since they come from external libraries (OpenCV and LibSVM), the
+regression mode was already implemented in these external libraries. So
+the integration of these models in OTB has been improved in order to
+allow the usage of regression mode. As a consequence , the machine
+learning models have nearly the same set of parameters for
+classification and regression mode.
.. |image11| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
.. |image12| image:: ../Art/MonteverdiImages/QB_1_ortho_MV_C123456_CM.png
@@ -468,8 +527,109 @@ Figure 6: From left to right: Original image, fancy colored classified image and
.. |image15| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
:scale: 88%
-.. |image16| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_CMR_input.png
- :scale: 88%
+- Decision Trees
-.. |image17| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_CMR_3.png
- :scale: 88%
+- Gradient Boosted Trees
+
+- Neural Network
+
+- Random Forests
+
+- K-Nearest Neighbors
+
+The behaviour of application is very similar to . From the input data
+set, a portion of the samples is used for training, whereas the other
+part is used for validation. The user may also set the model to train
+and its parameters. Once the training is done, the model is stored in an
+output file.
+
+::
+
+ otbcli_TrainRegression -io.il training_set.tif
+ -io.imstat stats.xml
+ -io.out model.txt
+ -sample.vtr 0.5
+ -classifier knn
+ -classifier.knn.k 5
+ -classifier.knn.rule median
+
+Prediction
+~~~~~~~~~~
+
+Once the model is trained, it can be used in application to perform the
+prediction on an entire image containing input predictors (i.e. an image
+with only *n* feature components). If the model was trained with
+normalization, the same statistic file must be used for prediction. The
+behavior of with respect to statistic file is identical to :
+
+- no statistic file : normalization off
+
+- *n* components : input only
+
+- *n+1* components : input and output
+
+The model to use is read from file (the one produced during training).
+
+::
+
+ otbcli_PredictRegression -in features_bis.tif
+ -model model.txt
+ -imstat stats.xml
+ -out prediction.tif
+
+Samples selection
+-----------------
+
+Since release 5.4, new functionalities related to the handling of the
+vectors from the training data set (see also [sssec:building]) were
+added to OTB.
+
+The first improvement was provided by the application
+PolygonClassStatistics. This application processes a set of training
+geometries, and outputs statistics about the sample distribution in the
+input geometries (in the form of a xml file) :
+
+- number of samples per class
+
+- number of samples per geometry
+
+Supported geometries are polygons, lines and points; depending on the
+geometry type, this application behaves differently :
+
+- polygon : select pixels whose center is inside the polygon
+
+- lines : select pixels intersecting the line
+
+- points : select closest pixel to the provided point
+
+The application also takes as input a support image, but the values of
+its pixels are not used. The purpose is rather to define the image grid
+that will later provide the samples. The user can also provide a raster
+mask, that will be used to discard pixel positions.
+
+A simple use of the application PolygonClassStatistics could be as
+follows :
+
+::
+
+ otbcli_PolygonClassStatistics -in support_image.tif
+ -vec variousTrainingVectors.sqlite
+ -field class
+ -out polygonStat.xml
+
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_fusion.jpg
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif.jpg
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C1_CM.png
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C2_CM.png
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C3_CM.png
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C4_CM.png
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C5_CM.png
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_C6_CM.png
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_MV_C123456_CM.png
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
+.. |image| image:: ../Art/MonteverdiImages/QB_1_ortho_DS_V_P_C123456_CM.png
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_inputimage.jpg
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_CMR_input.png
+.. |image| image:: ../Art/MonteverdiImages/classification_chain_fancyclassif_CMR_3.png
diff --git a/Documentation/Cookbook/rst/recipes/residual_registration.rst b/Documentation/Cookbook/rst/recipes/residual_registration.rst
index 5afb9c48ee5d4cd12715d31103fec660f5814dd3..420e3798940e4c157550b76f0562c7f8caa4e39a 100644
--- a/Documentation/Cookbook/rst/recipes/residual_registration.rst
+++ b/Documentation/Cookbook/rst/recipes/residual_registration.rst
@@ -5,14 +5,14 @@ Image registration is a fundamental problem in image processing. The aim
is to align two or more images of the same scene often taken at
different times, from different viewpoints, or by different sensors. It
is a basic step for orthorectification, image stitching, image fusion,
-change detection etc. But this process is also critical for stereo
+change detection, and others. But this process is also critical for stereo
reconstruction process to be able to obtain an accurate estimation of
epipolar geometry.
Sensor model is generally not sufficient to provide image registrations.
Indeed, several sources of geometric distortion can be contained in
optical remote sensing images including earth rotation, platform
-movement, non linearity etc.
+movement, non linearity, etc.
They result in geometric errors on scene level, image level and pixel
level. It is critical to rectify the errors before a thematic map is
diff --git a/Documentation/Cookbook/rst/sarprocessing.rst b/Documentation/Cookbook/rst/recipes/sarprocessing.rst
similarity index 100%
rename from Documentation/Cookbook/rst/sarprocessing.rst
rename to Documentation/Cookbook/rst/recipes/sarprocessing.rst
diff --git a/Documentation/Cookbook/rst/residual_registration.rst b/Documentation/Cookbook/rst/residual_registration.rst
deleted file mode 100644
index e07652163eaa8d0db6bc8e0c25c0d1d700effc2b..0000000000000000000000000000000000000000
--- a/Documentation/Cookbook/rst/residual_registration.rst
+++ /dev/null
@@ -1,233 +0,0 @@
-Residual registration
----------------------
-
-Image registration is a fundamental problem in image processing. The aim
-is to align two or more images of the same scene often taken at
-different times, from different viewpoints, or by different sensors. It
-is a basic step for orthorectification, image stitching, image fusion,
-change detection…But this process is also critical for stereo
-reconstruction process to be able to obtain an accurate estimation of
-epipolar geometry.
-
-Sensor model is generally not sufficient to provide image registrations.
-Indeed, several sources of geometric distortion can be contained in
-optical remote sensing images including earth rotation, platform
-movement, non linearity…
-
-They result in geometric errors on scene level, image level and pixel
-level. It is critical to rectify the errors before a thematic map is
-generated, especially when the remote sensing data need to be integrated
-together with other GIS data.
-
-This figure illustrates the generic workflow in the case of image series
-registration:
-
-[scale=0.15] (-1,-12) rectangle (75,17); in 5,...,1 (,) rectangle
-+(4,4); (InputSeries) at (4,-1) Input series; (9,5) – +(3,0); (12.2,3)
-rectangle +(6,4); (SensorModel) at (15,5) Sensor Model; (1,-10)
-rectangle +(4,4); (DEM) at (5,-11) DEM; (3,-5.5) – ++(0,3) – ++(12,0) –
-++(0,5); (18.5,5) – +(3,0); in 5,...,1 (,) rectangle +(4,4);
-(GeoRefSeries) at (28,-1) Geo-referenced Series;
-
-(25.5,8.5) – +(0,3);
-
-(22,12) rectangle +(8.5,4); (HomPoExtr) at (27,14) Homologous Points;
-
-(21.5,14) – +(-2.5,0);
-
-(11,12) rectangle +(8,4); (BBAdj) at (15.5,14) Bundle-block Adjustement;
-
-(15,11.5) – +(0,-4);
-
-(30,5) – +(3,0); (33.2,2.5) rectangle +(6,4.5); (FineRegistration) at
-(36,4.9) Fine Registration;
-
-(39.5,5) – +(3,0); in 5,...,1 (,) rectangle +(4,4); (RegistSeries) at
-(47,-1) Registered Series; (36,2) – ++(0,-10) – ++(-30,0);
-
-(52,5) – +(3,0); (55.2,2.5) rectangle +(6,4.5); (CartoProjection) at
-(57.5,4.9) Map Projection;
-
-(61.5,5) – +(3,0); in 5,...,1 (,) rectangle +(4,4); (CartoSeries) at
-(68,-1) Cartographic Series;
-
-We will now illustrate this process by applying this workflow to
-register two images. This process can be easily extended to perform
-image series registration.
-
-The aim of this example is to describe how to register a Level 1
-QuickBird image over an orthorectify Pleiades image over the area of
-Toulouse, France.
-
-|image| |image| [fig:InputImagesRegistration]
-
-Extract metadata from the image reference
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We first dump geometry metadata of the image we want to refine in a text
-file. In OTB, we use the extension *.geom* for this type of file. As you
-will see the application which will estimate a refine geometry only
-needs as input this metadata and a set of homologous points. The
-refinement application will create a new *.geom* file containing refined
-geometry parameters which can be used after for reprojection for
-example.
-
-The use of external *.geom* file is available in OTB since release
-:math:`3.16`. See
-`here <http://wiki.orfeo-toolbox.org/index.php/ExtendedFileName>`__ for
-more information.
-
-::
-
-
- otbcli_ReadImageInfo -in slave_image
- -outkwl TheGeom.geom
-
-Extract homologous points from images
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The main idea of the residual registration is to estimate an second
-transformation (after the application of sensors model).
-
-The homologous point application use interest point detection method to
-get a set of point which match in both images.
-
-The basic idea is to use this set of homologous points and estimate with
-them a residual transformation between the two images.
-
-There is a wide variety of keypoint detector in the literature. They
-allow to detect and describe local features in images. These algorithms
-provide for each interesting point a “feature descriptionâ€. This
-descriptor has the property to be invariant to image translation,
-scaling, and rotation, partially invariant to illumination changes and
-robust to local geometric distortion. keypoints. Features extracted from
-the input images are then matched against each other. These
-correspondences are then used to create the homologous points.
-
-`SIFT <http://en.wikipedia.org/wiki/Scale-invariant_feature_transform>`__
-or `SURF <http://en.wikipedia.org/wiki/SURF>`__ keypoints can be
-computed in the application. The band on which keypoints are computed
-can be set independently for both images.
-
-The application offers two modes :
-
-- the first is the full mode where keypoints are extracted from the
- full extent of both images (please note that in this mode large image
- file are not supported).
-
-- The second mode, called *geobins*, allows to set-up spatial binning
- so as to get fewer points spread across the entire image. In this
- mode, the corresponding spatial bin in the second image is estimated
- using geographical transform or sensor modeling, and is padded
- according to the user defined precision.
-
-Moreover, in both modes the application can filter matches whose
-co-localization in the first image exceed this precision. Last, the
-elevation parameters allow to deal more precisely with sensor modelling
-in case of sensor geometry data. The *outvector* option allows to create
-a vector file with segments corresponding to the localization error
-between the matches.
-
-Finally, with the *2wgs84* option, you can match two sensor geometry
-images or a sensor geometry image with an ortho-rectified reference. In
-all cases, you get a list of ground control points spread all over your
-image.
-
-::
-
-
-
- otbcli_HomologousPointsExtraction -in1 slave_image
- -in2 reference_image
- -algorithm surf
- -mode geobins
- -mode.geobins.binstep 512
- -mode.geobins.binsize 512
- -mfilter 1
- -precision 20
- -2wgs84 1
- -out homologous_points.txt
- -outvector points.shp
- -elev.dem dem_path/SRTM4-HGT/
- -elev.geoid OTB-Data/Input/DEM/egm96.grd
-
-Note that for a proper use of the application, elevation must be
-correctly set (including DEM and geoid file).
-
-Geometry refinement using homologous points
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now that we can use this set of tie points to estimate a residual
-transformation.For this we use the dedicated application called
-**RefineSensorModel**. This application make use of OSSIM capabilities
-to align the sensor model.
-
-It reads the input geometry metadata file (*.geom*) which contains the
-sensor model information that we want to refine and the text file
-(homologous\_points.txt) containing the list of ground control point. It
-performs a least-square fit of the sensor model adjustable parameters to
-these tie points and produces an updated geometry file as output (the
-extension which is always use is *.geom*)
-
-The application can provide as well an optional ground control points
-based statistics file and a vector file containing residues that you can
-display in a GIS software.
-
-Please note again that for a proper use of the application, elevation
-must be correctly set (including DEM and geoid file). The map parameters
-allows to choose a map projection in which the accuracy will be
-estimated (in meters).
-
-Accuracy values are provided as output of the application (computed
-using tie points location) and allow also to control the precision of
-the estimated model.
-
-::
-
-
- otbcli_RefineSensorModel -elev.dem dem_path/SRTM4-HGT/
- -elev.geoid OTB-Data/Input/DEM/egm96.grd
- -ingeom slave_image.geom
- -outgeom refined_slave_image.geom
- -inpoints homologous_points.txt
- -outstat stats.txt
- -outvector refined_slave_image.shp
-
-Orthorecrtify image using the affine geometry
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now we will show how we can use this new sensor model. In our case we’ll
-use this sensor model to orthorectify the image over the Pléiades
-reference. offers since version 3.16 the possibility to use
-hrefhttp://wiki.orfeo-toolbox.org/index.php/ExtendedFileNameextend image
-path to use different metadata file as input. That’s what we are going
-to use there to orthorectify the QuickBird image using the *.geom* file
-obtained by the **RefineSensorModel** applications. over the first one
-using for the second image estimated sensor model which take into
-account the original sensor model of the slave and which also fit to the
-set of tie points.
-
-::
-
-
- otbcli_OrthoRectification -io.in slave_image?&geom=TheRefinedGeom.geom
- -io.out ortho_slave_image
- -elev.dem dem_path/SRTM4-HGT/
- -elev.geoid OTB-Data/Input/DEM/egm96.grd
-
-
-As a result, if you’ve got enough homologous points in images and
-control that the residual error between the set of tie points and the
-estimated sensor model is small, you must achieve a good registration
-now between the 2 rectified images. Normally far better than ’only’
-performing separate orthorectification over the 2 images.
-
-This methodology can be adapt and apply in several cases, for example :
-
-- register stereo pair of images and estimate accurate epipolar
- geometry
-
-- registration prior to change detection
-
-.. |image| image:: ../Art/MonteverdiImages/registration_pleiades_ql.png
-.. |image| image:: ../Art/MonteverdiImages/registration_quickbird_ql.png
diff --git a/Documentation/Cookbook/rst/stereo.rst b/Documentation/Cookbook/rst/stereo.rst
deleted file mode 100644
index 9984b065076a2ae5787dd770f9d50250c9524d1a..0000000000000000000000000000000000000000
--- a/Documentation/Cookbook/rst/stereo.rst
+++ /dev/null
@@ -1,502 +0,0 @@
-Stereoscopic reconstruction from VHR optical images pair
-========================================================
-
-This section describes how to convert pair of stereo images into
-elevation information.
-
-The standard problem of terrain reconstruction with available contains
-the following steps:
-
-- Estimation of displacements grids for epipolar geometry
- transformation
-
-- Epipolar resampling of the image pair using those grids
-
-- Dense disparity map estimation
-
-- Projection of the disparities on a Digital Surface Model (DSM)
-
-Let’s go to the third dimension!
-
-Estimate epipolar geometry transformation
------------------------------------------
-
-The aim of this application is to generate resampled grids to transform
-images in epipolar geometry. Epipolar geometry is the geometry of stereo
-vision (see `here <http://en.wikipedia.org/wiki/Epipolar_geometry>`__).
-The operation of stereo rectification determines transformations to
-apply to each image such that pairs of conjugate epipolar lines become
-collinear, parallel to one of the image axes and aligned. In this
-geometry, the objects present on a given row of the left image are also
-located on the same line in the right image.
-
-Applying this transformation reduces the problem of elevation (or stereo
-correspondences determination) to a 1-D problem. We have two images
-image1 and image2 over the same area (the stereo pair) and we assume
-that we know the localization functions (forward and inverse) associated
-for each of these images.
-
-The forward function allows to go from the image referential to the
-geographic referential:
-
-.. math:: (long,lat) = f^{forward}_{image1}(i,j,h)
-
-where h is the elevation hypothesis, :math:`(i,j)` are the pixel
-coordinates in image1 and (long,lat) are geographic coordinates. As you
-can imagine, the inverse function allows to go from geographic
-coordinates to the image geometry.
-
-For the second image, in that case, the expression of the inverse
-function is:
-
-.. math:: (long,lat,h) = f^{inverse}_{image2}(i,j)
-
-Using jointly the forward and inverse functions from the image pair, we
-can construct a co-localization function
-:math:`f_{image1 \rightarrow image2}` between the position of a pixel in
-the first and its position in the second one:
-
-.. math:: (i_{image2},j_{image2}) = f_{image1 \rightarrow image2} (i_{image1} , j_{image1} , h)
-
-The expression of this function is:
-
-.. math:: f_{image1 \rightarrow image2} (i_{image1} , j_{image1} , h) = f^{inverse}_{image2} f^{forward}_{image1}((i_{image1} , j_{image1}), h)
-
-The expression is not really important, what we need to understand is
-that if we are able to determine for a given pixel in image1 the
-corresponding pixel in image2, as we know the expression of the
-co-localization function between both images, we can determine by
-identification the information about the elevation (variable h in the
-equation)!
-
-We now have the mathematical basis to understand how 3-D information can
-be extracted by examination of the relative positions of objects in the
-two 2-D epipolar images.
-
-The construction of the two epipolar grids is a little bit more
-complicated in the case of VHR optical images.That is because most of
-passive remote sensing from space use a push-broom sensor, which
-corresponds to a line of sensors arranged perpendicularly to the flight
-direction of the spacecraft. This acquisition configuration implies a
-slightly different strategy for stereo-rectification (see
-`here <http://en.wikipedia.org/wiki/Epipolar_geometry#Epipolar_geometry_of_pushbroom_sensor>`__).
-
-We will now explain how to use the application to produce two images
-which are **deformation grids** to resample the two images in epipolar
-geometry.
-
-::
-
- otbcli_StereoRectificationGridGenerator -io.inleft image1.tif
- -io.inright image2.tif
- -epi.elevation.avg.value 50
- -epi.step 5
- -io.outimage1 outimage1_grid.tif
- -io.outright outimage1_grid.tif
-
-The application estimates the displacement to apply to each pixel in
-both input images to obtain epipolar geometry.The application accept a
-‘step’ parameter to estimate displacements on a coarser grid. Here we
-estimate the displacements every 10 pixels. This is because in most
-cases with a pair of VHR and a small angle between the two images, this
-grid is very smooth. Moreover, the implementation is not *streamable*
-and uses potentially a lot of memory. Therefore it is generally a good
-idea to estimate the displacement grid at a coarser resolution.
-
-The application outputs the size of the output images in epipolar
-geometry. **Note these values**, we will use them in the next step to
-resample the two images in epipolar geometry.
-
-In our case, we have:
-
-::
-
- Output parameters value:
- epi.rectsizex: 4462
- epi.rectsizey: 2951
- epi.baseline: 0.2094
-
-The epi.baseline parameter provides the mean value (in
-:math:`pixels.meters^{-1}`) of the baseline to sensor altitude ratio. It
-can be used to convert disparities to physical elevation, since a
-disparity of this value will correspond to an elevation offset of one
-meter with respect to the mean elevation.
-
-we can now move forward to the resampling in epipolar geometry.
-
-Resample images in epipolar geometry
-------------------------------------
-
-The former application generates two grids of displacements. The allows
-to resample the two input images in the epipolar geometry using these
-grids. These grids are intermediary results not really useful on their
-own in most cases. This second step *only* consists in applying the
-transformation and resample both images. This application can obviously
-be used in lot of other contexts.
-
-The two commands to generate epipolar images are:
-
-::
-
- otbcli_GridBasedImageResampling -io.in image1.tif
- -io.out image1_epipolar.tif
- -grid.in outimage1_grid.tif
- -out.sizex 4462
- -out.sizey 2951
-
-::
-
- otbcli_GridBasedImageResampling -io.in image2.tif
- -io.out image2_epipolar.tif
- -grid.in outimage2_grid.tif
- -out.sizex 4462
- -out.sizey 2951
-
-As you can see, we set *sizex* and *sizey* parameters using output
-values given by the application to set the size of the output epipolar
-images.
-
-|image| |image| [fig:EpipolarImages]
-
-We obtain two images in epipolar geometry, as shown in
-figure [fig:EpipolarImages]. Note that the application allows to
-resample only a part of the image using the *-out.ulx* and *-out.uly*
-parameters.
-
-Disparity estimation: Block matching along epipolar lines
----------------------------------------------------------
-
-Finally, we can begin the stereo correspondences lookup process!
-
-Things are becoming a little bit more complex but do not worry. First,
-we will describe the power of the application.
-
-The resampling of our images in epipolar geometry allows us to constrain
-the search along a 1-dimensional line as opposed to both dimensions, but
-what is even more important is that the disparities along the lines,
-i.e. the offset along the lines measured by the block-matching process
-can be directly linked to the local elevation
-
-An almost complete spectrum of stereo correspondence algorithms has been
-published and it is still augmented at a significant rate! See for
-example `. <http://en.wikipedia.org/wiki/Block-matching_algorithm>`__
-The implements different strategies for block matching:
-
-- Sum of Square Distances block-matching (SSD)
-
-- Normalized Cross-Correlation (NCC)
-
-- Lp pseudo-norm (LP)
-
-An other important parameter (mandatory in the application!) is the
-range of disparities. In theory, the block matching can perform a blind
-exploration and search for a infinite range of disparities between the
-stereo pair. We need now to evaluate a range of disparities where the
-block matching will be performed (in the general case from the deepest
-point on Earth, `the Challenger
-Deep <http://en.wikipedia.org/wiki/Challenger_Deep>`__. to the Everest
-summit!)
-
-We deliberately exaggerated but you can imagine that without a smaller
-range the block matching algorithm can take a lot of time. That is why
-these parameters are mandatory for the application and as a consequence
-we need to estimate them manually. This is pretty simple using the two
-epipolar images.
-
-In our case, we take one point on a *flat* area. The image coordinate in
-:math:`image_{1}` is :math:`[1970,1525]` and in :math:`image_{2}` is
-:math:`[1970,1526]`. We then select a second point on a higher region
-(in our case a point near the top of the Pyramid of Cheops!). The image
-coordinate of this pixel in :math:`image_{1}` is :math:`[1661,1299]` and
-in :math:`image_{2}` is :math:`[1633,1300]`. So you see for the
-horizontal exploration, we must set the minimum value lower than
-:math:`-30` (the convention for the sign of the disparity range is from
-image1 to image2).
-
-Note that this estimation can be simplified using an external DEM in the
-application. Regarding the vertical disparity, in the first step we said
-that we reduced the problem of 3-D extraction to a 1-D problem, but this
-is not completely true in general cases. There might be small
-disparities in the vertical direction which are due to parallax errors
-(i.e. epipolar lines exhibit a small shift in the vertical direction,
-around 1 pixel). In fact, the exploration is typically smaller along the
-vertical direction of disparities than along the horizontal one. You can
-also estimate them on the epipolar pair (in our case we use a range of
-:math:`-1` to :math:`1`).
-
-One more time, take care of the sign of this minimum and this maximum
-for disparities (always from image1 to image2).
-
-The command line for the application is :
-
-::
-
- otbcli_BlockMatching -io.inleft image1_epipolar.tif
- -io.inright image2_epipolar.tif
- -io.out disparity_map_ncc.tif
- -bm.minhd -45
- -bm.maxhd 5
- -bm.minvd 1
- -bm.maxvd 1
- -mask.inleft image1_epipolar_mask.tif
- -mask.inright image2_epipolar_mask.tif
- -io.outmetric 1
- -bm.metric ncc
- -bm.subpixel dichotomy
- -bm.medianfilter.radius 5
- -bm.medianfilter.incoherence 2.0
-
-The application creates by default a two bands image : the horizontal
-and vertical disparities.
-
-The application gives access to a lot of other powerful functionalities
-to improve the quality of the output disparity map.
-
-Here are a few of these functionalities:
-
-- -io.outmetric: if the optimal metric values image is activated, it
- will be concatenated to the output image (which will then have three
- bands: horizontal disparity, vertical disparity and metric value)
-
-- -bm.subpixel: Perform sub-pixel estimation of disparities
-
-- -mask.inleft and -mask.inright: you can specify a no-data value which
- will discard pixels with this value (for example the epipolar
- geometry can generate large part of images with black pixels) This
- mask can be easily generated using the application:
-
- ::
-
- otbcli_BandMath -il image1_epipolar.tif
- -out image1_epipolar_mask.tif
- -exp "if(im1b1<=0,0,255)"
-
- ::
-
- otbcli_BandMath -il image2_epipolar.tif
- -out image2_epipolar_mask.tif
- -exp "if(im1b1<=0,0,255)"
-
-- -mask.variancet : The block matching algorithm has difficulties to
- find matches on uniform areas. We can use the variance threshold to
- discard those regions and speed-up computation time.
-
-- -bm.medianfilter.radius 5 and -bm.medianfilter.incoherence 2.0:
- Applies a median filter to the disparity map. The median filter
- belongs to the family of nonlinear filters. It is used to smooth an
- image without being biased by outliers or shot noise. The radius
- corresponds to the neighbourhood where the median value is computed.
- A detection of incoherence between the input disparity map and the
- median-filtered one is performed (a pixel corresponds to an
- incoherence if the absolute value of the difference between the pixel
- value in the disparity map and in the median image is higher than the
- incoherence threshold, whose default value is 1). Both parameters
- must be defined in the application to activate the filter.
-
-Of course all these parameters can be combined to improve the disparity
-map.
-
-|image| |image| [fig:DisparityMetric]
-
-From disparity to Digital Surface Model
----------------------------------------
-
-Using the previous application, we evaluated disparities between images.
-The next (and last!) step is now to transform the disparity map into an
-elevation information to produce an elevation map. It uses as input the
-disparity maps (horizontal and vertical) to produce a Digital Surface
-Model (DSM) with a regular sampling. The elevation values is computed
-from the triangulation of the “left-right†pairs of matched pixels. When
-several elevations are available on a DSM cell, the highest one is kept.
-
-First, an important point is that it is often a good idea to rework the
-disparity map given by the application to only keep relevant
-disparities. For this purpose, we can use the output optimal metric
-image and filter disparities with respect to this value.
-
-For example, if we used Normalized Cross-Correlation (NCC), we can keep
-only disparities where optimal metric value is superior to :math:`0.9`.
-Disparities below this value can be consider as inaccurate and will not
-be used to compute elevation information (the *-io.mask* parameter can
-be used for this purpose).
-
-This filtering can be easily done with .
-
-We first use the application to filter disparities according to their
-optimal metric value:
-
-::
-
- otbcli_BandMath -il disparity_map_ncc.tif
- -out thres_hdisparity.tif uint8
- -exp "if(im1b3>0.9,255,0)"
-
-Then, we concatenate thresholded disparities using the :
-
-::
-
- otbcli_ConcatenateImages -il thres_hdisparity.tif thres_vdisparity.tif
- -out thres_hvdisparity.tif
-
-Now, we can use the application to compute the elevation map from the
-filtered disparity maps.
-
-::
-
- otbcli_DisparityMapToElevationMap -io.in disparity_map_ncc.tif
- -io.left image1.tif
- -io.right image2.tif
- -io.lgrid outimage1_pyramid.tif
- -io.rgrid outimage2_pyramid.tif
- -io.mask thres_hdisparity.tif
- -io.out disparity_map_ssd_to_elevation.tif
- -hmin 10
- -hmax 400
- -elev.default 50
-
-It produces the elevation map projected in WGS84 (EPSG
-code:\ :math:`4326`) over the ground area covered by the stereo pair.
-Pixels values are expressed in meters.
-
-|image| [fig:stereo:sub:`o`\ ut]
-
-This is it ! Figure [fig:stereo\ :sub:`o`\ ut] shows the output DEM from
-the Cheops pair.
-
-One application to rule them all in multi stereo framework scheme
------------------------------------------------------------------
-
-An application has been added to fuse one or multiple stereo
-reconstruction(s) using all in one approach : . It computes the DSM from
-one or several stereo pair. First of all the user have to choose his
-input data and defines stereo couples using *-input.co* string
-parameter. This parameter use the following formatting convention “
-:math:`index_{0}` :math:`index_{1}`, :math:`index_{2}`
-:math:`index_{3}`, …â€, which will create a first couple with image
-:math:`index_{0}` and :math:`index_{1}`, a second with image
-:math:`index_{1}` and :math:`index_{2}`, and so on. If left blank images
-are processed by pairs (which is equivalent as using “ 0 1,2 3,4 5 †…).
-In addition to the usual elevation and projection parameters, main
-parameters have been splitted in groups detailled below:
-
-Output :
- output parameters : DSM resolution, NoData value, Cell Fusion
- method,
-
- - : output projection map selection.
-
- - : Spatial Sampling Distance of the output DSM in meters
-
- - : DSM empty cells are filled with this float value (-32768 by
- default)
-
- - : Choice of fusion strategy in each DSM cell (max, min, mean,
- acc)
-
- - : Output DSM
-
- - : Output DSM extent choice
-
-Stereorect :
- Direct and inverse stereorectification grid subsampling parameters
-
- - : Step of the direct deformation grid (in pixels)
-
- - : Sub-sampling of the inverse epipolar grid
-
-BM :
- Block Matching parameters.
-
- - : Block-matching metric choice (robust SSD, SSD, NCC, Lp Norm)
-
- - : Radius of blocks for matching filter (in pixels, :math:`2` by
- default)
-
- - : Minimum altitude below the selected elevation source (in
- meters, -20.0 by default)
-
- - : Maximum altitude above the selected elevation source (in
- meters, 20.0 by default)
-
-Postproc :
- Post-Processing parameters
-
- - : use bijection consistency. Right to Left correlation is
- computed to validate Left to Right disparities. If bijection is
- not found pixel is rejected
-
- - : use median disparities filtering (disabled by default)
-
- - : use block matching metric output to discard pixels with low
- correlation value (disabled by default, float value)");
-
-Mask :
- Compute optional intermediate masks.
-
- - : Mask for left input image (must have the same size for all
- couples)
-
- - : Mask for right input image (must have the same size for all
- couples)
-
- - : This parameter allows to discard pixels whose local variance is
- too small. The size of the neighborhood is given by the radius
- parameter. (disabledd by default)
-
-Stereo reconstruction good practices
-------------------------------------
-
-The parameters and are used inside the application to derive the minimum
-and maximum horizontal disparity exploration, so they have a critical
-impact on computation time. It is advised to choose an elevation source
-that is not too far from the DSM you want to produce (for instance, an
-SRTM elevation model). Therefore, the altitude from your elevation
-source will be already taken into account in the epipolar geometry and
-the disparities will reveal the elevation offsets (such as buildings).
-It allows you to use a smaller exploration range along the elevation
-axis, causing a smaller exploration along horizontal disparities and
-faster computation.
-
-and have also a deep impact in time consumption, thus they have to be
-carefully chosen in case of large image processing.
-
-To reduce time consumption it would be useful to crop all sensor images
-to the same extent. The easiest way to do that is to choose an image as
-reference, and then apply application on the other sensor images using
-the fit mode option.
-
-Algorithm outline
------------------
-
-The following algorithms are used in the application: For each sensor
-pair
-
-- Compute the epipolar deformation grids from the stereo pair (direct
- and inverse)
-
-- Resample into epipolar geometry with BCO interpolator
-
-- Create masks for each epipolar image : remove black borders and
- resample input masks
-
-- Compute horizontal disparities with a block matching algorithm
-
-- Refing Disparities to sub-pixel precision with a dichotomy algorithm
-
-- Apply an optional Median filter
-
-- Filter disparities based on the correlation score (optional) and
- exploration bounds
-
-- Translate disparities in sensor geometry
-
-- Convert disparity map to 3D map
-
-Then fuse all 3D maps to produce DSM with desired geographic or
-cartographic projection and parametrizable extent.
-
-.. |image| image:: ../Art/MonteverdiImages/stereo_image1_epipolar.png
-.. |image| image:: ../Art/MonteverdiImages/stereo_image2_epipolar.png
-.. |image| image:: ../Art/MonteverdiImages/stereo_disparity_horizontal.png
-.. |image| image:: ../Art/MonteverdiImages/stereo_disparity_metric.png
-.. |image| image:: ../Art/MonteverdiImages/stereo_dem_zoom.png