Commit 59c693f0 authored by Victor Poughon's avatar Victor Poughon

DOC: reorder cookbook and update style

parent 99d20ace
......@@ -404,7 +404,7 @@ def GenerateRstForApplications(rst_dir):
appNames = [app for app in allApps if app not in blackList]
appIndexFile = open(rst_dir + '/Applications.rst', 'w')
appIndexFile.write(RstPageHeading("Applications", "2", ref="apprefdoc"))
appIndexFile.write(RstPageHeading("All Applications", "2", ref="apprefdoc"))
print("Generating rst for {} applications".format(len(appNames)))
......
.wy-nav-content {
max-width: 800px;
/* Style of the toctree captions
* inspired from sphinx-rtd-theme docs
*/
.wy-menu-vertical header, .wy-menu-vertical p.caption {
color: #2980b9; /* sphinx blue */
line-height: 32px;
font-weight: bold;
text-transform: uppercase;
white-space: nowrap;
margin-top: .8em;
}
/* Reduce the effect of the p bottom margin before lists
* Very useful for choice parameters in app doc for example
*/
p + ul {
.wy-nav-content .document p + ul {
margin-top: -18px;
}
/* Custom colors for the logo background */
.wy-side-nav-search, .wy-nav-top {
background: #1e1f22; /* otb black */
}
.wy-side-nav-search input[type="text"] {
border-color: #1e1f22; /* otb black */
}
A brief tour of OTB Applications
================================
Command-line interface
======================
OTB ships with more than 100 ready to use applications for remote sensing tasks.
They usually expose existing processing functions from the underlying C++
......@@ -142,99 +142,6 @@ Parameters are passed to the application using the parameter key (which
might include one or several ``.`` character), prefixed by a ``-``.
Command-line examples are provided in the chapter :ref:`apprefdoc`.
Graphical launcher
------------------
The graphical interface for the applications provides a useful
interactive user interface to set the parameters, choose files, and
monitor the execution progress.
This launcher needs the same two arguments as the command line launcher:
::
$ otbApplicationLauncherQt module_name [MODULEPATH]
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 graphical user interface, one will start the
``otbgui_Rescale`` script.
The resulting graphical application displays a window with several tabs:
- Parameters is where you set the parameters and execute the
application.
- Logs is where you see the output 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.
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 is shown here as an example:
.. figure:: Art/QtImages/rescale_param.png
:align: center
Python interface
----------------
The applications can also be accessed from Python, through a module
named ``otbApplication``. However, there are technical requirements to use it.
If you use OTB through standalone packages, you should use the supplied
environment script ``otbenv`` to properly setup variables such as
``PYTHONPATH`` and ``OTB_APPLICATION_PATH`` (on Unix systems, don't forget to
source the script). In other cases, you should set these variables depending on
your configuration.
On Unix systems, it is typically available in the ``/usr/lib/otb/python``
directory. Depending on how you installed OTB, you may need to configure the
environment variable ``PYTHONPATH`` to include this directory so that the module
becomes available from Python.
On Windows, you can install the ``otb-python`` package, and the module
will be automatically available from an OSGeo4W shell.
As for the command line and GUI launchers, the path to the application
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 ``OTB_APPLICATION_PATH`` doesn't need to be modified
``OTB_APPLICATION_PATH``.
Once your environment is set, you can use OTB applications from Python, just
like this small example:
.. code-block:: python
# Example on the use of the Smoothing application
# The python module providing access to OTB applications is otbApplication
import otbApplication as otb
# Let's create the application with codename "Smoothing"
app = otb.Registry.CreateApplication("Smoothing")
# We set its parameters
app.SetParameterString("in", "my_input_image.tif")
app.SetParameterString("type", "mean")
app.SetParameterString("out", "my_output_image.tif")
# This will execute the application and save the output file
app.ExecuteAndWriteOutput()
For more information about this Python interface, check the recipe section.
Load and save parameters to XML
-------------------------------
......
.. _compilingfromsource:
Compiling OTB from source
=========================
......
Environment variables
=====================
The following environment variables are parsed by Orfeo ToolBox. Note
that they only affect default values, and that settings in extended
filenames, applications, Monteverdi or custom C++ code might override
those values.
* ``OTB_DEM_DIRECTORY``: Default directory were DEM tiles are
stored. It should only contain ```.hgt`` or or georeferenced
``.tif`` files. Empty if not set (no directory set)
* ``OTB_GEOID_FILE``: Default path to the geoid file that will be used
to retrieve height of DEM above ellipsoid. Empty if not set (no
geoid set)
* ``OTB_MAX_RAM_HINT``: Default maximum memory that OTB should use for
processing, in MB. If not set, default value is 128 MB.
* ``OTB_LOGGER_LEVEL``: Default level of logging for OTB. Should be
one of ``DEBUG``, ``INFO``, ``WARNING``, ``CRITICAL`` or ``FATAL``,
by increasing order of priority. Only messages with a higher
priority than the level of logging will be displayed. If not set,
default level is ``INFO``.
In addition to OTB specific environment variables, the following
environment variables are parsed by third party libraries and also
affect how OTB works:
* ``GDAL_CACHEMAX``: GDAL has an internal cache mechanism to avoid reading or decoding again image chunks. This environment variable controls the amount of memory that GDAL can use for caching. By default, GDAL can use up to 5 percent of the system's available RAM, which may be a lot. In addition, caching is only needed if the processing chain is likely to request the same chunk several times, which is unlikely to happen for a standard pixel based OTB pipeline. Setting a lower value facilitates the allocation of more memory to OTB itself (using applications ``-ram`` parameter or ``OTB_MAX_RAM_HINT`` environment variable). If the value is small, i.e. less than 100 000, it is assumed to be in megabytes, otherwise, it is assumed to be in bytes.
* ``GDAL_NUM_THREADS``: GDAL can take advantage of multi-threading to decode some formats. This variable controls the number of threads GDAL is allowed to use.
* ``OPJ_NUM_THREADS``: OpenJpeg can take advantage of multi-threading when decoding images. This variable controls the number of threads OpenJpeg is allowed to use.
* ``ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS``: This variable controls the number of threads used by ITK for processing.
Advanced Use
============
This section describes advanced configuration options and tricks.
Environment variables that affect Orfeo ToolBox
-----------------------------------------------
The following environment variables are parsed by Orfeo ToolBox. Note
that they only affect default values, and that settings in extended
filenames, applications, Monteverdi or custom C++ code might override
those values.
* ``OTB_DEM_DIRECTORY``: Default directory were DEM tiles are
stored. It should only contain ```.hgt`` or or georeferenced
``.tif`` files. Empty if not set (no directory set)
* ``OTB_GEOID_FILE``: Default path to the geoid file that will be used
to retrieve height of DEM above ellipsoid. Empty if not set (no
geoid set)
* ``OTB_MAX_RAM_HINT``: Default maximum memory that OTB should use for
processing, in MB. If not set, default value is 128 MB.
* ``OTB_LOGGER_LEVEL``: Default level of logging for OTB. Should be
one of ``DEBUG``, ``INFO``, ``WARNING``, ``CRITICAL`` or ``FATAL``,
by increasing order of priority. Only messages with a higher
priority than the level of logging will be displayed. If not set,
default level is ``INFO``.
In addition to OTB specific environment variables, the following
environment variables are parsed by third party libraries and also
affect how OTB works:
* ``GDAL_CACHEMAX``: GDAL has an internal cache mechanism to avoid reading or decoding again image chunks. This environment variable controls the amount of memory that GDAL can use for caching. By default, GDAL can use up to 5 percent of the system's available RAM, which may be a lot. In addition, caching is only needed if the processing chain is likely to request the same chunk several times, which is unlikely to happen for a standard pixel based OTB pipeline. Setting a lower value facilitates the allocation of more memory to OTB itself (using applications ``-ram`` parameter or ``OTB_MAX_RAM_HINT`` environment variable). If the value is small, i.e. less than 100 000, it is assumed to be in megabytes, otherwise, it is assumed to be in bytes.
* ``GDAL_NUM_THREADS``: GDAL can take advantage of multi-threading to decode some formats. This variable controls the number of threads GDAL is allowed to use.
* ``OPJ_NUM_THREADS``: OpenJpeg can take advantage of multi-threading when decoding images. This variable controls the number of threads OpenJpeg is allowed to use.
* ``ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS``: This variable controls the number of threads used by ITK for processing.
.. _extended-filenames:
Extended filenames
------------------
==================
Extended filenames are an interesting feature of OTB. With them, it is possible to control
several aspects of the behavior of OTB in the OTB-Applications or in our
......
Graphical interface
===================
The graphical interface for the applications provides a useful
interactive user interface to set the parameters, choose files, and
monitor the execution progress.
This launcher needs the same two arguments as the command line launcher:
::
$ otbApplicationLauncherQt module_name [MODULEPATH]
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 graphical user interface, one will start the
``otbgui_Rescale`` script.
The resulting graphical application displays a window with several tabs:
- Parameters is where you set the parameters and execute the
application.
- Logs is where you see the output 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.
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 is shown here as an example:
.. figure:: Art/QtImages/rescale_param.png
:align: center
......@@ -13,8 +13,7 @@ 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,
information is available in the `Software Guide <http://orfeo-toolbox.org/SoftwareGuide/>`_,
in the section "Building from Source".
information is available in the :ref:`compilingfromsource` section.
You can get latest binary packages from our `Download page <https://www.orfeo-toolbox.org/download>`__.
......
Python API
==========
The applications can also be accessed from Python, through a module
named ``otbApplication``. However, there are technical requirements to use it.
If you use OTB through standalone packages, you should use the supplied
environment script ``otbenv`` to properly setup variables such as
``PYTHONPATH`` and ``OTB_APPLICATION_PATH`` (on Unix systems, don't forget to
source the script). In other cases, you should set these variables depending on
your configuration.
On Unix systems, it is typically available in the ``/usr/lib/otb/python``
directory. Depending on how you installed OTB, you may need to configure the
environment variable ``PYTHONPATH`` to include this directory so that the module
becomes available from Python.
On Windows, you can install the ``otb-python`` package, and the module
will be automatically available from an OSGeo4W shell.
As for the command line and GUI launchers, the path to the application
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 ``OTB_APPLICATION_PATH`` doesn't need to be modified
``OTB_APPLICATION_PATH``.
Once your environment is set, you can use OTB applications from Python, just
like this small example:
.. code-block:: python
# Example on the use of the Smoothing application
# The python module providing access to OTB applications is otbApplication
import otbApplication as otb
# Let's create the application with codename "Smoothing"
app = otb.Registry.CreateApplication("Smoothing")
# We set its parameters
app.SetParameterString("in", "my_input_image.tif")
app.SetParameterString("type", "mean")
app.SetParameterString("out", "my_output_image.tif")
# This will execute the application and save the output file
app.ExecuteAndWriteOutput()
For more information about this Python interface, check the recipe section.
......@@ -53,10 +53,10 @@ source_suffix = '.rst'
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index_TOC'
master_doc = 'index'
# General information about the project.
project = u'OTB CookBook'
project = u'Orfeo ToolBox'
copyright = u'@OTB_COPYRIGHT_TEXT@'
#copyright = u'2014, OTB Team'
# The version info for the project you're documenting, acts as replacement for
......@@ -119,8 +119,9 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
html_theme_options = {
'logo_only': True
}
# The name for this set of Sphinx documents. If None, it defaults to
......@@ -132,7 +133,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = "rst/Art/logo.png"
html_logo = "rst/Art/logo-with-text.png"
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
......
.. OTB documentation master file, created by
sphinx-quickstart on Thu Jul 9 11:22:08 2015
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Orfeo ToolBox!
=========================
......@@ -44,3 +39,34 @@ For other documentation, be sure to read:
- `Doxygen <http://orfeo-toolbox.org/doxygen/>`_, for exhaustive documentation
of the C++ API.
Table of Contents
=================
.. toctree::
:maxdepth: 2
:caption: Get Started
Installation
Monteverdi
.. toctree::
:maxdepth: 2
:caption: Applications
CliInterface
GraphicalInterface
PythonAPI
QGISInterface
Recipes
Applications
.. toctree::
:maxdepth: 1
:caption: Advanced use
EnvironmentVariables
ExtendedFilenames
CompilingOTBFromSource
C++
FAQ
Contributors
Table of Contents
=================
.. toctree::
:maxdepth: 3
index
Installation
CompilingOTBFromSource
OTB-Applications
QGIS-interface
Monteverdi
AdvancedUse
Recipes
Applications
C++
FAQ
Contributors
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment