KMeansClassification¶

Unsupervised KMeans image classification

Description¶

Unsupervised KMeans image classification. This is a composite application, using existing training and classification applications. The SharkKMeans model is used.

This application is only available if OTB is compiled with Shark support(CMake option OTB_USE_SHARK=ON).

The steps of this composite application:

ImageEnvelope: create a shapefile (1 polygon),
PolygonClassStatistics: compute the statistics,
SampleSelection: select the samples by constant strategy in the shapefile (1000000 samples max),
SampleExtraction: extract the samples descriptors (update of SampleSelection output file),
ComputeImagesStatistics: compute images second order statistics,
TrainVectorClassifier: train the SharkKMeans model,
ImageClassifier: perform the classification of the input image according to a model file.

It is possible to choose random/periodic modes of the SampleSelection application. If you do not want to keep the temporary files (sample selected, model file, …), initialize cleanup parameter. For more information on shark KMeans algorithm [1].

Parameters¶

Input Image -in image Mandatory
Input image filename.

Output Image -out image [dtype] Mandatory
Output image containing class labels

Number of classes -nc int Default value: 5
Number of modes, which will be used to generate class membership.

Training set size -ts int Default value: 100
Size of the training set (in pixels).

Maximum number of iterations -maxit int Default value: 1000
Maximum number of iterations for the learning step. If this parameter is set to 0, the KMeans algorithm will not stop until convergence

Centroids IO parameters ¶

Group of parameters for centroids IO.

input centroids text file -centroids.in filename [dtype]
Input text file containing centroid positions used to initialize the algorithm. Each centroid must be described by p parameters, p being the number of bands in the input image, and the number of centroids must be equal to the number of classes (one centroid per line with values separated by spaces).

Output centroids text file -centroids.out filename [dtype]
Output text file containing centroids after the kmean algorithm.

Available RAM (MB) -ram int Default value: 256
Available memory for processing (in MB).

Sampler type -sampler [periodic|random] Default value: periodic
Type of sampling (periodic, pattern based, random)

Periodic sampler
Takes samples regularly spaced
Random sampler
The positions to select are randomly shuffled.

Periodic sampler options ¶

Jitter amplitude -sampler.periodic.jitter int Default value: 0
Jitter amplitude added during sample selection (0 = no jitter)

Validity Mask -vm image
Validity mask, only non-zero pixels will be used to estimate KMeans modes.

Label mask value -nodatalabel int Default value: 0
By default, hidden pixels will have the assigned label 0 in the output image. It’s possible to define the label mask by another value, but be careful to not take a label from another class. This application initializes the labels from 0 to N-1, N is the number of class (defined by ‘nc’ parameter).

Clean-up of temporary files -cleanup bool Default value: true
If activated, the application will try to clean all temporary files it created

Random seed -rand int
Set a specific random seed with integer value.

Examples¶

From the command-line:

otbcli_KMeansClassification -in QB_1_ortho.tif -ts 1000 -nc 5 -maxit 1000 -out ClassificationFilterOutput.tif uint8

From Python:

import otbApplication

app = otbApplication.Registry.CreateApplication("KMeansClassification")

app.SetParameterString("in", "QB_1_ortho.tif")
app.SetParameterInt("ts", 1000)
app.SetParameterInt("nc", 5)
app.SetParameterInt("maxit", 1000)
app.SetParameterString("out", "ClassificationFilterOutput.tif")
app.SetParameterOutputImagePixelType("out", 1)

app.ExecuteAndWriteOutput()

Limitations¶

The application does not support NaN in the input image