Sophie

Sophie

distrib > Fedora > 13 > i386 > by-pkgid > 413e0bdb3c48563b2d8d9038d07d5533 > files > 2116

grass-6.3.0-15.fc13.i686.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS: r.terraflow</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">

<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>

<h2>NAME</h2>
<em><b>r.terraflow</b></em>  - Flow computation for massive grids (Float version).
<h2>KEYWORDS</h2>
<h2>SYNOPSIS</h2>
<b>r.terraflow</b><br>
<b>r.terraflow help</b><br>
<b>r.terraflow</b> [-<b>sq</b>] <b>elev</b>=<em>string</em> <b>filled</b>=<em>string</em> <b>direction</b>=<em>string</em> <b>swatershed</b>=<em>string</em> <b>accumulation</b>=<em>string</em> <b>tci</b>=<em>string</em>  [<b>d8cut</b>=<em>float</em>]   [<b>memory</b>=<em>integer</em>]   [<b>STREAM_DIR</b>=<em>string</em>]   [<b>stats</b>=<em>string</em>]   [--<b>overwrite</b>]  [--<b>verbose</b>]  [--<b>quiet</b>] 

<h3>Flags:</h3>
<DL>
<DT><b>-s</b></DT>
<DD>SFD (D8) flow (default is MFD)</DD>

<DT><b>-q</b></DT>
<DD>Quiet</DD>

<DT><b>--overwrite</b></DT>
<DD>Allow output files to overwrite existing files</DD>
<DT><b>--verbose</b></DT>
<DD>Verbose module output</DD>
<DT><b>--quiet</b></DT>
<DD>Quiet module output</DD>
</DL>

<h3>Parameters:</h3>
<DL>
<DT><b>elev</b>=<em>string</em></DT>
<DD>Input elevation grid</DD>

<DT><b>filled</b>=<em>string</em></DT>
<DD>Output (filled) elevation grid</DD>

<DT><b>direction</b>=<em>string</em></DT>
<DD>Output direction grid</DD>

<DT><b>swatershed</b>=<em>string</em></DT>
<DD>Output sink-watershed grid</DD>

<DT><b>accumulation</b>=<em>string</em></DT>
<DD>Output accumulation grid</DD>

<DT><b>tci</b>=<em>string</em></DT>
<DD>Output tci grid</DD>

<DT><b>d8cut</b>=<em>float</em></DT>
<DD>If flow accumulation is larger than this value it is routed using SFD (D8) direction <br> 		 (meaningfull only  for MFD flow)</DD>
<DD>Default: <em>infinity</em></DD>

<DT><b>memory</b>=<em>integer</em></DT>
<DD>Main memory size (in MB)</DD>
<DD>Default: <em>300</em></DD>

<DT><b>STREAM_DIR</b>=<em>string</em></DT>
<DD>Location of intermediate STREAMs</DD>
<DD>Default: <em>/var/tmp</em></DD>

<DT><b>stats</b>=<em>string</em></DT>
<DD>Stats file</DD>
<DD>Default: <em>stats.out</em></DD>

</DL>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>r.terraflow</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">

<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>

<H2>NAME</H2> <B><I>r.terraflow </I></B>- computation of <i>flow
direction</i>, <i>flow accumulation</i> and other basic topographic terrain
indices from a raster digital elevation model (DEM).

<P><I>(GRASS Raster Program)</I>

<H2>SYNOPSIS</H2>
<B>r.terraflow</B>
<BR>
<B>r.terraflow</B> help</br>
<BR>
<B>r.terraflow</b> <b>[ -sq ]</b>
<b>elev</b>=name
<b>filled</b>=name
<b>direction</b>=name
<b>swatershed</b>=name
<b>accumulation</b>=name
<b>tci</b>=name
[<b>d8cut</b>=value]
[<b>memory</b>=value]
[<b>STREAM_DIR</b>=name]
[<b>stats</b>=name]


<H2>DESCRIPTION</H2>

<p><EM>r.terraflow</EM> takes as input a raster digital elevation
model (DEM) and computes the flow direction raster and the flow
accumulation raster, as well as the flooded elevation raster,
sink-watershed raster (partition into watersheds around sinks) and tci
(topographic convergence index) raster.

