User's Guide

ANUDEM

Calculates a regular grid of values of a smooth surface fitted to large numbers of irregularly spaced elevation data points, contour lines, stream lines and sink points.

Function:

The program then employs a simple multi-grid method which calculates grids at successively finer resolutions, starting from an initial coarse grid, until the final, user specified grid resolution and simultaneously imposes sensible drainage conditions to remove sinks where possible. The program uses five different types of input data files. The five file types are:

     1. Point elevation data 
     2. Sink point data 
     3. Stream line data
     4. Polygonal line data
     5. Contour line data

Parameters:

DRAINOPT(0)
Drainage option. Level of drainage enforcement:


  = 0:  No drainage enforcement
  = 1:  Drainage enforcement where possible 
	(normal option)
  = 2:  Drainage enforcement with sink diagnostics
  = 3:  Drainage enforcement with full diagnostics
	(not normal used)

ELEVOPT(1)
Contour data option.


  = 0:  Elevation data consists mainly of spot heights
  = 1:  Elevation data consists mainly of contours

RIDGELEN
Maximum ridge length. Valid only if contour data option is 1. Inferred ridge lines are only enforced if their length is less than the maximum ridge length, e.g. 500m. No ridges are set if the maximum ridge length is zero. All ridges are set if the maximum ridge length is set to a very large value.

RMSVAL
Root mean square residual. For elevation data consisting mainly of scattered spot heights, set to zero. For elevation data consisting mainly of contours, set to 0.5-1% of the contour interval. e.g. set initially to 0.05 if the contour interval is 10. Increase the residual if contours calculated from the fitted grid at the same heights as the data contours show small crenulations (i.e. are crinkly).

MAXFLG(NO)
Maximum flag. If NO then local maxima in the fitted grid are not constrained to lie at data points. If YES then local maxima in the fitted grid are constrained to lie at data points. Normally NO for both contour line data and point data. Set to YES if spurious maxima are generated using NO and the data consists of well chosen point data which include all significant local maxima.

  = YES: Maxima not constrained
         to lie at data points.
  = NO:  Maxima constrained
         to lie at data points.

ROUGHVAL
Roughness penalty trade-off.

  = 0.0: Minimum curvature for contour data.
  = 0.5: Recommended for mixture of minimum curvature and 
         minimum potential (appropriate for spot heights).
  = 1.0: Approaching minimum potential (not recommended)

TOLVAL1
First elevation tolerance. First tolerance reflects accuracy of elevation data.

TOLVAL2
Second elevation tolerance. Second tolerance must exceed the first tolerance. Setting the second tolerance to be twice the first tolerance is a reasonable compromise between strength of drainage enforcement and elevation accuracy. Set the second tolerance to a higher value for poor quality or sparse data or to ensure more conservative drainage enforcement. When contour data is used set the second tolerance equal to the data contour interval.

TOLVAL3
Third elevation tolerance. Side conditions of streams are only set if they do not conflict with the data by more than the third tolerance and saddles which exceed adjacent sink heights by more than twice the third tolerance are not cleared by the drainage enforcement algorithm. See notes on the drainage enforcement algorithm.

MAXNUMIT
Maximum number of iterations. Normally 30 is adequate for most applications. Set to a larger value (say 35 or 40) if more sinks may be cleared or more streams and ridges may be set when using contour data. Iteration ceases for each grid resolution when the maximum number of iterations has been reached.

MINHT
Minimum elevation height limit. Data points less than MINHT are ignored, and the fitted grid values are constrained to lie between MINHT and MAXHT.

MAXHT
Maximum elevation height limit. Data points greater than MAXHT are ignored, and the fitted grid values are constrained to lie between MINHT and MAXHT.

RESFILE(--)
Residual File Name. Name of file where all residuals larger than the specified minimum residual are written. If defaulted then no residuals are calculated.

RESVAL(1)
Minimum residual value. Include only if the residual file name (RESFILE) is not blank. All data points whose residual exceeds the minimum residual are calculated and written to the user specified residual file. The true root mean square residual from the final grid of all data points, in their true positions, which lie within the user specified limits (and polygon limits), is also calculated and written to output.

XMIN
Minimum X longitude. Data points less than XMIN are ignored.

XMAX
Maximum X longitude. Data points greater than XMAX are ignored.

