i.segment manual update

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@55013 15284696-431f-4ddb-bdfa-cd5b030d7da7

imagery/i.segment/i.segment.html

@@ -0,0 +1,195 @@
+<h2>DESCRIPTION</h2>
+Image segmentation or object recognition is the process of grouping 
+similar pixels into unique segments, also refered to as objects. 
+Boundary and region based algorithms are described in the literature, 
+currently a region growing and merging algorithm is implemented. Each 
+object found during the segmentation process is given a unique ID and 
+is a collection of contiguous pixels meeting some criteria. Note the 
+contrast with image classification where all pixels similar to each 
+other are assigned to the same class and do not need to be contiguous. 
+The image segmentation results can be useful on their own, or used as a 
+preprocessing step for image classification. The segmentation 
+preprocessing step can reduce noise and speed up the classification.
+
+<H2>NOTES</h2>
+
+<h3>Region Growing and Merging</h3>
+This segmentation algorithm sequentially examines all current 
+segments in the map. The similarity between the current segment and 
+each of its neighbors is calculated according to the given distance 
+formula. Segments will be merged if they meet a number of criteria, 
+including: 1. The pair is mutually most similar to each other (the 
+similarity distance will be smaller than to any other neighbor), and 
+2. The similarity must be lower than the input threshold. The process 
+is repeated until no merges are made during a complete pass.
+
+<h3>Similarity and Threshold</h3>
+The similarity between segments and unmerged objects is used to 
+determine which objects are merged. Smaller distance values indicate a 
+closer match, with a similarity score of zero for identical pixels.
+<p>
+During normal processing, merges are only allowed when the 
+similarity between two segments is lower than the givem 
+threshold value. During the final pass, however, if a minimum 
+segment size of 2 or larger is given with the <em>minsize</em> 
+parameter, segments with a smaller pixel count will be merged with 
+their most similar neighbor even if the similarity is greater than 
+the threshold.
+<p>
+The threshold must be larger than 0.0 and smaller than 1.0. A threshold 
+of 0 would allow only identical valued pixels to be merged, while a 
+threshold of 1 would allow everything to be merged. Initial empirical 
+tests indicate threshold values of 0.01 to 0.05 are reasonable values 
+to start. It is recommended to start with a low value, e.g. 0.01, and 
+then perform hierachical segmentation by using the output of the last 
+run as seeds for the next run.
+
+<h4>Calculation Formulas</h4>
+Both Euclidean and Manhattan distances use the normal definition, 
+considering each raster in the image group as a dimension.
+
+In future , the distance calculation will also take into account the 
+shape characteristics of the segments. The normal distances are then
+multiplied by the input radiometric weight. Next an additional 
+contribution is added: (1-radioweight) * {smoothness * smoothness 
+weight + compactness * (1-smoothness weight)}, where compactness = 
+the Perimeter Length / sqrt( Area ) and smoothness = Perimeter 
+Length / the Bounding Box. The perimeter length is estimated as the 
+number of pixel sides the segment has.
+
+<h3>Seeds</h3>
+The seeds map can be used to provide either seed pixels (random or 
+selected points from which to start the segmentation process) or 
+seed segments (results of previous segmentations or 
+classifications). The different approaches are automatically 
+detected by the program: any pixels that have identical seed values 
+and are contiguous will be assigned a unique segment ID.
+<p>
+It is expected that the <em>minsize</em> will be set to 1 if a seed 
+map is used, but the program will allow other values to be used. If 
+both options are used, the final iteration that ignores the 
+threshold also will ignore the seed map and force merges for all 
+pixels (not just segments that have grown/merged from the seeds).
+
+<h3>Maximum number of starting segments</h3>
+For the region growing algorithm without starting seeds, each pixel 
+is sequentially numbered. The current limit with CELL storage is 2 
+billion starting segment IDs. If the initial map has a larger 
+number of non-null pixels, there are two workarounds:
+<p>
+1.  Use starting seed pixels. (Maximum 2 billion pixels can be 
+labeled with positive integers.)
+<p>
+2.  Use starting seed segments. (By initial classification or other 
+methods.)
+
+<h3>Boundary Constraints</h3>
+Boundary constraints limit the adjacency of pixels and segments. 
+Each unique value present in the <em>bounds</em> raster are 
+considered as a MASK. Thus no segments in the final segmentated map 
+will cross a boundary, even if their spectral data is very similar.
+
+<h3>Minimum Segment Size</h3>
+To reduce the salt and pepper affect, a <em>minsize</em> greater 
+than 1 will add one additional pass to the processing. During the 
+final pass, the threshold is ignored for any segments smaller then 
+the set size, thus forcing very small segments to merge with their 
+most similar neighbor.
+
+<h2>EXAMPLES</h2>
+This example uses the ortho photograph included in the NC Sample 
+Dataset. Set up an imagery group:<br>
+<div class="code"><pre>
+i.group group=ortho_group input=ortho_2001_t792_1m@PERMANENT
+</pre></div>
+
+<p>Set the region to a smaller test region. <br>
+
+<div class="code"><pre>
+g.region -p n=220446 s=220075 e=639151 w=638592
+</pre></div>
+
+Try out a low threshold and check the results.<br>
+<div class="code"><pre>
+i.segment group=ortho_group output=ortho_segs_l1 threshold=0.02
+</pre></div>
+<p></p>
+From a visual inspection, it seems this results in too many segments. 
+Increasing the threshold, using the previous results as seeds, 
+and setting a minimum size of 2: <br>
+<div class="code"><pre>
+i.segment group=ortho_group output=ortho_segs_l2 threshold=0.05 \
+          seeds=ortho_segs_l1 min=2
+
+i.segment group=ortho_group output=ortho_segs_l3 threshold=0.1 \
+          seeds=ortho_segs_l2
+
+i.segment group=ortho_group output=ortho_segs_l4 threshold=0.2 \
+          seeds=ortho_segs_l3
+
+i.segment group=ortho_group output=ortho_segs_l5 threshold=0.3 \
+          seeds=ortho_segs_l4
+</pre></div>
+<p>
+The output ortho_segs_l4 with threshold=0.2 looks best. There is some 
+noise in the image, lets next force all segments smaller than 5 pixels 
+to be merged into their most similar neighbor (even if they are less 
+similar then required by our threshold):<br>
+
+<p>Set the region to match the entire map(s) in the group. <br>
+<div class="code"><pre>
+g.region -p rast=ortho_2001_t792_1m@PERMANENT
+</pre></div>
+
+Run i.segment on the full map:
+
+<div class="code"><pre>
+i.segment group=ortho_group output=ortho_segs_final \
+          threshold=0.2 min=5
+</pre></div>
+<p></p>
+Processing the entire ortho image with nearly 10 million pixels took about 
+15 minutes for the first run.
+
+<h2>TODO</h2>
+<h3>Functionality</h3>
+<ul>
+<li>Further testing of the shape characteristics (smoothness, 
+compactness), if it looks good it should be added.
+<b>in progress</b></li>
+<li>Malahanobis distance for the similarity calculation.</li>
+</ul>
+<h3>Use of Segmentation Results</h3>
+<ul>
+<li>Improve the optional output from this module, or better yet, add a 
+module for <em>i.segment.metrics</em>.</li>
+<li>Providing updates to i.maxlik to ensure the segmentation output can 
+be used as input for the existing classification functionality.</li>
+<li>Integration/workflow for <em>r.fuzzy</em>.</li>
+</ul>
+<h3>Speed</h3>
+<ul>
+<li>See create_isegs.c</li>
+</ul>
+<H2>REFERENCES</h2>
+This project was first developed during GSoC 2012. Project documentation, 
+Image Segmentation references, and other information is at the 
+<a href="http://grass.osgeo.org/wiki/GRASS_GSoC_2012_Image_Segmentation">project wiki</a>.
+<p>
+Information about 
+<a href="http://grass.osgeo.org/wiki/Image_classification">classification in GRASS</a> 
+is at available on the wiki.
+</p>
+<h2>SEE ALSO</h2>
+<em>
+<a href="i.group.html">i.group</a>, 
+<a href="i.maxlik.html">i.maxlik</a>, 
+<a href="r.fuzzy">r.fuzzy</a>, 
+<a href="i.smap.html">i.smap</a>, 
+<a href="r.seg.html">r.seg</a> (Addon)
+</em>
+
+<h2>AUTHORS</h2>
+Eric Momsen - North Dakota State University<br>
+Markus Metz (GSoC Mentor)
+