Merge branch 'doc_update' into 'develop'

Updating the documentation in preparation for OTB 8.0.0-alpha1

See merge request !780

Documentation/Cookbook/rst/C++/DEM.rst

+DEM Handler
+===========
+
+
+The ``otb::DEMHandler`` class is a singleton, a reference to the singleton object can be acquired via the ``otb::DEMHandler::GetInstance()`` method. The DEMHandler is based on RasterIO from GDAL. A 2x2 window is extracted around the point of interest, and the height above ellipsoid or above mean sea level is interpolated on this window. The interpolation is bilinear. The following methods are provided:
+
+- GetHeightAboveEllipsoid(lon, lat)
+    * SRTM and geoid both available: dem_value + geoid_offset
+    * No SRTM but geoid available: default height above ellipsoid + geoid_offset
+    * SRTM available, but no geoid: dem_value
+    * No SRTM and no geoid available: default height above ellipsoid
+
+- GetHeightAboveMSL(lon, lat)
+    * SRTM and geoid both available: dem_value
+    * No SRTM but geoid available: 0
+    * SRTM available, but no geoid: dem_value
+    * No SRTM and no geoid available: 0
+
+Several DEM tiles can be provided at the same time, using the ``OpenDEMDirectory`` method. All raster from the input directory will be opened by GDAL. Internally, a mosaic of all DEM tiles is then created as a virtual dataset (vrt).
+
+All raster that can be opened by gdal can be used as a geoid. In previous OTB versions (using Ossim) it was common to use the egm96.grd file as geoid, this file cannot be opened by GDAL. However it is still possible to use it by using the following egm96.grd.hdr file::
+
+  ENVI
+  samples = 1441
+  lines   = 721
+  bands   = 1
+  header offset = 24
+  file type = ENVI Standard
+  data type = 4
+  interleave = bsq
+  sensor type = Unknown
+  byte order = 1
+  wavelength units = Unknown
+  map info = {Geographic Lat/Lon, 1, 1,-0.125, 90.125, 0.25, 0.25,WGS-84}
+  coordinate system string = {GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]]}
+  band names = {
+  Band 1}
+
+
+With this file attached, GDAL will be able to read the egm96.grd file as a ENVI dataset
\ No newline at end of file

Documentation/Cookbook/rst/C++/DeveloperGuide.rst

@@ -7,6 +7,9 @@ Developer Guide
     Iterators
     Filters
     StreamingAndThreading
+    Metadata
+    DEM
+    SensorModel
     FunctorImageFilter
     PersistentFilters
     WriteAnApplication

Documentation/Cookbook/rst/C++/Metadata.rst

