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

FreeBSD Manual Pages

  
 
  

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

NAME
       r.spread	 - Simulates elliptically anisotropic spread.
       Generates  a  raster map	of the cumulative time of spread, given	raster
       maps containing the rates of spread (ROS), the ROS directions  and  the
       spread  origins.	It optionally produces raster maps to contain backlink
       UTM coordinates for tracing spread paths. Usable	for fire spread	 simu-
       lations.

KEYWORDS
       raster, fire, spread, hazard, model

SYNOPSIS
       r.spread
       r.spread	--help
       r.spread	  [-si]	 base_ros=string  max_ros=string  direction_ros=string
       start=string	 [spotting_distance=string]	   [wind_speed=string]
       [fuel_moisture=string]	  [least_size=odd  int]	   [comp_dens=decimal]
       [init_time=int (_= 0)]	[lag=int  (_=  0)]    [backdrop=string]	  out-
       put=string    [x_output=string]	   [y_output=string]	 [--overwrite]
       [--help]	 [--verbose]  [--quiet]	 [--ui]

   Flags:
       -s
	   Consider spotting effect (for wildfires)

       -i
	   Use start raster map	values in output spread	time raster map
	   Designed to be used with output of previous run  of	r.spread  when
	   computing  spread  iteratively.  The	values in start	raster map are
	   considered as time. Allowed values in raster	map are	from  zero  to
	   the value of	init_time option. If not enabled, init_time is used in
	   the area of start raster map

       --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:
       base_ros=stringA	[required]
	   Raster map containing base ROS (cm/min)
	   Name	of an existing raster map layer	in the user's  current	mapset
	   search path containing the ROS values in the	directions perpendicu-
	   lar to maximum ROSes' (cm/minute). These ROSes are  also  the  ones
	   without the effect of directional factors.

       max_ros=stringA [required]
	   Raster map containing maximal ROS (cm/min)
	   Name	 of  an	existing raster	map layer in the user's	current	mapset
	   search path containing the maximum ROS values (cm/minute).

       direction_ros=stringA [required]
	   Raster map containing directions of maximal ROS (degree)
	   Name	of an existing raster map layer	in the user's  current	mapset
	   search  path	 containing directions of the maximum ROSes, clockwise
	   from	north (degree).

       start=stringA [required]
	   Raster map containing starting sources
	   Name	of an existing raster map layer	in the user's  current	mapset
	   search path containing starting locations of	the spread phenomenon.
	   Any positive	integers  in  this  map	 are  recognized  as  starting
	   sources (seeds).

       spotting_distance=string
	   Raster  map	containing maximal spotting distance (m, required with
	   -s)
	   Name	of an existing raster map layer	in the user's  current	mapset
	   search  path	 containing  the  maximum potential spotting distances
	   (meters).

       wind_speed=string
	   Raster map containing midflame wind speed  (ft/min,	required  with
	   -s)
	   Name	 of  an	existing raster	map layer in the user's	current	mapset
	   search path containing wind velocities at half of the average flame
	   height (feet/minute).

       fuel_moisture=string
	   Raster  map	containing  fine fuel moisture of the cell receiving a
	   spotting firebrand (%, required with	-s)
	   Name	of an existing raster map layer	in the user's  current	mapset
	   search path containing the 1-hour (<.25") fuel moisture (percentage
	   content multiplied by 100).

       least_size=odd int
	   Basic sampling window size needed to	meet certain accuracy (3)
	   An odd integer ranging 3 - 15 indicating the	basic sampling	window
	   size	 within	which all cells	will be	considered to see whether they
	   will	be reached by the current spread cell. The default number is 3
	   which means a 3x3 window.
	   Options: 3, 5, 7, 9,	11, 13,	15

       comp_dens=decimal
	   Sampling density for	additional computing (range: 0.0 - 1.0 (0.5))
	   A  decimal  number ranging 0.0 - 1.0	indicating additional sampling
	   cells will be considered to see whether they	will be	reached	by the
	   current  spread  cell. The closer to	1.0 the	decimal	number is, the
	   longer the program will run and the higher the simulation  accuracy
	   will	be. The	default	number is 0.5.

       init_time=int (_= 0)
	   Initial time	for current simulation (0) (min)
	   A  non-negative  number specifying the initial time for the current
	   spread simulation (minutes).	This is	 useful	 when  multiple	 phase
	   simulation is conducted. The	default	time is	0.
	   Default: 0

       lag=int (_= 0)
	   Simulating time duration LAG	(fill the region) (min)
	   A  non-negative integer specifying the simulating duration time lag
	   (minutes). The default is infinite, but the program will  terminate
	   when	 the  current  geographic region/mask has been filled. It also
	   controls the	computational time, the	 shorter  the  time  lag,  the
	   faster the program will run.

       backdrop=string
	   Name	of raster map as a display backdrop
	   Name	 of  an	existing raster	map layer in the user's	current	mapset
	   search path to be used as the background on which the "live"	 move-
	   ment	will be	shown.

       output=stringA [required]
	   Raster map to contain output	spread time (min)
	   Name	 of the	new raster map layer to	contain	the results of the cu-
	   mulative spread time	needed for a phenomenon	 to  reach  each  cell
	   from	the starting sources (minutes).

       x_output=string
	   Name	of raster map to contain X back	coordinates
	   Name	of the new raster map layer to contain the results of backlink
	   information in UTM easting coordinates for each cell.

       y_output=string
	   Name	of raster map to contain Y back	coordinates
	   Name	of the new raster map layer to contain the results of backlink
	   information in UTM northing coordinates for each cell.

