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.