In the first part of this exercise, we explored “what if” scenarios using Macro Modeler. This section of the exercise will explore the use of IDRISI Macro Language to construct macros. Unlike using the graphical interface with Macro Modeler, macros are strictly-script based and provide slightly different capabilities. However, all module functionality found in Macro Modeler is based on TerrSet Macros. This exercise will cover the exact same “what if” scenario covered above with Macro Modeler, but using macros. The assumption is that the same planners who set the four criteria for the suitability study in Exercise 2-3 later decide that slopes up to 4 degrees rather than 2.5 degrees should be considered suitable for development.
We can automate our analysis through the use of macros. A macro is sometimes referred to as a meta-program since it is, in effect, a program that executes a set of programs. In TerrSet, a macro is an ASCII file that lists each module to be used and all the parameters required for its execution. The entire set of modules may be executed by simply entering the macro filename in the Run Macro dialog box called from the File menu. If we had a macro built for our suitability analysis, we could easily use Edit to change any module parameters (e.g., 2.5 to 4.0 for the slopes reclassification step) and then we could run the entire process again.
For each TerrSet module that can be used in a macro file, there is a specific format known as the macro command format. The syntax of these commands may be found in the description of the modules in the on-line Help System. The format always begins with the module name, followed by an X to indicate that parameters should be taken from the file rather than from the dialog box. Next, all the parameters needed for the execution of the module are given in a specific order and format, separated by asterisks (*). These parameters supply all the information you would enter into the dialog boxes if you were using the modules interactively.
Input and output filenames in macros may optionally include filename extensions and/or paths. If no extension is given, the logical extension for that operation is added automatically. For example, when an image is required, entering LANDUSE or LANDUSE.RST in the macro will
EXERCISE 2-4 EXPLORING THE POWER OF MACRO MODELER 90
produce the same result. As with the interactive use of TerrSet, full paths may be given for input and output filenames. If no path is given, the program first looks in the Working Folder, then in each Resource Folder until it finds the specified input file. For output, if no path is specified, the file is written to the Working Folder.
Macro files must have the extension .IML (for IDRISI Macro Language). If created in the TerrSet Edit module, the proper extension will automatically be added if you choose to save as a macro file.
Note that some modules do not have a macro command version. These are typically modules that do not produce a resulting file (e.g., TerrSet Explorer) or modules that require interaction from the user (e.g., Edit). In the menu, any module written in all upper-case letters may be used in a macro. For more detailed information, see the section on Command Line Macros in the chapter TerrSet Modeling Tools in the TerrSet Manual.
In this exercise, we will write a macro for the analysis that was done interactively in Exercise 2-3. All the modules we used in that exercise are available for use in macros except Edit. Since Edit is not available for the macro, we can either produce the values files necessary for use with ASSIGN prior to executing the macro, or we can replace the Edit/ASSIGN steps with RECLASS steps. We will do the latter.
R
Let’s first look at the steps needed to create the image SLOPEBOOL from the elevation model RELIEF as shown in Exercise 2-3.The first module we used was SURFACE. Go to the TerrSet on-line Help System, click on the Index tab, and search for SURFACE. Display the topic, then choose the Macro Command item. The information is shown as follows:
SURFACE Macro Command
Running this module in macro mode requires the following parameters:
1: x (to indicate that macro mode is being used)
2: operation number (1=Slope / 2=Aspect / 3=Both / 4=Hillshading) 3: input filename (the image containing values to use in the calculation) 4: output filename (the new image to be created)
5: second filename (if both slope and aspect calculated, # if not used) 6: slope measurement (“d”=degrees / “p”=percent)
7: conversion factor (optional -- converts val. units to ref. units) e.g., “surface x 3*relief*slope*aspect*p”
For Analytical Hillshading (operation 4 in #2), parameters 5 and 6 require:
5: sun azimuth (sun azimuth [in degrees clockwise from north]) 6: sun elevation (sun elevation [in degrees up from horizon])
To execute the first step of our analysis, creating a slope image from the elevation model, we would use the following macro command:
surface x 1*relief*slopes*#*d
EXERCISE 2-4 EXPLORING THE POWER OF MACRO MODELER 91
S
The next module we used was RECLASS to create a Boolean image of slopes less than 2.5 degrees from our slope image. Again, access the on-line Help System for the Macro Command format for RECLASS. Given our variables, the next line in the macro file should be:reclass x i*slopes*slopebl*2*1*0*2.5*0*2.5*999*-9999
T
Run Edit from the Data Entry submenu under the File menu. From the File menu in Edit, choose to open a file. Select the macro file type and open the file EXERCISE2-3. The macro has already been created for you. Each line executes an TerrSet module using the same parameters we used in Exercise 2-3. As the last line indicates, the final image will be called SUITABLE2, rather than SUITABLE (created in Exercise 2-3), so we may compare the two. Note that the lines beginning with the letters REM are considered by the program to be remarks and will not be executed. These remarks are used to document the macro.U
Take some time to compare the Macro Command format information in the on-line Help System with some of the lines in the macro. Note that you may size the on-line Help window smaller so you may have both it and the Edit window visible at the same time. You may also choose to have the Help System stay on top from the Help System Options menu.V
When you are finished examining the macro, choose to Exit. Do not save any changes you may have inadvertently made.W
Choose Run Macro from the Model Deployment Tools submenu under the IDRISI GIS Analysis menu, then enter EXERCISE2-3 as the macro filename, and leave the macro parameters input box blank. As the macro is running, you will see a report on the screen showing which step is currently being processed. When the macro has finished, SUITABLE2 will automatically display with the Qual palette. Then display SUITABLE (created in Exercise 2-3) in a separate window with the same palette and position it to see both images simultaneously.X
Open the macro file with the TerrSet Edit module again and change it so that slopes less than 4 degrees are considered suitable.The altered command line should be:
reclass x i*slopes*slopebl*2*1*0*4*0*4*999*-9999
You should also change the remark above the RECLASS command to indicate that you are creating a Boolean image of slopes less than 4 degrees. In Edit, choose to Save then Exit. Run the macro and compare the results (SUITABLE2) to SUITABLE.
Y
Use the Edit module to open and change the macro once again so that it does not use diagonals in the GROUP process. Also change the final image name to be SUITABLE3. (Retain the 4 degree slope threshold.) Save the macro and run it.4
Describe the differences between SUITABLE, SUITABLE2 and SUITABLE3 and explain what caused these differences.Command macros may also be written with variable “placeholders” as command line parameters. For example, suppose we wish to run several iterations of the macro, each with a different slope threshold. We can set up the macro with a variable placeholder for the threshold parameter. The desired threshold can then be entered into the Run Macro dialog in the Macro Parameters input box. This will be easier than editing and saving a new macro file for each iteration. We will change the macro to take both the slope threshold and the output filename from the Macro Parameters input box.
EXERCISE 2-4 EXPLORING THE POWER OF MACRO MODELER 92
Z
Open the macro EXERCISE2-3 in Edit. In the reclassification step for the slope criterion, replace the slope threshold value 4 with the variable placeholder %1 in both places in which it occurs. The new command line should appear as follows:reclass x i*slopes*slopebl*2*1*0*%1*0*%1*999*-9999
Also replace the output filename, SUITABLE3, with a second variable placeholder, %2, both in the last reclassification step and in the last display step as follows
reclass x i*sitearea*%2*2*0*0*10*1*10*99999*-9999 display x n*%2*qual256*y
Save the macro file and Exit the editor.
AA
Choose Run Macro. Enter the macro filename and in the Macro Parameters input box, enter the slope threshold of interest and the desired output filename, separated by a space. For example, if you wished to evaluate a thresold of 5 degrees and call the output SUITABLE5, you would enter the following in the Macro Parameters box:5 suitable5 Press Run Macro
BB
You may now quickly evaluate the results of using several different slope thresholds. Each time you run the macro, enter a slope threshold value and an output filename.Command macros are clearly a very powerful tool in GIS analysis. Once they are created, they allow for the very rapid evaluation of variations on the same analysis. In addition, exactly the same analysis may be quickly performed for another study area simply by changing the original input filenames. As an added advantage, macro files may be saved or printed along with the corresponding cartographic model.
This would provide a detailed record for checking possible sources of error in an analysis or for replicating the study.
Note:
TerrSet records all the commands you execute in a text file located in the Working Folder. This file is called a LOG file. The commands are recorded in a similar format to the macro command format that we used in this exercise. All the error messages that are generated are also recorded. Each time you open TerrSet, a new LOG file is created and the previous files are renamed. The log files of your five most recent TerrSet projects are saved under the filenames IDRISI32.LOG, IDRISI32.LO2, ... IDRISI32.LO5 with IDRISI32.LOG being the most recent.
The LOG file may be edited and then saved as a macro file using Edit. Open the LOG file in Edit, edit the file to have a macro file format, then choose the Save As option. Choose Macro file (*.iml) as the file type and enter a filename.
Note also that the command line used to generate each output image, whether interactively or by a macro, is recorded in that image’s Lineage field in its documentation file. This may be viewed with the Metadata utility in TerrSet Explorer and may be copied and pasted into a macro file using the CTRL+C keyboard sequence to copy highlighted text in Metadata and the CTRL+V keyboard sequence to paste it into the macro file in Edit.
EXERCISE 2-4 EXPLORING THE POWER OF MACRO MODELER 93
In addition to macros, Image Calculator offers some degree of automation. While the macro file offers more flexibility, any analyis that is limited to the modules OVERLAY, SCALAR, TRANSFORM and RECLASS may be carried out with Image Calculator. Expressions in Image Calculator may be saved to a file and called up again for later use.