In this exercise we will customize Arcview using scripts that utilize
the raster functionality provided by the Spatial Analyst extension.
We will look at how to use the Customize menu, how to add scripts from
ascii files, how to compile those scripts and attach them to both buttons
and tools. You will be using the work from this part of the exercise
in the script writing exercise so be sure to save your project.
General setup
Using the Customizing menu
Scripts
Attaching scripts to buttons
Results
Attaching the script to a tool
Using the new tool
General Setup
Please use the ashfield_nos DEM in /mit/gis/data/grids for this exercise. You willl need to attach the gis directory before you start Arcview:
Athena% attach gis
Bring up Arcview.
add arcinfo; arcview
Once Arcview starts, use the File->Extensions menu choice and add the Spatial Analyst extenion to your project. Even though we will use scripts we built here, we are using requests that are available through this extension.
Open a new view and add the ashfield_nos grid to the view.
Now double click in the area to the right of the button or tool controls to get the Customize interface. You will use this interface to add buttons and associate scripts with the buttons. When you click on the button, the script you associated with the button will run. This is what the Customize interface looks like:
Arcview allows you to add widgets (menus, buttons, tools, and popups)
to all of the document types that Arcview supports (View, Table, Chart,
Layout, Script, Project, and Application). In this exercise we will
add a button to the View interface. To do so, you will need to change
the "Type" to View and the "Category" to Buttons.
Select the Add Theme button: 
.
Notice that there is a Click property with the value of "View.Add".
This is the script that runs when you press the button. Select the
ZoomIn button: 
. This
also has an associated script, called "View.ZoomIn". Notice that
the Diabled Property is set to True. This is because there are no
active themes so Arcview doesn't know how to Zoom In. Add your DEM
and then look at the properties. Remember to add the Spatial Analyst
Extension or you won't be able to add the DEM as a Grid Data Source.
This won't be one of the available Data Source Types until you
add the Extension (Using the File->Extensions menu choice)
Once you get the DEM loaded, you should see that ZoomIn is not disabled.
It now has a spatial frame of reference that includes x, y extent and scale.
Importing scripts and adding buttons and tools and associating the scripts with the new controls.
Adding a script to the project
There is a script that take the elevation grid (Digital Elecation Model)
and creates a Flow Direction grid and then creates a Flow Accumulation
grid from the Flow Direction grid. The Flow Direction grid shows
which direction water will flow to from all of the cells in the Grid.
There are only 8 possible directions for water to flow to and are represented
by the following matrix of cells surrounding any cell in the grid:
| 32 | 64 | 128 |
| 16 | x | 1 |
| 8 | 4 | 2 |
These numbers seem arbitrary but are uniform across grids created with this command. "32" indicates that water will flow from the current cell(0,0) to cell(x-1,y+1). "4" indicates that water will flow from the current cell (0,0) to cell(x,y-1). The Flow Accumulation grid indicates how many cells are upstream or upslope of the current cell. This is useful for flood forecasting and stream ordering. The area represented by the cell is the number * area of each cell. The area is the (cell size * cell size). You should be aware of the units and the cellsize of your DEM. The DEM imported from the USGS website for this exercise has a cellsize of 30 meters so each cell represents an area 30 meters by 30 meters or 900 square meters. The number of cells in the Flow Accumulation Grid for any given cell represent the total area contributing water flow to that cell (number of cells * 900 square meters).
You should attach the /mit/gis directory (which you needed to do to access the ashfield_nos DEM) in order to find the script to run these commands. If you didn't do this already, you should now run this command at the Athena prompt in a tty (xterm) window:
Athena% attach gis
Go back in Arcview, make the project window active:
Select "Scripts" from the Project Window and make a new script window
using the NEW button in the Project window. Notice the new
menus, buttons, and tools that are available when a Script is the active
document. These are the three buttons used for getting and writing
out scripts: 
.
The first button is for loading system scripts into the current script
window. The second button is for loading scripts available through
Athena. The third is for witing scripts as UNIX text files .
Use the middle button to load /mit/gis/programs/avenue/flowacc.ave
into your script window. Change the script name to _flowacc using
the Script->Properties menu choice. Use the "_" so
that you will be able to find the script among the many system scripts.
Also change the font size on this menu.
These are the compile (check) and run buttons: 
.
Press the compile button to check for any errors. The compiler doesn't
actually compile the code as a "c" compiler creates a binary that can be
executed. This compiler is really a lint checker, it simply points out
inconsistencies in the Avenue script. Even after you compile a script,
you can have run time errors. Care should be taken to check the result
of many commands that expect to return an object.
Attaching Scripts to Buttons
Once you have compiled the script, bring up the Customize interface (double click to the right of the controls on the button or tool bars. Make View as the Type and Buttons as the Category. Create a new button (NEW) and associate the new script with the Click Property. Double clicking on Property will give you the full list of system scripts and the script you just saved. You script should be easy to find at the end of the list of scripts if you have a special character as the first character of its name. Double click on the Help component and give a help message ("using the first active theme, creates a flowdirection and flowaccumulation grid"). Add an icon by clicking on the icon property and selecting one of the stock icons. This scripts assumes a single active Grid theme and will crash if that isn't true. We'll correct this later.
Results
Let's look at the script. We will see that we are making two grids. First, you send the FlowDirection request to the DEM object, returning the FlowDir object (Grid). Then you send the FlowAccumulation request to the FlowDir object, returning the FlowAcc object (Grid). Then you add both of these Grids to the view as Grid Themes.
Now make the view the active document and try running the new button you just created. The script runs immediately after you press the button. Now double click on the legend entry to get the Legend Editor menu.
Click on the Classify ... button so we could change the way the color scheme was created. This Classify ... button brings up the Classification menu. Change the Type to Standard Deviation. Then Click OK on this menu and Apply on Legend Editor menu. You should be able easily see channels. You could refine this classification by manually changing the Values in the Legend Editor. The Labels will change automatically. Check your numbers in the value column - Arcview won't tell you if you left large gaps in your numbers.
Your view should look like this after make you the FlowAccGrd active and visible and then reclassified the grid using standard deviations. These made the stream channels obvious. The apparent discontinuity is an artifact of screen resolution.
Adding a script and attaching it to a tool
The principal difference between buttons (which we added above) and tools is that when you press a button the action (running a script) is taken immediately whereas when you press a tool, you select the cursor that interacts with the map and change the action (running a script) that will occur after you press the mouse button with the cursor over the view. The stock tools (Identify button, Zoom in, and Zoom out) behave like this. If you have selected the identify cursor and then press the mouse button over the active theme, a script (View.Identify) is run. You can look at the tool using the Customize window and see the script that is associated with the Apply event (i.e., when you actually click with the cursor over the view).
We will add a tool and associate a script with this tool so that the script is run when
Go back to the Project window and make Scripts the Active interface again. Creating three new scripts and add the following files to these: downstream1.ave, downstream2.ave, and loadtable.ave. All of these scripts are in the /mit/gis/programs/avenue directory. You should retain the naming convention, except add the "_" at the beginning of each name and drop the ".ave". This makes the scripts easier to find in the list of scripts. Also, _downstream1calls _downstream2 which calls _loadtable. You will need to compile _downstream1 before _downstream2 since there are global variables set in _downstream1 that are used in downstream2. Before running this code, attach the gis directory:
Athena% attach gis
The program and a legend that are used in these scripts are located in that directory.
Attach _downstream1 as the Apply property for a new tool.
To do this you need to change the Type to View and the Category
to
Tools.
Use "Tool" to make a new tool. Add a help response, change the cursor
to the CrossHair cursor by clicking on Cursor and selecting a cursor
from the Picker menu, and add an icon by clicking on Icon and selecting
an icon from Icon Manager menu:
Since _downstream1 calls _downstream2 and _loadtable, you need to associate one script with the Apply function of the tool.
Using the new tool
Before running the tool, make sure the Spatial Analyst extension is active or the scripts will fail with any error messages. To open the extension, or check whether it is active, use the File->Extensions menu choice. This opens the Extension menu. If the extension has a checkbox, the extension is active. If it isn't, check the box. The checkbox may be gray if you there are elements of the project that rely on Spatial Analyst. If Click on OK in either case.
We could insert this code snippet at the beginning of _downstream to check whether the extension was loaded. Use the Athena Copy and Paste to copy the code snippet from this window. You will need to use "Control-v" to paste it into the script window. When you are using Windows machines, you will need to use "Control-c" to copy this from your browser.
result = Extension.Find("Spatial Analyst")
if (result = nil) then
MsgBox.Info("Please add the Spatial Analyst extension before
using this tool","Error")
return nil
end
This checks if the extension was loaded. If the result is "nil", i.e., the extension was not loaded, the script will return control to Arcview.
Now try running the tool. Make the view the active document, click on your new tool, bring the cursor over the DEM and select a point. Make sure the FlowAccGrd is the active grid. You should be prompted for a new grid name. This grid will contain cells that are downslope and downstream of your selected point. The table "tablename" contains three columns of data, the Elevation, and the FlowAccumulation for all the cells in the grid.