+Metadata
+========
+
+This chapter explains how OTB deals with the metadata.
+
+otbImageMetadata
+----------------
+
+OTB uses the classes ``otbImageMetadata`` and ``otbImageMetadataBase``
+to store the metadata.
+
+.. image:: /Art/C++/UmlImageMetadata.png
+
+``otbImageMetadataBase`` encapsulates seven ``std::map`` to store
+seven different kind of metadata:
+
+- Numeric metadata for the metadata that can be stored as a double
+
+- String metadata for the metadata that can be stored as a std::string
+
+- LUT 1D metadata the metadata that can be stored as a one dimension table
+
+- LUT 2D metadata for the metadata that can be stored as two dimensions table
+
+- Time metadata for the metadata that can be stored as a time object
+
+- Geometry metadata for the metadata that represent a model
+
+- Extra metadata for non generic metadata stored as std::string
+
+The keys of the maps are described in the file
+``otbMetaDataKey.h``. This file also defines the time object.
+
+For each map, the class provides 4 methods:
+
+- the ``[] operator`` for a read-only access the metadata from the key
+
+- the ``Add`` method to set a metadata value
+
+- the ``Remove`` method to delete a metadata va1ue
+
+- the ``Has`` method to test if a key has a value
+
+An instance of ``otbImageMetadata`` is used to store the metadata. It
+inherits from ``otbImageMetadataBase``, therefore it encapsulates
+seven maps used to store the metadata. It also contains a vector of
+``otbImageMetadataBase`` to store band specific metadata
+(``m_Bands``).
+
+Metadata workflow
+-----------------
+
+OTB reads and writes metadata from and to products through the
+workflow described by this figure:
+
+.. image:: /Art/C++/MetadataWorkflow.png
+
+- The GDAL input/output capabilities are encapsulated in the
+  ``otbGDALImageIO`` class, which derivates from ``otbImageIO``. This
+  class is in charge of fetching the metadata from the product
+  (supplier capabilities inherited from the class
+  ``otbMetadataSupplierInterface``) and storing them in memory as a
+  keywordlist. It is also in charge of writing the metadata to the
+  product (storage capabilities inherited from the class
+  ``otbMetadataStorageInterface``).
+
+- An ImageMetadataInterface (IMI) is then called to parse the
+  metadata. There is one IMI per sensor. We use a classical Factory to
+  find which one can parse the metadata of a product. The IMI's parse
+  method will pick the metadata from the ImageIO and fill an
+  ImageMetadata object.
+
+- Some metadata are not read by GDAL. To parse those metadata, the IMI
+  can call other suppliers, depending on the file format:
+
+    * to parse XML files, ``otbXMLMetadataSupplier`` uses GDAL's XML
+      parsing mechanism ("ReadXMLToList" method from the
+      "GDALMDReaderBase" class) to convert the XML file into a GDAL
+      ListString, which is a succession of 'key=value' pairs.
+
+    * to parse text files, TextMetadataSupplier tries to parse
+      'key=value' pairs.
+
+  Other suppliers can be added if needed. Those classes (including
+  ``otbGDALImageIO``) all implement the method ``GetMetadataValue``
+  which returns the value of the metadata from a given key. The base
+  class also implements the methods ``GetAs`` and ``GetAsVector``
+  which are used by the IMI.
+
+- The IMI finds the relevant metadata in the different Metadata
+  Suppliers and use the ``Add`` method of the ImageMetadata object to
+  store the metadata. If the parsing returns successfully, the
+  generated ImageMetadata is given to the ImageCommon that propagate
+  through the pipeline.

Documentation/Cookbook/rst/C++/SensorModel.rst

+Sensor model
+============
+
+The class ``otb::SensorTransformBase`` is the base class for sensor
+models. It inherits from ``otb::Transform``, which inherits from
+``itk::Transform``. It is templated over the data type, and input and
+output dimentions. All sensor model classes should inherit from it,
+and implement the methods:
+
+- ``SetMetadataModel`` that takes a ``boost::any`` object representing the model;
+
+- ``IsValidSensorModel`` that returns true if the model is correctly set;
+
+- ``TransformPoint`` that process the transformation.
+
+.. image:: /Art/C++/UmlSensorModel.png
+
+RPC sensor model
+----------------
+
+The structure ``otb::Projection::RPCParam`` is used to store the
+parameters of the RPC model. It is based on `GDAL's RPC structure
+<https://gdal.org/development/rfc/rfc22_rpc.html>`_.
+
+The RPC model is stored in the ``otb::ImageMetadata`` object, using
+the key ``MDGeom::RPC``. The classes ``otb::RPCTransformBase``,
+``otb::RPCForwardTransform`` and ``otb::RPCInverseTransform`` are used
+to perform forward and inverse transformation using this model.
+
+The abstract class ``otb::RPCTransformBase`` contains the
+implementation of the SetMetadataModel method, which receives the RPC
+description from the ``otb::ImageMetadata`` and instantiates an
+``otb::GDALRPCTransformer``.
+
+The classes ``otb::RPCForwardTransform`` and
+``otb::RPCInverseTransform`` each implement a version of the
+``TransformPoint`` method which uses the ``otb::GDALRPCTransformer``.