r.carve(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💧 r.carve — bestie edition 💧

ok so you found yourself a page from the GRASS GIS User's Manual and the command is r.carve(1). Buckle up, we're carving streams today and it's gonna be gorgeous. 🎀

✨ NAME ✨

r.carve — it generates stream channels, periodt.

What it actually does: takes your vector stream data, transforms it to raster, and then subtracts depth from the output DEM. Like, it digs the stream into the terrain. Iconic behaviour honestly. 💅

🏷️ KEYWORDS 🏷️

raster, hydrology

(so if you're into water stuff, this is your main character)

📜 SYNOPSIS 📜

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

🚩 Flags 🚩

  • -n — No flat areas allowed in flow direction. Bestie, this one is doing the most so your water actually flows. 🦋
  • --overwrite — Allow output files to overwrite existing files. (yes queen, replace it, no hesitation)
  • --help — Print usage summary
  • --verbose — Verbose module output
  • --quiet — Quiet module output
  • --ui — Force launching GUI dialog

🧸 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)

💖 DESCRIPTION 💖

So r.carve accepts vector stream data as input, transforms them to raster, and subtracts a default-depth + additional-depth from a DEM. Simple as that, no cap.

If the given width is more than 1 cell, it will carve the stream with the given width. Very demure, very mindful, very matching-your-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 way that water just goes? Obsessed. 🌊

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. Like, glow-up for your terrain. ✨

📝 NOTES 📝

r.carve does not create a depressionless DEM because many depressions are in flat areas and not in the streams. Not me expecting it to fix everything — it literally cannot, bestie. 💀

🌸 EXAMPLE 🌸

North Carolina sample dataset, let's gooo:

# 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

Fig: Original 1m LiDAR based DEM with vector streams map on top Fig: Original 1m LiDAR based DEM shown as shaded terrain Fig: Carved 1m LiDAR based DEM Fig: Carved 1m LiDAR based DEM shown as shaded terrain Fig: Flow accumulation in original 1m LiDAR based DEM Fig: Flow accumulation in carved 1m LiDAR based DEM

(visual proof bestie, it's giving before-and-after 🫶)

💀 KNOWN ISSUES 💀

The module does not operate yet in latitude-longitude coordinate reference system. And it has not been thoroughly tested, so not all options may work properly — but this was the intention. So like, they meant it. 🤷‍♀️

Lowkey read that twice before you trust it, fr fr.

📚 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)

Accessed: Saturday Jan 17 05:40:43 2026

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

ok that's the whole thing, no notes, you ate. This was the GRASS GIS 8.4.2 Reference Manual, accessed Saturday Jan 17 05:40:43 2026, © 2003-2025 GRASS Development Team, and it's genuinely giving r.carve(1) energy. Go carve something pretty. 💖✨🌸

📦 where this page comes from