Skip to content

r.object.thickness

Evaluates minimum, maximum and mean thickness of objects of a given category on a raster map.

r.object.thickness input=name category=integer tsize=float tspace=float resolutiondir=string [rmedian=name] [vmedian=name] [vcategories=name] [transects=name] [itransects=name] [csvfilename=name] [metric=string] [transect_perpendicular=string] [iterations=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.object.thickness input=name category=0 tsize=100 tspace=2 resolutiondir=N-S

grass.script.run_command("r.object.thickness", input, category, tsize=100, tspace=2, resolutiondir="N-S", rmedian=None, vmedian=None, vcategories=None, transects=None, itransects=None, csvfilename=None, metric="straight", transect_perpendicular="trend", iterations=200, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.object.thickness", input="name", category=0, tsize=100, tspace=2, resolutiondir="N-S")

grass.tools.Tools.r_object_thickness(input, category, tsize=100, tspace=2, resolutiondir="N-S", rmedian=None, vmedian=None, vcategories=None, transects=None, itransects=None, csvfilename=None, metric="straight", transect_perpendicular="trend", iterations=200, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_object_thickness(input="name", category=0, tsize=100, tspace=2, resolutiondir="N-S")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

input=name [required]
    Name of input raster map
category=integer [required]
    Category to evaluate
tsize=float [required]
    Expected maximum size in map units
    Default: 100
tspace=float [required]
    Transect spacing in map units
    Default: 2
resolutiondir=string [required]
    Resolution for output in pixels
    Allowed values: N-S, E-W
    Default: N-S
rmedian=name
    Raster map of median lines
vmedian=name
    Vector map of median lines
vcategories=name
    Vector map of areas
transects=name
    Vector map of complete transects
itransects=name
    Vector map of inner transects
csvfilename=name
    CSV output file
metric=string
    Determines how transect spacing is measured
    Allowed values: straight, along
    Default: straight
    straight: Straight distance between transect points
    along: Distance along the line (see v.transect for details)
transect_perpendicular=string
    Determines which line is the transect perpendicular to
    Allowed values: trend, line
    Default: trend
    trend: Perpendicular to the line connecting transect points. line
iterations=integer
    Maximum number of iterations (used during thinning)
    Default: 200
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Name of input raster map
    Used as: input, raster, name
category : int, required
    Category to evaluate
tsize : float, required
    Expected maximum size in map units
    Default: 100
tspace : float, required
    Transect spacing in map units
    Default: 2
resolutiondir : str, required
    Resolution for output in pixels
    Allowed values: N-S, E-W
    Default: N-S
rmedian : str, optional
    Raster map of median lines
    Used as: output, raster, name
vmedian : str, optional
    Vector map of median lines
    Used as: output, vector, name
vcategories : str, optional
    Vector map of areas
    Used as: output, vector, name
transects : str, optional
    Vector map of complete transects
    Used as: output, vector, name
itransects : str, optional
    Vector map of inner transects
    Used as: output, vector, name
csvfilename : str, optional
    CSV output file
    Used as: output, file, name
metric : str, optional
    Determines how transect spacing is measured
    Allowed values: straight, along
    straight: Straight distance between transect points
    along: Distance along the line (see v.transect for details)
    Default: straight
transect_perpendicular : str, optional
    Determines which line is the transect perpendicular to
    Allowed values: trend, line
    trend: Perpendicular to the line connecting transect points. line
    Default: trend
iterations : int, optional
    Maximum number of iterations (used during thinning)
    Default: 200
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose: bool, optional
    Verbose module output
    Default: None
quiet: bool, optional
    Quiet module output
    Default: None
superquiet: bool, optional
    Very quiet module output
    Default: None

input : str, required
    Name of input raster map
    Used as: input, raster, name
category : int, required
    Category to evaluate
tsize : float, required
    Expected maximum size in map units
    Default: 100
tspace : float, required
    Transect spacing in map units
    Default: 2
resolutiondir : str, required
    Resolution for output in pixels
    Allowed values: N-S, E-W
    Default: N-S
rmedian : str, optional
    Raster map of median lines
    Used as: output, raster, name
vmedian : str, optional
    Vector map of median lines
    Used as: output, vector, name
vcategories : str, optional
    Vector map of areas
    Used as: output, vector, name
transects : str, optional
    Vector map of complete transects
    Used as: output, vector, name
itransects : str, optional
    Vector map of inner transects
    Used as: output, vector, name
csvfilename : str, optional
    CSV output file
    Used as: output, file, name
metric : str, optional
    Determines how transect spacing is measured
    Allowed values: straight, along
    straight: Straight distance between transect points
    along: Distance along the line (see v.transect for details)
    Default: straight
transect_perpendicular : str, optional
    Determines which line is the transect perpendicular to
    Allowed values: trend, line
    trend: Perpendicular to the line connecting transect points. line
    Default: trend
iterations : int, optional
    Maximum number of iterations (used during thinning)
    Default: 200
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose: bool, optional
    Verbose module output
    Default: None
quiet: bool, optional
    Quiet module output
    Default: None
superquiet: bool, optional
    Very quiet module output
    Default: None

DESCRIPTION

r.object.thickness evaluates the minimum, maximum, and mean thickness of objects of a given category on a raster map.

The thickness is reported both in map units and pixels. The module is primarily used to estimate the neighborhood window size for filters, such as those used by r.neighbors and r.fill.category.

Another use case is to estimate the width of small landscape elements (SLE), e.g., to complement statistics computed by r.object.geometry

Object thickness is evaluated by creating transects along the median lines of the raster objects, clipping them with objects themselves, and evaluating their lengths. This is done using the v.transects addon, which must therefore be installed to run this module.

Optionally, r.object.thickness can save a CSV file containing the complete list of the lengths of the parts of all created transects inside the objects. It is possible to save a vector map containing the transects, a vector map containing the clipped transects and maps containing the median lines of the objects, in both raster and vector format. The attribute table of the latter contains the average, minimum, and maximum widths of the transects within the objects.

PARAMETERS

The user must indicate the category of the objects whose thickness should be evaluated, as well as the expected maximum length of the transects and their spacing.

The expected maximum length of the transects is used to create the transects before clipping them with the raster objects. It must therefore be large enough to contain the longer cross section of the biggest object. The module issues a warning if the maximum evaluated thickness is less than or equal to the expected maximum: in that case, at least one transect has not been clipped because it does not intersect the object boundary. Therefore, the expected maximum size parameter must be raised.

Transect spacing controls the distance between transects along the median line. It must be chosen so that at least one transect is created on each median line. Smaller values can provide slightly more accurate results but require more processing time. As a rule of thumb, a good starting point is setting transects spacing around 1/50 of the expected maximum size, but the minimum value can change. If the transects spacing value is too low, no transect is created and no thickness can be evaluated: in that case, the module issues an error and stops.

It is possible to choose the direction (N-S or E-W) of the region resolution used to convert the estimated lengths in pixels. The choice is irrelevant for regions with square cells.

By default, the transect spacing is measured as straight distances between the transects (default) or along the line. This is set by the metric parameter. In addition, the parameter transect_perpendicular determines whether the transects are generated perpendicular to either the input line or to the line connecting the transect points. See the manual page of v.transects for more details.

Optional maps containing the median lines of the objects, in both raster and vector format, the vector map containing the transects, and the vector map containing the clipped transects are created only if a name is provided for them. In the same way, a CSV file containing the complete list of the lengths of the parts of all created transects inside the objects is also created only if a file name is given.

EXAMPLE

In this example, the width of the water bodies in the landuse map in the North Carolina sample dataset is evaluated:

# set the region on the landuse map
g.region rast=landuse@PERMANENT
# evaluate the thickness of water bodies (category 6) in the landuse map
# create a vector map containing the median lines called median
# create a vector map containing the transects inside the water bodies
# called transects_in
r.object.thickness input=landuse@PERMANENT category=6 tsize=4000 tspace=100 \
vmedian=median itransects=transects_in

outputs

Thickness in map units: 
min = 1.525433 
max = 2962.446155 
mean = 301.059197

Thickness in pixels: 
min = 0.053524
max = 103.945479
mean = 10.563481

SEE ALSO

r.neighbors, r.reclass.area, v.transects

AUTHOR

  • Paolo Zatelli, DICAM, University of Trento, Italy (original version)
  • Paulo van Breugel, HAS green academy, Netherlands (add stats to generated vector layers).

SOURCE CODE

Available at: r.object.thickness source code (history)
Latest change: Friday Jun 06 23:38:55 2025 in commit 1ff8dde