Request for Changes-96: Long help in otbcli

From OTBWiki
Jump to: navigation, search

Status

Summary

This RFC introduces display of long help for command-line applications using the -help switch.

Rationale

as raised during the brainstorming session of the 2017 users days, for now only a short description is displayed when no parameters are set or if the -help switch is used. If one wants to read the full help, it is necessary to open the provided link in a browser.

This RFC proposes to implement a different behaviour for the help switch, described as follows.

Short Help

$ ./bin/otbcli SampleSelection

Before RFC:

ERROR: Waiting for at least one parameter...
This is the SampleSelection application, version 6.1.0
Selects samples from a training vector data set.

Complete documentation: http://www.orfeo-toolbox.org/Applications/SampleSelection.html

Parameters: 
        -progress                <boolean>        Report progress 
MISSING -in                      <string>         InputImage  (mandatory)
        -mask                    <string>         InputMask  (optional, off by default)
MISSING -vec                     <string>         Input vectors  (mandatory)
MISSING -out                     <string>         Output vectors  (mandatory)
MISSING -instats                 <string>         Input Statistics  (mandatory)
        -outrates                <string>         Output rates  (optional, off by default)
        -sampler                 <string>         Sampler type [periodic/random] (mandatory, default value is periodic)
        -sampler.periodic.jitter <int32>          Jitter amplitude  (optional, on by default, default value is 0)
        -strategy                <string>         Sampling strategy [byclass/constant/percent/total/smallest/all] (mandatory, default value is smallest)
        -strategy.byclass.in     <string>         Number of samples by class  (mandatory)
        -strategy.constant.nb    <int32>          Number of samples for all classes  (mandatory)
        -strategy.percent.p      <float>          The percentage to use  (mandatory, default value is 0.5)
        -strategy.total.v        <int32>          The number of samples to generate  (mandatory, default value is 1000)
        -field                   <string>         Field Name  (mandatory, default value is )
        -layer                   <int32>          Layer Index  (optional, on by default, default value is 0)
        -elev.dem                <string>         DEM directory  (optional, off by default)
        -elev.geoid              <string>         Geoid File  (optional, off by default)
        -elev.default            <float>          Default elevation  (mandatory, default value is 0)
        -ram                     <int32>          Available RAM (Mb)  (optional, off by default, default value is 128)
        -rand                    <int32>          set user defined seed  (optional, off by default)
        -inxml                   <string>         Load otb application from xml file  (optional, off by default)

Examples: 
otbcli_SampleSelection -in support_image.tif -vec variousVectors.sqlite -field label -instats apTvClPolygonClassStatisticsOut.xml -out resampledVectors.sqlite


After RFC:

ERROR: Waiting for at least one parameter...

This is the Sample Selection (SampleSelection) application, version 6.1.0

Selects samples from a training vector data set.
Complete documentation: http://www.orfeo-toolbox.org/Applications/SampleSelection.html or -help

Parameters: 
        -progress                <boolean>        Report progress 
        -help                    <string list>    Display long help (empty list), or help for given parameters keys
MISSING -in                      <string>         InputImage  (mandatory)
        -mask                    <string>         InputMask  (optional, off by default)
MISSING -vec                     <string>         Input vectors  (mandatory)
MISSING -out                     <string>         Output vectors  (mandatory)
MISSING -instats                 <string>         Input Statistics  (mandatory)
        -outrates                <string>         Output rates  (optional, off by default)
        -sampler                 <string>         Sampler type [periodic/random] (mandatory, default value is periodic)
        -sampler.periodic.jitter <int32>          Jitter amplitude  (optional, on by default, default value is 0)
        -strategy                <string>         Sampling strategy [byclass/constant/percent/total/smallest/all] (mandatory, default value is smallest)
        -strategy.byclass.in     <string>         Number of samples by class  (mandatory)
        -strategy.constant.nb    <int32>          Number of samples for all classes  (mandatory)
        -strategy.percent.p      <float>          The percentage to use  (mandatory, default value is 0.5)
        -strategy.total.v        <int32>          The number of samples to generate  (mandatory, default value is 1000)
        -field                   <string>         Field Name  (mandatory, default value is )
        -layer                   <int32>          Layer Index  (optional, on by default, default value is 0)
        -elev.dem                <string>         DEM directory  (optional, off by default)
        -elev.geoid              <string>         Geoid File  (optional, off by default)
        -elev.default            <float>          Default elevation  (mandatory, default value is 0)
        -ram                     <int32>          Available RAM (Mb)  (optional, off by default, default value is 128)
        -rand                    <int32>          set user defined seed  (optional, off by default)
        -inxml                   <string>         Load otb application from xml file  (optional, off by default) 

Use -help param1 [... paramN] to see detailed documentation of those parameters. 

Examples: 
otbcli_SampleSelection -in support_image.tif -vec variousVectors.sqlite -field label -instats apTvClPolygonClassStatisticsOut.xml -out resampledVectors.sqlite

On can note:

  • Both app name and app doc name are displayed:
This is the Sample Selection (SampleSelection) application, version 6.1.0
  • The app advertises the -help flag:
 Complete documentation: http://www.orfeo-toolbox.org/Applications/SampleSelection.html or -help
  • The -help flag is visible in app parameters:
        -help                    <string list>    Display long help (empty list), or help for given parameters keys
  • A string explains how to get parameter help (more on that later):
