Merge branch 'develop' of https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb into develop

.clang-format

 ---
-Language:        Cpp
-BasedOnStyle:  Mozilla
-AccessModifierOffset: -2
 AlignAfterOpenBracket: Align
-AlignConsecutiveAssignments: false
+AlignConsecutiveAssignments: true
 AlignConsecutiveDeclarations: true
 AlignEscapedNewlinesLeft: true
 AlignOperands:   true
 AlignTrailingComments: true
-AllowAllParametersOfDeclarationOnNextLine: false
 AllowShortBlocksOnASingleLine: false
 AllowShortCaseLabelsOnASingleLine: false
-AllowShortFunctionsOnASingleLine: Inline
+AllowShortFunctionsOnASingleLine: false
 AllowShortIfStatementsOnASingleLine: false
 AllowShortLoopsOnASingleLine: false
-AlwaysBreakAfterReturnType: All
 AlwaysBreakBeforeMultilineStrings: true
 AlwaysBreakTemplateDeclarations: true
-BinPackArguments: false
-BinPackParameters: true
-BraceWrapping:
-  AfterClass:      true
-  AfterControlStatement: true
-  AfterEnum:       true
-  AfterFunction:   true
-  AfterNamespace:  true
-  AfterObjCDeclaration: true
-  AfterStruct:     true
-  AfterUnion:      true
-  BeforeCatch:     true
-  BeforeElse:      true
-  IndentBraces:    true
-BreakBeforeBinaryOperators: None
-BreakBeforeBraces: GNU
-BreakBeforeTernaryOperators: true
-BreakConstructorInitializersBeforeComma: true
-BreakAfterJavaFieldAnnotations: false
-BreakStringLiterals: true
-ColumnLimit:     200
-# ColumnLimit:     80
-CommentPragmas:  '^ IWYU pragma:'
-ConstructorInitializerAllOnOneLineOrOnePerLine: false
+BreakBeforeBraces: Allman
+ColumnLimit:     160
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
 ConstructorInitializerIndentWidth: 2
-ContinuationIndentWidth: 2
-Cpp11BracedListStyle: false
+Cpp11BracedListStyle: true
 DerivePointerAlignment: false
-DisableFormat:   false
-ExperimentalAutoDetectBinPacking: false
-ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
-IncludeCategories:
-  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
-    Priority:        2
-  - Regex:           '^(<|"(gtest|isl|json)/)'
-    Priority:        3
-  - Regex:           '.*'
-    Priority:        1
-IncludeIsMainRegex: '$'
-IndentCaseLabels: true
 IndentWidth:     2
-IndentWrappedFunctionNames: false
-JavaScriptQuotes: Leave
-JavaScriptWrapImports: true
-KeepEmptyLinesAtTheStartOfBlocks: false
-MacroBlockBegin: ''
-MacroBlockEnd:   ''
+Language:        Cpp
 MaxEmptyLinesToKeep: 2
 NamespaceIndentation: None
-ObjCBlockIndentWidth: 2
-ObjCSpaceAfterProperty: true
-ObjCSpaceBeforeProtocolList: false
-PenaltyBreakBeforeFirstCallParameter: 19
-PenaltyBreakComment: 300
-PenaltyBreakFirstLessLess: 120
-PenaltyBreakString: 1000
-PenaltyExcessCharacter: 1000000
-PenaltyReturnTypeOnItsOwnLine: 0
 PointerAlignment: Left
-ReflowComments:  true
-SortIncludes:    true
-SpaceAfterCStyleCast: false
-SpaceBeforeAssignmentOperators: true
-SpaceBeforeParens: ControlStatements
-SpaceInEmptyParentheses: false
-SpacesBeforeTrailingComments: 1
-SpacesInAngles:  true
-SpacesInCStyleCastParentheses: false
-SpacesInContainerLiterals: true
-SpacesInParentheses: true
-SpacesInSquareBrackets: false
-Standard:        Cpp03
+SortIncludes: false
+Standard:        Cpp11
 TabWidth:        2
 UseTab:          Never
 ...

