GRASS logo

Note: This document is for an older version of GRASS GIS that will be discontinued soon. You should upgrade, and read the current manual page.

NAME

r.smooth.seg - Generates a piece-wise smooth approximation of the input raster and a discontinuity map.

KEYWORDS

raster, segmentation, imagery, edge detection, smoothing

SYNOPSIS

r.smooth.seg
r.smooth.seg --help
r.smooth.seg [-k] in_g=name[,name,...] out_u=name out_z=name [lambda=float] [alpha=float] [mxi=integer] [tol=float] [kepsilon=float] [beta=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-k
Activate MSK model (Mumford-Shah with curvature term)
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

in_g=name[,name,...] [required]
Input raster map to segment
out_u=name [required]
Output segmented raster map
out_z=name [required]
Output raster map with detected discontinuities
lambda=float
Smoothness coefficient [>0]
Default: 1.0
alpha=float
Discontinuity coefficient [>0]
Default: 1.0
mxi=integer
Maximal number of numerical iterations
Default: 100
tol=float
Convergence tolerance [>0]
Default: 0.001
kepsilon=float
Discontinuity thickness [>0]
Default: 1.0
beta=float
Curvature coefficient [>=0]
Default: 0.0

Table of contents

DESCRIPTION

r.smooth.seg generates a piece-wise smooth approximation of the input raster map and a raster map of the discontinuities of the output approximation.
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.
The module makes use of the varseg 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).
An overview of the underlying theory with some applications can be found in [3].
Other examples of use of the module can be found here and in this presentation [FOSS4G 2009 - pdf].
For details on the numerical implementation see [4].

NOTES

Remove any MASK before the execution of the module.

Replace any NULL data (using r.null) with the map average value (calculate it with r.univar).

The segmentation depends on the parameters alpha and lambda: The module computes the segmentation by means of an iterative procedure.
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].
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].
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.

The data type of the output raster maps is DOUBLE PRECISION.

The module works on one raster map at a time, imagery groups are not supported.

To avoid to inappropriately re-sampled the input raster map, the settings for the current region should be set so that: The discontinuity thickness should be changed for test purposes only.

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.

EXAMPLE

This example is based on the North Carolina GRASS sample data set: 
# set the region to match the ortho_2001_t792_1m raster map:
g.region raster=ortho_2001_t792_1m -p

# select a smaller region:
g.region n=221725 s=220225 w=638350 e=639550 -p

# run r.smooth.seg:
r.smooth.seg in_g=ortho_2001_t792_1m out_u=u_OF out_z=z_OF lambda=10 alpha=200 mxi=250

# for a better visualization of the output raster map u_OF, set its color table to:
r.colors u_OF raster=ortho_2001_t792_1m

# compute the difference between the input raster map and the output raster map u_OF:
r.mapcalc "diff = abs(ortho_2001_t792_1m@PERMANENT - u_OF)"

# for a better visualization of the differences, compute the natural logarithm of the diff 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 u_OF, 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 out_u=u1_OF out_z=z1_OF lambda=10 alpha=65 mxi=250
r.smooth.seg in_g=ortho_2001_t792_1m out_u=u2_OF out_z=z2_OF lambda=10 alpha=600 mxi=250
r.smooth.seg in_g=ortho_2001_t792_1m out_u=u3_OF out_z=z3_OF lambda=0.1 alpha=200 mxi=250
r.smooth.seg in_g=ortho_2001_t792_1m out_u=u4_OF out_z=z4_OF lambda=1 alpha=200 mxi=250

# visualize and compare the different results

REFERENCES

SEE ALSO

i.smap, i.zc, r.clump, r.mfilter

AUTHOR

Alfonso Vitti
  Dept. Civil, Environmental and Mechanical Engineering
  University of Trento - Italy
  alfonso.vitti [at] unitn.it

SOURCE CODE

Available at: r.smooth.seg source code (history)

Latest change: Monday Jan 30 19:52:26 2023 in commit: cac8d9d848299297977d1315b7e90cc3f7698730

Note: This document is for an older version of GRASS GIS that will be discontinued soon. You should upgrade, and read the current manual page.

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2023 GRASS Development Team, GRASS GIS 8.2.2dev Reference Manual