View source for Request for Changes-29: Sampling Framework - Polygon analysis

== [Request for Changes - 29] Sampling Framework - Polygon analysis ==

=== Status === 

* Author: Guillaume Pasero
* Additional Contributors :
* Submitted on 10.03.2016
* Proposed target release : 5.4
* Adopted : +4 (Guillaume, Julien, Manuel, Jordi)
* Merged : [https://git.orfeo-toolbox.org/otb.git/commit/cc8b62663484c3d80c81366ca3410e5160321aef cc8b62663484c3d80c81366ca3410e5160321aef]

=== Summary ===

This RFC is the first part of new developments to introduce a new sampling framework for machine learning. The purpose of this RFC is to :
* add a filter to analyse the geometries that contain training regions
* compute the number of samples per class, and per polygon
* handle an optional mask on the support image

=== Rationale ===

This analysis is the first step to a coherent sampling strategy between several images. 

=== Implementation details ===

==== Classes and files ====

A dedicated module has been added : OTBSampling (under group Learning)
<pre>
A       Modules/Learning/Sampling/CMakeLists.txt
A       Modules/Learning/Sampling/include/otbOGRDataToClassStatisticsFilter.h
A       Modules/Learning/Sampling/include/otbOGRDataToClassStatisticsFilter.txx
A       Modules/Learning/Sampling/include/otbPolygonClassStatisticsAccumulator.h
A       Modules/Learning/Sampling/include/otbPolygonClassStatisticsAccumulator.txx
A       Modules/Learning/Sampling/otb-module.cmake
A       Modules/Learning/Sampling/src/CMakeLists.txt
A       Modules/Learning/Sampling/src/otbPolygonClassStatisticsAccumulator.cxx
</pre>

In a nutshell :
* otb::OGRDataToClassStatisticsFilter : Filter that computes number of samples per class or per geometry from an OGRDataSource. It can use an optional mask, thus the filter is persistent. The input support image is actually never read (only its extent is needed).
* otb::PolygonClassStatisticsAccumulator : small class used to do the real work on OGR geometries.
* This filter supports Polygons, Lines, Points, as well as geometry containers (multi-polygons, multi-lines, ...)

==== Applications ==== 

The associated application has been added in module OTBAppClassification
<pre>
M       Modules/Applications/AppClassification/app/CMakeLists.txt
A       Modules/Applications/AppClassification/app/otbPolygonClassStatistics.cxx
M       Modules/Applications/AppClassification/otb-module.cmake
</pre>

The statistics are exported into an XML file (like the one produced by ComputeImagesStatistics). In order to easily export/import these stats, the filter otb::StatisticsXMLFileReader and otb::StatisticsXMLFileWriter have been enhanced to support the storage of map structures :
<pre>
M       Modules/IO/IOXML/include/otbStatisticsXMLFileReader.h
M       Modules/IO/IOXML/include/otbStatisticsXMLFileReader.txx
M       Modules/IO/IOXML/include/otbStatisticsXMLFileWriter.h
M       Modules/IO/IOXML/include/otbStatisticsXMLFileWriter.txx
M       Modules/IO/IOXML/otb-module.cmake
A       Modules/IO/IOXML/test/CMakeLists.txt
A       Modules/IO/IOXML/test/otbIOXMLTestDriver.cxx
A       Modules/IO/IOXML/test/otbStatisticsXMLFileWriteAndRead.cxx
</pre>

In addition, missing tests have been added to the module IOXML, and some methods that were missing in the API have been added :
* otb::StatisticsXMLFileReader::GetStatisticsVectorNames() : return available stats
* otb::StatisticsXMLFileWriter::CleanInputs() : remove all previous inputs added with AddInput() or AddInputMap()

==== Tests ====
<pre>
A       Modules/Learning/Sampling/test/CMakeLists.txt
A       Modules/Learning/Sampling/test/otbOGRDataToClassStatisticsFilterTest.cxx
A       Modules/Learning/Sampling/test/otbSamplingTestDriver.cxx
M       Modules/Applications/AppClassification/test/CMakeLists.txt
</pre>

Tests have been added for the base filter (quite exhaustive), and the application (simple use-case).

==== Documentation ====

TODO : start a CookBook recipe

=== Additional notes ===