.\" %W% %G%
.TH watershed 1
.SH NAME
watershed \- menu driven user interface for running
watershed analysis steps
.br
.I (GRASS-GRID Tool)
.SH SYNOPSIS
.nf
watershed
.fi
.SH DESCRIPTION
Watershed
is an interface to routines which perform various
steps related to completing a watershed analysis.

For the purpose of completing all steps of the
process with a minimum of input required at 
each step, and in order to maintain a record of
all parameters used to obtain a particular
result, a "project" file is created to hold
information pertaining to map layer names and
input parameter values.
Upon entry of the watershed program, the user
will first see the following:
.nf


         WELCOME TO THE WATERSHED SOFTWARE SYSTEM!                             
                                                                               
  This program is designed to help you follow the correct                      
  steps to obtain a GRASS raster file depicting watershed                      
  geometry using a raster elevation file (with true elevation                  
  values) as a starting point.  All steps are recorded                         
  under the project name, which must be a legal GRASS                          
  system filename, unique within the current location and                      
  mapset.                                                                      
                                                                               
  Choose desired option:                                                       
                                                                               
  1.  Create new project                                                       
  2.  Create new project based on currently existing project                   
  3.  Work on an existing project                                              
                                                                               
.fi

The user can exit from the program after completing
any number of steps. Hence, the option to "Work
on an existing project" allows for finishing any
remaining steps, or for redoing particular steps,
or both.

A new project may be created with all new inputs,
or a new project can be created using inputs
from a previous project.

Once an old or new project has been chosen,
the user will be presented the following menu and
allowed to choose an option:

.nf
1.  Filtering elevation data                                                   
2.  Processing pits                                                            
3.  Calculating drainage accumulation/outlining watershed                      
4.  Creating stream network                                                    
5.  Coding stream segments/finding segment lengths                             
6.  Finding subwatershed basins                                                
                                                                               
7.  Quit
.fi

The steps are presented in the order they should be used to
complete the total watershed analysis for the purposes of
creating all products.  While input is being accepted for
each individual step, the option is given whether to
run the actual program.  If the program has been run
and completes without error, the word "COMPLETE" will
appear on the above menu after the listing of that
step.

It is not required that
all the steps be completed, or that they be run in this
particular order, except where products from one step are
required for another.
Steps 1 and 2 can be used apart from the rest of 
the steps in the menu, but steps 2, 3, 4, and 6 require
products from other steps.  In order to complete all
six steps, all parts must be completed, with the
exception of step number 1 (unfiltered data may be
used for steps 2 and 3, but time requirements will be
affected -- see explanations below).

.SH FILTERING
This function smoothes elevation data using a particular
filter for the purpose of descreasing significatnly
the number of pits found, eliminating many pits which
are glitches in the data instead of true pits.

Any data can be filtered with this program, but for
the purposes of watershed analysis, the input layer
must contain true elevation values.
The user is asked for the input layer,
an output layer name, and the desired
number of filter iterations.  It is normally sufficient
to filter the data once.  Some pit points will
remain, but these are probably true pits.  The filtering
is done on 3x3 neighborhoods,
with the following weighted average:
.NF
1 2 1
2 4 2  /  16
1 2 1
.FI
The filtering is done only on the input values, not on rows
already averaged during the filtering process.
.SH NOTES
The current window setting is ignored.  Instead,
the window of the input map layer is used.

For the purposes of completing all the steps of the
watershed analysis, this is the only optional step.
If filtering of the elevation data is not done, it is
likely that an abundance of pits will be found, and execution
of the next couple of steps will be time consuming.

.SH PROCESSING PITS
This step 
generates a list of pit points designated by their
UTM (easting and northing) coordinates.
Pits are points which are characterized as
having a lower elevation value than all points surrounding
them.  Input to this program should be a cell file containing
true elevation values. It is usually helpful to
filter the elevation file first  (see "FILTERING" above).
The pit points are sorted by decreasing elevation value, and
stored in a miscellaneous file under the current location
and mapset.
.SH NOTES
The current window setting is ignored.  Instead,
the window of the input (elevation) map layer is used.

