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



NNAAMMEE
       r.spread  - Simulates elliptically anisotropic spread on a
       graphics window and generates a raster map of the  cumula-
       tive  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/Display 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 unevenness 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	determin-
       ing factors have directional components. For example, wind
       and topography cause anisotropic 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  com-
       monly not an ellipse.

	_r_._s_p_r_e_a_d  simulates  elliptically anisotropic spread phe-
       nomena, 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 locations 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  pro-
       gram 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 back-
       link UTM coordinates 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  pro-
       gram 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 standard 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, clockwise from north (degree).

	bbaassee==name  Name  of  an  existing raster map layer in the
       user's current mapset search path containing the ROS  val-
       ues  in	the  directions  perpendicular	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 phenomenon. 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 current mapset search path containing the maxi-
       mum potential spotting distances (meters).

	ww__ssppeeeedd==name Name of an existing raster map layer in  the
       user's  current mapset search path containing wind veloci-
       ties at half of the average 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 (percentage  content  multiplied  by
       100).

	lleeaasstt__ssiizzee==odd int An odd integer ranging 3 - 15 indicat-
       ing 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 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 accu-
       racy will be. The default number is 0.5.

	iinniitt__ttiimmee==int A non-negative number specifying	the  ini-
       tial  time  for	the  current spread simulation (minutes).
       This is useful when  multiple  phase  simulation  is  con-
       ducted. 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 controls the computa-
       tional time, the shorter the time lag, the faster the pro-
       gram will run.

	bbaacckkddrroopp==name Name of an existing raster map layer in the
       user's  current mapset search path to be used as the back-
       ground 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 coordi-
       nates for each cell.

	yy__oouuttppuutt=name Name of the new raster map layer to contain
       the results of backlink information in UTM northing  coor-
       dinates 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 specifying 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)]   [backdrop=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 contain spread time, backlink infor-
       mation 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.spot-
       dist   w_speed=wind_speed   f_mois=1hour_moisture    back-
       drop=image_burned   output=my_spread  x_output=my_spread.x
       y_output=my_spread.y



NNOOTTEESS
       1. r.spread is a specific implementation of  the  shortest
       path algorithm.	r.cost GRASS program served as the start-
       ing 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  simu-
       late  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 mod-
       els. 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  pro-
       gram 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 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.



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 Service, 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 geographic 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)