<p><EM>r.terraflow</EM> computes these rasters using well-known
approaches, with the difference that its emphasis is on the
computational complexity of the algorithms, rather than on modeling
realistic flow.  <EM>r.terraflow</EM> emerged from the necessity of
having scalable software able to process efficiently very large
terrains.  It is based on theoretically optimal algorithms developed
in the framework of I/O-efficient algorithms.  <EM>r.terraflow</EM>
was designed and optimized especially for massive grids and is able to
process terrains which were impractical with similar functions
existing in other GIS systems.

<p>Flow directions are computed using either the MFD (Multiple Flow
Direction) model or the SFD (Single Flow Direction, or D8) model,
illustrated below. Both methods compute downslope flow directions by
inspecting the 3-by-3 window around the current cell. The SFD method
assigns a unique flow direction towards the steepest downslope
neighbor. The MFD method assigns multiple flow directions towards all
downslope neighbors.

<p>
<table width=80%>
<tr>
<th><img src="rterraflow_dir2.png" alt="[SFD]" border=0></td>
<th><img src="rterraflow_dir3.png" alt="[SFD]" border=0></td>
<tr>
<th>Flow direction to steepest<br> downslope neighbor (SFD).</th>
<th>Flow direction to all<br> downslope neighbors (MFD).</th>
</table>


<p>The SFD and the MFD method cannot compute flow directions for
cells which have the same height as all their neighbors (flat areas)
or cells which do not have downslope neighbors (one-cell pits).
<ul>
  <li>On plateaus (flat areas that spill out) <EM>r.terraflow</EM>
routes flow so that globally the flow goes towards the spill cells of
the plateaus.

  <li>On sinks (flat areas that do not spill out, including one-cell
pits) <EM>r.terraflow</EM> assigns flow by flooding the terrain until
all the sinks are filled and assigning flow directions on the filled
terrain.

</ul>

<p>In order to flood the terrain, <EM>r.terraflow</EM> identifies all
sinks and partitions the terrain into sink-watersheds (a
sink-watershed contains all the cells that flow into that sink),
builds a graph representing the adjacency information of the
sink-watersheds, and uses this sink-watershed graph to merge
watersheds into each other along their lowest common boundary until
all watersheds have a flow path outside the terrain. Flooding produces
a sink-less terrain in which every cell has a downslope flow path
leading outside the terrain and therefore every cell in the terrain
can be assigned SFD/MFD flow directions as above.

<p>Once flow directions are computed for every cell in the terrain,
<EM>r.terraflow</EM> computes flow accumulation by routing water using
the flow directions and keeping track of how much water flows through
each cell.

<EM>r.terraflow</EM> also computes the tci raster (topographic convergence
index, defined as the logarithm of the ratio of flow accumulation and
local slope).

<p>For more details on the algorithms see [1,2,3].


<H2>OPTIONS</H2>

The program will run non-interactively if the user specifies program
arguments and flag settings on the command line using the following
form:

<P><B>r.terraflow</b> <b>[ -sq ]</b>
<b>elev</b>=name
<b>filled</b>=name
<b>direction</b>=name
<b>swatershed</b>=name
<b>accumulation</b>=name
<b>tci</b>=name
[<b>d8cut</b>=value]
[<b>memory</b>=value]
[<b>STREAM_DIR</b>=name]
[<b>stats</b>=name]



<P>Alternatively, the user can simply type <EM>r.terraflow</EM> on the
command line and the program will ask for parameter values and flag
settings interactively, using the standard GRASS parser interface.


<H3>Flags:</H3>
<dl>
  <dt><B>-s</B>
  <dd>Use SFD (D8) flow. By default MFD flow is used. 
  <dt><B>-q</B>
  <dd>Run quietly (do not display status messages). By default
<EM>r.terraflow</EM> is run verbosely.  </dl>


<H3>Parameters:</H3>
<dl>
 <dt><B>elev</B>=<I>name</I>
 <dd>Input elevation raster. Required.</dd>

 <dt><b>filled</b>=<I>name</I>
 <dd> Output filled (flooded) elevation raster. Required.</dd>

 <dt><b>direction</b> =<I>name</I>
 <dd> Output flow direction raster. Required.</dd>

 <dt><b>swatershed</b> =<I>name</I>
 <dd> Output sink-watershed raster. Required.</dd>

 <dt><b>accumulation </b> =<I>name</I>
 <dd>Output flow accumulation raster. Required.</dd>

 <dt><b>tci</b> =<I>name</I>
 <dd> Output topographic convergence index (tci) raster. Required.</dd>

 <dt>[<b>d8cut</b> =<I>value</I>]
 <dd> If flow accumulation of a cell is larger than this value, then