For the purposes of completing all the steps of the
watershed analysis, pit points are used to begin the
process of identifying depression areas (possible
lakes).

.SH CALCULATING DRAINAGE ACCUMULATION
This step
generates a drainage accumulation map layer from elevation
data. Drainage accumulation is designated by 
assigning each cell a category value equivalent
to the number of cells within the designated
watershed that drain into that cell. An implied watershed
boundary is generated, as all cells outside the
watershed have category value zero (no data).
Also generated are an adjusted
drainage direction map (adjusted to allow for the draining
of water across lakes), and an optional product which denotes
designated lakes, pits, and redirected routes. 

The elevation map layer used for input will be that used
in the previous step to find pit points.  User must supply all
output map names and the desired watershed outlet point,
as well as two threshold values.

The resulting
drainage accumulation file is needed in the following step
to generate a stream network.
.SH NOTES
The pit processing step must be completed before this
step.

The current window setting is used.  The user should
take care that the desired watershed is within the current
window if possible.

See "WATSHED -- A Proposed Method for Automated
Extraction of Geometric and Topologic Information
from Digital Elevation Data" for detailed suggestions
on input parameter values.

.SH CREATING STREAM NETWORK
This step
generates a stream network map layer from a drainage
accumulation input layer.
User must supply an accumulation
threshold, as well as the desired number of thinning
iterations.  The accumulation threshold will determine
the detail of the tributaries in the resulting stream
network.  (The smaller the threshold, the more tributaries
in the result.)  All cells within the input layer which have
category values less than the threshold will be eliminated.
If the resulting stream network is to be used to
complete the rest of the steps of this interface,
it is essential the thinning be done
to one pixel width.  This may require a high number of
thinning iterations.
.SH NOTES
The current window setting is ignored.  Instead,
the window of the input map layer is used.

See "WATSHED -- A Proposed Method for Automated
Extraction of Geometric and Topologic Information
from Digital Elevation Data" for detailed suggestions
on choosing a threshold value.

.SH CODING STREAM SEGMENTS
This step
generates a coded stream network given a binary input layer
of a one pixel width stream network generated through the
steps in this menu.  At each branching
of the original network, a new category number is assigned.
Thus, the resulting network has each channel segment denoted by
a unique category number.  This numbering will correspond with
the numbering of subbasins within the given watershed.

A miscellaneous file is also created which contains
the nodes (beginning and ending points) for each segment, as
well as the length of each segment.

In the output map layer, channel segments are
numbered according to their necessary input order into the
armsed modelling system.  This product is optional,
as the miscellaneous nodes file is all that is
necessary for completing the next step of this process.
.SH NOTES
The current window setting is ignored.  Instead,
the window of the input map layer is used.

This step expects binary input.  However, the output map
layer (if requested) will have as many categories as
there are channel segments in the network representation.

.SH FINDING SUBWATERSHED BASINS
This final step in the process
generates an output layer containing a unique category number
and area for each subbasin within a given watershed and for
a given stream network.  This must be run as part of
the series of steps from this menu, and needs an input map
layer of corrected drainage directions and the name
of the thinned stream network for which the nodes file
will be obtained.  Therefore, steps 2 through 5 must be
completed before this program can be run.

Output basins are numbered 
according to the needs of input for the armsed modelling
system.
.SH NOTES
The current window setting is ignored.  Instead,
the window of the stream network input map layer
is used.

Number of categories in the output layer is
equivalent to the number of channel segments
in the stream network.
.SH BUGS
Results of this step may not be completely accurate.
Problems are
due to routing of water over lakes and flat areas,
as well as problems with the thinning routine.  To create
a product using alternate means, see suggestions in
"WATSHED -- A Proposed Method for Automated
Extraction of Geometric and Topologic Information
from Digital Elevation Data."
.SH "AUTHOR"
Marjorie Larson, U.S. Army Construction Engineering Research Laboratory
.br
Larry Band, Dept. of Geography, University of Toronto
