INSTRUCTIONS - ArcView GIS Basin1 Extension

Extension Particulars

Extension Name:  Basin1
Software:  ArcView GIS
Programming Language:  Avenue
Date of Completion:  11 April 2000
Date of Revision:  12 February 2003
Institution:  Department of Water Affairs & Forestry, Pretoria, South Africa
Author:  Ivan Petras


Contents of the

Basin1.avx - the ArcView GIS extension
Read_1st.txt - basic information
Tips.doc - tips on DEM and Hydrological Analysis

Instructions.doc - this document

Short Description

Extends the Spatial Analyst user interface for the following functions:

The extension adds new icons in the Button Bar and Tool Bar. Their functionality is described below. The reference to the icon name in the following text is by the first part of the help string, i.e. by the text displayed below the icon on a yellow background when the mouse pointer is positioned over the icon.

 Background information

 The team of Engineering Decision Support Section of the Department of Water Affairs and Forestry (DWAF) in Pretoria, South Africa, developed Hydrological Modelling System involving Digital Elevation Models (DEM) in 1955. The system was developed in ArcInfo using Arc Macro Language (AML) and included more than seventy AML programs.

After ArcView 2.1 was released, some of AMLs were transferred to the ArcView platform. Scripts dealing with delineating a catchment from a point defined by user were adapted for use with ArcView GIS “Watershed” Extensions in 1997. ESRI and other scripts were modified and included too. Before the Watershed Extension was tested for errors, one of the team members without consulting the team published it in various GIS web sites. The following information might be of interest to those who have downloaded and used the Watershed.  The attribute table of a catchment delineated by using Watershed displayed the following incorrect values:

The errors discovered during the intensive testing of Watershed have been fixed, its scripts enhanced and included in Basin1 Extension. Enhancement of Watershed scripts among other includes their modifying to eliminate frequent ArcView error messages and adding message boxes to guide and inform the user during the process. New functions in Basin1 include the start up script written to disable icons before properties are set, to avoid error messages, the delineation of stream network, display of raindrop path traced from point defined by user, and display of elevations extracted from grid and surface for points defined by user.

The Basin.StreamNetwork script attached to the Basin1's StreamNetwork button is a result of a modification and enhancement of Hydro.StreamNetwork script supplied with the ESRI Hydrologic Modelling v1.1 extension. The functionality of the StreamNetwork button includes new features as follows:

The Basin.RaindropPathTool script attached to the Basin1's RainDropPath button is a modification of the Hydro.RaindropTool script supplied with the ESRI Hydrologic Modelling extension. The script is modified for use with the Basin1 extension. The path is returned in blue colour.


ArcView 3.1, Spatial Analyst 1.1 (or later), Elevation Grid with sinks filled, Flow Direction Grid and Flow Accumulation Grid. Setting the above grid themes by running the Basin.InitiateButton script attached to the Initiate icon in a Button Bar. Elevation Grid theme must be active in View's Table of Contents (TOC) before clicking on the Initiate icon. Requires projected data and metres as map units.

The Basin1 Extension is dependent on the Spatial Analyst Extension. Because of a defined dependency, the Spatial Analyst Extension is loaded automatically with the Basin1 Extension. Its check mark will be an outline instead of being solid in the Extensions dialog.




Description:  Sets Elevation Grid, Flow Direction Grid and Flow Accumulation Grid required by the Basin1 Extension. Allows the user to add the Elevation Grid from a file, if one is not available or active in TOC. Allows the user to select Flow Direction and Flow Accumulation Grids. The grid selection options are from the View, import from a file and create from a grid.

Requires:  The Initiate button must be executed before starting analysis to set properties required by the Basin1 and to enable its icons. The grid theme must be active in TOC before the script allows setting the properties. The active grid theme must be the Elevation Grid. If no grid theme, more than one grid theme or a feature theme is active in TOC instead of the Elevation Grid, the user is directed to select the Elevation Grid.

WARNING: If any other grid theme than the Elevation Grid is active in TOC before executing the Initiate button, properties are set but results of analysis will be incorrect.