the flow of this cell is routed to its neighbors using the SFD (D8)
model. This option affects only the flow accumulation raster and is
meaningfull only for MFD flow (i.e. if the -s flag is not used); If
this option is used for SFD flow it is ignored. The default value of
<b>d8cut</b> is <i>infinity</i>. </dd>

 <dt>[<b>memory</b> =<I>value (in MB)</I>]
 <dd> The main memory size (in MB) to be used by
<EM>r.terraflow</EM>. In practice <I>value</I> should be an
underestimate of the amount of available (free) main memory on the
machine. <EM>r.terraflow</EM> will use at all times at most this much
memory, and the virtual memory system will never be in use. The
default value is 300 MB. </dd>

 <dt>[<b>STREAM_DIR</b> =<I>path name</I>]
 <dd> Location of the intermediate files generated by
<EM>r.terraflow</EM>.  The default location is <i>/var/tmp</i>. </dd>

 <dt>[<b>stats</b> =<I>name</I>]
 <dd> The name of the file that contains the statistics (stats) of the
run. The default name is <i>stats.out</i> (in the current
directory). </dd>

</dl>
      

<H3>Examples</H3>

<ul>
  <li> <B>r.terraflow</b> elev=spearfish filled=spearfish-filled
       dir=spearfish-mfdir swatershed=spearfish-watershed
       accumulation=spearfish-accu tci=spearfish-tci
  <li> <B>r.terraflow</b> elev=spearfish filled=spearfish-filled
       dir=spearfish-mfdir swatershed=spearfish-watershed
       accumulation=spearfish-accu tci=spearfish-tci d8cut=500 memory=800
       STREAM-DIR=/var/tmp/ stats=spearfish-stats.txt 
</ul>

<H2>NOTES</H2>

<p>One of the techniques used by <EM>r.terraflow</EM> is the
space-time trade-off. In particular, in order to avoid searches, which
are I/O-expensive, <EM>r.terraflow</EM> computes and works with an
augmented elevation raster in which each cell stores relevant
information about its 8 neighbors, in total up to 80B per cell.  As a
result <EM>r.terraflow</EM> works with intermediate temporary files
that may be up to 80N bytes, where N is the number of cells (rows x
columns) in the elevation raster (more precisely, 80K bytes, where K
is the number of valid (not nodata) cells in the input elevation
raster).

All this intermediate temporary files are stored in the path specified
by <b>STREAM_DIR</b>. Note: <b>STREAM_DIR</b> must contain enough free
disk space in order to store up to 2 x 80N bytes.


<p>The internal type used by <EM>r.terraflow</EM> to store elevations
can be defined at compile-time.  By default, <EM>r.terraflow</EM> is
compiled to store elevations internally as floats.
A version which is compiled to store elevations internally as
shorts is available as <EM>r.terraflow.short</EM>. Other versions can
be created by the user if needed. 

<p><EM>r.terraflow.short</EM> uses less space (up to 60B per cell, up
to 60N intermediate file) and therefore is more space and time
efficient.  <EM>r.terraflow</EM> is intended for use with floating
point raster data (FCELL), and <EM>r.terraflow.short</EM> with integer
raster data (CELL) in which the maximum elevation does not exceed the
value of a short SHRT_MAX=32767 (this is not a constraint for any
terrain data of the Earth, if elevation is stored in meters).

<p>Both <EM>r.terraflow</EM> and <EM>r.terraflow.short</EM> work with
input elevation rasters which can be either integer, floating point or
double (CELL, FCELL, DCELL). If the input raster contains a value that
exceeds the allowed internal range (short for
<EM>r.terraflow.short</EM>, float for <EM>r.terraflow</EM>), the
program exits with a warning message. Otherwise, if all values in the
input elevation raster are in range, they will be converted
(truncated) to the internal elevation type (short for
<EM>r.terraflow.short</EM>, float for <EM>r.terraflow</EM>). In this
case precision may be lost and artificial flat areas may be created.

