Request for Changes-97: KMeansClassification reimplemented

From OTBWiki
Jump to: navigation, search

[Request for Changes - 97] KMeansClassification reimplemented



Reimplement using Shark KMeans composite application.


Implement KMeansClassification as a composite application using an existing training and classification application.

The SharkKMeans model is used instead of ITK classes.

Implementation details

Classes and files

M       Modules/Applications/AppClassification/include/otbTrainVectorBase.txx
M       Modules/Learning/Sampling/include/otbImageSampleExtractorFilter.txx


M       Modules/Applications/AppClassification/app/otbImageClassifier.cxx
M       Modules/Applications/AppClassification/app/otbKMeansClassification.cxx
M       Modules/Applications/AppClassification/app/otbTrainVectorClassifier.cxx

Add the nodatalabel parameter in ImageClassifier application.

Add verbose parameter, display the contingency table result, in TrainVectorClassifier application.

The applications pipeline for this composite application is :

ImageEnveloppe => PolygonClassStatistics => SampleSelection => SamplesExtraction => ComputeImagesStatistics  => TrainVectorClassifier => 
        -progress                <boolean>        Report progress 
        -help                    <string list>    Display long help (empty list), or help for given parameters keys
MISSING -in                      <string>         Input Image  (mandatory)
MISSING -out                     <string> [pixel] Output Image  [pixel=uint8/uint16/int16/uint32/int32/float/double] (default value is uint8) (mandatory)
        -nc                      <int32>          Number of classes  (mandatory, default value is 5)
        -ts                      <int32>          Training set size  (optional, on by default, default value is 100)
        -maxit                   <int32>          Maximum number of iterations  (optional, on by default, default value is 1000)
        -outmeans                <string>         Centroid filename  (optional, off by default)
        -ram                     <int32>          Available RAM (Mb)  (optional, off by default, default value is 128)
        -sampler                 <string>         Sampler type [periodic/random] (mandatory, default value is periodic)
        -sampler.periodic.jitter <int32>          Jitter amplitude  (optional, on by default, default value is 0)
        -vm                      <string>         Validity Mask  (optional, off by default)
        -nodatalabel             <int32>          Label mask value  (optional, on by default, default value is 0)
        -cleanup                 <boolean>        Temporary files cleaning  (optional, on by default)
        -rand                    <int32>          set user defined seed  (optional, off by default)
        -inxml                   <string>         Load otb application from xml file  (optional, off by default)

Use this application for:

  • ImageEnveloppe: create an image envelope
  • PolygonClassStatistics : create the statistics
  • SampleSelection : select the samples by constant strategy in the shapefile
  • SamplesExtraction : extract the samples descriptors
  • ComputeImagesStatistics : compute images second order statistics
  • TrainVectorClassifier : train the model with Shark KMeans
  • ImageClassifier: performs the classification of the input image according to a model file

Adding of "cleanup" parameter in KMeansClassification (remove temporary files), but it should to add more to define another internal applications (SampleSelection, ...).

The parameters of the internal applications have been initialized such as:

  • SampleSelection : constant strategy
  • ImageClassifier : sharkkm.maxiter = kmeansclassification.maxit
  • ImageClassifier : sharkkm.k =

The rest of the settings are by default.

The nodatalabel parameter has been added to ImageClassifier to be able to define the label of the hidden pixels (by default 0, the same behavior).

Currently, the centroids are normalized, see the imstat parameter of the ImageClassifier application. So the outmeans parameter return the centroids normalized.


Updated KMeansClassification test:

M       Modules/Applications/AppClassification/test/CMakeLists.txt

Add mutli-baseline and binary mask:

A       Baseline/OTB-Applications/Images/apTvClKMeansImageClassificationFilterOutput.tif
A       Baseline/OTB-Applications/Images/apTvClKMeansImageClassificationFilterOutput.1.tif
A       Input/qb_RoadExtract_mask_binary.png
A       Input/qb_RoadExtract_mask_binary.png.aux.xml


Updated documentation in KMeansClassification application.

Additional notes


A composite application of the first part could be created, such as:

RandomSamples = ImageEnveloppe + PolygonClassStatistics + SampleSelection

Which can be used by users or in other future composite application.

For KMeansClassification, it will be necessary to do:

KMeans = RandomSamples + SamplesExtraction + ComputeImagesStatistics + TrainVectorClassifier + ImageClassifier

There are duplications or strong similarities of functions between ClassKMeansBase and TrainImagesBase:

  • KMeansFileNamesHandler :: RemoveFile () = TrainFileNamesHandler :: RemoveFile ()
  • SelectAndExtractSamples (): we could make it generic
  • ComputePolygonStatistics (): we could make it generic