Request for Changes-97: KMeansClassification reimplemented

From OTBWiki
Jump to: navigation, search

[Request for Changes - 97] KMeansClassification reimplemented

Status

Summary

Reimplement using Shark KMeans composite application.

Rationale

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

Applications

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 => 
ImageClassifier.
Parameter
Parameters: 
        -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 = kmeansclassification.nc

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.

Tests

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

Documentation

Updated documentation in KMeansClassification application.

Additional notes

Suggestions

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