<p>For instance, if <EM>r.terraflow.short</EM> is used with floating
point raster data (FCELL or DCELL), the values of the elevation will
be truncated as shorts. This may create artificial flat areas, and the
outpus of <EM>r.terraflow.short</EM> may be less realistic than those
of <EM>r.terraflow</EM> on floating point raster data.

The outputs of <EM>r.terraflow.short</EM> and <EM>r.terraflow</EM> are
identical on integer raster data (CELL).



<H2>SEE ALSO</H2>
<ul>
  <li>The <a
href="http://www.cs.duke.edu/geo*/terraflow/">TerraFlow</a> project at Duke University
       
  <li><a href=r.flow.html>r.flow</a>,
       <A HREF="r.basins.fill.html">r.basins.fill</A>,
       <A HREF="r.drain.html">r.drain</A>,
       <a href="r.topidx.html>r.topidx</a>,
       <a href="r.topmodel.html>r.topmodel</a>,
       <A HREF="r.water.outlet.html">r.water.outlet</A>,
       <A HREF="r.watershed.html">r.watershed</A>
</ul>



<H2>AUTHORS</H2>

<dl>
  <dt>Original version of program: The <a
	   href="http://www.cs.duke.edu/geo*/terraflow/">TerraFlow</a> project,
	1999, Duke University.
	<dd><a href="http://www.cs.duke.edu/~large/">Lars Arge</a>,
		<a href="http://www.cs.duke.edu/~chase/">Jeff Chase</a>,
        <a href="http://www.env.duke.edu/faculty/bios/halpin.html">Pat Halpin</a>,
        <a href="http://www.cs.duke.edu/~laura/">Laura Toma</a>,
        <a href="http://www.env.duke.edu/faculty/bios/urban.html">Dean Urban</a>,
        <a href="http://www.cs.duke.edu/~jsv/">Jeff Vitter</a>,
        <a href="http://www.cs.duke.edu/~rajiv/">Rajiv Wickremesinghe</a>.
       
  <dt>Porting for GRASS, 2002:
    <dd> <a href="http://www.cs.duke.edu/~large/">Lars Arge</a>,
	     <a href="http://skagit.meas.ncsu.edu/~helena/index.html">Helena Mitasova,</a>
		 <a href="http://www.cs.duke.edu/~laura/">Laura Toma</a>. 
	   
	<dt>Contact: <a href="mailto:laura@cs.duke.edu"> Laura Toma</a></dt>
</dl>


<H2>REFERENCES</H2>

<ol>
  <li><A NAME="arge:drainage"
       HREF="http://www.cs.duke.edu/geo*/terraflow/papers/alenex00_drainage.ps.gz">
       I/O-efficient algorithms for problems on grid-based
       terrains</A>.  Lars Arge, Laura Toma, and Jeffrey S. Vitter. In
       <EM>Proc. Workshop on Algorithm Engineering and Experimentation</EM>,
       2000. To appear in <EM>Journal of Experimental Algorithms</EM>.
       
  <li><A NAME="terraflow:acmgis01"
       HREF="http://www.cs.duke.edu/geo*/terraflow/papers/acmgis01_terraflow.pdf">
       Flow computation on massive grids</A>.
       Lars Arge, Jeffrey S. Chase, Patrick N. Halpin, Laura Toma,
       Jeffrey S. Vitter, Dean Urban and Rajiv Wickremesinghe. In
       <EM>Proc. ACM Symposium on Advances in Geographic Information
       Systems</EM>, 2001.
       
  <li><A NAME="terraflow:geoinformatica"
       HREF="http://www.cs.duke.edu/geo*/terraflow/papers/journal_terraflow.pdf">
       Flow computation on massive grid terrains</A>.
       Lars Arge, Jeffrey S. Chase, Patrick N. Halpin, Laura Toma,
       Jeffrey S. Vitter, Dean Urban and Rajiv Wickremesinghe.
       To appear in <EM>GeoInformatica, International Journal on
       Advances of Computer Science for Geographic Information
       Systems</EM>.
       
</ol>

<p><i>Last changed: $Date: 2006-09-22 16:57:14 +0200 (Fri, 22 Sep 2006) $</i>
</body>
</html>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional