Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
r.path(1)		    GRASS GIS User's Manual		     r.path(1)

       r.path  - Traces	paths from starting points following input directions.

       raster, hydrology, cost surface

       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]

	   Copy	input cell values on output

	   Accumulate input values along the path

	   Count cell numbers along the	path

	   Allow output	files to overwrite existing files

	   Print usage summary

	   Verbose module output

	   Quiet module	output

	   Force launching GUI dialog

       input=nameA [required]
	   Name	of input direction
	   Direction in	degrees	CCW from east, or bitmask encoded

       format=stringA [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-
	   bitmask: bitmask encoded directions (e.g. r.cost -b)

	   Name	of input raster	values to be used for output
	   Name	of input raster	map

	   Name	for output raster path map
	   Name	for output raster map

	   Name	for output vector path map
	   Name	for output vector map

	   Coordinates of starting point(s) (E,N)

	   Name	of starting vector points map(s)
	   Or data source(s) for direct	OGR access

       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 ax  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.

       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.

   Hydrological	path
       We are using the	full North Carolina sample dataset.  First  we	create
       the  two	points from a text file	using 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): input=- output=start format=point separator=comma <<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
       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
       # 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

	 g.region,  r.basins.fill,  r.cost,  r.fill.dir,  r.mapcalc, r.recode,
       r.terraflow, r.walk, r.watershed

       Markus Metz
       Multiple	path directions	sponsored by mundialis

       Available at: r.path source code	(history)

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

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.5 Reference	Manual

GRASS 7.8.5							     r.path(1)


Want to link to this manual page? Use this URL:

home | help