Unsupervised KMeans image classification


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:

  1. ImageEnvelope: create a shapefile (1 polygon),
  2. PolygonClassStatistics: compute the statistics,
  3. SampleSelection: select the samples by constant strategy in the shapefile (1000000 samples max),
  4. SampleExtraction: extract the samples descriptors (update of SampleSelection output file),
  5. ComputeImagesStatistics: compute images second order statistics,
  6. TrainVectorClassifier: train the SharkKMeans model,
  7. 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].

This application has several output images and supports “multi-writing”. Instead of computing and writing each image independently, the streamed image blocks are written in a synchronous way for each output. The output images will be computed strip by strip, using the available RAM to compute the strip size, and a user defined streaming mode can be specified using the streaming extended filenames (type, mode and value). Note that multi-writing can be disabled using the multi-write extended filename option: &multiwrite=false, in this case the output images will be written one by one. Note that multi-writing is not supported for MPI writers.


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 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.


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)



The application does not support NaN in the input image