====== RP → Segmenter ======

Image segmentation covers techniques for splitting one image into its components as homogeneous regions.

Input:
  * One [[wiki:designimplementation:raster|Raster]]
  * A vector of band indices used to perform segmentation.
{{:wiki:designimplementation:rp:cbers_segmentation_input.png?200|}}

Output:
  * One [[wiki:designimplementation:raster|Raster]] with a single band, where the pixel value stands for the index of the region to which it belongs. It can be transformed to a vector of [[wiki:designimplementation:geom#polygon|Polygons]] using the method //te::gdal::Vectorize//.
{{:wiki:designimplementation:rp:cbers_segmentation_geosom.png?200|}}

The available method in TerraLib is:
  * [[#Region Growing]]
  * [[#Based on Baatz and Shape, 2000]]

The following methods will be implemented in TerraLib:
  * [[#Based on Self Organizing Maps]]

Dependencies: [[wiki:designimplementation:raster|Raster]], [[wiki:designimplementation:geom|Geometry]]

===== Region Growing =====

Creates regions by merging similar neighboring pixels. To reduce processing time, the raster is divided into pieces, and such pieces are segmented individually.

Algorithm parameters:
  * //m_minSegmentSize//: size of the smallest segment to be created
  * //m_segmentsSimilarityThreshold//: similarity between neighboring segments to merge them or not

References:
  * [[http://www.dpi.inpe.br/~tkorting/docs/korting2011divide.pdf|Thales Sehn Korting, Emiliano Ferreira Castejon, Leila Fonseca. Divide and Segment - An alternative for parallel segmentation. GEOINFO. Campos do Jordão, Brazil. 2011.]]
  * [[http://marte.dpi.inpe.br/col/sid.inpe.br/deise/1999/02.05.09.30/doc/T205.pdf|Leonardo Bins, Leila Fonseca, Guaraci Erthal, Fernando Ii. Satellite imagery segmentation: A region growing approach. SBSR. 1996.]]

==== Example of use ====

To make a segmentation using Region Growing algorithm, the following parameters are necessary:
<code c++>
// ... (set input data)
 
// link specific parameters with chosen implementation
te::rp::SegmenterRegionGrowingStrategy::Parameters segparameters;
segparameters.m_minSegmentSize = 50;
segparameters.m_segmentsSimilarityThreshold = 30;

algoInputParameters.m_strategyName = "regiongrowing";
algoInputParameters.setSegStrategyParams(segparameters);
 
// ... (set output data and start algorithm)
</code>

===== Based on Baatz and Shape, 2000 =====

Creates regions by merging similar neighboring pixels. The resultant regions must fit a predefined scale and compactness, provided by the user.

Algorithm parameters:
  * //Compactness Weight//: Related to how close to a rectangle will be the output regions.
  * //Color Weight//: The influence of spectral properties to compute if pixels are similar.
  * //Scale Parameter//: Related to the size of the output regions.

References:
  * [[http://www.ecognition.cc/download/baatz_schaepe.pdf|Baatz, M.; Schäpe, A. Multiresolution segmentation: an optimization approach for high quality multi-scale image segmentation. In: XII Angewandte Geographische Informationsverarbeitung, Wichmann Verlag, Heidelberg, 2000.]]

==== Example of use ====

To make a segmentation using Baatz and Shape algorithm, the following parameters are necessary:
<code c++>
// ... (set input data)
 
// link specific parameters with chosen implementation
te::rp::SegmenterRegionGrowingStrategy::Parameters segparameters;
segparameters.m_compactness = 0.5;
segparameters.m_color = 0.3;
segparameters.m_scale = 60;

algoInputParameters.m_strategyName = "baatz";
algoInputParameters.setSegStrategyParams(segparameters);
 
// ... (set output data and start algorithm)
</code>

**<color red>Code under development!!!</color>**

===== Based on Self Organizing Maps =====

This algorithm performs pixel-based classification using a geographic approach of the Self-Organizing Maps algorithm. Then neighboring pixels of the same class define the regions.

References:
  * [[http://www.dpi.inpe.br/~tkorting/docs/korting2011geographical.pdf|Thales Sehn Korting, Leila Fonseca, Gilberto Camara. A Geographical Approach to Self-Organizing Maps Algorithm Applied to Image Segmentation. Advances Concepts for Intelligent Vision Systems. 2011.]]

==== Example of use ====

To make a segmentation using Self Organizing Maps algorithm, the following parameters are necessary:
<code c++>
// ... (set input data)
 
// link specific parameters with chosen implementation
te::rp::SegmenterRegionGrowingStrategy::Parameters segparameters;
segparameters.m_mapHeight = 3;
segparameters.m_mapWidth = 4;
segparameters.m_radius = 20;
segparameters.m_alpha = 50;
segparameters.m_K = 30;

algoInputParameters.m_strategyName = "som";
algoInputParameters.setSegStrategyParams(segparameters);
 
// ... (set output data and start algorithm)
</code>

**<color red>Code under development!!!</color>**

===== From theory to practice =====

The following code shows how to perform a segmentation using Region Growing method.

<code c++>
// open input raster
std::map<std::string, std::string> rinfo;
rinfo["URI"] = "input.tif";
te::rst::Raster* rin = te::rst::RasterFactory::open(rinfo);

// define segmentation parameters

// input parameters
te::rp::Segmenter::InputParameters algoInputParameters;
algoInputParameters.m_inputRasterPtr = rin;
algoInputParameters.m_inputRasterBands.push_back(0);
algoInputParameters.m_inputRasterBands.push_back(1);
algoInputParameters.m_inputRasterBands.push_back(2);

// link specific parameters with chosen implementation
te::rp::SegmenterRegionGrowingStrategy::Parameters segparameters;
segparameters.m_minSegmentSize = 50;
segparameters.m_segmentsSimilarityThreshold = 30;

algoInputParameters.m_strategyName = "regiongrowing";
algoInputParameters.setSegStrategyParams(segparameters);

// output parameters
te::rp::Segmenter::OutputParameters algoOutputParameters;
std::map<std::string, std::string> orinfo;
orinfo["URI"] = "output-segmentation.tif";
algoOutputParameters.m_rInfo = orinfo;
algoOutputParameters.m_rType = "GDAL";

// execute the algorithm
te::rp::Segmenter seginstance;
bool initok = seginstance.initialize(algoInputParameters);
if(initok)
  seginstance.execute(algoOutputParameters);

// clean up
delete rin;
</code>