KMeansClassification - Unsupervised KMeans image classification

Unsupervised KMeans image classification

Detailed description

Performs unsupervised KMeans image classification.KMeansClassification is a composite application, using an existing training and classification application.The SharkKMeans model is used. KMeansClassification application is only available if OTB is compiled with Shark support(CMake option OTB_USE_SHARK=ON) The steps of this composite application : 1) ImageEnveloppe : 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) SamplesExtraction : extract the samples descriptors (update of SampleSelection output file), 5) ComputeImagesStatistics : compute images second order statistics, 6) TrainVectorClassifier : train the SharkKMeans model, 7) ImageClassifier : performs the classification of the input image according to a model file.

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

Parameters

This section describes in details the parameters available for this application. Table [1] presents a summary of these parameters and the parameters keys to be used in command-line and programming languages. Application key is KMeansClassification .

[1]Table: Parameters table for Unsupervised KMeans image classification.
Parameter Key Parameter Name Parameter Type
in Input Image Input image
out Output Image Output image
nc Number of classes Int
ts Training set size Int
maxit Maximum number of iterations Int
outmeans Centroid filename Output File name
ram Available RAM (Mb) Int
sampler Sampler type Choices
sampler periodic Periodic sampler Choice
sampler random Random sampler Choice
sampler.periodic.jitter Jitter amplitude Int
vm Validity Mask Input image
nodatalabel Label mask value Int
cleanup Temporary files cleaning Boolean
rand set user defined seed Int
inxml Load otb application from xml file XML input parameters file
outxml Save otb application to xml file XML output parameters file

Input Image: Input image filename.

Output Image: Output image containing class labels.

Number of classes: Number of modes, which will be used to generate class membership.

Training set size: Size of the training set (in pixels).

Maximum number of iterations: Maximum number of iterations for the learning step.

Centroid filename: Output text file containing centroid positions.

Available RAM (Mb): Available memory for processing (in MB).

Sampler type: Type of sampling (periodic, pattern based, random). Available choices are:

  • Periodic sampler: Takes samples regularly spaced.
  • Jitter amplitude: Jitter amplitude added during sample selection (0 = no jitter).
  • Random sampler: The positions to select are randomly shuffled.

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

Label mask value: 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 initialize the labels from 0 to N-1, N is the number of class (defined by ‘nc’ parameter).

Temporary files cleaning: If activated, the application will try to clean all temporary files it created.

set user defined seed: Set specific seed. with integer value.

Load otb application from xml file: Load otb application from xml file.

Save otb application to xml file: Save otb application to xml file.

Example

To run this example in command-line, use the following:

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

To run this example from Python, use the following code snippet:

#!/usr/bin/python

# Import the otb applications package
import otbApplication

# The following line creates an instance of the KMeansClassification application
KMeansClassification = otbApplication.Registry.CreateApplication("KMeansClassification")

# The following lines set all the application parameters:
KMeansClassification.SetParameterString("in", "QB_1_ortho.tif")

KMeansClassification.SetParameterInt("ts", 1000)

KMeansClassification.SetParameterInt("nc", 5)

KMeansClassification.SetParameterInt("maxit", 1000)

KMeansClassification.SetParameterString("out", "ClassificationFilterOutput.tif")
KMeansClassification.SetParameterOutputImagePixelType("out", 1)

# The following line execute the application
KMeansClassification.ExecuteAndWriteOutput()

Limitations

The application doesn’t support NaN in the input image

Authors

This application has been written by OTB-Team.

See Also

These additional resources can be useful for further information:
ImageEnveloppe PolygonClassStatistics SampleSelection SamplesExtraction PolygonClassStatistics TrainVectorClassifier ImageClassifier