CMake/OTBModuleHeaderTest.cmake

@@ -131,13 +131,11 @@ macro( otb_module_headertest _name )
         )
       add_executable( ${_test_name} ${_header_test_src} )
       target_link_libraries( ${_test_name} OTBCommon )
+
       if (${_name}_LIBRARIES)
-        # OTBBoostAdapters depends only on OTBBoost,
-        # and OTBBoost_LIBRARIES can be empty, so check for it
-        add_dependencies(${_test_name} ${${_name}_LIBRARIES})
-        # this target_link should be needed only on WIN32
         target_link_libraries(${_test_name} ${${_name}_LIBRARIES})
       endif()
+
       add_dependencies(${_name}-all ${_test_name})
       math( EXPR _test_num "${_test_num} + 1" )
     endforeach()

CMakeLists.txt

@@ -23,6 +23,8 @@ cmake_minimum_required(VERSION 3.1.0)
 foreach(p
     CMP0025 # CMake 3.0
     CMP0042 # CMake 3.0
+    CMP0046 # CMake 3.0
+    CMP0054 # CMake 3.1
     CMP0058 # CMake 3.3
     CMP0072 # CMake 3.11
     )
@@ -31,17 +33,6 @@ foreach(p
   endif()
 endforeach()
 
-# CMP0046 : from CMake 3.0, old behaviour is more convenient
-if(POLICY CMP0046)
-  cmake_policy(SET CMP0046 OLD)
-endif()
-
-# TODO Check if OTB cmake is compatible with CMP0054 NEW policy
-# CMP0054 : New policy introduce in CMake 3.1, keep old behaviour for now
-if(POLICY CMP0054)
-  cmake_policy(SET CMP0054 OLD)
-endif()
-
 project(OTB)
 
 set(CMAKE_CXX_STANDARD 14)

Documentation/Cookbook/CMake/RunApplicationsRstGenerator.sh.cmake.in

@@ -5,4 +5,4 @@
 export PYTHONPATH=@PYTHONPATH_COOKBOOK@:$PYTHONPATH
 export OTB_APPLICATION_PATH=@CMAKE_BINARY_DIR@/lib/otb/applications
 
-python3 @CMAKE_CURRENT_SOURCE_DIR@/Scripts/otbGenerateWrappersRstDoc.py -o "$1"
+python3 @CMAKE_CURRENT_SOURCE_DIR@/Scripts/otbGenerateWrappersRstDoc.py "$1"

Documentation/Cookbook/CMakeLists.txt

@@ -120,6 +120,8 @@ set(OTB_COPYRIGHT_TEXT "${OTB_COPYRIGHT_YEAR} CNES.The OTB CookBook is licensed
 
 configure_file(${RST_SOURCE_DIR}/conf.py.in ${SPHINX_CONF_DIR}/conf.py @ONLY)
 
+file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/_static DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+
 add_custom_target(generate_otbapps_rst
   COMMAND ${SH_INTERP} ${CMAKE_CURRENT_BINARY_DIR}/RunApplicationsRstGenerator.sh
   ${RST_BINARY_DIR}
@@ -142,7 +144,6 @@ add_custom_target(CookBookHTML
   -b html
   ${RST_BINARY_DIR}
   ${HTML_DIR}
-  -W
   -v
   -c ${SPHINX_CONF_DIR}
   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
@@ -163,7 +164,6 @@ add_custom_target(CookBookArchive
    -b latex
    ${RST_BINARY_DIR}
    ${LATEX_DIR}
-   -W
    -v
    -c ${SPHINX_CONF_DIR}
    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}

Documentation/Cookbook/README.md

@@ -3,11 +3,11 @@ RST docs for Orfeo Toolbox CookBook
 Introduction
 ============
 
-This is a replacement of old OTB Cookbook which was written in Latex. This version is completely deviate from existing Latex format to reStructured format (rst).
+This is a replacement of the old OTB Cookbook which was written in LaTeX. This version has deviated completely from the existing LaTeX format to reStructured format (rst).
 
-Converting existing latex to rst is not that straightforward. All rst files for OTB applications are generated using python script otbGenerateWrappersRstDoc.py.
-For others in recipes, we used a tool called pandoc to get an initial rst and then edited out errors manually. You do not have to generate them again.
-The old Cookbook in otb-documents is deprecated.
+Converting existing LaTeX to rst is not that straightforward. All rst files for OTB applications are generated using the Python script otbGenerateWrappersRstDoc.py.
+For others files in the Recipes, we used a tool called pandoc to get an initial rst and then manually edit and remove the errors. You do not have to generate them again.
+The old Cookbook in otb-documents is now deprecated.
 
 Requirements
 ============

Documentation/Cookbook/Scripts/otb_warnings.py

+import sys
+import re
+
+def parameter_warnings(app_warn, app, key):
+
+    def warn(message):
+        app_warn("Parameter '{}' ".format(key) + message)
+
+    name = app.GetParameterName(key)
+    description = app.GetParameterDescription(key)
+
+    if name[-1] == " ":
+        warn("name ends with a space")
+
+    if ":" in name:
+        warn("name contains a special character (:)")
+
+    if "." in name:
+        warn("name contains a special character (.)")
+
+    # disabled because there are so many for now
+    #if description == "":
+        #warn("missing description")
+
+    # disabled because there are so many for now
+    #if len(description) > 0 and description[-1] != ".":
+        #warn("description does not end with a period")
+
+    if len(description) > 0 and " :" in description:
+        warn("description has a space before a colon")
+
+def application_documentation_warnings(app):
+    "Emit warnings about application documentation"
+
+    def warn(message):
+        print("OTB Documentation Warning ({}): {}".format(app.GetName(), message), file=sys.stderr)
+
+    description = app.GetDescription()
+    longdescription = app.GetDocLongDescription()
+
+    # disable because there are so many for now
+    #if not longdescription[-1] == ".":
+        #warn("Application Long Description does not end with a period (.)")
+
+    if re.search("\\n [a-zA-Z]", longdescription):
+        warn("Application Long Description contains '\\n ' pattern (usually not intended)")
+
+    if " :" in longdescription:
+        warn("Application Long Description has a space before a colon")
+
+    if app.GetNumberOfExamples() == 0:
+        warn("Application has no examples")
+
+    keys = app.GetParametersKeys()
+    for key in app.GetParametersKeys():
+        parameter_warnings(warn, app, key)
+
+    if "ram" in keys and not keys[-3] == "ram":
+        warn("'ram' parameter is not third from last")
+
+    if "inxml" in keys and not keys[-2] == "inxml":
+        warn("'inxml' parameter is not second from last parameter")
+
+    if "outxml" in keys and not keys[-1] == "outxml":
+        warn("'outxml' is not last parameter")
+

Documentation/Cookbook/_static/css/otb_theme.css

+.wy-nav-content {
+    max-width: 800px;
+}
+
+/* Reduce the effect of the p bottom margin before lists
+ * Very useful for choice parameters in app doc for example
+ */
+p + ul {
+    margin-top: -18px;
+}

Documentation/Cookbook/rst/FAQ.rst

@@ -30,10 +30,10 @@ What's in OTB?
 
 -  Geospatial analysis.
 
-For a full list of applications see the :ref:`apprefdoc`.
+For a full list of applications see the chapter :ref:`apprefdoc`.
 For an introduction to the C++ API see the
 `Software Guide <https://www.orfeo-toolbox.org/SoftwareGuide/>`_.
-And for exhaustive descrpition of the C++ API see the
+And for an exhaustive description of the C++ API see the
 `Doxygen <https://www.orfeo-toolbox.org/doxygen/>`_.
 
 What is ORFEO?

Documentation/Cookbook/rst/Installation.rst

@@ -24,7 +24,7 @@ Windows
 .. include:: Installation_Windows.rst
 
 Linux
-------------
+-----
 
 .. include:: Installation_Linux.rst
 

Documentation/Cookbook/rst/conf.py.in

@@ -21,6 +21,11 @@ import sphinx_rtd_theme
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 
+# Customize read the docs theme a bit with a custom css
+# taken from https://stackoverflow.com/a/43186995/5815110
+def setup(app):
+    app.add_stylesheet("css/otb_theme.css")
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -75,7 +80,7 @@ release = '@OTB_VERSION@'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['@RST_BUILD_DIR@']
+exclude_patterns = ['@RST_BUILD_DIR@', 'templates/*.rst']
 #exclude_patterns = ['_build']
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -167,6 +172,16 @@ html_static_path = ['_static']
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
 
+html_context = {
+    'display_gitlab': True,
+    'gitlab_host': "gitlab.orfeo-toolbox.org",
+    'gitlab_user': 'orfeotoolbox',
+    'gitlab_repo': 'OTB',
+    'gitlab_version': 'develop',
+    'conf_py_path': '/Documentation/Cookbook/rst/',
+    #'source_url_prefix': "https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/tree/develop/Documentation/Cookbook/rst/",
+}
+
 # If true, links to the reST sources are added to the pages.
 html_show_sourcelink = True
 

Documentation/Cookbook/rst/recipes/bandmathx.rst

@@ -20,6 +20,8 @@ A simple example is given below:
 As we can see, the new band math filter works with the class
 otb::VectorImage.
 
+.. _syntax:
+
 Syntax: first elements
 ----------------------
 
@@ -134,8 +136,7 @@ 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]-).
+two vectors (see next section :ref:`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
@@ -170,6 +171,8 @@ Fundamentally, a neighbourhood is represented as a matrix inside the
 muParserX framework; so the remark about mathematically well-defined
 formulas still stands.
 
+.. _operators:
+
 New operators and functions
 ---------------------------
 
@@ -205,7 +208,7 @@ ones. For instance:
 .. 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 a
+But ’pw’ is a little bit more permissive, and can tolerate a
 one-dimensional vector as the right operand.
 
 **Operators pow and pw** The first operator allows the definition of an
@@ -267,20 +270,20 @@ takes two inputs). For instance:
 
 .. math:: corr(im1b1N3x3,im1b2N3x3)
 
-**Function maj** This function allows to compute the most represented
+**Function maj** This function computes 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
+**Function vmin and vmax** These functions calculate 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
+**Function cat** This function concatenates the results of
 several expressions into a multidimensional vector, whatever their
 respective dimensions (the function can take as many inputs as needed).
 For instance:
@@ -293,8 +296,7 @@ application will call the function ’cat’ automatically. For instance:
 
 .. math:: filter->SetExpression("im3b1 ; vmin(im3b1N3x5) ; median(im3b1N3x5) ; vmax(im3b1N3x5)");
 
-Please, also refer to the next section “Application Programming
-Interface” ([ssec:API]).
+Please, also refer to the next section :ref:`API`. 
 
 **Function ndvi** This function implements the classical normalized
 difference vegetation index; it takes two inputs. For instance:
@@ -302,7 +304,7 @@ difference vegetation index; it takes 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 near-infrared band.
 
 The table below summarises the different functions and operators.
 
@@ -366,6 +368,8 @@ Functions and operators summary:
 
 [variables]
 
+.. _API: 
+
 Application Programming Interface (API)
 ---------------------------------------
 
@@ -381,7 +385,7 @@ of the new band math filter.
     /** Return a pointer on the nth filter input */
     ImageType * GetNthInput(unsigned int idx);
 
-Refer to the section “Syntax: first elements” ([ssec:syntax]) where the
+Refer to the section :ref:`syntax`, where the
 two first functions have already been commented. The function
 GetNthInput is quite clear to understand.
 
@@ -394,13 +398,13 @@ Each time the function SetExpression is called, a new expression is
 pushed inside the filter. **There are as many outputs as there are
 expressions. The dimensions of the outputs (number of bands) are totally
 dependent on the dimensions of the related expressions (see also last
-remark of the section “Syntax: first element” -[ssec:syntax]-).** Thus,
+remark of the section :ref:`syntax`).** Thus,
 the filter always performs a pre-evaluation of each expression, in order
 to guess how to allocate the outputs.
 
 The concatenation of the results of many expressions (whose results can
 have different dimensions) into one unique output is possible. For that
-puropose, semi-colons (“;”) are used as separating characters. For
+purpose, semi-colons (“;”) are used as separating characters. For
 instance:
 
 .. math:: filter->SetExpression("im1 + im2 ; im1b1*im2b1");
@@ -494,7 +498,7 @@ expr. For instance:
       /** Export constants and expressions to a given filename */
       void ExportContext(const std::string& filename);
 
-This function allows the user to export a txt file that saves its
+This function allows the user to export a text file that saves its
 favorite constant or expression definitions. Such a file will be
 reusable by the ImportContext function (see above).
 

Documentation/Cookbook/rst/recipes/improc.rst

@@ -70,7 +70,7 @@ input image to the default value for DEM (which is -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
+no-data, but the no-data value in the image metadata does not 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:
@@ -91,8 +91,8 @@ For instance:
                         -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.
+“mode.apply.ndval”. This parameter sets the output nodata value
+of the input mask.
 
 Segmentation
 ------------
@@ -274,7 +274,7 @@ all the previous steps:
 
 Most of the settings from the previous applications are also exposed in this
 composite application. The range and spatial radius used for the segmentation
-step are half the values used for Mean-Shift smooting, which are obtained from
+step are half the values used for Mean-Shift smoothing, which are obtained from
 LargeScaleMeanShift parameters. There are two output modes: vector (default)
 and raster. When the raster output is chosen, last step (vectorization) is
 skipped.
@@ -295,8 +295,8 @@ 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
+the results viability by using a classifier fusion algorithm. Using a
+set of descriptors, the processing chain validates or invalidates the
 input geometrical features.
 
 Fuzzy Model (requisite)
@@ -341,7 +341,7 @@ for each studied polyline, the chosen descriptors. In this context, the
 *ComputePolylineFeatureFromImage* 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 chosen
+-  ``-in`` an image (of the studied scene) corresponding to the chosen
    descriptor (NDVI, building Mask…)
 
 -  ``-vd`` a vector data containing polyline of interest
@@ -394,7 +394,7 @@ Second Step: Feature Validation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The final application (*VectorDataDSValidation* ) will validate or
-unvalidate the studied samples using `the Dempster-Shafer
+invalidate the studied samples using `the Dempster-Shafer
 theory <http://en.wikipedia.org/wiki/Dempster%E2%80%93Shafer_theory>`_ 
 . Its inputs are:
 

Documentation/Cookbook/rst/recipes/optpreproc.rst

@@ -10,7 +10,7 @@ Optical radiometric calibration
 In remote sensing imagery, pixel values are referred to as Digital
 Numbers (DN) and they cannot be physically interpreted or compared. They are
 influenced by various factors such as the amount of light flowing through
-the sensor, the gain of the detectors and the analogic to numeric
+the sensor, the gain of the detectors and the analogue to digital
 converter.
 
 Depending on the season, the light and atmospheric conditions, the
@@ -63,7 +63,7 @@ sensors are:
 
 -  Formosat
 
-The *OpticalCalibration* application allows to perform optical
+The *OpticalCalibration* application performs 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
@@ -128,7 +128,7 @@ Using either **OTB Applications** or modules from **Monteverdi** , it is
 possible to perform both steps in a row, or step-by-step fusion, as
 described in the above sections.
 
-The *BundleToPerfectSensor* application allows to perform both steps in
+The *BundleToPerfectSensor* application performs 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
@@ -157,15 +157,15 @@ application:
 
 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])
+-  The ``-elev`` option specifies the elevation, either with a
+   DEM formatted for OTB (``-elev.dem`` option, see section :ref:`section2`)
    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.
+   perfect in case of a landscape with a large variation in elevation. In this
+   case a DEM will allow for a better registration to be achieved. 
 
--  The ``-lmSpacing`` option allows to specify the step of the
+-  The ``-lmSpacing`` option specifies 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
@@ -173,15 +173,15 @@ There are also optional parameters that can be useful for this tool: