# TrainImagesClassifier

## Brief Description

Train a classifier from multiple pairs of images and training vector data.

## Tags

Learning

## Long Description

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. 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 to manage the size of the training and validation sets per class and per image. 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. This application is based on LibSVM and on OpenCV Machine Learning classifiers, and is compatible with OpenCV 2.3.1 and later.

## Parameters

- [param] -io <string> This group of parameters allows setting input and output data.. Mandatory: True. Default Value: "0"
- [param] -elev <string> This group of parameters allows managing elevation values. Supported formats are SRTM, DTED or any geotiff processed by the DEM import application. Mandatory: True. Default Value: "0"
- [param] -sample <string> This group of parameters allows setting training and validation sample lists parameters.. Mandatory: True. Default Value: "0"
- [param] -rand <int32> Set specific seed. with integer value.. Mandatory: False. Default Value: "0"
[choice] -classifier Choice of the classifier to use for the training. libsvm,svm,boost,dt,gbt,ann,bayes,rf,knn. Mandatory: True. Default Value: "libsvm"

- [group] -libsvm

- [param] -classifier.libsvm.k <string> SVM Kernel Type.. Mandatory: True. Default Value: "linear"
- [param] -classifier.libsvm.c <float> SVM models have a cost parameter C (1 by default) to control the trade-off between training errors and forcing rigid margins.. Mandatory: True. Default Value: "1"
- [param] -classifier.libsvm.opt <boolean> SVM parameters optimization flag.. Mandatory: False. Default Value: "True"

- [group] -svm

- [param] -classifier.svm.m <string> Type of SVM formulation.. Mandatory: True. Default Value: "csvc"
- [param] -classifier.svm.k <string> SVM Kernel Type.. Mandatory: True. Default Value: "linear"
- [param] -classifier.svm.c <float> SVM models have a cost parameter C (1 by default) to control the trade-off between training errors and forcing rigid margins.. Mandatory: True. Default Value: "1"
- [param] -classifier.svm.nu <float> Parameter nu of a SVM optimization problem.. Mandatory: True. Default Value: "0"
- [param] -classifier.svm.coef0 <float> Parameter coef0 of a kernel function (POLY / SIGMOID).. Mandatory: True. Default Value: "0"
- [param] -classifier.svm.gamma <float> Parameter gamma of a kernel function (POLY / RBF / SIGMOID).. Mandatory: True. Default Value: "1"
- [param] -classifier.svm.degree <float> Parameter degree of a kernel function (POLY).. Mandatory: True. Default Value: "1"
- [param] -classifier.svm.opt <boolean> SVM parameters optimization flag. -If set to True, then the optimal SVM parameters will be estimated. Parameters are considered optimal by OpenCV when the cross-validation estimate of the test set error is minimal. Finally, the SVM training process is computed 10 times with these optimal parameters over subsets corresponding to 1/10th of the training samples using the k-fold cross-validation (with k = 10). -If set to False, the SVM classification process will be computed once with the currently set input SVM parameters over the training samples. -Thus, even with identical input SVM parameters and a similar random seed, the output SVM models will be different according to the method used (optimized or not) because the samples are not identically processed within OpenCV.. Mandatory: False. Default Value: "True"

- [group] -boost

- [param] -classifier.boost.t <string> Type of Boosting algorithm.. Mandatory: True. Default Value: "real"
- [param] -classifier.boost.w <int32> The number of weak classifiers.. Mandatory: True. Default Value: "100"
- [param] -classifier.boost.r <float> A threshold between 0 and 1 used to save computational time. Samples with summary weight <= (1 - weight_trim_rate) do not participate in the next iteration of training. Set this parameter to 0 to turn off this functionality.. Mandatory: True. Default Value: "0.95"
- [param] -classifier.boost.m <int32> Maximum depth of the tree.. Mandatory: True. Default Value: "1"

- [group] -dt

- [param] -classifier.dt.max <int32> The training algorithm attempts to split each node while its depth is smaller than the maximum possible depth of the tree. The actual depth may be smaller if the other termination criteria are met, and/or if the tree is pruned.. Mandatory: True. Default Value: "65535"
- [param] -classifier.dt.min <int32> If all absolute differences between an estimated value in a node and the values of the train samples in this node are smaller than this regression accuracy parameter, then the node will not be split.. Mandatory: True. Default Value: "10"
- [param] -classifier.dt.ra <float> . Mandatory: True. Default Value: "0.01"
- [param] -classifier.dt.cat <int32> Cluster possible values of a categorical variable into K <= cat clusters to find a suboptimal split.. Mandatory: True. Default Value: "10"
- [param] -classifier.dt.f <int32> If cv_folds > 1, then it prunes a tree with K-fold cross-validation where K is equal to cv_folds.. Mandatory: True. Default Value: "10"
- [param] -classifier.dt.r <boolean> If true, then a pruning will be harsher. This will make a tree more compact and more resistant to the training data noise but a bit less accurate.. Mandatory: False. Default Value: "True"
- [param] -classifier.dt.t <boolean> If true, then pruned branches are physically removed from the tree.. Mandatory: False. Default Value: "True"

- [group] -gbt

