Merge branch '1865-examples-review1' into 'develop'

Examples review (part 1)

See merge request orfeotoolbox/otb!477

Documentation/Cookbook/Scripts/RunExamples.py

@@ -33,7 +33,7 @@ blacklist = [
         "LAIAndPROSAILToSensorResponse" # does not run, wrong arguments
     ]
 
-def run_example(otb_root, otb_data, name, dry_run):
+def run_example(otb_root, name, dry_run):
     """
     Run an example by name
     Assumes the current working directory is an OTB build
@@ -71,6 +71,7 @@ def run_example(otb_root, otb_data, name, dry_run):
         print("$ " + binary + " " + " ".join(example_args))
 
         if not dry_run:
+            otb_data = join(otb_root, "Data")
             # Make sure Output dir exists
             os.makedirs(join(otb_data, "Output"), exist_ok=True)
 
@@ -81,19 +82,18 @@ def run_example(otb_root, otb_data, name, dry_run):
 def main():
     parser = argparse.ArgumentParser(usage="Run one or all OTB cxx examples")
     parser.add_argument("otb_root", help="Path to otb repository")
-    parser.add_argument("otb_data", help="Path to otb-data repository")
     parser.add_argument("--name", type=str, help="Run only one example with then given name")
     parser.add_argument("-n", "--dry-run", action='store_true', help="Dry run, only print commands")
     parser.add_argument("-k", "--keep-going", action='store_true', help="Keep going after failing examples")
     args = parser.parse_args()
 
     if args.name:
-        run_example(args.otb_root, args.otb_data, args.name, dry_run=args.dry_run)
+        run_example(args.otb_root, args.name, dry_run=args.dry_run)
     else:
         list_of_examples =[os.path.splitext(os.path.basename(f))[0] for f in glob.glob(join(args.otb_root, "Examples/*/*.cxx"))]
         for name in list_of_examples:
             try:
-                run_example(args.otb_root, args.otb_data, name, dry_run=args.dry_run)
+                run_example(args.otb_root, name, dry_run=args.dry_run)
             except Exception as e:
                 if args.keep_going:
                     print("Warning:", e)

Documentation/Cookbook/Scripts/otbGenerateExamplesRstDoc.py

@@ -44,7 +44,7 @@ def generate_examples_index(rst_dir, list_of_examples):
     index_f = open(join(rst_dir, "Examples.rst"), "w")
     index_f.write(RstPageHeading("C++ Examples", 3, ref="cpp-examples"))
 
-    for tag, examples_filenames in tag_files.items():
+    for tag, examples_filenames in sorted(tag_files.items()):
         tag_filename = join("Examples", tag + ".rst")
         index_f.write("\t" + tag_filename + "\n")
 

Examples/BasicFilters/BandMathFilterExample.cxx

@@ -22,22 +22,6 @@
 ./BandMathFilterExample Input/qb_RoadExtract.tif Output/RoadExtractBandMath.tif Output/qb_BandMath-pretty.jpg
 */
 
-
-// This filter is based on the mathematical parser library muParser.
-// The built in functions and operators list is available at:
-// http://muparser.sourceforge.net/mup_features.html.
-//
-// In order to use this filter, at least one input image should be
-// set. An associated variable name can be specified or not by using
-// the corresponding SetNthInput method. For the nth input image, if
-// no associated variable name has been specified, a default variable
-// name is given by concatenating the letter "b" (for band) and the
-// corresponding input index.
-//
-// The next step is to set the expression according to the variable
-// names. For example, in the default case with three input images the
-// following expression is valid: ``(b1+b2)*b3``.
-
 #include "itkMacro.h"
 #include <iostream>
 
@@ -65,11 +49,10 @@ int main(int argc, char* argv[])
     return EXIT_FAILURE;
   }
 
-  // We start by the typedef needed for reading and
+  // We start by the typedefs needed for reading and
   // writing the images. The BandMathImageFilter class
   // works with Image as input, so we need to define additional
   // filters to extract each layer of the multispectral image.
-
   typedef double                                                           PixelType;
   typedef otb::VectorImage<PixelType, 2>                                   InputImageType;
   typedef otb::Image<PixelType, 2>                                         OutputImageType;
@@ -78,13 +61,12 @@ int main(int argc, char* argv[])
   typedef otb::ImageFileReader<InputImageType>                             ReaderType;
   typedef otb::ImageFileWriter<OutputImageType>                            WriterType;
 
-  // We can now define the type for the filter:
+  // We can now define the type for the filter
   typedef otb::BandMathImageFilter<OutputImageType> FilterType;
 
-  // We instantiate the filter, the reader, and the writer:
+  // We instantiate the filter, the reader, and the writer
   ReaderType::Pointer reader = ReaderType::New();
   WriterType::Pointer writer = WriterType::New();
-
   FilterType::Pointer filter = FilterType::New();
 
   writer->SetInput(filter->GetOutput());
@@ -93,9 +75,9 @@ int main(int argc, char* argv[])
 
   reader->UpdateOutputInformation();
 
-  // We now need to extract each band from the input \doxygen{otb}{VectorImage},
-  // it illustrates the use of the \doxygen{otb}{VectorImageToImageList}.
-  // Each extracted layer is an input to the \doxygen{otb}{BandMathImageFilter}:
+  // We now need to extract each band from the input VectorImage,
+  // it illustrates the use of the VectorImageToImageList.
+  // Each extracted layer is an input to the BandMathImageFilter
   VectorImageToImageListType::Pointer imageList = VectorImageToImageListType::New();
   imageList->SetInput(reader->GetOutput());
 
@@ -111,8 +93,8 @@ int main(int argc, char* argv[])
   // Now we can define the mathematical expression to perform on the layers (b1, b2, b3, b4).
   // The filter takes advantage of the parsing capabilities of the muParser library and
   // allows setting the expression as on a digital calculator.
-  //
-  // The expression below returns 255 if the ratio $(NIR-RED)/(NIR+RED)$ is greater than 0.4 and 0 if not.
+
+  // The expression below returns 255 if the ratio (NIR-RED)/(NIR+RED) is greater than 0.4 and 0 if not.
   filter->SetExpression("if((b4-b3)/(b4+b3) > 0.4, 255, 0)");
 
 #ifdef OTB_MUPARSER_HAS_CXX_LOGICAL_OPERATORS
@@ -125,19 +107,7 @@ int main(int argc, char* argv[])
   writer->Update();
 
   // The muParser library also provides the possibility to extend existing built-in functions. For example,
-  // you can use the OTB expression "ndvi(b3, b4)" with the filter. In this instance, the mathematical expression would be
-  // \textit{if($ndvi(b3, b4)>0.4$, 255, 0)}, which would return the same result.
-
-  // Figure~\ref{fig:BandMathImageFilter} shows the result of the threshold applied to the NDVI index
-  // of a Quickbird image.
-  // \begin{figure}
-  // \center
-  // \includegraphics[width=0.45\textwidth]{qb_ExtractRoad_pretty.eps}
-  // \includegraphics[width=0.45\textwidth]{qb_BandMath-pretty.eps}
-  // \itkcaption[Band Math]{From left to right:
-  // Original image, thresholded NDVI index.}
-  // \label{fig:BandMathImageFilter}
-  // \end{figure}
+  // you can use the OTB expression "ndvi(b3, b4)" with the filter. In this instance, the mathematical expression would be "if(ndvi(b3, b4)>0.4, 255, 0)", which would return the same result.
 
   typedef otb::Image<unsigned char, 2>                                 OutputPrettyImageType;
   typedef otb::ImageFileWriter<OutputPrettyImageType>                  PrettyImageFileWriterType;
@@ -151,6 +121,4 @@ int main(int argc, char* argv[])
   prettyWriter->SetFileName(argv[3]);
 
   prettyWriter->Update();
-
-  return EXIT_SUCCESS;
 }

Examples/BasicFilters/BandMathFilterExample.rst

+The :doxygen:`BandMathImageFilter` is based on the mathematical parser library muParser.
+The built in functions and operators list is available at:
+http://muparser.sourceforge.net/mup_features.html.
+
+In order to use this filter, at least one input image should be
+set. An associated variable name can be specified or not by using
+the corresponding ``SetNthInput`` method. For the nth input image, if
+no associated variable name has been specified, a default variable
+name is given by concatenating the letter "b" (for band) and the
+corresponding input index.
+
+The next step is to set the expression according to the variable
+names. For example, in the default case with three input images the
+following expression is valid: ``(b1+b2)*b3``.
+
+.. |image1| image:: /Input/qb_ExtractRoad_pretty.png
+
+.. |image2| image:: /Output/qb_BandMath-pretty.jpg
+
+.. _Figure1:
+
++--------------------------+-------------------------+
+|        |image1|          |         |image2|        |
++--------------------------+-------------------------+
+
+    NDVI of a Quickbird image computed with BandMathImageFilter
+