Runs:  Basin.DisableStartUp script. The script disables Basin1's icons when the project is open, i.e. before Basin1 properties are set. The icons are enabled after executing the Initiate button.

Help String:  Initiate//Sets Basin1 extension properties and enables its icons. Elevation Grid must be active in View's TOC !


Description:  Creates a vector stream network from a Flow Accumulation Grid based on a user specified threshold. Allows the user to specify the file name and directory in which to save a shape file of generated streams. Allows the user to choose between Strahler and Shreve stream ordering methods. The theme attribute table displays stream order and stream link length values.

Help String:  StreamNetwork//Generates a stream network from a Flow Accumulation Grid (Please, execute the "INITIATE" button to enable this icon).




Description:  Delineates a catchment from a point defined on a stream by a user and calculates the catchment's characteristics. A grid of 4x4-cell extent represents the user defined point. Allows the user to specify file name and directory in which to save a shape file of a delineated catchment. The theme attribute table displays calculated characteristics of the delineated catchment in the following fields:

Area_km2 - Catchment area (A) in kilometres square

Perimet_km - Catchment perimeter (P) in kilometres

Sl_min_prc - Minimum catchment slope as a percentage

Sl_max_prc - Maximum catchment slope as a percentage

Sl_ave_prc - Mean catchment slope as a percentage

El_min_m - Minimum catchment elevation in metres

El_max_m - Maximum catchment elevation in metres

El_ave_m - Mean catchment elevation in metres

El_stdev - Standard deviation of a catchment elevations

L_max_km - Length of the longest watercourse (L) in kilometres. The distance from the pour point along the longest watercourse to the catchment boundary.

L_eqv_km - Equivalent length of catchment (Le) in kilometres. The longer side of rectangle which has the same area and perimeter as the catchment.

Le = (P+(P^2-16*A)^0.5)/4 (traditional operator precedence rule is used to show the formula). If P^2-16*A < 0 then the script returns Le = NIL, i.e. the corresponding cell in the attribute table has no value. P^2-16*A = 0 applies to a square and P^2-16*A< 0 to a circle.

L_relat - Relative longest watercourse length (Lr), dimensionless. Large values indicate an elongated catchment or meandering river. Lr = L/A^0.5. (Used by the Department of Water Affairs and Forestry, South Africa).

Help String:  BasinDelineate//Delineates a drainage basin for the point defined by a user and calculates basin's characteristics. (Please, execute the "INITIATE" button to enable this icon).

Tip:  Create a temporary directory e.g. "Bas_del" for a project, make it the working directory and save delineated catchments there.


Description:  Traces the path of a raindrop from a point defined by a user to an outlet. Returns a blue graphic line.

Help String:  RainDropPath//Traces the flow path of a raindrop (Please, execute the "INITIATE" button to enable this icon).


Tool Menu

Click on the Tool Menu to display a pull down palette of the ElevationPointSurface and ElevationPointGrid tools and drag to a particular tool. ElevationPointSurface is the tool visible in the Tool Bar by default when a project is open.


Description:  ElevationPointSurface returns X and Y co-ordinates and an interpolated Z value for a point defined by a user on the surface defined by the Elevation Grid. The point is displayed in magenta colour. Interpolating from the four nearest cell centres derives the interpolated Z value for the point. The first two lines are interpolated between the cell centres in the Y direction. Then a line is interpolated from these two lines in the X direction that intersects the point. Finally the point's elevation is interpolated from this line. All interpolations are linear.


Help String:  ElevationPointSurface//Extracts the elevation of a point (magenta) from a surface. (Please, execute the "INITIATE" button to enable this icon).


Description:  ElevationPointGrid returns the user defined point's X and Y co-ordinates and the Z value of the cell in the Elevation Grid that contains the point. The point is displayed in green colour.

Help String:  ElevationPointGrid//Extracts the elevation of a point (green) from a grid - cell value. (Please, execute the "INITIATE" button to enable this icon).

File basin_tips.htm contains additional information.



Dr Ivan Petras, Pr. Eng.
Specialist Engineer
Department of Water Affairs & Forestry
Private Bag X313
Pretoria, South Africa 0001