HELP FILE -- DEM DRAINAGE SOFTWARE -- VMS,UNIX,PRIMOS 
 
Sue Jenson - EROS Data Center - (605)594-6011 - FTS753-7011 
 
                      September 20, 1988 
 
************************  DRAFT  **************************** 
 
The twelve FORTRAN programs used to extract hydrologic information
from Digital Elevation Models are in a generic form which allows them
to be run under VMS, UNIX, or PRIMOS operating systems.  System is
prompted for in order for the programs to know which record length
value to use in opening the files. 
 
INSTALLATION 

No subroutine libraries are needed.  Each program compiles and runs as
an independent unit.  For VMS, use the FOR and LINK routines.  For
UNIX, use F77.  For PRIMOS, use F77 and BIND.
 
PROMPTING 

The programs prompt for parameters and file names as a first step.
File names and other literals must be entered differently on the three
systems.  For VMS and PRIMOS, enclose all literals in single quotes.
For UNIX, no quotes are necessary unless special characters such as /
are used -- then double quotes must enclose the literal.
 
FILE CHARACTERISTICS AND FILE TRANSFER 

The programs operate on binary I*2 and I*4 disk files.  They require
fixed length record type in order to perform random I/O.  On a VMS
system with LAS software, the sequence of programs to follow is LAS
DALOUT and then TRANSFER with a variable to fixed record length
option.  To bring output files back into LAS, use the inverse
sequence.  On a UNIX system with LAS, the DISKDAL function alone will
do the file transfers.  EDC has not yet completed file transfer
capabilities for PRIMOS, although a quick tape interface has been
written.
 
All raster datasets are I*2 except for the COUNT and DELTA datasets
which are I*4. 
 
RESTART 

A restart capability has been built into the COUNT and DIRECT
programs.  Enter a zero for a restart code unless restart is desired
due to system failure or other interruption.  To request restart,
enter a 1.
 
INFORMATION MESSAGES 

Since many of the programs are iterative, they report the completion
of each iteration for user information.  CONCAVE prints a message as
it initializes each box, DOPOLYS reports how many polygons it found,
and SEED reports how many basin starts it seeded. 
 
LIMITATIONS 

The programs limit the number of samples to 4000.  CONCAVE has limits
of 400 for BOXNL and BOXNS.  PPUPDATE and PPTABLE have limits of 2000
pour point table entries.  If this table limit is encountered,
indicated by a STOP 72, it is possible to process the datset in
pieces.
 
STUDY AREA MASK 

A value of zero is recognized as study area mask. 
 
BRIEF PROGRAM DESCRIPTIONS AND PARAMETER LIST 

  CONCAVE - Fills depressions in a DEM. 
     Parameters:  NL,NS,BOXNL,BOXNS,OVERLAP,ELEV FILE,SYSTEM 
 
  COUNT - Computes flow accumulation values from flow direction
values. 
     Parameters:  NL,NS,CODE 1 TO RESTART,DIR FILE,COUNT
FILE,SYSTEM           
 
  DELTA - Computes flow accumulation increments from flow
accumulation values. 
     Parameters:  NL,NS,DIR FILE,COUNT FILE,DELTA FILE,SYSTEM 
 
  DIRECT - Computes flow direction values from a DEM. 
     Parameters:  NL,NS,CODE 1 TO RESTART,ELEV FILE,DIR FILE,SYSTEM
 
  DOPOLYS - Assigns unique labels to eight-way connected polygons.

     Parameters:  NL,NS,LINK FILE,MASK FILE,SYSTEM 
 
  FILLSNGL - Fills single-cell depressions in a DEM. 
     Parameters:  NL,NS,TOPO FILE,SYSTEM 
 
  MINIMA - Finds local minima and flats in a DEM. 
     Parameters:  NL,NS,TOPO FILE,MINIMA FILE,SYSTEM 
 
  OVERLAND - Traces overland paths for user-specified cell(s). 
     Parameters:  NL,NS,DIR FILE,MASK FILE,SYSTEM  
 
  PPTABLE - Builds a table of pour points for watersheds. 
     Parameters:  NL,NS,BASIN FILE,ELEV FILE,TABLE FILE,SYSTEM 
 
  PPUPDATE - Performs the final DEM update in the
depression-filling procedure. 
     Parameters:  NL,NS,BASIN FILE,ELEV FILE,SYSTEM 
 
  SEED - Finds starting points for automatic watershed generation.

     Parameters:  NL,NS,THRESHHOLD,EDGES,SEED FILE,DELTA FILE,COUNT
FILE,SYSTEM 
 
  WTRSHED - Finds watersheds for user-specified cell(s). 
     Parameters:  NL,NS,DIR FILE,MASK FILE,SYSTEM 
 
