r.path(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💅 r.path — the GRASS User's Manual page, but make it cute

okay bestie, buckle up 🎀 this is r.path from the GRASS User's Manual and she is literally the main character of raster hydrology. let's get into it 💖

✨ NAME ✨

r.path — traces paths from starting points following input directions. yes queen, she walks the walk 🚶‍♀️👑

🏷️ KEYWORDS 🏷️

raster, hydrology, cost surface — iykyk 💅

📜 SYNOPSIS 📜

r.path
r.path --help
r.path [-ebcan] input=name format=string  [values=name]
[raster_path=name]   [vector_path=name]
[start_coordinates=east,north[,east,north,...]]
[start_points=name[,name,...]]   [--overwrite]  [--help]  [--verbose]
[--quiet]  [--ui]

🚩 Flags 🚩

  • -e — start bitmask encoded directions from East (like what r.terraflow gives you, bestie)
  • -b — do not break lines (faster for single-direction bitmask encoding) ⚡
  • -c — copy input cell values onto the output, verbatim, no notes
  • -a — accumulate input values along the path (running total energy 💫)
  • -n — count cell numbers along the path (1, 2, 3… slay)
  • --overwrite — let output files overwrite files that already exist. be careful, this one does not ask permission 💀
  • --help — print the usage summary
  • --verbose — verbose module output (she's chatty)
  • --quiet — quiet module output (she's mysterious)
  • --ui — force launching the GUI dialog 🖥️✨

🎛️ Parameters 🎛️

  • input=name [required] — name of input direction. it's either direction in degrees CCW from east, or bitmask encoded. no input, no path, periodt.
  • format=string [required] — the format of the input direction map. options are auto, degree, 45degree, bitmask. default is auto.
    • auto: auto-detect the direction format 🔍
    • degree: degrees CCW from East
    • 45degree: degrees CCW from East divided by 45 (e.g. r.watershed directions)
    • bitmask: bitmask encoded directions (e.g. r.cost -b)
  • values=name — name of input raster values to be used for output. (Name of input raster map.)
  • raster_path=name — name for output raster path map. (Name for output raster map.)
  • vector_path=name — name for output vector path map. (Name for output vector map.)
  • start_coordinates=east,north[,east,north,...] — coordinates of starting point(s) (E,N)
  • start_points=name[,name,...] — name of starting vector points map(s), or data source(s) for direct OGR access 🗺️

💖 DESCRIPTION 💖

r.path traces a path from starting points following input directions. that movement direction map? you can generate it with r.walk, r.cost, r.slope.aspect, r.watershed, or r.fill.dir — as long as the direction is in degrees, measured counterclockwise from east. 🌈

alternatively, you can hand her bitmask-encoded directions, where each bit position corresponds to a specific neighbour. a path will continue to all neighbours with their bit set. meaning: a path can split and merge. not me being a whole multiverse situation 😭 such bitmasked directions can be created with the -b flag of r.cost and r.walk.

Direction encoding for neighbors of x
  135  90  45          7 8 1
  180  x  360          6 x 2
  225 270 315          5 4 3
  degrees           bit positions
  CCW from East

a path stops when the direction is zero or negative, indicating a stop point or outlet. 🛑

the output raster map will show one or more least-cost paths between each user-provided location(s) and the target points (direction ≤ 0). by default, the output will be an integer CELL map with the id of the start points along the least cost path, and null cells elsewhere.

with the -c (copy) flag, the values raster map cell values are copied verbatim along the path. with the -a (accumulate) flag, the accumulated cell value from the starting point up to the current cell is written on output. with either the -c or the -a flags, the raster_path map is created with the same cell type as the values raster map (integer, float or double). with the -n (number) flag, the cells are numbered consecutively from the starting point to the final point. 🔢

⚠️ the -c, -a, and -n flags are mutually incompatible. pick one, bestie, she will not do all three at once 💅

the start_coordinates parameter consists of map E and N grid coordinates of a starting point. each x,y pair is the easting and northing (respectively) of a starting point from which a path will be traced following input directions. the start_points parameter can take multiple vector maps containing additional starting points. 📍📍📍

📝 NOTES 📝

the directions are recorded as degrees CCW from East, and the Knight's move of r.cost and r.walk is considered:

       112.5     67.5
157.5  135   90  45   22.5
       180   x   0
202.5  225  270  315  337.5
       247.5     292.5

i.e. a cell with the value 135 means the next cell is to the North-West, and a cell with the value 157.5 means that the next cell is to the West-North-West. lowkey poetic 🧭✨

🌊 EXAMPLES 🌊

💧 Hydrological path

we are using the full North Carolina sample dataset. first we create the two points from a text file using v.in.ascii module (here the text file is CSV and we are using unix here-file syntax with EOF, in GUI just enter the values directly for the parameter input):

v.in.ascii input=- output=start format=point separator=comma <<EOF
638667.15686275,220610.29411765
638610.78431373,220223.03921569
EOF

we need to supply a direction raster map to the r.path module. to get these directions, we use the r.watershed module:

r.watershed elevation=elev_lid792_1m accumulation=accum drainage=drain_dir

the directions are categorical and we convert them to degrees using raster algebra:

r.mapcalc "drain_deg = if(drain_dir != 0, 45. * abs(drain_dir), null())"

now we are ready to extract the drainage paths starting at the two points. 🔥

r.path input=drain_deg raster_path=drain_path vector_path=drain_path start_points=start

before we visualize the result, we set a color table for the elevation we are using and create a shaded relief map:

r.colors map=elev_lid792_1m color=elevation
r.relief input=elev_lid792_1m output=relief

we visualize the input and output data:

d.shade shade=relief color=elev_lid792_1m
d.vect map=drain_path color=0:0:61 width=4 legend_label="drainage paths"
d.vect map=start color=none fill_color=224:0:0 icon=basic/circle size=15 legend_label=origins
d.legend.vect -b

Figure: Drainage paths from two points where directions from r.watershed were used 🖼️

💸 Least-cost path

we compute bitmask encoded movement directions using r.walk:

g.region swwake_30m -p
# create friction map based on land cover
r.recode input=landclass96 output=friction rules=- << EOF
1:3:0.1:0.1
4:5:10.:10.
6:6:1000.0:1000.0
7:7:0.3:0.3
EOF
# without Knight’s move
r.walk -b elevation=elev_ned_30m friction=friction output=walkcost \
    outdir=walkdir start_coordinates=635576,216485
r.path input=walkdir start_coordinates=640206,222795 \
    raster_path=walkpath vector_path=walkpath
# with Knight’s move
r.walk -b -k elevation=elev_ned_30m friction=friction output=walkcost_k \
    outdir=walkdir_k start_coordinates=635576,216485
r.path input=walkdir_k start_coordinates=640206,222795 \
    raster_path=walkpath_k vector_path=walkpath_k
# without Knight’s move and without bitmask encoding (single direction)
r.walk elevation=elev_ned_30m friction=friction output=walkcost_s \
    outdir=walkdir_s start_coordinates=635576,216485
r.path input=walkdir_s start_coordinates=640206,222795 \
    raster_path=walkpath_s vector_path=walkpath_s

the extracted least-cost path splits and merges on the way from the start point to the stop point (start point for r.walk). note the gaps in the raster path when using the Knight's move. 🙈

Figure: Comparison of shortest paths using single directions and multiple bitmask encoded directions without and with Knight's move 🖼️

👀 SEE ALSO 👀

g.region, r.basins.fill, r.cost, r.fill.dir, r.mapcalc, r.recode, r.terraflow, r.walk, r.watershed — go read those next, bestie, they're all iconic in their own way 💜

👑 AUTHOR 👑

Markus Metz Multiple path directions sponsored by mundialis

🔗 SOURCE CODE 🔗

Available at: r.path source code (history)

Latest change: Friday Jan 02 21:25:59 2026 in commit: 83362df5af36c1e7d95fad93dff0a57b4dfde476

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

and that's the whole thing, babe 🫶 this was GRASS 8.5.0, from the GRASS User's Manual, © 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual. go trace some paths, you absolute legend ⭐🌈💅

📦 where this page comes from