CliInterface.rst 11.3 KB
Newer Older
1
2
Command-line interface
======================
3

4
OTB ships with more than 100 ready to use applications for remote sensing tasks.
5
They usually expose existing processing functions from the underlying C++
6
7
library, or integrate them into high level pipelines. OTB applications allow the user 
to:
8

9
-  Combine two or more functions from the Orfeo ToolBox,
10

11
12
-  Provide a high level interface to handle: input and output data, 
   definition of parameters and communication with the user.
13
14

OTB applications can be launched in different ways, and accessed from different
15
entry points. While the framework can be extended, the Orfeo ToolBox ships with the following:
16

17
-  A command-line launcher, to call applications from the terminal,
18
19
20
21
22

-  A graphical launcher, with an auto-generated QT interface, providing
   ergonomic parameters setting, display of documentation, and progress
   reporting,

23
-  A SWIG interface, which means that any application can be loaded,
Julien Michel's avatar
Julien Michel committed
24
   set-up and executed into a high-level language such as Python
25
26
   for instance.

Julien Osman's avatar
Julien Osman committed
27
28
29
-  A :doc:`QGISInterface` based on the providers is built on top of the
   SWIG/Python interface and is available with seamless integration
   within `QGIS <http://www.qgis.org/>`_.
30

31
The complete list of applications is described in the Chapter :ref:`apprefdoc`.
32

33
34
35
All standard applications share the same implementation and automatically expose
generated interfaces.
However they are accessed in a slightly different way: the command-line interface is prefixed by ``otbcli_``, while the Qt interface is prefixed by
Cédric Traizet's avatar
Cédric Traizet committed
36
``otbgui_``. For instance, calling ``otbcli_DynamicConvert`` will launch the
37
38
command-line interface of the DynamicConvert application, while
``otbgui_DynamicConvert`` will launch the GUI.
39

40
41
Command-line launcher
---------------------
42

43
The command-line application launcher loads an application
44
plugin, allows for its parameters to be set, and can then be executed from the command line.
45
Launching the ``otbApplicationLauncherCommandLine`` without any arguments provided,
46
47
48
49
results in the following help to be displayed:

::

50
    $ otbApplicationLauncherCommandLine
51
    Usage: ./otbApplicationLauncherCommandLine module_name [MODULEPATH] [arguments]
52
53

The ``module_name`` parameter corresponds to the application name. The
54
``[MODULEPATH]`` argument is optional and allows the path to the shared library 
55
(or plugin) corresponding to the ``module_name`` to be passed to the launcher.
56
57

It is also possible to set this path with the environment variable
58
``OTB_APPLICATION_PATH``, making the ``[MODULEPATH]`` optional. This
59
variable is checked by default when no ``[MODULEPATH]`` argument is
60
given. When using multiple paths in ``OTB_APPLICATION_PATH``, one must
61
ensure that the standard path separator of the target system is used, which
62
is ``:`` on Unix and ``;`` on Windows.
63
64

An error in the application name (i.e. in parameter ``module_name``)
65
will make the ``otbApplicationLauncherCommandLine`` list the name of
66
all applications found in the available path (either ``[MODULEPATH]``
67
and/or ``OTB_APPLICATION_PATH``).
68

69
70
71
To ease the use of the applications, and to avoid extensive
environment customizations; ready-to-use scripts are provided by the OTB
installation to launch each application. They take care of adding the
72
standard application installation path to the ``OTB_APPLICATION_PATH``
73
74
75
environment variable.

These scripts are named ``otbcli_<ApplicationName>`` and do not need any
76
path settings. For example, you can start the Orthorectification
77
78
application with the script called ``otbcli_Orthorectification``.

79
80
81
Launching an application without parameters, or with incomplete parameters, will cause the
launcher to display a summary of the parameters. This summary will display the minimum set
of parameters that are required to execute the application. Here is an
82
example based on the OrthoRectification application:
83
84
85
86

::

    $ otbcli_OrthoRectification
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
    ERROR: Waiting for at least one parameter.


    This is the Ortho-rectification (OrthoRectification) application, version 6.7.0

    This application allows ortho-rectifying optical and radar images from supported sensors.
    Complete documentation: https://www.orfeo-toolbox.org/CookBook/Applications/app_OrthoRectification.html or -help

    Parameters:
            -io                      <group>          Input and output data
    MISSING -io.in                   <string>         Input Image  (mandatory)
    MISSING -io.out                  <string> [pixel] Output Image  [pixel=uint8/uint16/int16/uint32/int32/float/double/cint16/cint32/cfloat/cdouble] (default value is float) (mandatory)
            -map                     <string>         Map Projection [utm/lambert2/lambert93/wgs/epsg] (mandatory, default value is utm)
            -map.utm.zone            <int32>          Zone number  (mandatory, default value is 31)
            -map.utm.northhem        <boolean>        Northern Hemisphere  (mandatory, default value is false)
            -map.epsg.code           <int32>          EPSG Code  (mandatory, default value is 4326)
            -outputs                 <group>          Output Image Grid
            -outputs.mode            <string>         Parameters estimation modes [auto/autosize/autospacing/outputroi/orthofit] (mandatory, default value is auto)
    MISSING -outputs.ulx             <float>          Upper Left X  (mandatory)
    MISSING -outputs.uly             <float>          Upper Left Y  (mandatory)
    MISSING -outputs.sizex           <int32>          Size X  (mandatory)
    MISSING -outputs.sizey           <int32>          Size Y  (mandatory)
    MISSING -outputs.spacingx        <float>          Pixel Size X  (mandatory)
    MISSING -outputs.spacingy        <float>          Pixel Size Y  (mandatory)
            -outputs.lrx             <float>          Lower right X  (optional, off by default)
            -outputs.lry             <float>          Lower right Y  (optional, off by default)
            -outputs.ortho           <string>         Model ortho-image  (optional, off by default)
            -outputs.isotropic       <boolean>        Force isotropic spacing by default  (mandatory, default value is true)
            -outputs.default         <float>          Default pixel value  (optional, off by default, default value is 0)
            -elev                    <group>          Elevation management
            -elev.dem                <string>         DEM directory  (optional, off by default)
            -elev.geoid              <string>         Geoid File  (optional, off by default)
            -elev.default            <float>          Default elevation  (mandatory, default value is 0)
            -interpolator            <string>         Interpolation [bco/nn/linear] (mandatory, default value is bco)
            -interpolator.bco.radius <int32>          Radius for bicubic interpolation  (mandatory, default value is 2)
            -opt                     <group>          Speed optimization parameters
            -opt.rpc                 <int32>          RPC modeling (points per axis)  (optional, off by default, default value is 10)
            -opt.ram                 <int32>          Available RAM (MB)  (optional, off by default, default value is 128)
            -opt.gridspacing         <float>          Resampling grid spacing  (optional, off by default, default value is 4)
            -progress                <boolean>        Report progress
            -help                    <string list>    Display long help (empty list), or help for given parameters keys

    Use -help param1 [... paramN] to see detailed documentation of those parameters.

    Examples:
