Skip to content

r.carve

Generates stream channels.

Takes vector stream data, transforms it to raster and subtracts depth from the output DEM.

r.carve [-n] raster=name vector=name output=name [points=name] [width=float] [depth=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.carve raster=name vector=name output=name

grass.script.run_command("r.carve", raster, vector, output, points=None, width=None, depth=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.carve", raster="name", vector="name", output="name")

Parameters

raster=name [required]
    Name of input raster elevation map
vector=name [required]
    Name of input vector map containing stream(s)
    Or data source for direct OGR access
output=name [required]
    Name for output raster map
points=name
    Name for output vector map for adjusted stream points
width=float
    Stream width (in meters)
    Default is raster cell width
depth=float
    Additional stream depth (in meters)
-n
    No flat areas allowed in flow direction
--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

raster : str, required
    Name of input raster elevation map
    Used as: input, raster, name
vector : str, required
    Name of input vector map containing stream(s)
    Or data source for direct OGR access
    Used as: input, vector, name
output : str, required
    Name for output raster map
    Used as: output, raster, name
points : str, optional
    Name for output vector map for adjusted stream points
    Used as: output, vector, name
width : float, optional
    Stream width (in meters)
    Default is raster cell width
depth : float, optional
    Additional stream depth (in meters)
flags : str, optional
    Allowed values: n
    n
        No flat areas allowed in flow direction
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.carve accepts vector stream data as input, transforms them to raster, and subtracts a default-depth + additional-depth from a DEM. If the given width is more than 1 cell, it will carve the stream with the given width. With the -n flag it should eliminate all flat cells within the stream, so when and if the water gets into the stream it will flow. The points option generates x,y,z for points which define the stream with the z-value of the bottom of the carved-in stream. These points can then be combined with contours to interpolate a new DEM with better representation of valleys.

NOTES

r.carve does not create a depressionless DEM because many depressions are in flat areas and not in the streams.

EXAMPLE

North Carolina sample dataset:

# set computational region
g.region raster=elev_lid792_1m -p

# digitize a ditch for the farm pond
echo "L  3 1
 638692.93595422 220198.90026383
 638737.42270627 220149.74706926
 638984.43306379 220148.19158842
 1     1" | v.in.ascii -n input=- output=ditch format=standard

# visualize original data
d.mon wx0
d.rast elev_lid792_1m
d.vect ditch

# carve
r.carve raster=elev_lid792_1m vector=ditch output=carved_dem width=3 depth=0.5

# visualize resulting carved DEM map
d.rast carved_dem

# visualize
r.relief input=elev_lid792_1m output=elev_lid792_1m_shaded
r.relief input=carved_dem output=carved_dem_shaded
d.rast elev_lid792_1m_shaded
d.erase
d.rast carved_dem_shaded

# flow accumulation
r.watershed elevation=elev_lid792_1m accumulation=elev_lid792_1m_accum
r.watershed elevation=carved_dem accumulation=carved_dem_accum
d.rast elev_lid792_1m_accum
d.erase
d.rast carved_dem_accum

# differences
r.mapcalc "accum_diff = elev_lid792_1m_accum - carved_dem_accum"
r.colors accum_diff color=differences
d.erase
d.rast accum_diff

Original DEM with vector streams
Fig: Original 1m LiDAR based DEM with vector streams map on top

Original DEM shaded
Fig: Original 1m LiDAR based DEM shown as shaded terrain

Carved DEM
Fig: Carved 1m LiDAR based DEM

Carved DEM shaded
Fig: Carved 1m LiDAR based DEM shown as shaded terrain

Flow accumulation in original DEM
Fig: Flow accumulation in original 1m LiDAR based DEM

Flow accumulation in carved DEM
Fig: Flow accumulation in carved 1m LiDAR based DEM

KNOWN ISSUES

The module does not operate yet in latitude-longitude coordinate reference system.

REFERENCES

Terrain modeling and Soil Erosion Simulations for Fort Hood and Fort Polk test areas, by Helena Mitasova, Lubos Mitas, William M. Brown, Douglas M. Johnston, GMSL (Report for CERL 1999)

SEE ALSO

r.flow, r.fill.dir, r.watershed

AUTHORS

Bill Brown (GMSL)
GRASS 6 update: Brad Douglas

SOURCE CODE

Available at: r.carve source code (history)
Latest change: Thursday Feb 13 11:55:34 2025 in commit ffc0b8c