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.
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 [#]_ presents a summary of these parameters and the parameters keys to be used in command-line and programming languages. Application key is *KMeansClassification* .

.. [#] 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
~~~~~~~~~~~

None

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
  | [1] http://image.diku.dk/shark/sphinx_pages/build/html/rest_sources/tutorials/algorithms/kmeans.html