- [param] -classifier.gbt.w <int32> Number "w" of boosting algorithm iterations, with w*K being the total number of trees in the GBT model, where K is the output number of classes.. Mandatory: True. Default Value: "200"
- [param] -classifier.gbt.s <float> Regularization parameter.. Mandatory: True. Default Value: "0.01"
- [param] -classifier.gbt.p <float> Portion of the whole training set used for each algorithm iteration. The subset is generated randomly.. Mandatory: True. Default Value: "0.8"
- [param] -classifier.gbt.max <int32> The training algorithm attempts to split each node while its depth is smaller than the maximum possible depth of the tree. The actual depth may be smaller if the other termination criteria are met, and/or if the tree is pruned.. Mandatory: True. Default Value: "3"

- [group] -ann

- [param] -classifier.ann.t <string> Type of training method for the multilayer perceptron (MLP) neural network.. Mandatory: True. Default Value: "reg"
- [param] -classifier.ann.sizes <string> The number of neurons in each intermediate layer (excluding input and output layers).. Mandatory: True. Default Value: ""
- [param] -classifier.ann.f <string> Neuron activation function.. Mandatory: True. Default Value: "sig"
- [param] -classifier.ann.a <float> Alpha parameter of the activation function (used only with sigmoid and gaussian functions).. Mandatory: True. Default Value: "1"
- [param] -classifier.ann.b <float> Beta parameter of the activation function (used only with sigmoid and gaussian functions).. Mandatory: True. Default Value: "1"
- [param] -classifier.ann.bpdw <float> Strength of the weight gradient term in the BACKPROP method. The recommended value is about 0.1.. Mandatory: True. Default Value: "0.1"
- [param] -classifier.ann.bpms <float> Strength of the momentum term (the difference between weights on the 2 previous iterations). This parameter provides some inertia to smooth the random fluctuations of the weights. It can vary from 0 (the feature is disabled) to 1 and beyond. The value 0.1 or so is good enough.. Mandatory: True. Default Value: "0.1"
- [param] -classifier.ann.rdw <float> Initial value Delta_0 of update-values Delta_{ij} in RPROP method (default = 0.1).. Mandatory: True. Default Value: "0.1"
- [param] -classifier.ann.rdwm <float> Update-values lower limit Delta_{min} in RPROP method. It must be positive (default = 1e-7).. Mandatory: True. Default Value: "1e-07"
- [param] -classifier.ann.term <string> Termination criteria.. Mandatory: True. Default Value: "all"
- [param] -classifier.ann.eps <float> Epsilon value used in the Termination criteria.. Mandatory: True. Default Value: "0.01"
- [param] -classifier.ann.iter <int32> Maximum number of iterations used in the Termination criteria.. Mandatory: True. Default Value: "1000"

- [group] -bayes

- [group] -rf

- [param] -classifier.rf.max <int32> The depth of the tree. A low value will likely underfit and conversely a high value will likely overfit. The optimal value can be obtained using cross validation or other suitable methods.. Mandatory: True. Default Value: "5"
- [param] -classifier.rf.min <int32> If the number of samples in a node is smaller than this parameter, then the node will not be split. A reasonable value is a small percentage of the total data e.g. 1 percent.. Mandatory: True. Default Value: "10"
- [param] -classifier.rf.ra <float> If all absolute differences between an estimated value in a node and the values of the train samples in this node are smaller than this regression accuracy parameter, then the node will not be split.. Mandatory: True. Default Value: "0"
- [param] -classifier.rf.cat <int32> Cluster possible values of a categorical variable into K <= cat clusters to find a suboptimal split.. Mandatory: True. Default Value: "10"
- [param] -classifier.rf.var <int32> The size of the subset of features, randomly selected at each tree node, that are used to find the best split(s). If you set it to 0, then the size will be set to the square root of the total number of features.. Mandatory: True. Default Value: "0"
- [param] -classifier.rf.nbtrees <int32> The maximum number of trees in the forest. Typically, the more trees you have, the better the accuracy. However, the improvement in accuracy generally diminishes and reaches an asymptote for a certain number of trees. Also to keep in mind, increasing the number of trees increases the prediction time linearly.. Mandatory: True. Default Value: "100"
- [param] -classifier.rf.acc <float> Sufficient accuracy (OOB error).. Mandatory: True. Default Value: "0.01"

- [group] -knn

- [param] -classifier.knn.k <int32> The number of neighbors to use.. Mandatory: True. Default Value: "32"

## Limitations

None

## Authors

OTB-Team

## See Also

OpenCV documentation for machine learning http://docs.opencv.org/modules/ml/doc/ml.html

## Example of use

- io.il: QB_1_ortho.tif

- io.vd: VectorData_QB1.shp

- io.imstat: EstimateImageStatisticsQB1.xml

- sample.mv: 100

- sample.mt: 100

- sample.vtr: 0.5

- sample.edg: false

- sample.vfn: Class

- classifier: libsvm

- classifier.libsvm.k: linear

- classifier.libsvm.c: 1

- classifier.libsvm.opt: false

- io.out: svmModelQB1.txt

- io.confmatout: svmConfusionMatrixQB1.csv