RECOMMENDED USAGE 

Regardless of the application, it is generally recommended that the
analyst always perform three processing procedures - fill depressions,
compute flow directions, and compute flow accumulation values.  If
possible, prior to these procedures, the quality of the DEM should be
verified by viewing a shaded-relief representation.  These
capabilities are intended to be used in combination with
general-purpose raster and vector spatial processing software to
provide utility functions, display, and plotting.
 
FILLING DEPRESSIONS 

Option One - Use the program CONCAVE.  The DEM should be a copy of the
original since CONCAVE uses the same file for input and output.
CONCAVE fills depressions in overlapping rectangles of BOXNL by BOXNS
dimensions with an overlap of OVERLAP.  Depressions not wholly
contained in one of the rectangles will not be filled.
 
Option Two - This option is faster than option one, but involves
running more programs.  First run FILLSNGL to remove single-cell
depressions.  Then run DIRECT to compute flow directions.  DIRECT will
leave flow direction values negative for at least one cell in the
bottom of each depression and will issue the message, "COULD NOT SOLVE
FOR ALL CELLS" if any cells are left negative.  Then run DOPOLYS which
finds all eight-way connected polygons of negative cells and labels
each polygon uniquely in a background of -1's.  The output dataset
from DOPOLYS must then be processed by the WTRSHED program, building
watersheds for each of the depressions.  This watershed mask, the flow
direction dataset, and the DEM from FILLSNGL must then finally be
processed by PPUPDATE which will fill the remaining depressions in the
DEM.
 
The depressionless DEM resulting from options one or two is referred
to as the LEV dataset.  All other datasets made in the
depression-filling process are temporary and should be deleted.
 
COMPUTE FLOW DIRECTIONS 

The DIRECT program should be run on the LEV dataset to produce a final
flow directions dataset, referred to as the DIR dataset.  The flow
direction is encoded as : 
                   64 128   1
                   32   x   2 
                   16   8   4      for any cell x, indicating to
which of its eight neighbors x flows.  This dataset differs from a
maximum drop aspect dataset in that flow is routed across flat areas.
 
COMPUTE FLOW ACCUMULATION VALUES 

The COUNT program should be run on the DIR dataset to produce the
COUNT dataset.  Each cell in the COUNT dataset receives a value equal
to the number of cells which flow to it.  The COUNT dataset usually
can be threshholded to produce a reasonable drainage line network.
 
MANUAL WATERSHED SEEDING 

If a watershed is desired for a particular feature or point, examine
the COUNT dataset to determine the cell or cells where a digital "dam"
would block the flow paths to the feature.  Use a general-purpose
raster processing system to insert positive-valued cells to represent
this "dam" in a background of -1's.  Use a unique value for each dam.
Process this watershed "seed" dataset with the WTRSHED program to fill
out the watershed polygons.
 
AUTOMATIC WATERSHED SEEDING 

A "seed" dataset may be produced automatically by the SEED program.  A
threshhold must be chosen by the user.  A watershed will be seeded at
every major tributary where the area draining to the tributary, as
indicated by the COUNT and DELTA datasets, exceeds the threshhold.  To
build the watershed polygons, run WTRSHED on this "seeded" dataset.
This process requires that the DELTA program be run previously.  An
EDGES parameter in SEED indicates whether or not the user wants a seed
to be built on the dataset edge where COUNT exceeds the threshhold.

 
MAKING A POUR POINT TABLE 

After watersheds have been built, the PPTABLE program may be used to
compute a table of pour points between watersheds.  The program
computes all possible pour points, since in some flat terrains there
may be multiple pour points that are close in elevation.  The table
must be edited to reflect the final linkages selected by the user.
 
TRACING OVERLAND PATHS 

To produce the overland path(s) for specific cells, such as pollution
sources, embed the cells as positive values in a background of -1's
and run the OVERLAND program on this seeded dataset.  The cells need
not have unique values, however each cell's value will be used in
marking its downstream path cells.
 
For DEMs with broad flat valleys or artifacts that make the COUNT
dataset unsatisfactory as a drainage network, another approach is to
run OVERLAND on the local minima in the DEM.  The local minima can be
isolated by running the MINIMA program on the original or the LEV DEM.
The minima will have a value of 2 in a background of -1's.  The MINIMA
program also isolates flat areas and marks them with a value of 3.
The locations of flats are valuable as indicators of areas that may
have yielded poor drainage lines.
 
RASTER TO VECTOR CONVERSION 

The watershed polygons can be converted from a raster to a vector
representation by the ARC/INFO GRIDPOLY function.  The raster drainage
lines can be converted to vector by software developed by Dave
Greenlee at EROS Data Center.  It is currently operational in a PC
environment and is being converted to a more generic form.  