DESCRIPTION
       r.spread	 is  part  of  the  wildfire simulation	toolset. Preparational
       steps for the fire simulation are the calculation of the	rate of	spread
       (ROS)  with r.ros, and the creating of spread map with r.spread.	 Even-
       tually, the fire	path(s)	based on starting point(s) are calculated with
       r.spreadpath.

       Spread  phenomena usually show uneven movement over space. Such uneven-
       ness is due to two reasons:

       1      the uneven conditions from location to location,	which  can  be
	      called spatial heterogeneity, and

       2      the  uneven  conditions  in  different  directions, which	can be
	      called anisotropy.

       The anisotropy of spread	occurs when any	 of  the  determining  factors
       have directional	components. For	example, wind and topography cause an-
       isotropic spread	of wildfires.

       One of the simplest spatial heterogeneous and anisotropic spread	is el-
       liptical	spread,	in which, each local spread shape can be thought as an
       ellipse.	In a raster setting, cell centers are foci of the  spread  el-
       lipses,	and  the  spread  phenomenon  moves fastest toward apogees and
       slowest to perigees. The	sizes and shapes of spread ellipses  may  vary
       cell by cell.  So the overall spread shape is commonly not an ellipse.

       r.spreadsimulates  elliptically	anisotropic  spread  phenomena,	 given
       three raster map	layers about ROS (base ROS, maximum ROS	and  direction
       of  the	maximum	 ROS)  plus  a	raster	map layer showing the starting
       sources.	 These ROS layers define unique	ellipses for  all  cell	 loca-
       tions  in the current computational region as if	each cell center was a
       potential spread	origin.	 For some wildfire spread,  these  ROS	layers
       can  be generated by another GRASS raster program r.ros.	The actual lo-
       cations reached by a spread event are constrained by the	actual	spread
       origins and the elapsed spread time.

       r.spreadoptionally produces raster maps to contain backlink UTM coordi-
       nates for each raster cell of the spread	time map. The spread paths can
       be  accurately traced based on the backlink information by r.spreadpath
       module.

       Part of the spotting function in	r.spread is based on Chase (1984)  and
       Rothermel  (1983). More information on r.spread,	r.ros and r.spreadpath
       can be found in Xu (1994).

       Options spot_dist, w_speed and f_mois must  all	be  given  if  the  -s
       (spotting) flag is used.

EXAMPLE
       Assume  we  have	 inputs,  the following	simulates a spotting- involved
       wildfire	and generates three raster maps	to contain spread time,	 back-
       link information	in UTM northing	and easting coordinates:
       r.spread	-s max=my_ros.max dir=my_ros.maxdir base=my_ros.base \
	   start=fire_origin spot_dist=my_ros.spotdist w_speed=wind_speed \
	   f_mois=1hour_moisture output=my_spread \
	   x_output=my_spread.x	y_output=my_spread.y

NOTES
       1.  r.spread  is	 a  specific implementation of the shortest path algo-
       rithm. r.cost module served as the starting point for  the  development
       of  r.spread.  One of the major differences between the two programs is
       that r.cost only	simulates isotropic spread while r.spread can simulate
       elliptically  anisotropic  spread, including isotropic spread as	a spe-
       cial case.

       2. Before running r.spread, the user should prepare the ROS (base,  max
       and direction) maps using appropriate models. For some wildfire spread,
       the r.ros module	based on Rothermel's fire  equation  does  such	 work.
       The combination of the two forms	a simulation of	wildfire spread.

       3.  The	relationship of	the start map and ROS maps should be logically
       correct,	i.e. a starting	source (a positive value  in  the  start  map)
       should not be located in	a spread barrier (zero value in	the ROS	maps).
       Otherwise the program refuses to	run.

       4. r.spread uses	the current computational region settings. The	output
       map  layer  will	 not  go outside the boundaries	set in the region, and
       will not	be influenced by starting sources outside. So  any  change  of
       the  current  region may	influence the output. The recommendation is to
       use slightly larger region than needed.	Refer to g.region  to  set  an
       appropriate computational region.

       5.  The	user  should be	sure that the inputs to	r.spread are in	proper
       units.

       6. r.spread is a	computationally	intensive program. The user  may  need
       to choose appropriate size of the computational region and resolution.

       7. A low	and medium (i.e. <= 0.5) sampling density can improve accuracy
       for elliptical simulation significantly,	without	 adding	 significantly
       extra running time. Further increasing the sample density will not gain
       much accuracy while requiring greatly additional	running	time.

REFERENCES
	   o   Chase, Carolyn, H., 1984, Spotting  distance  from  wind-driven
	       surface	fires  --  extensions of equations for pocket calcula-
	       tors, US	Forest Service,	Res.  Note INT-346, Ogden, Utah.

	   o   Rothermel, R. C., 1983, How to predict the spread and intensity
	       of  forest  and range fires. US Forest Service, Gen. Tech. Rep.
	       INT-143.	 Ogden,	Utah.

	   o   Xu, Jianping, 1994, Simulating the spread of wildfires using  a
	       geographic  information	system and remote sensing, Ph. D. Dis-
	       sertation, Rutgers University, New Brunswick, New Jersey	(ref).

SEE ALSO
	r.cost,	r.mask,	r.ros, r.spreadpath Sample data	download:  firedemo.sh
       (run this script	within the "Fire simulation data set" location.

AUTHOR
       Jianping	 Xu and	Richard	G. Lathrop, Jr., Center	for Remote Sensing and
       Spatial Analysis, Rutgers University.

SOURCE CODE
       Available at: r.spread 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.3 Reference	Manual

GRASS 7.8.3							   r.spread(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | EXAMPLE | NOTES | REFERENCES | SEE ALSO | AUTHOR | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=r.spread&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help