Commit 191e8808 authored by Victor Poughon's avatar Victor Poughon
Browse files

DOC: Update rst CookBook from upstream Latex

This was done by regenerating all .rst files from the current version
(master branch) of the cookbook files in otb-documents.
Copying the files in this worktree and carefully going over the changes
to keep useful formatting manual work that was done in the previous attempt at
conversion to rst.
parent 60ab7797
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
......
[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
A brief tour of
================
A brief tour of Monteverdi
==========================
Introduction
------------
......
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
......
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**
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]
This diff is collapsed.
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
<