Skip to content

The Big Examples Review

This is a planning issue for the review and modernization of OTB C++ examples, now rendered in the cookbook documentation (!395 (merged)).

How examples work

Examples are made of two files: a .cxx and an optional .rst file with the same basename, in a directory indicating their category, for example:

Examples/FeatureExtraction/TextureExample.cxx
Examples/FeatureExtraction/TextureExample.rst (optional file)
The cxx file

The C++ code should be normal C++14 code with two additional things:

  • The license header at the top (available in Documentation/Cookbook/rst/templates/examples_license_header.txt)
  • An example usage, i.e a comment that looks like this:
/* Example usage:
./TextureExample Input/ADS40RoiSmall.png Output/TextureOutput.tif Output/pretty_TextureOutput.png 2 1 1
*/

The directories Input/ and Output/ are a reference to Data/Input and Data/Output in OTB main repository. Input and output data are stored with git LFS.

The license header and example usage are not shown in the code in the html rendering.

The rst file

In the description .rst file, you can write normal Sphinx rst and make automatic references to a doxygen class, an application or another example with special roles:

the class :doxygen:`Image` is used for...
the ITK class :doxygen-itk:`ImageToImageFilter` is a...
the application :ref:`BundleToPerfectSensor` is...
see example :ref:`ApplicationExample.cxx` for more...

In the description .rst file, you can include input or output images from Data/Input or Data/Output using the absolute path syntax, for example:

.. figure:: /Input/QB_Toulouse.png

.. figure:: /Output/qb_BandMath-pretty.jpg
    :scale: 50%

    Thresholded NDVI of a Quickbird image computed with a BandMathFilter
How to run an example

From your OTB build directory, use the script:

$ ~/otb/Documentation/Cookbook/Scripts/RunExamples.py ~/otb --name BandMathFilterExample

This will run the given example in the working directory ~/otb/Data.

How to review an example

Before you begin: Have a working OTB build of develop with the CookBook and examples activated:

cmake -DBUILD_COOKBOOK=ON -DBUILD_EXAMPLES=ON .
make
firefox Documentation/Cookbook/html/index.html &

Note: currently it is advised that you delete Documentation/CookBook/ manually from your build directory between each rebuild of the cookbook.

