[GRASS-SVN] r65478 - grass-addons/grass7/raster/r.seg

svn_grass at osgeo.org svn_grass at osgeo.org
Tue Jun 16 02:31:31 PDT 2015 

Author: avitti
Date: 2015-06-16 02:31:31 -0700 (Tue, 16 Jun 2015)
New Revision: 65478

Added:
   grass-addons/grass7/raster/r.seg/r.smooth.seg.html
Log:
Service commit before module rename [from r.seg to r.smooth.seg]

Added: grass-addons/grass7/raster/r.seg/r.smooth.seg.html
===================================================================
--- grass-addons/grass7/raster/r.seg/r.smooth.seg.html	                        (rev 0)
+++ grass-addons/grass7/raster/r.seg/r.smooth.seg.html	2015-06-16 09:31:31 UTC (rev 65478)
@@ -0,0 +1,168 @@
+<h2>DESCRIPTION</h2>
+
+<em><b>r.smooth.seg</b></em> generates a piece-wise smooth approximation of the
+input raster map and a raster map of the discontinuities of the output
+approximation. <br>
+
+The discontinuities of the output approximation are preserved from being
+smoothed. The values of the discontinuity map are close to one where the
+output approximation is "homogeneous", where the output approximation
+has discontinuities (edges) the values are close to zero. <br>
+
+The module makes use of the <em>varseg</em> library which implements
+the Mumford-Shah [1] variational model for image segmentation. The
+Mumford-Shah variational model with curvature term [2] is also implemented
+in the library. The curvature term prevents the discontinuities from being
+shortened too much when the parameter alpha is set to very high values,
+(this happens very rarely). <br>
+
+An overview of the underlying theory with some applications cab be found in 
+<a href="http://dx.doi.org/10.1016/j.isprsjprs.2012.02.005">[3]</a>.<br>
+Other examples of use of the module can be found 
+<a href="http://www.ing.unitn.it/~vittia/sw/sw_index.html">here</a> 
+and in 
+<a href="http://download.osgeo.org/osgeo/foss4g/2009/SPREP/2Thu/Parkside%20GO4/1500/Thu%20G04%201545%20Zatelli.pdf"
+>this presentation [FOSS4G 2009 - pdf]</a>. <br>
+For details on the numerical implementation see [4].
+
+<h2>NOTES</h2>
+Remove any MASK before the execution of the module.
+<br><br>
+
+Replace any NULL data (using <em>r.null</em>) with the map average value (get it with <em>r.univar</em>).
+<br><br>
+
+The segmentation depends on the parameters alpha and lambda:
+<ul>
+<li> alpha controls how many discontinuities are allowed to exist.
+<li> lambda controls the smoothness of the solution.
+<li> It is not possible to select the values of the parameters in an
+     automatic way. Test some different values to understand their 
+     influence on the results.<br>
+     Try the following procedure:
+<ul>
+  <li> run the module with both alpha and lambda set to 1.0
+  <li> run the module with alpha set to 1.0 and different values for lambda<br> 
+       e.g., 0.01, 0.1, 1, 10, 100
+  <li> run the module with lambda set to 1.0 and different values for alpha<br> 
+       e.g., 0.01, 0.1, 1, 10, 100
+  <li> see how the segmentations change and select the values that
+       produce the result that best fits your requirements.
+</ul>
+</ul>
+
+The module computes the segmentation by means of an iterative
+procedure.<br>
+The module stops either when the number of iterations reaches the maximum 
+number of iterations [mxi] or when the maximum difference between the solutions 
+of two successive iterations is less than the convergence tolerance [tol].<br>
+To stop the iteration procedure, it is easier to act on the maximum number of 
+iterations parameter [mxi] than on the convergence tolerance parameter [tol].<br>
+The number of iterations needed to reach the convergence tolerance increases 
+for high values of the parameter lambda. The larger the total number of pixels
+of the input raster map the larger the number of iterations will be.<br>
+<br>
+
+The data type of the output raster maps is DOUBLE PRECISION.  <br><br>
+
+The module works on one raster map at a time, imagery groups are not
+supported.  <br><br>
+
+To avoid to inappropriately re-sampled the input raster map, the settings
+for the current region should be set so that:
+<ul>
+<li> the resolution of the region matches the resolution of the input raster map;
+<li> the boundaries of the region are lined up along the edges of the nearest 
+     cells in the input raster map.
+</ul>
+
+The discontinuity thickness should be changed for test purposes only.<br>
+<br>
+
+The actual need to use the MSK model should be very rare, see [4].
+Due to a different implementation of the MSK model with respect to MS
+one, the values of the parameters lambda and alpha in MSK have to be
+set independently from the values used in MS.
+
+<h2>EXAMPLE</h2>
+
+This example is based the <a
+href="http://grass.OSGeo.org/download/data.php">North Carolina GRASS sample
+data set</a>, [complete GRASS location].
+
+
+<div><pre class="code">
+# set the region to match the <em>ortho_2001_t792_1m</em> raster map:
+g.region rast=ortho_2001_t792_1m
+
+# select a smaller region:
+g.region n=221725 s=220225 w=638350 e=639550
+
+# run r.smooth.seg:
+r.smooth.seg in_g=ortho_2001_t792_1m at PERMANENT out_u=u_OF out_z=z_OF lambda=10 alpha=200 mxi=250
+
+# for a better visualization of the output raster map <em>u_OF</em>, set its color table to:
+r.colors u_OF rast=ortho_2001_t792_1m
+
+# compute the difference between the input raster map and the output raster map <em>u_OF</em>:
+r.mapcalc "diff = abs(ortho_2001_t792_1m at PERMANENT - u_OF)"
+
+# for a better visualization of the differences, compute the natural logarithm of the <em>diff</em> map:
+r.mapcalc "log_diff = log(1 + diff)"
+
+# and set its color table to the "differences" style:
+r.colors log_diff color=differences
+
+# for a better visualization of the output raster map <em>u_OF</em>, set its color table to:
+r.colors z_OF color=bgyr
+
+# run r.smooth.seg with different parameter values:
+r.smooth.seg in_g=ortho_2001_t792_1m at PERMANENT out_u=u1_OF out_z=z1_OF lambda=10 alpha=65 mxi=250
+r.smooth.seg in_g=ortho_2001_t792_1m at PERMANENT out_u=u2_OF out_z=z2_OF lambda=10 alpha=600 mxi=250
+r.smooth.seg in_g=ortho_2001_t792_1m at PERMANENT out_u=u3_OF out_z=z3_OF lambda=0.1 alpha=200 mxi=250
+r.smooth.seg in_g=ortho_2001_t792_1m at PERMANENT out_u=u4_OF out_z=z4_OF lambda=1 alpha=200 mxi=250
+
+# visualize and compare the different results
+</pre></div>
+
+<h2>REFERENCES</h2>
+
+<ul> 
+<li> <b>[1]</b> D. Mumford and J. Shah. <em>Optimal Approximation by
+Piecewise Smooth Functions and Associated Variational Problems</em>. <br>
+Communications on Pure Applied Mathematics, 42(5):577-685, 1989.<br>
+DOI: 10.1002/cpa.3160420503
+
+<li> <b>[2]</b> R. March and M. Dozio. <em>A variational method for the
+recovery of smooth boundaries</em>. <br> Image and Vision Computing,
+15(9):705-712, 1997.<br>
+DOI: 10.1016/S0262-8856(97)00002-4
+
+<li> <b>[3]</b> A. Vitti. <em>The Mumford-Shah variational model 
+for image segmentation: An overview of the theory, implementation and use</em>. <br>
+ISPRS Journal of Photogrammetry and Remote Sensing, 69:50-64, 2012.<br>
+DOI: 10.1016/j.isprsjprs.2012.02.005
+
+<li> <b>[4]</b> A. Vitti. <em>Free discontinuity
+problems in image and signal segmentatiion</em>. <br>
+Ph.D. Thesis - University of Trento (Italy), 2008. <br> <a
+href="http://www.ing.unitn.it/~vittia/misc/vitti_phd.pdf">http://www.ing.unitn.it/~vittia/misc/vitti_phd.pdf</a>
+</ul>
+
+
+<h2>SEE ALSO</h2>
+
+<em><a href="r.clump.html">r.clump</a></em>,
+<em><a href="i.smap.html">i.smap</a></em>,
+<em><a href="i.zc.html">i.zc</a></em>,
+<em><a href="r.mfilter.html">r.mfilter</a></em>
+
+
+<h2>AUTHOR</h2>
+
+Alfonso Vitti <br> 
+  Dept. Civil, Environmental and Mechanical Engineering <br> 
+  University of Trento - Italy<br>
+  alfonso.vitti [at] unitn.it
+
+<p><i>Last changed: $Date: 2015-06-16 12:00:00 +0200 (Tue, 16 Jun 2015)$</i>

More information about the grass-commit mailing list