Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in
otb
otb
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 292
    • Issues 292
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
  • Merge Requests 15
    • Merge Requests 15
  • CI / CD
    • CI / CD
    • Pipelines
    • Jobs
    • Schedules
  • Operations
    • Operations
    • Incidents
    • Environments
  • Packages & Registries
    • Packages & Registries
    • Container Registry
  • Analytics
    • Analytics
    • CI / CD
    • Repository
    • Value Stream
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Members
    • Members
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • Main Repositories
  • otbotb
  • Merge Requests
  • !395

Merged
Opened Feb 20, 2019 by Victor Poughon@poughovContributor

Render examples in the CookBook

  • Overview 30
  • Commits 12
  • Pipelines 6
  • Changes 141

Summary

The next step in the Software Guide migration to the rst CookBook: render examples.

  • New CookBook section: C++
  • Render examples in the CookBook section C++/Examples
  • Rewrite two examples with the new format (see below)
    • Examples/BasicFilters/LeeImageFilter.rst
    • Examples/FeatureExtraction/TextureExample.rst
  • clang-format all examples & cleanup old tags
How to write a "new style" example
  • Put the .cxx file in Examples/tag/YourExample.cxx
  • Use normal C++14 style (no more BeginLatex/BeginCmdLineArgs/etc)
  • At the top of the .cxx file there must be a "usage" comment with the following syntax:
/* Example usage:
./TextureExample Input/ADS40RoiSmall.png Output/TextureOutput.tif Output/pretty_TextureOutput.png 2 1 1
*/
  • (Optional) Write a description in Examples/tag/YourExample.rst. You may include figures from otb-data/Input or otb-data/Output (e.g. the output of your example) with the "absolute path" syntax, for example:
.. figure:: /Output/pretty_TextureOutput.png

    Result of applying the ScalarImageToTexturesFilter to an image (contrast).
  • Run your example and add the figures needed for the description in otb-data/Output.
How to run examples

Contrary to the software guide, examples are not run when building the CookBook. They can be run manually using a new script: Documentation/Cookbook/Scripts/RunExamples.py. You can run all examples or only one. For example, in an OTB build directory do:

RunExamples.py /path/to/otb /path/to/otb-data

or:

RunExamples.py /path/to/otb /path/to/otb-data --name TextureExample
TODO in future work:
  • Update all examples from old latex format to new rst format
    • Remove \doxygen and \code macros
    • Replace \includegraphics{} directives with .. figure:: filename.png in the .rst file
    • Add needed .png figures to otb-data/Output
  • Remove examples tests
  • Remove examples tests baselines
  • Add RunExamples.py script in a new test
  • Fix missing usages
  • Improve RunExamples.py to be able to run in another working directory than otb-data
  • Modernize examples to C++14
  • Continue migrating Software Guide sections that are not examples
  • Improve license header filtering in rst render (itk copyright)
  • Handle ApplicationExample
  • Move Documentation/Cookbook/Art/ to Data/ after the LFS migration is complete

Rationale

#1679

Implementation Details

Most of the implementation is in the new scripts Documentation/Cookbook/Scripts/otbGenerateWrappersRstDoc.py and Documentation/Cookbook/Scripts/RunExamples.py.

The "usage" command is extracted from the cxx source code with this regex: \/\* Example usage:\n(\.\/[a-zA-Z]+ (.*?))\*\/.

otb-data

Changes in otb-data (otb-data!16 (merged)) are adding the examples outputs that are needed for the examples:

A       Output/GomaSmallLeeFiltered.png
A       Output/pretty_TextureOutput.png

As we improve the old examples or add new ones, figures can be added in Documentation/Cookbook/Art/ if they are static, or otb-data/Output if they are the output of an example.

Copyright

The copyright owner is CNES and has signed the ORFEO ToolBox Contributor License Agreement.


Check before merging:

  • All discussions are resolved
  • At least 2 👍 votes from core developers, no 👎 vote.
  • The feature branch is (reasonably) up-to-date with the base branch
  • Dashboard is green
  • Copyright owner has signed the ORFEO ToolBox Contributor License Agreement
Edited Mar 01, 2019 by Victor Poughon
Assignee
Assign to
Reviewer
Request review from
7.0.0
Milestone
7.0.0
Assign milestone
Time tracking
Reference: orfeotoolbox/otb!395
Source branch: cookbook_examples