******************************************************************************** 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. is an interpolation of flood water elevations. The map depth. 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. --------------------------------------------------