YMIN
Minimum Y latitude. Data points less than YMIN are ignored.

YMAX
Maximum Y latitude. Data points greater than YMAX are ignored.

GRDSPACE
Grid spacing. The resolution of the final grid. The spacing should divide the X and Y ranges an integral number of times. The number of grid points in the X direction is (XMAX-XMIN)/GRDSPACE+1 and the number of grid points in the Y direction is (YMAX-YMIN)/GRDSPACE+1. (See User Note #3)

DATAFMT("2F18.6, F12.1")
Data file (x,y,z) format, at most one point per record.

SINKFMT("2F18.6, F12.1")
Sink data file (x,y,z) format, at most one point per record.

STRMHFMT("I9, 2F9.1")
Data file header format for reading no. of coordinate pairs, height of first point, and height of last point.

STRMPFMT("2F18.6")
Data file line string format, more than one point per record allowed.

POLYHFMT("I9, 2F9.1")
Data file header format 4 - for reading no. of coordinate pairs only.

POLYPFMT("2F18.6")
Data file line string format, more than one point per record allowed.

CONTHFMT("I9, 2F12.1")
Data file header format 5 - for reading no. of coordinate pairs and height of contour line.

CONTPFMT("2F18.6")
Data file line string format, more than one point per record allowed.

OUT
Output image. The LAS output image calculated from the input elevation data files.

ODTYPE("I*2")
Output data type of OUT.


  = SAME: Same as input
  = BYTE: BYTE      ( 8-bit unsigned integer)
  = I*2:  INTEGER*2 (16-bit signed integer)
  = I*4:  INTEGER*4 (32-bit signed integer)
  = R*4:  REAL*4    (32-bit signed real)

SINKOUT(--)
Sink output file name. If specified, remaining sink points in the final grid are written to this file for later plotting.

STRMOUT(--)
Stream output file name. If specified, stream lines and ordered chain conditions, as incorporated in the final grid, are written to this file for later plotting.

INFILE
Input data files. The input data files should be specified using Unix name conventions.

IFTYPE
Input data file type (1-5).

  = 1:  Data point file
  = 2:  Sink point file
  = 3:  Streamline file
  = 4:  Polygon file
  = 5:  Contour file

Examples:

  1. LAS> anudem in=("data/point.dat","data/sink.dat", "data/stream.dat" "poly.dat","contour.dat", "data/contour.dat") iftype=(1,2,3,4,5,5) out=[smith.images]elevation ridgelen=100000000 rmsval=0.05 xmin=51.5 xmax=53.5 ymin=28.5 ymax=30.5 minht=0 maxht=12000 grdspace=0.00416666667 tolval1=10 tolval2=20 tolval3=150 maxnumit=25

    The user has specified six input files. Two input files are of type 5 (contour line data). Note the input file names are specified using Unix file names and the output image [smith.images]elevation using a LAS file name.

  2. LAS> anudem in="data/point.dat","data/stream.dat" "data/contour.dat","data/contour2.dat) iftype=(1,3,5,5) out=elevation ridgelen=100000000 rmsval=0.05 xmin=51.5 xmax=53.5 ymin=28.5 ymax=30.5 minht=0 maxht=12000 grdspace=0.00416666667 tolval1=10 tolval2=20 tolval3=150 maxnumit=25 contpfmt="2f12.6" conthfmt="i6,2f10.1" odtype="real"

    The user has specified a four input files. Two input files are of type 5 (contour line data). The user also specified a format for the contour data files. By specifiying the CONTPFMT and CONTHFMT both contour data files must be in the specified format. The output image is named elevation and is created in the current library and is of data type real.

Description/Algorithm:

Description

Detailed specifications of each type of data file are given below. The program first reads input data points from each input data file, windows the data to the user specified map limits and then generalizes the data to the user specified grid resolution. Point data are generalized by accepting at most MAXW data points per grid cell (currently MAXW=4) and discarding any remaining points. Line data are generalized by accepting at most one line data point per grid cell, and, in the case of stream line data, removing unnecessary kinks. The selected data points are written to unformatted scratch files, one file for each of the five types of data, for quick retrieval during program execution.

The program then employs a simple multi-grid method which calculates grids at successively finer resolutions, starting from an initial coarse grid, until the final, user specified grid resolution and simultaneously imposes sensible drainage conditions to remove sinks where possible according to the algorithm described above. For each grid resolution, the accepted data points are read from the five scratch files and values at grid points not occupied by data points are calculated by Gauss-Seidel iteration with overrelaxation (SOR method) subject to an appropriate roughness penalty and ordered chain constraints. The ordered chain constraints are obtained from user supplied stream line data, sink point data and contour line data and by automatic drainage enforcement as calculated by the program. Iteration terminates when the user specified maximum number of iterations (normally 25) has been reached. Starting values for the first coarse grid resolution are calculated from a least squares plane fit to the data points. Starting values for each successive finer grid are linearly interpolated from the preceding coarser grid.

On completion of the multi-grid iterations, the program calculates all sink points remaining in the fitted grid and optionally writes a detailed summary to output. These sink points are also optionally written to a user specified file for plotting. The program optionally calculates the true root mean square residual from the fitted grid of the data points in their original positions, using bilinear interpolation across the grid cells. Stream line information, as incorporated onto the grid, is also written to a LAS image file.

Algorithm

The program has been designed to produce accurate digital elevation models with sensible drainage properties from comparatively small, but well chosen, elevation and stream line data sets. It normally achieves this by imposing two critical, but optional, assumptions on the input elevation data: 1. That the elevation data points include ALL significant local maxima.

2. That the input data include ALL significant local minima (sink points).

The algorithm implemented by the program interpolates the elevation data onto a regular grid by minimizing a suitably weak roughness penalty on the fitted grid values and by simultaneously imposing constraints which take into account these two assumptions.

The first assumption, which is optional, is incorporated simply by permitting local maxima to lie only at grid points to which data points have been allocated. This removes the spurious peaks away from data points often generated by general purpose interpolation techniques. The first assumption may be dropped when input elevation data consists principally of detailed contour lines since these data do not normally include local maxima. The program then interpolates heights of local maxima on the basis of the surrounding contour height information.

The second assumption is incorporated by imposing a global drainage condition on the fitted grid values which automatically removes spurious sinks or pits. This is the principal innovation of the program. It eliminates one of the main weaknesses of elevation grids produced by general purpose interpolation techniques which has limited their usefulness in hydrologic applications, particularly those which rely on the automatic calculation of catchment areas.

Moreover, the imposed global drainage condition has been found in pratice to be a powerful condition which can significantly increase the accuracy, especially in terms of their drainage properties, of digital elevation models interpolated from sparse sets of surface specific data. The size of such data sets can be at least an order of magnitude smaller than the number of points normally required to adequately describe elevation using digitized contours. This minimizes the expense of obtaining reliable digital elevation models in terms of the capture, correction and storage of primary elevation data. The global drainage condition also virtually eliminates the need for detailed manual editing of interpolated elevation grids to remove spurious drainage features.

The second of the two assumptions above is not as critical as the first, since the program acts conservatively when attempting to remove sinks and does not impose drainage conditions which would plainly contradict the elevation data. A consequence of this is that errors in both elevation and position of input elevation data can often be indicated by sinks in the final fitted grid, especially when the input data includes at least the principal stream line networks. This is highly useful when processing very large data sets, and the program can optionally write out diagnostic information for each sink to assist in the correction of data errors. The number of such sinks is usually quite small. The conservative nature of the program imposed drainage conditions also makes the program quite robust to moderate errors in the positions of input stream line data and capable of producing generalized (coarse resolution) elevation models with appropriately generalized drainage properties.

Drainage enforcement algorithm.

The global drainage condition is imposed by attempting to remove all sink points which have not been identified as such in input sink data files.

The essence of the drainage enforcement algorithm is to find for each sink point the lowest adjacent saddle point which leads to a lower data point, sink or edge, and then, provided an elevation data point has not been allocated to the saddle, enforcing a descending chain condition from the sink via the intervening saddle to the lower data point, sink or edge. This action is in fact modified by the systematic application of three user supplied tolerances. These tolerances allow the user to adjust the strength of drainage enforcement in relation to both the accuracy and density of the input elevation data.

The detailed action of these tolerances has undergone considerable development and testing with data sets of varying densities and accuracies at a variety of scales. The aim has been to achieve the strongest possible drainage enforcement without making serious errors in the placement of drainage lines, particularly when the input data is limited in terms of accuracy or density. The action of the tolerances naturally becomes less critical as the accuracy and density of the input data improves. When the tolerances have been set appropriately, the sink points not cleared by the program are normally those associated either with significant elevation errors in input data or with areas where the input data are not of sufficient density to reliably resolve the drainage characteristics of the fitted grid.

The first user supplied tolerance should principally reflect the elevation accuracy of the input data points but can also reflect the density of the input elevation data. Elevation differences between data points not exceeding this tolerance are judged to be insignificant with respect to drainage. Thus data points which block drainage by no more than this tolerance are removed. When data points are not sufficiently dense to accurately resolve drainage, this tolerance may be increased somewhat and will yield a slightly generalized drainage pattern at the expense of fidelity to the elevation data. This is especially useful when working at smaller scales (less than say 1:100,000). The first tolerance is also used when searching for possible clearances for sinks, to slightly favour those saddle points which are not associated with data points over saddle points which are associated with data points.

The second tolerance limits the height above each data point sink of data point saddles which may be considered as possible exits from the sink. This can remove from consideration certain data point saddles, even though they are the lowest saddle associated with particular sinks, in order to allow drainage clearance via a higher non-data point saddle. This tolerance normally has a significant effect only when data points are relatively sparse. Setting the second tolerance to its minimum allowable value of twice the first tolerance is applicable when data point density is only just sufficient to accurately resolve drainage characteristics. Setting the second tolerance to a larger value ensures that the program acts conservatively when attempting to remove sinks and consequently more sinks may remain in the final grid. This is appropriate when data point density is not sufficient to completely resolve the drainage characteristics of the fitted grid. The user may wish to remove remaining sinks by adding more data points or streamlines in critical areas in this case.

Drainage enforcement can also be obtained by incorporating stream line data. This is useful when more accurate placement of streams is required than can be calculated automatically by the program. It can also be used to remove sinks which would not otherwise be removed by the automatic drainage enforcement algorithm. This is in fact the recommended way to correct drainage anomalies in elevation grids calculated by the program. All elevation data points which conflict with strict descent down each stream line are removed, with all conflicts which exceed the third user specified elevation tolerance being written to output for possible correction of errors. Side conditions are also set for each stream line. These ensure that the stream line acts as a breakline for the interpolation conditions and simultaneously ensure that each stream line lies at the bottom of its accompanying valley. Side conditions are not set for data points beside streams whose elevations are more than the third tolerance below the height of the stream. These conflicts are written to output for possible correction of errors. The third elevation tolerance is also used to prevent automatic clearances of sinks via saddles whose elevation exceed the height of the sink by more than twice the value of the third tolerance. Such situations are normally caused by significant elevation errors but can also arise when data points are very sparse.

Nonfatal Error Messages:

    None.

Fatal Error Messages:

  1. [anudem-files] Number of INFILE's does not match number of IFTYPE's

    The error is caused by an unequal number of INFILE's and IFTYPE's. Each input file needs to have a type specified.

  2. [anudem-size] Output image size to large

    The applications can not support images larger then 3600x3600. By decreasing the the GRDSPACE paramter the image size will be smaller.

  3. [anudem-runtime] Execution error encountered

    Execution of the program has caused an error to be returned. The cause of this may be due to low resources on the host computer.

  4. [anudem-open] Fatal error opening output image

    An error occurred when the application attempted to create the LAS image. The LAS image may already exists or the LAS image could not be created. A more detailed description will be printed on the line above this error message

  5. [anudem-close] Fatal error closing image

    An error occurred when the application attempted to close the LAS image. A more detailed description will be printed on the line above this error message

  6. [anudem-write] Fatal error writing image

    An error occurred when the application attempted to write to the LAS image. A more detailed description will be printed on the line above this error message

User Notes

  1. Format of input data files is as follows:

    Elevation data points.

    Each file contains ordered X,Y,Z triples which denote the position and elevation of each data point, with at most one data point per record. For each grid resolution, these data points are allocated to the nearest grid point. If more than one data point is allocated to the same grid point, then the average value is taken, with no more than MAXW data points being considered for each grid point. MAXW is a program supplied parameter (See User Note 4). There is no limit on the number of input elevation data points read from the user supplied data files.

    Sink data points.

    Each file contains ordered X,Y,Z triples which denote the position and elevation of nominated sink points. The program will not attempt to remove sinks at such points. The height of a sink point can be left unspecified by setting the Z value to a value lying outside the user specified height limits (MINHT and MAXHT).

    Streamline data points.

    Each file contains strings of X,Y coordinate pairs, in order of descending elevation, each string being preceded by a header which contains, in order, the number of coordinate pairs in the following string, the height of the first coordinate pair and the height of the last coordinate pair. These heights can be left unspecified, in a similar manner to sink point elevations, by setting them to values lying outside the user specified height limits. However, the coordinate pairs in each streamline must be ordered from highest point to the lowest point, since the values in the grid are constrained to descend down each streamline. Streamline data take priority over point elevation and contour line data. Thus elevation data points which conflict with descent down each streamline are ignored.

    Polygonal data points.

    Each file contains strings of X,Y coordinate pairs, each string being preceded by a header which contains the number of coordinate pairs in the following string. Each string or consecutive group of strings must close within a program calculated tolerance to form a closed polygon. Polygons with an area less than a small fraction of the area of one grid cell are ignored. Points in the final output grid which lie outside the polygons specified by these line strings are set to a program determined special value which is less than the user specified minimum height limit. This special value is written to output. If no polygon strings are read then no grid points are set to special values.

    Contour lines.

    Each file contains strings of X,Y coordinate pairs, each string being preceded by a header which contains the number of coordinate pairs and the height of the contour line. The heights of the points making up the contour are incorporated into the grid.

  2. Tolerance values range according to the scale and other characteristics of the input data. Typical values for adequate data at a scale of 1:100,000 are: 5.0 20.0 100.0, for TOLVAL1, TOLVAL2 and TOLVAL3 respectively. Values for less dense data at a scale of 1:500,000 are: 10.0 20.0 150.0. Typical values for contour data with a contour spacing of 10 are: 2.5 10.0 50.0.

  3. The GRDSPACE paramter determines the size of the output image. If the image is to large for ANUDEM (See User Note #4) the processing will fail. To decrease the size of the image a larger GRDSPACE should be specified.

  4. Some paramters cannot be specified by running ANUDEM from TAE or from the Unix command line. These paramters are set as maximum values which are limitations of the program. Some of these parameters are dependent upon the size of the output image. Some of these paramters are as follows:

    	Image size	Parameter	Value
    	----------	---------	-----
    	0   -900	MAXSIZE		901
    	901 -2000	MAXSIZE		2001
    	2001-3600	MAXSIZE		3601
    	0   -900	MAXW		4
    	901 -2000	MAXW		8
    	2001-3600	MAXW		8
    	0   -900	MAXFIL		80
    	901 -2000	MAXFIL		80
    	2001-3600	MAXFIL		80
    
    	MAXD    = MAXSIZE*MAXSIZE/4 MAXM    = 2 * MAXSIZE MAXREF  = 6
    

  5. ANUDEM can also be run from the unix command line. This may be neccessary if more flexibility is needed when specifying the format of the input data files. It is also required when an output file type other then a LAS image is needed. Other possible output file types are: grid values by rows, (x,y,z) format, standard USGS (ARC/INFO) DEM format, or ARC/LAS BIL format with ARC header.

    The size of the output image (See User Note #3) determines which program to execute. If the image is between 0 and 900 then run anudem_sm, between 901 and 2000 then run anudem_med, and between 2001 and 360 run anudem_lg. Larger images are not supported. The exact syntax for this is as follows:

         $LASLOCAL/anudem_sm		(images 0    -    0)
         $LASLOCAL/anudem_med		(images 901  - 2000)
         $LASLOCAL/anudem_lg		(images 2001 - 3600)
    

    The program will then be prompt for the parameter inputs. Note that the parameters are in the same order as in this user guide.

  6. Anudem was written by: M.F. Hutchinson, Centre for Resource and Environmental Studies, Australian National University, G.P.O. Box 4, Canberra ACT 2601.

    The source code was purchased and maintained by M.F. Hutchinson. The last revision made to the algorithim of ANUDEM was on March 11, 1991. The modifications made at EROS Data Center were made to accomodate various input and output data needs.

    The program ANUDEM is written in FORTRAN 77 and all Modifications made at EROS Data Center were made in ANSI C.