Pick an example to review from the list below, then:

  1. Check that there is an "example usage", if not add it and check it with RunExamples.py
  2. Make a description .rst file from:
    • the content of the C++ comments (usually the first big block of text)
    • latex content from the old software guide where the example appears
    • the included figures
  3. Review C++ comments, make sure they don't contain embedded latex
  4. Review C++ code, make sure it's clean and modern C++14
  5. Run the example, add output images that are necessary to the build to the MR (don't add other output, e.g. .tif, .shp)
  6. Re-build the cookbook and check the output

When you are done, make a MR and list the example you reviewed. Edit the list with your progress.

You can also propose some examples for merge, deletion or refactoring.

List of examples

BasicFilters
  • BasicFilters/BandMathFilterExample.cxx
  • BasicFilters/BandMathXImageFilterExample.cxx
  • BasicFilters/DEMToRainbowExample.cxx
  • BasicFilters/FrostImageFilter.cxx
  • BasicFilters/HillShadingExample.cxx
  • BasicFilters/IndexedToRGBExample.cxx
  • BasicFilters/LeeImageFilter.cxx
  • BasicFilters/MeanShiftSegmentationFilterExample.cxx
  • BasicFilters/PrintableImageFilterExample.cxx
  • BasicFilters/ScalingFilterExample.cxx
ChangeDetection
  • ChangeDetection/CorrelChDet.cxx
  • ChangeDetection/DiffChDet.cxx
  • ChangeDetection/KullbackLeiblerDistanceChDet.cxx
  • ChangeDetection/KullbackLeiblerProfileChDet.cxx
  • ChangeDetection/MultivariateAlterationDetector.cxx
  • ChangeDetection/RatioChDet.cxx
Classification
  • Classification/ClassificationMapRegularizationExample.cxx (doesn't run, no usage)
  • Classification/DempsterShaferFusionOfClassificationMapsExample.cxx (doesn't run, no usage)
  • Classification/SOMImageClassificationExample.cxx (doesn't run, no usage)
  • Classification/SupervisedImageClassificationExample.cxx (doesn't run, no usage)
DimensionReduction

(all can't run because of missing file: Input/wv2_cannes_8bands.tif)

  • DimensionReduction/ICAExample.cxx
  • DimensionReduction/MaximumAutocorrelationFactor.cxx
  • DimensionReduction/MNFExample.cxx
  • DimensionReduction/NAPCAExample.cxx
  • DimensionReduction/PCAExample.cxx
DisparityMap
  • DisparityMap/FineRegistrationImageFilterExample.cxx
  • DisparityMap/NCCRegistrationFilterExample.cxx
  • DisparityMap/StereoReconstructionExample.cxx
FeatureExtraction
  • FeatureExtraction/AsymmetricFusionOfLineDetectorExample.cxx
  • FeatureExtraction/CloudDetectionExample.cxx
  • FeatureExtraction/ComplexMomentPathExample.cxx
  • FeatureExtraction/ComplexMomentsImageFunctionExample.cxx
  • FeatureExtraction/CorrelationLineDetectorExample.cxx
  • FeatureExtraction/EdgeDensityExample.cxx
  • FeatureExtraction/ExtractRoadByStepsExample.cxx
  • FeatureExtraction/ExtractRoadExample.cxx
  • FeatureExtraction/FlusserMomentsImageFunctionExample.cxx
  • FeatureExtraction/HarrisExample.cxx
  • FeatureExtraction/HuMomentsImageFunctionExample.cxx
  • FeatureExtraction/LineSegmentDetectorExample.cxx
  • FeatureExtraction/PanTexExample.cxx
  • FeatureExtraction/ParallelLineDetectionExample.cxx
  • FeatureExtraction/RatioLineDetectorExample.cxx
  • FeatureExtraction/RightAngleDetectionExample.cxx
  • FeatureExtraction/SeamCarvingExample.cxx
  • FeatureExtraction/SeamCarvingOtherExample.cxx
  • FeatureExtraction/SFSExample.cxx
  • FeatureExtraction/SURFExample.cxx
  • FeatureExtraction/TextureExample.cxx
  • FeatureExtraction/ThresholdToPointSetExample.cxx
  • FeatureExtraction/TouziEdgeDetectorExample.cxx
Filtering
  • Filtering/CompositeFilterExample.cxx
  • Filtering/DanielssonDistanceMapImageFilter.cxx
  • Filtering/SecondDerivativeRecursiveGaussianImageFilter.cxx
Fusion
  • Fusion/BayesianFusionImageFilter.cxx
  • Fusion/PanSharpeningExample.cxx
Hyperspectral
  • Hyperspectral/HyperspectralUnmixingExample.cxx
Image
  • Image/Image1.cxx
  • Image/Image2.cxx
  • Image/Image3.cxx
  • Image/Image4.cxx
  • Image/Image5.cxx
  • Image/ImageListExample.cxx
  • Image/VectorImage.cxx
Installation
  • Installation/HelloWorld.cxx
IO
  • IO/ComplexImageReadWrite.cxx
  • IO/DEMHandlerExample.cxx
  • IO/DEMToImageGenerator.cxx
  • IO/ExtractROI.cxx
  • IO/ImageReadCastWrite.cxx
  • IO/ImageReadRegionOfInterestWrite.cxx
  • IO/ImageReadWrite.cxx
  • IO/ImageSeriesIOExample.cxx
  • IO/MetadataExample.cxx
  • IO/MultibandImageReadWrite.cxx
  • IO/VectorDataIOExample.cxx
Iterators
  • Iterators/ImageLinearIteratorWithIndex2.cxx
  • Iterators/ImageLinearIteratorWithIndex.cxx
  • Iterators/ImageRandomConstIteratorWithIndex.cxx
  • Iterators/ImageRegionIterator.cxx
  • Iterators/ImageRegionIteratorWithIndex.cxx
  • Iterators/ImageSliceIteratorWithIndex.cxx
  • Iterators/IteratorsExamples.cxx
  • Iterators/NeighborhoodIterators1.cxx
  • Iterators/NeighborhoodIterators2.cxx
  • Iterators/NeighborhoodIterators3.cxx
  • Iterators/NeighborhoodIterators4.cxx
  • Iterators/NeighborhoodIterators5.cxx
  • Iterators/NeighborhoodIterators6.cxx
  • Iterators/ShapedNeighborhoodIterators1.cxx
  • Iterators/ShapedNeighborhoodIterators2.cxx
Learning
  • Learning/GenerateTrainingImageExample.cxx
  • Learning/SEMModelEstimatorExample.cxx
  • Learning/SOMClassifierExample.cxx
  • Learning/SOMExample.cxx
  • Learning/SVMImageEstimatorClassificationMultiExample.cxx
  • Learning/TrainMachineLearningModelFromImagesExample.cxx
  • Learning/TrainMachineLearningModelFromSamplesExample.cxx
Markov
  • Markov/MarkovClassification1Example.cxx
  • Markov/MarkovClassification2Example.cxx
  • Markov/MarkovClassification3Example.cxx
  • Markov/MarkovRegularizationExample.cxx
  • Markov/MarkovRestorationExample.cxx
OBIA
  • OBIA/HooverMetricsEstimation.cxx
  • OBIA/LabelMapToVectorData.cxx
  • OBIA/RadiometricAttributesLabelMapFilterExample.cxx
Patented
  • Patented/SIFTDensityExample.cxx
  • Patented/SIFTDisparityMapEstimation.cxx
  • Patented/SIFTExample.cxx
  • Patented/SIFTFastExample.cxx
Projections
  • Projections/EstimateRPCSensorModelExample.cxx
  • Projections/GeometriesProjectionExample.cxx
  • Projections/OrthoRectificationExample.cxx
  • Projections/PlaceNameToLonLatExample.cxx
  • Projections/VectorDataExtractROIExample.cxx
  • Projections/VectorDataProjectionExample.cxx
Radiometry
  • Radiometry/ARVIMultiChannelRAndBAndNIRVegetationIndexImageFilter.cxx (doesn't run, missing data)
  • Radiometry/AtmosphericCorrectionSequencement.cxx
  • Radiometry/AVIMultiChannelRAndGAndNIRVegetationIndexImageFilter.cxx
  • Radiometry/NDVIRAndNIRVegetationIndexImageFilter.cxx
Simulation
  • Simulation/LAIAndPROSAILToSensorResponse.cxx
  • Simulation/LAIFromNDVIImageTransform.cxx
  • Simulation/ProsailModel.cxx
Tutorials
  • Tutorials/FilteringPipeline.cxx
  • Tutorials/HelloWorldOTB.cxx
  • Tutorials/Multispectral.cxx
  • Tutorials/OrthoFusion.cxx
  • Tutorials/Pipeline.cxx
  • Tutorials/ScalingPipeline.cxx
Edited by Victor Poughon