Commit ec651ec0 authored by Victor Poughon's avatar Victor Poughon
Browse files

REFAC: rewrite of otbGenerateWrappersRstDoc.py & doc improvements

parent 33f5066a
......@@ -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"
......@@ -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}
......
.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;
}
......@@ -24,7 +24,7 @@ Windows
.. include:: Installation_Windows.rst
Linux
------------
-----
.. include:: Installation_Linux.rst
......
......@@ -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
......
{heading}
{description}
Description
-----------
{longdescription}
Parameters
----------
.. contents:: :local:
.. |br| raw:: html
<br />
.. |em| raw:: html
&emsp;
{parameters}
Examples
--------
From the command-line:
.. code-block:: bash
{examples_cli}
From Python:
.. code-block:: python
{examples_python}
{limitations}
{see_also}
**{name}** :code:`-{key} {value}` {flags}|br|
{description}
**{name}** :code:`-{key} {value}` {flags}|br|
{description}
{choices}
......@@ -136,7 +136,7 @@ private:
SetParameterDescription("method.dempstershafer","Fusion of classification maps by the Dempster Shafer combination method for each output pixel.");
AddParameter(ParameterType_InputFilenameList, "method.dempstershafer.cmfl", "Confusion Matrices");
SetParameterDescription("method.dempstershafer.cmfl", "A list of confusion matrix files (*.CSV format) to define the masses of belief and the class labels. Each file should be formatted the following way: "
SetParameterDescription("method.dempstershafer.cmfl", "A list of confusion matrix files (.csv format) to define the masses of belief and the class labels. Each file should be formatted the following way: "
"the first line, beginning with a '#' symbol, should be a list of the class labels present in the corresponding input classification image, organized in the same order as the confusion matrix rows/columns.");
AddParameter(ParameterType_Choice, "method.dempstershafer.mob", "Mass of belief measurement");
......
......@@ -116,17 +116,16 @@ private:
SetDefaultOutputPixelType( "out", ImagePixelType_uint8);
AddParameter(ParameterType_OutputImage, "confmap", "Confidence map");
SetParameterDescription( "confmap", "Confidence map of the produced classification. The confidence index depends on the model : \n"
" - LibSVM : difference between the two highest probabilities (needs a model with probability estimates, so that classes probabilities can be computed for each sample)\n"
" - OpenCV\n"
" * Boost : sum of votes\n"
" * DecisionTree : (not supported)\n"
" * GradientBoostedTree : (not supported)\n"
" * KNearestNeighbors : number of neighbors with the same label\n"
" * NeuralNetwork : difference between the two highest responses\n"
" * NormalBayes : (not supported)\n"
" * RandomForest : Confidence (proportion of votes for the majority class). Margin (normalized difference of the votes of the 2 majority classes) is not available for now.\n"
" * SVM : distance to margin (only works for 2-class models)\n");
SetParameterDescription( "confmap", "Confidence map of the produced classification. The confidence index depends on the model: \n\n"
"* LibSVM: difference between the two highest probabilities (needs a model with probability estimates, so that classes probabilities can be computed for each sample)\n"
"* Boost: sum of votes\n"
"* DecisionTree: (not supported)\n"
"* GradientBoostedTree: (not supported)\n"
"* KNearestNeighbors: number of neighbors with the same label\n"
"* NeuralNetwork: difference between the two highest responses\n"
"* NormalBayes: (not supported)\n"
"* RandomForest: Confidence (proportion of votes for the majority class). Margin (normalized difference of the votes of the 2 majority classes) is not available for now.\n"
"* SVM: distance to margin (only works for 2-class models)\n");
SetDefaultOutputPixelType( "confmap", ImagePixelType_double);
MandatoryOff("confmap");
......
......@@ -43,18 +43,27 @@ public:
// Documentation
SetDocName( "Train a classifier from multiple images" );
SetDocLongDescription(
"This application performs a classifier training from multiple pairs of input images and training vector data. "
"Samples are composed of pixel values in each band optionally centered and reduced using an XML statistics file produced by "
"the ComputeImagesStatistics application.\n The training vector data must contain polygons with a positive integer field "
"representing the class label. The name of this field can be set using the \"Class label field\" parameter. Training and validation "
"sample lists are built such that each class is equally represented in both lists. One parameter allows controlling the ratio "
"between the number of samples in training and validation sets. Two parameters allow managing the size of the training and "
"validation sets per class and per image.\n Several classifier parameters can be set depending on the chosen classifier. In the "
"validation process, the confusion matrix is organized the following way: rows = reference labels, columns = produced labels. "
"In the header of the optional confusion matrix output file, the validation (reference) and predicted (produced) class labels"
" are ordered according to the rows/columns of the confusion matrix.\n This application is based on LibSVM, OpenCV Machine Learning "
"(2.3.1 and later), and Shark ML. The output of this application is a text model file, whose format corresponds to the "
"ML model type chosen. There is no image nor vector data output." );
"Train a classifier from multiple pairs of images and training vector data. "
"Samples are composed of pixel values in each band optionally centered and reduced using an XML statistics file produced by "
"the ComputeImagesStatistics application.\n\n"
"The training vector data must contain polygons with a positive integer field "
"representing the class label. The name of this field can be set using the *Class label field* parameter.\n\n"
"Training and validation sample lists are built such that each class is equally represented in both lists. One parameter allows controlling the ratio "
"between the number of samples in training and validation sets. Two parameters allow managing the size of the training and "
"validation sets per class and per image.\n\n"
"In the validation process, the confusion matrix is organized the following way:\n\n"
"* Rows: reference labels,\n"
"* Columns: produced labels.\n\n"
"In the header of the optional confusion matrix output file, the validation (reference) and predicted (produced) class labels"
" are ordered according to the rows/columns of the confusion matrix.\n\n"
"This application is based on LibSVM, OpenCV Machine Learning, and Shark ML. "
"The output of this application is a text model file, whose format corresponds to the "
"ML model type chosen. There is no image nor vector data output.");
SetDocLimitations( "None" );
SetDocAuthors( "OTB-Team" );
SetDocSeeAlso( "OpenCV documentation for machine learning http://docs.opencv.org/modules/ml/doc/ml.html " );
......
......@@ -67,7 +67,7 @@ protected:
"Learning (2.3.1 and later), and Shark ML The output of this application "
"is a text model file, whose format corresponds to the ML model type "
"chosen. There is no image nor vector data output.");
SetDocLimitations( " " );
SetDocLimitations("");
SetDocAuthors( "OTB Team" );
SetDocSeeAlso( " " );
......
......@@ -131,20 +131,16 @@ private:
"Put the same field names as the TrainVectorClassifier application.");
AddParameter(ParameterType_Bool, "confmap", "Confidence map");
SetParameterDescription( "confmap", "Confidence map of the produced classification. "
"The confidence index depends on the model : \n"
" - LibSVM : difference between the two highest probabilities "
"(needs a model with probability estimates, so that classes probabilities can be computed for each sample)\n"
" - OpenCV\n"
" * Boost : sum of votes\n"
" * DecisionTree : (not supported)\n"
" * GradientBoostedTree : (not supported)\n"
" * KNearestNeighbors : number of neighbors with the same label\n"
" * NeuralNetwork : difference between the two highest responses\n"
" * NormalBayes : (not supported)\n"
" * RandomForest : Confidence (proportion of votes for the majority class). "
"Margin (normalized difference of the votes of the 2 majority classes) is not available for now.\n"
" * SVM : distance to margin (only works for 2-class models).\n");
SetParameterDescription( "confmap", "Confidence map of the produced classification. The confidence index depends on the model: \n\n"
"* LibSVM: difference between the two highest probabilities (needs a model with probability estimates, so that classes probabilities can be computed for each sample)\n"
"* Boost: sum of votes\n"
"* DecisionTree: (not supported)\n"
"* GradientBoostedTree: (not supported)\n"
"* KNearestNeighbors: number of neighbors with the same label\n"
"* NeuralNetwork: difference between the two highest responses\n"
"* NormalBayes: (not supported)\n"
"* RandomForest: Confidence (proportion of votes for the majority class). Margin (normalized difference of the votes of the 2 majority classes) is not available for now.\n"
"* SVM: distance to margin (only works for 2-class models)\n");
AddParameter(ParameterType_OutputFilename, "out", "Output vector data file containing class labels");
SetParameterDescription("out","Output vector data file storing sample values (OGR format)."
......
......@@ -34,8 +34,7 @@ namespace Wrapper
::InitBoostParams()
{
AddChoice("classifier.boost", "Boost classifier");
SetParameterDescription("classifier.boost", "This group of parameters allows setting Boost classifier parameters. "
"See complete documentation here \\url{http://docs.opencv.org/modules/ml/doc/boosting.html}.");
SetParameterDescription("classifier.boost", "http://docs.opencv.org/modules/ml/doc/boosting.html");
//BoostType
AddParameter(ParameterType_Choice, "classifier.boost.t", "Boost Type");
AddChoice("classifier.boost.t.discrete", "Discrete AdaBoost");
......
......@@ -35,8 +35,7 @@ LearningApplicationBase<TInputValue,TOutputValue>
{
AddChoice("classifier.dt", "Decision Tree classifier");
SetParameterDescription("classifier.dt",
"This group of parameters allows setting Decision Tree classifier parameters. "
"See complete documentation here \\url{http://docs.opencv.org/modules/ml/doc/decision_trees.html}.");
"http://docs.opencv.org/modules/ml/doc/decision_trees.html");
//MaxDepth
AddParameter(ParameterType_Int, "classifier.dt.max", "Maximum depth of the tree");
#ifdef OTB_OPENCV_3
......
......@@ -38,8 +38,7 @@ LearningApplicationBase<TInputValue,TOutputValue>
AddChoice("classifier.gbt", "Gradient Boosted Tree classifier");
SetParameterDescription(
"classifier.gbt",
"This group of parameters allows setting Gradient Boosted Tree classifier parameters. "
"See complete documentation here \\url{http://docs.opencv.org/modules/ml/doc/gradient_boosted_trees.html}.");
"http://docs.opencv.org/modules/ml/doc/gradient_boosted_trees.html");
if (m_RegressionFlag)
{
......
......@@ -34,8 +34,7 @@ namespace Wrapper
::InitKNNParams()
{
AddChoice("classifier.knn", "KNN classifier");
SetParameterDescription("classifier.knn", "This group of parameters allows setting KNN classifier parameters. "
"See complete documentation here \\url{http://docs.opencv.org/modules/ml/doc/k_nearest_neighbors.html}.");
SetParameterDescription("classifier.knn", "http://docs.opencv.org/modules/ml/doc/k_nearest_neighbors.html");
//K parameter
AddParameter(ParameterType_Int, "classifier.knn.k", "Number of Neighbors");
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment