********************************************************************************

                    Floodplain Analysis Toolkit
               Mother Earth Systems, Boulder, Colorado


This software was been developed for the U.S. Army Corps of Engineers,
Ft. Worth District under contract #DACW63-91-M-1085 and for the Omaha
District under contract #DACW45-92-P-1301.

This code is in the public domain.  Permission to use, copy, modify, and
distribute this software and its documentation for any purpose and without
fee is granted.

Mother Earth Systems disclaims all warranties with regard to this
software, including all implied warranties of merchantability and
fitness. In no event shall Mother Earth Systems be liable for any
special, indirect or consequential damages or any damages whatsoever
resulting from loss of use, data or profits, whether in an action of
contract, negligence or other tortious action, arising out of or in
connection with the use or performance of this software.

********************************************************************************

CREDITS:
Mother Earth Systems owes much credit to the following...

C.M. Gold (1989) "Surface interpolation, spatial adjacency and GIS" in
     _Three Dimensional Applications in Geographic Information Systems_
     Edited by Jonathan Raper; Taylor & Francis.
     (Gold's paper forms the basis for the r.surf.voronoi algorithm.)

Steve J. Fortune (1987) "A Sweepline Algorithm for Voronoi Diagrams"
     _Algorithmica_ 2, 153-174.
     (An implementation of Fortune's sweep algorithm, available via
Internet, 
      lies at the heart of the r.surf.voronoi code ).

James Darrell McCauley (mccauley@ecn.purdue.edu) 
     (McCauley first integrated Fortune's sweep algorithm with GRASS to
      produce "s.voronoi".  McCauley's implementation provided a valuable
      example of the use of the sweep code for GRASS. )


LIMITATIONS:
1)  The sweep line code limits the number of voronoi sites to 4K.  
    This means that the number of non-zero cells in the GRASS input map 
    is also limited to 4K.

2)  r.surf.voronoi does not handle longitude/latitude data.

********************************************************************************

AUTHOR INFORMATION:
Questions and suggestions are welcome. Write or call:

Terri L. Betancourt
Mother Earth Systems
891 Crescent Dr.
Boulder, CO 80303-2759
(303) 499-7883


Current on-line documentation for this software will provide you
with a brief introduction to the available commands.  There are
plans to complete the information in electronic form.

If you are attempting to use these tools, and need additional
documentation, a hard copy of a 33-page document titled "F-Tools: 
Floodplain Analysis Tools User Documentation" is available by contacting:

        Scott Walker
        US Army Corps of Engineers
        Fort Worth District
        ATTN:  SWFPIR
        P.O. Box 17300
        Fort Worth, TX 76102-3000
        ph 817-334-3246
        fx 817-885-7539

-----------------------------------------------------------------------

f.input

This tool reads the results of the HEC-2 Water Surface Profile model
and generates a vector map of water surface elevations at hydraulic
sections.  The user supplies to f.input a vector map of the hydraulic
cross sections used in the HEC-2 model along with the HEC-2 model
results.

The results of f.input, a vector map, is generally uninteresting to
the user and is intended to be used only as input to the f.wsurf
program.  The functionality of f.input and f.wsurf could have been
combined into a single tool but was separated out because of the
intense CPU requirements of f.wsurf.  This functional separation
allows the user to process single flood events through f.wsurf.

In the input vector map, cross sections must be labeled with the same
section numbers as were used in the HEC-2 model.  These section
numbers must be unique within the integer portion of the id.

It is not necessary for all cross sections from the HEC-2 model to
appear in the GRASS map or vice versa.  Vector cross sections are not
used in the HEC-2 model will be assigned to a water surface elevation
to zero by f.input.  Modeled cross sections which are not in the
vector map will be ignored by f.input.

The user specify to f.input the flood events represented in the HEC-2
output file.  The order in which the user specifies the flood events
must correspond to the order in which the events were modeled in
HEC-2.  Events are specified in terms of their recurrence interval and
may be specified interactively or through the use of a control file.
Enumeration of recurrence intervals is important to subsequent
economic calculations performed in f.econ.

Split flow conditions which have been modeled as two separate HEC-2
model runs yielding two HEC-2 output files is supported by f.input.
However, the vector sections for both the primary and split flow runs
should appear in a single GRASS map.

Only one split flow file is allowed, and f.input assumes that the
flood events modeled for the split flow are the same as those modeled
in the primary HEC-2 run.

Any cross section which is modeled in both the primary and split flow
HEC-2 runs may have two different water surface elevations calculated
by HEC-2.  When generating the vector map of water surface elevations,
f.input will overwrite the primary water surface elevation with the
elevation in the split flow file.

GRASS maps can only contain integer values.  In order to maintain
one-tenth foot precision in the floodplain analysis data, water
surface elevations calculated by HEC-2 are multiplied by 10 before
being assigned to the GRASS vector maps.  This multiplication factor
is accommodated by other f-tools.


f.acap

This tool calculates area-capacity for select areas of interest.  The
area-capacity shows relationships between water surface elevation,
water surface area, and volume of water.

Areas of interest (AOI) are mapped in a raster map with each area
having a unique if (attribute value).  AOI's to be analyzed are
selected by the user interactively.  The user also provides the
desired starting water surface elevation, ending water surface
elevation, and increment elevation for the area-capacity curve.  With
the water surface elevation values, the raster AOI map, and raster
terrain elevation map, f.acap calculates area and volume.

The user may choose to terminate the area-capacity curve by specifying
a maximum volume instead of a maximum water surface elevation.  This
can be done by typing "v" or "V" when f.acap requests the ending
elevation.  The user will then be promoted for maximum volume.

f.acap is designed to produce a elevation-area-volume curve not a
head-area-volume curve.  Thus, the user must water surface elevations
not water surface head.

The algorithm for f.acap does not examine the terrain elevation
outside the area of interest.  The perimeter of the AOI acts as a
vertical wall in the area and volume calculations.

This is a fully interactive tool, i.e., no control file is processed
and areas of interest are identified by mouse selection.
Area-capacity curves are printed to the screen.


f.detail

This tool functions identically to f.econ, but provides two detailed
reports as output.  The detailed reports provide economic damage and
depth of flooding for each building in the study area.  Economic
damages are reported as a sum of the structure and content damage.


f.econ

This tool takes as input the results of f.wsurf along with a
user-supplied vector map of building sites and two ASCII files of
economic data.  As output f.econ generates a vector map of total
damage to each building in the floodplain along with a summary ASCII
report of flood damages categorized by building types (residential,
public, ...) and damage type (structure or content).  f.econ also
reports areal extent of flooding.

The user may choose to run f.econ on selected flood events.  Events
are specified in terms of their recurrence interval and may be
selected interactively or through the use of a control file.  Only
those events previously processed by f.wsurf are available to f.econ.
If run interactively, f.econ provides the user with a list of
available flood events.

The user must define for f.econ a recurrence interval to associate
with an SPF flood event.  The specified recurrence interval affects
only the calculation of expected annual damage (EAD), not river
hydraulics or floodplain delineation.

EAD is calculated on the following equation:

           [(D-E1 + D-E2) / 2] * [1/E1 - 1/E2]
           + [(D-E2 + D-E3) / 2] * [1/E2 - 1/E3]
           + ...
           + [(D-En + D-Espf) / 2] * [1/En - 1/Espf]
           + [D-Espf] * [1/Espf]





where:

     Ex    is the recurrence interval for flood event x.
     1/Ex  is the probability of flood event x occurring in a given year.
     D-Ex  is the calculated damage for flood event x.
     spf   is the "standard project flood"


f.reach

This tool provides floodwater statistics, including areal extent of
flooding, average flood depth, and volume of water, calculated on a
reach-by-reach basis.

Reach boundaries are based on the input cross section map.  The
determination of reach boundaries assumes that cross sections in the
input vector map occur in sequence, i.e., the cross sections were
digitized in order from upstream down or from downstream up.

In addition to a vector cross map, f.reach requires as input a raster
map of flood depths.  If a raster map is displayed in the GRASS
graphics window, that map will be used as the input depth map.  If no
raster map is displayed, the user will be promoted for the appropriate
depth map.

Since flood depths are required to calculate reach statistics, f.input
and f.wsurf should be run prior to f.reach to provide depth maps as
input.  Since depth maps from f.wsurf contain a factor of 10 to
provide one-tenth foot precision in the data, f.reach adjusts for this
factor in its calculations.

f.reach will function successfully with raster maps other than flood
depth; however, interpretation of the calculated statistics is left to
the user.

This is a fully interactive tool, i.e., no control file is processed
and reaches of interest are identified by mouse selection.  Research
statistics are printed to the screen.


f.wsurf

This took takes the results of f.input along with a raster terrain
elevation map and generates two raster maps describing the floodplain.
The map wsurf.<event> is an interpolation of flood water elevations.
The map depth.<event> is a calculation of flood water depths where:
     
     value = water surface elevation - terrain elevation
     if value > 0
           then flood depth = value
           else flood depth = 0

The water surface interpolation method used in f.wsurf is supplied by
the GRASS function r.surf.idw which is a two-dimensional interpolation
algorithm based on inverse distance squared weighting.

Interpolation of water surfaces causes f.wsurf to be quite slow.  The
speed is greatly affected by the size of study area and the cell
resolution.  Both size and resolution are established by the user with
the GRASS g.region command.

Because of the computation time required for surface interpolation,
the user may only want to run f.wsurf on selected flood events.
Events are specified in terms of their recurrence interval and may be
selected interactively or through the use of a control file.  Only
those events previously processed by f.input are available to f.wsurf.
If run interactively, f.wsurf provides the user with a list of
available flood events.

Like the vector maps generated by f.input, the raster maps generated
by f.wsurf contain a multiplication factor of 10 in order to maintain
one-tenth foot precision within GRASS.


f.xsection

This tool provides an interactive means for digitizing new cross
sections to be used as input to HEC-2 modeling.  Digitized cross
sections are described in an ASCII output file in an format suitable
as input to the HEC-2 Water Surface Profile model.

f.xsection uses a vector cross section map and raster elevation map as
the basis for cross section modifications.  Cross sections can be
added to a new or existing vector map.  If added to an existing cross
section map, the modified cross sections (original plus newly
digitized) are output into a vector map with the suffix ".mod"
appended to the original cross section map name.

This is a fully interactive tool, i.e., no control file is processed
and cross section are digitized by mouse interaction.

As new cross sections are added, reach lengths for existing cross
section must be adjusted.  Adjusted lengths are calculated and
included in the ASCII output file.  Reach lengths may be corrected
multiple times, as more and more new cross sections are added.  Thus,
the last reach length correction for a given cross section represents
the adjustment which should be used as input to subsequent HEC-2
modeling.

Prior to digitizing each new cross section, f.xsection prompts the
user for the section number id.  This id may be entered as a real
value.  In the ASCII output file, the id will be represented as
entered by the user up to a field width of six.  However, since GRASS
only supports integer values, the cross section id will be truncated
to its integer portion for the modified cross section vector map.  For
this reason, the user is recommended to use only integer cross section
id's.

f.xsection, like HEC-2, operates in a backwater fashion.  This
assumption dictates that the order in which the original cross
sections are digitized must be downstream-to- upstream, and that HEC-2
is used to model a subcritical flow.  (Enhancements are necessary for
f.xsection to handle supercritical flow regimes.)  New cross sections
can be digitized in any order and f.xsection will maintain the
upstream-to-downstream ordering for the modified cross section vector
map.  HEC-2 descriptions of the newly digitized cross sections will
occur in the ASCII output file in the order in which they were
digitized.

--------------------------------------------------