r.spread(1)		      Grass User's Manual		   r.spread(1)



NNAAMMEE
       r.spread - Simulates elliptically anisotropic spread on a graphics win-
       dow and 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. (GRASS Raster/Dis-
       play Program)

SSYYNNOOPPSSIISS
       rr..sspprreeaadd

       rr..sspprreeaadd hheellpp

       rr..sspprreeaadd [-vds] mmaaxx==name ddiirr==name bbaassee==name ssttaarrtt==name [ssppoott__ddiisstt==name]
       [ww__ssppeeeedd==name]  [ff__mmooiiss==name] [lleeaasstt__ssiizzee==odds int] [ccoommpp__ddeennss==decimal]
       [iinniitt__ttiimmee==int (>=0)]  [llaagg==int	(>=  0)]  [bbaacckkddrroopp==name]  oouuttppuutt==name
       [xx__oouuttppuutt==name] [yy__oouuttppuutt==name]

DDEESSCCRRIIPPTTIIOONN
       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
       elliptical  spread, in which, each local spread shape can be thought as
       an ellipse. In a raster setting, cell centers are foci  of  the	spread
       ellipses,  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_._s_p_r_e_a_d simulates 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 geographic 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
       locations  reached  by  a  spread  event  are constrained by the actual
       spread origins and the elapsed spread time.

	_r_._s_p_r_e_a_d optionally produces raster maps to contain backlink UTM coor-
       dinates	for  each raster cell of the spread time map. The spread paths
       can be accurately traced based on the backlink information  by  another
       GRASS raster program r.spreadpath.

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



FFllaaggss::
       -v  Run verbosely, printing information about program progress to stan-
       dard output.

	-d Display the "live" simulation on screen. A graphics window must  be
       opened and selected before using this option.

	-s For wildfires, also consider spotting.



PPaarraammeetteerrss::
       mmaaxx==name  Name  of  an  existing raster map layer in the user's current
       mapset search path containing the maximum ROS values (cm/minute).

	ddiirr==name Name of an existing raster map layer in  the  user's  current
       mapset  search  path containing directions of the maximum ROSes, clock-
       wise from north (degree).

	bbaassee==name Name of an existing raster map layer in the  user's  current
       mapset  search path containing the ROS values in the directions perpen-
       dicular to maximum ROSes' (cm/minute). These ROSes are  also  the  ones
       without the effect of directional factors.

	ssttaarrtt==name  Name of an existing raster map layer in the user's current
       mapset search path containing starting locations of the spread phenome-
       non.  Any  positive  integers  in  this	map are recognized as starting
       sources.

	ssppoott__ddiisstt==name Name of an existing raster map layer in the user's cur-
       rent  mapset search path containing the maximum potential spotting dis-
       tances (meters).

	ww__ssppeeeedd==name Name of an existing raster map layer in the  user's  cur-
       rent mapset search path containing wind velocities at half of the aver-
       age flame height (feet/minute).

	ff__mmooiiss=name Name of an existing raster map layer in the user's current
       mapset  search  path  containing the 1-hour (<.25") fuel moisture (per-
       centage content multiplied by 100).

	lleeaasstt__ssiizzee==odd int 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.

	ccoommpp__ddeennss==decimal  A decimal number ranging 0.0 - 1.0 indicating addi-
       tional sampling cells will be considered to see whether	they  will  be
       reached	by the current spread cell. The closer to 1.0 the decimal num-
       ber is, the longer the program will run and the higher  the  simulation
       accuracy will be. The default number is 0.5.

	iinniitt__ttiimmee==int  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.

	llaagg==int 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 con-
       trols the computational time, the shorter the time lag, the faster  the
       program will run.

	bbaacckkddrroopp==name  Name of an existing raster map layer in the user's cur-
       rent mapset search path to be used  as  the  background	on  which  the
       "live" movement will be shown.

	oouuttppuutt==name Name of the new raster map layer to contain the results of
       the cumulative spread time needed for a phenomenon to reach  each  cell
       from the starting sources (minutes).

	xx__oouuttppuutt==name  Name of the new raster map layer to contain the results
       of backlink information in UTM easting coordinates for each cell.

	yy__oouuttppuutt=name Name of the new raster map layer to contain the  results
       of backlink information in UTM northing coordinates for each cell.



OOPPTTIIOONNSS
       The  user  can run r.spread either interactively or non- interactively.
       The program is run interactively if the	user  types  _r_._s_p_r_e_a_d  without
       specifying  flag  settings and parameter values on the command line. In
       this case, the user will be prompted for input.

	Alternately, the user can run r.spread non-interactively, by  specify-
       ing  the  names of raster map layers and desired options on the command
       line, using the form:

	r.spread    [-vds]    max=name	  dir=name    base=name     start=name
       [spot_dist=name]  [w_speed=name]  [f_mois=name]	[least_size=odds  int]
       [comp_dens=decimal]  [init_time=int  (>=0)]  [lag=int  (>=  0)]	[back-
       drop=name]  output=name	[x_output=name]  [y_output=name] The -d option
       can only be used after a graphics window is opened and selected.

	Options spot_dist=name, w_speed=name and f_mois=name must all be given
       if the -s option is used.



EEXXAAMMPPLLEE
       Assume  we  have  inputs,  the following simulates a spotting- involved
       wildfire on the graphics window and generates three raster maps to con-
       tain  spread  time,  backlink  information  in UTM northing and easting
       coordinates:

	r.spread   -ds	 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  backdrop=image_burned  output=my_spread	x_out-
       put=my_spread.x y_output=my_spread.y



NNOOTTEESS
       1.  r.spread  is  a  specific implementation of the shortest path algo-
       rithm.  r.cost GRASS program 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 special case.

	2. Before running r.spread, the user should prepare the ROS (base, max
       and direction) maps using appropriate models. For some wildfire spread,
       a separate GRASS program r.ros 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 geographic 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 geographic region.

	5. The inputs to r.spread should be in proper units.

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

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



SSEEEE AALLSSOO
       _r_._c_o_s_t, _r_._s_p_r_e_a_d_p_a_t_h, _r_._r_o_s.



RREEFFEERREENNCCEESS
       Chase,  Carolyn,  H.,  1984, Spotting distance from wind-driven surface
       fires -- extensions of equations for pocket calculators, US Forest Ser-
       vice, Res.  Note INT-346, Ogden, Utah.

	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.

	Xu,  Jianping,	1994,  Simulating the spread of wildfires using a geo-
       graphic information system and remote  sensing,	Ph.  D.  Dissertation,
       Rutgers University, New Brunswick, New Jersey.



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

NNOOTTIICCEE
       This program is part of the alpha section of  the  GRASS  distribution.
       Unlike  the  code  in the main section of GRASS, the alpha code has not
       yet been fully tested for one release cycle.

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0							   r.spread(1)