Use -help param1 [... paramN] to see detailed documentation of those parameters.

Long Help

Using the -help flag now displays the long help:

$ ./bin/otbcli SampleSelection -help

This is the Sample Selection (SampleSelection) application, version 6.1.0

Selects samples from a training vector data set.
Tags: Learning 

The application selects a set of samples from geometries intended for training (they should have a field giving the associated class). 

First of all, the geometries must be analyzed by the PolygonClassStatistics application to compute statistics about the geometries, which are summarized in an xml file. 
Then, this xml file must be given as input to this application (parameter instats).

The input support image and the input training vectors shall be given in parameters 'in' and 'vec' respectively. Only the sampling grid (origin, size, spacing)will be read in the input image.
There are several strategies to select samples (parameter strategy) : 

  - smallest (default) : select the same number of sample in each class so that the smallest one is fully sampled.
  - constant : select the same number of samples N in each class (with N below or equal to the size of the smallest class).
  - byclass : set the required number for each class manually, with an input CSV file (first column is class name, second one is the required samples number).

  - percent: set a target global percentage of samples to use. Class proportions will be respected. 

  - total: set a target total number of samples to use. Class proportions will be respected. 

There is also a choice on the sampling type to performs : 

  - periodic : select samples uniformly distributed
  - random : select samples randomly distributed

Once the strategy and type are selected, the application outputs samples positions(parameter out).

The other parameters to look at are : 

  - layer : index specifying from which layer to pick geometries.
  - field : set the field name containing the class.
  - mask : an optional raster mask can be used to discard samples.
  - outrates : allows outputting a CSV file that summarizes the sampling rates for each class.

As with the PolygonClassStatistics application, different types  of geometry are supported : polygons, lines, points. 
The behavior of this application is different for each type of geometry : 

  - polygon: select points whose center is inside the polygon
  - lines  : select points intersecting the line
  - points : select closest point to the provided point


Parameters: 
        -progress                <boolean>        Report progress 
        -help                    <string list>    Display long help (empty list), or help for given parameters keys
MISSING -in                      <string>         InputImage  (mandatory)
        -mask                    <string>         InputMask  (optional, off by default)
MISSING -vec                     <string>         Input vectors  (mandatory)
MISSING -out                     <string>         Output vectors  (mandatory)
MISSING -instats                 <string>         Input Statistics  (mandatory)
        -outrates                <string>         Output rates  (optional, off by default)
        -sampler                 <string>         Sampler type [periodic/random] (mandatory, default value is periodic)
        -sampler.periodic.jitter <int32>          Jitter amplitude  (optional, on by default, default value is 0)
        -strategy                <string>         Sampling strategy [byclass/constant/percent/total/smallest/all] (mandatory, default value is smallest)
        -strategy.byclass.in     <string>         Number of samples by class  (mandatory)
        -strategy.constant.nb    <int32>          Number of samples for all classes  (mandatory)
        -strategy.percent.p      <float>          The percentage to use  (mandatory, default value is 0.5)
        -strategy.total.v        <int32>          The number of samples to generate  (mandatory, default value is 1000)
        -field                   <string>         Field Name  (mandatory, default value is )
        -layer                   <int32>          Layer Index  (optional, on by default, default value is 0)
        -elev.dem                <string>         DEM directory  (optional, off by default)
        -elev.geoid              <string>         Geoid File  (optional, off by default)
        -elev.default            <float>          Default elevation  (mandatory, default value is 0)
        -ram                     <int32>          Available RAM (Mb)  (optional, off by default, default value is 128)
        -rand                    <int32>          set user defined seed  (optional, off by default)
        -inxml                   <string>         Load otb application from xml file  (optional, off by default)

Use -help param1 [... paramN] to see detailed documentation of those parameters.

Examples: 
otbcli_SampleSelection -in support_image.tif -vec variousVectors.sqlite -field label -instats apTvClPolygonClassStatisticsOut.xml -out resampledVectors.sqlite

Authors: 
OTB-Team

Limitations: 
None

See also: 

Parameters help

Displaying description of all parameters when using the -help flag could lead to several screens of documentation. Therefore, the documentation for each parameter can be accessed by passing their name to the -help flag:

$ ./bin/otbcli SampleSelection -help instats sampler vec
MISSING -instats                 <string>         Input Statistics  (mandatory)
                                                  Input file storing statistics (XML format)

        -sampler                 <string>         Sampler type [periodic/random] (mandatory, default value is periodic)
                                                  Type of sampling (periodic, pattern based, random)

MISSING -vec                     <string>         Input vectors  (mandatory)
                                                  Input geometries to analyse

Implementation details

Classes and files

Most modifications are in otb::WrapperCommandLineLaucher class in CommandLine module:

https://git.orfeo-toolbox.org/otb.git/commitdiff/993f51dd0697e0b70e74e456c22585b0a0be3328

There is also a small patch to otbWrapperCommandLineLauncher.cxx, so as to display the -help switch:

https://git.orfeo-toolbox.org/otb.git/commitdiff/df29e62d6d551d633ab0df9a72bbfcdb4e656868

Applications

All applications will seamlessly benefit from this.

Tests

Tested on dashboard. No tests look specificaly broken by this RFC.

Documentation

Nothing to do here.

Additional notes

Formatting of long help highly depends on how strings are formatted in each application. Result might look ugly, and apps might appear insufficiently documented.