r.path(1grass) GRASS GIS User's Manual r.path(1grass)
NAME
r.path - Traces paths from starting points following input directions.
KEYWORDS
raster, hydrology, cost surface
SYNOPSIS
r.path
r.path --help
r.path [-can] input=name format=string [values=name]
[raster_path=name] [vector_path=name] [start_coordi-
nates=east,north[,east,north,...]] [start_points=name[,name,...]]
[--overwrite] [--help] [--verbose] [--quiet] [--ui]
Flags:
-c
Copy input cell values on output
-a
Accumulate input values along the path
-n
Count cell numbers along the path
--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:
input=name [required]
Name of input direction
Direction in degrees CCW from east, or bitmask encoded
format=string [required]
Format of the input direction map
Options: auto, degree, 45degree, bitmask
Default: auto
auto: auto-detect direction format
degree: degrees CCW from East
45degree: degrees CCW from East divided by 45 (e.g. r.watershed di-
rections)
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.
Such a movement direction map can be generated with r.walk, r.cost,
r.slope.aspect, r.watershed, or r.fill.dir, provided that the direction
is in degrees, measured counterclockwise from east.
Alternatively, bitmask-encoded directions can be provided where each
bit position corresponds to a specific neighbour. A path will continue
to all neighbours with their bit set. This means a path can split and
merge. 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 cre-
ated with the same cell type as the values raster map (integer, float
or double). With the -n (number) flag, the cells are numbered consecu-
tively from the starting point to the final point. The -c, -a, and -n
flags are mutually incompatible.
The start_coordinates parameter consists of map E and N grid coordi-
nates 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 multi-
ple vector maps containing additional starting points.
NOTES
The directions are recorded as degrees CCW from East, 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.
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.water-
shed 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 multi-
ple 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
AUTHORS
Markus Metz
Multiple path directions sponsored by mundialis
SOURCE CODE
Available at: r.path source code (history)
Accessed: unknown
Main index | Raster index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 r.path(1grass)
Generated by dwww version 1.14 on Thu Dec 5 15:09:43 CET 2024.