132
133
    otbcli_OrthoRectification -io.in QB_TOULOUSE_MUL_Extract_500_500.tif -io.out QB_Toulouse_ortho.tif

134

135
136
137

For a detailed description of the application behaviour and parameters,
please check the application reference documentation presented
138
139
in chapter :ref:`apprefdoc`  or follow the ``DOCUMENTATION``
hyperlink provided in the output of ``otbApplicationLauncherCommandLine``.
140
141
Parameters are passed to the application using the parameter key (which
might include one or several ``.`` character), prefixed by a ``-``.
142
Command-line examples are provided in the chapter :ref:`apprefdoc`.
143

144
145
Load and save parameters to XML
-------------------------------
146

147
148
149
150
OTB application parameters can be saved and loaded to
an XML file using the special ``-inxml`` and ``-outxml`` parameters.
Those parameters are available in all applications.
For example:
151
152
153
154
155
156
157
158
159

::

    otbcli_BandMath -il input_image_1 input_image_2
                    -exp "abs(im1b1 - im2b1)"
                    -out output_image
                    -outxml saved_applications_parameters.xml

Then, you can run the applications with the same parameters using the
160
output XML file previously saved. For this, you have to use the inxml
161
162
163
164
165
166
parameter:

::

    otbcli_BandMath -inxml saved_applications_parameters.xml

167
Note that you can also add additional parameters to the command line at the same
168
169
170
171
time

::

172
    otbcli_BandMath -inxml saved_applications_parameters.xml
173
174
                    -exp "(im1b1 - im2b1)"

175
In this case it will use as mathematical expression “(im1b1 - im2b1)”
176
177
instead of “abs(im1b1 - im2b1)”.

178
Parallel execution with MPI
179
---------------------------
180
181
182
183
184
185
186
187

Provided that Orfeo ToolBox has been built with MPI and SPTW modules
activated, it is possible to use MPI for massive parallel computation
and writing of an output image. A simple call to ``mpirun`` before the
command-line activates this behaviour, with the following logic. MPI
writing is only triggered if:

- OTB is built with MPI and SPTW,
188

189
- The number of MPI processes is greater than 1,
190

191
192
- The output filename is ``.tif`` or ``.vrt``

193

194
In this case, the output image will be divided into several tiles
195
196
according to the number of MPI processes specified to the ``mpirun``
command, and all tiles will be computed in parallel.
197

198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
If the output filename extension is ``.tif``, tiles will be written in
parallel to a single Tiff file using SPTW (Simple Parallel Tiff Writer).

If the output filename extension is ``.vrt``, each tile will be
written to a separate Tiff file, and a global VRT_ file will be written.

.. _VRT: http://gdal.org/gdal_vrttut.html

Here is an example of MPI call on a cluster::

  $ mpirun -np $nb_procs --hostfile $PBS_NODEFILE  \
    otbcli_BundleToPerfectSensor \
    -inp $ROOT/IMG_PHR1A_P_001/IMG_PHR1A_P_201605260427149_ORT_1792732101-001_R1C1.JP2 \
    -inxs $ROOT/IMG_PHR1A_MS_002/IMG_PHR1A_MS_201605260427149_ORT_1792732101-002_R1C1.JP2 \
    -out $ROOT/pxs.tif uint16 -ram 1024
213

214
215
216
217
218
219
220
221
222
223
224
225
226
227
    ------------ JOB INFO 1043196.tu-adm01 -------------

    JOBID           : 1043196.tu-adm01
    USER            : michelj
    GROUP           : ctsiap
    JOB NAME        : OTB_mpi
    SESSION         : 631249
    RES REQSTED     : mem=1575000mb,ncpus=560,place=free,walltime=04:00:00
    RES USED        : cpupercent=1553,cput=00:56:12,mem=4784872kb,ncpus=560,vmem=18558416kb,
    walltime=00:04:35
    BILLING         : 42:46:40 (ncpus x walltime)
    QUEUE           : t72h
    ACCOUNT         : null
    JOB EXIT CODE   : 0
228

229
230
231
  ------------ END JOB INFO 1043196.tu-adm01 ---------

One can see that the registration and pan-sharpening of the
232
panchromatic and multi-spectral bands of a Pleiades image has been split
233
between 560 CPUs and only took 56 seconds to complete.
234
235
236
237

Note that this MPI parallel invocation of applications is only
available for command-line calls to OTB applications, and only for
images output parameters.