This chapter describes how to use the scripting language, Skm, to take full advantage of the command interface in IRIS Explorer. It covers these topics:
running IRIS Explorer with a script
examples of its use
the structure and syntax of Skm commands
the Skm Editor window
IRIS Explorer provides two user interface mechanisms: the graphical user interface (GUI) which is described in the previous chapters, and a command interface. The command interface allows you to run IRIS Explorer using text-based commands. You can issue these commands directly from the keyboard, or you can write a script that IRIS Explorer runs, using the IRIS Explorer scripting language called Skm (pronounced scheme).
The scripting language is useful for three reasons:
You can set up a series of commands for testing new modules, maps, or applications.
You can run IRIS Explorer automatically by piping information into it, which is handy for running batch jobs and test suites.
You can run IRIS Explorer remotely from another system, such as a personal computer, and you can write the results to a file.
To create a script, you use the IRIS Explorer scripting commands. The commands are described in Section B.1.3.
To run a script when IRIS Explorer starts up, at the shell prompt (%), type:
explorer -script scriptfilename
A map file and a script file can be specified on the command line. For example:
explorer -map mymap -script scriptfile.skm
To set up IRIS Explorer for interactive scripting, at the shell prompt (%), type either:
explorer -script -
explorer -script %
Both of these put you into the Skm interpreter, which displays this start up message and prompt:
IRIS Explorer Version 5.0 skm>
If you use the explorer -script - option this prompt appears in the shell window you invoked IRIS Explorer from. If you use the explorer -script % option then this message and subsequent scheme output appears in a dedicated Skm Editor Window.
At this prompt, you can type Skm commands as you go and have them executed in IRIS Explorer immediately.
You can pipe commands to IRIS Explorer using explorer -script - with a UNIX pipe. For example:
cat myFile.skm | explorer -script -
If you do use a pipe, although Skm output will appear as normal, subsequent commands cannot be entered from the keyboard as IRIS Explorer will still be receiving its input from the pipe. A pipe sends the output of one command into a second command. For more information, refer to the UNIX documentation.
This section gives examples of how to use the Skm scripting commands. If you are entering commands interactively, you type each command on a separate line after the Skm prompt (skm>). If you are creating a script file, simply type the commands, each on a separate line.
The startcommand is used to start modules. For example,
launches the ReadImg module in the Map Editor. The name of the module is enclosed in double quotes. The command:
skm>(start "SharpenImg" "at" 200 300)
launches the SharpenImg module in the Map Editor at the specified location. The coordinates specify the position of the top left-hand corner in pixels. Both the name of the module and the argument at are enclosed, separately, in double quotes.
Modules can be destroyed using the destroy command. For example,
destroys the ReadImg module that was previously launched.
Maps are started by using the start-map command. For example,
launches the cfd map.
The connect command specifies two ports to be connected. The command lists the output module name, the output port name, the input module name, and the input port name. For example,
skm>(connect "ReadImg" "Output" "SharpenImg" "Img In")
connects the Output port of ReadImg to the Img In port of SharpenImg.
You can use the define command to define a variable for use in other commands. For example, you can use this command:
skm>(define mod1 (start "ReadImg"))
to start the module ReadImg and create a reference to the module in a variable called mod1. Then you can destroy ReadImg by giving the command:
You can substitute the variable mod1 for ReadImg whenever you choose. This is important when you launch more than one copy of the same module (see Section 6.3).
Similarly, you can save information about a connect command in the variable c1:
skm>(define c1 (connect "ReadImg" "Output" "SharpenImg" "Img In"))
This particular connection can be referenced later as c1. For example, you can break the connection using either of these commands:
skm>(disconnect "ReadImg" "Output" "SharpenImg" "Img In")
Variables containing module and connection information remain even after the IRIS Explorer objects to which they refer are gone, so you can reconnect the modules just disconnected with the command:
Here is an example of a script that demonstrates the use of define in simplifing module connections. You can use the script as a template and substitute your own module and port names in the appropriate places.
(define m1 (start "GenLat")) (define m2 (start "LatToGeom")) (define m3 (start "Render")) (define m4 (start "PrintLat")) (set-param m1 "Dimensions" 2) (set-param m1 "Function" 3) (define c1 (connect m1 "Output" m2 "Input")) (define c2 (connect m2 "Output" m3 "Input")) (define c3 (connect m1 "Output" m4 "Input")) (disconnect c3) (fire m1)
Note that parameters are set by numbers. The statements
(set-param m1 "Dimensions" 2) (set-param m1 "Function" 3)
set the value on the Dimensions widget of the GenLat module to 2, and the value on the Functions widget to "random" (the first option on a widget has index 0).
To use the script, save it with the .skm suffix, for example, Testlat.skm. You can load the script in skm using the command load, e.g.
skm> (load "Testlat.skm")
or with the IRIS Explorer command using
IRISExplorer -script Testlat.skm
You can use the Skm commands to manipulate modules and maps in the Map Editor. Some of the commands let you emulate options available from the Map Editor and module pop-up menus. Using a Skm script, you can:
launch a module and start maps and applications
fire a module
enable and disable selected modules or complete maps
switch execution highlighting on and off
destroy selected modules or complete maps
make and break connections between modules
edit a map, including cutting, pasting and duplicating selected modules
manipulate module parameters
quit IRIS Explorer
Table B-1 lists, in alphabetical order, the Skm commands you can use to perform functions in IRIS Explorer.
The structure of these commands, plus any arguments they may take is listed in Table B-2.
In the Skm scripting language, all commands precede arguments and operands, and all expressions are enclosed in parentheses. If you want to say do something the Skm expression is:
skm> (do something)
For example, to add two numbers, the addition operator precedes the arguments. Numeric constants do not require quotes:
skm> (+ 1 2) 3
White space separates operands and operators, as well as commands and arguments. You can use the space character, a tab, or a newline character. Non-numeric constants without spaces are preceded by a single quote, for example:
skm> (set-param "NAGGraph" "Plot Title" 'This_is_the_title)
will assign the character string This_is_the_title to the parameter Plot Title of the NAGGraph module.
Character sequences that include spaces should be enclosed by double quotes, i.e.,
skm> (set-param "NAGGraph" "Plot Title" "This is the title")
will assign the character string This is the title to the same variable.
To obtain details on the syntax of a command from within Skm itself, type (help) at the Skm prompt (skm>). This gives a list of available commands. You can also type (help "command") which will give you help for the specified command. Finally, the command (help-mod "mod-name") opens a separate window displaying the help page for the module named mod-name.
You can use the commands in several different ways (see Table 6-1).
This section describes the Skm command syntax in more detail to help you create flexible scripts for performing activities in IRIS Explorer.
Symbols are identifiers that are preceded by a single quote. For example:
(define var 'size)
assigns the symbol size to the variable var.
The semicolon is the comment character in Skm. It comments out the remainder of the line on which it is located, for example:
(disable "GenLat") ; disable the GenLat module
You assign values to a variable using the define command. For example, to define a variable called myVar and assign it the value simple, you write:
(define myVar simple)
To display the value of a variable, type the name of the variable at the Skm prompt without using parentheses, for example:
skm> myVar simple
The assignment of a module to a variable is important because the actual name of the module depends on whether or not there are other copies of the module running.
If, for example, you use the command start to launch a copy of ReadImg, but there is already another active copy of ReadImg in the Map Editor, your module will be named ReadImg<2>. If you then use a connect command that explicitly refers to ReadImg, you will be referencing the wrong module.
The solution is to avoid referring to modules by the name used in the start command. Instead, assign the result of the start command to a variable and use the variable for subsequent references to the module.
(define mod1 (start "ReadImg")) (connect mod1 "Output" "SharpenImg" "Img In")
Skm provides the commands module? and connection? to test the type of a variable. They return the value () for false or t for true. For example:
skm> (module? m1) t
means that the variable m1 contains information about a module started some time in the past. It does not, however, necessarily mean that the module still exists.
Similarly, when connection? returns a value of true, it indicates that a particular connection once existed and information about that connection persists, but the connection itself may possibly have been broken.
You can create a procedure in Skm with the define and procedure commands. This example demonstrates how to define a procedure that takes a single argument, declared formally as a, and adds 1 to it. The value returned by the procedure, if any, is the last value of the procedure.
(procedure (a) (+ a 1))
This procedure does not have a name yet (procedures can be anonymous in Skm). To give the procedure the name plus1, type:
(define plus1 (procedure (a) (+ a 1)))
You can invoke this procedure as follows:
skm> (plus1 3) 4
This example shows how to carry out the action of connecting image processing modules in IRIS Explorer. Image processing modules that operate on a single input typically have an input port called Img In and an output port named Img Out.
First you define a procedure that will connect specified ports in two different modules. This procedure simplifies the connection of the modules by supplying the port names automatically:
(define image-conn (procedure ( mod1 mod2 ) (connect mod1 "Img Out" mod2 "Img In")))
Then you invoke the procedure and provide the names of the modules to be connected:
(image-conn "SharpenImg" "DisplayImg")
You can use the print command to print the output from a Skm command or script to the "IRIS Explorer console" (either the shell from which IRIS Explorer was launched or the Skm Editor Window, depending if IRIS Explorer was started with -script - or -script %). print takes one or more arguments; here are two examples of its use:
skm> (define v1 "abc") skm> (define v2 123) skm> (define m1 (start "ReadImg")) skm> (print v1 v2) abc123
skm> (print "My module is " m1) My module is #< IRIS Explorer Module Ref: ReadImg >
If you started IRIS Explorer with the explorer -script % option, IRIS Explorer will open a dedicated window in which Skm interactions can take place, see Figure 6-1. The Skm Editor Window can be opened and closed by toggling the Skm Window option from the Map Editor's Layout menu.
This main window is divided into four key areas described in the following subsections.
All output from Skm is directed here, including the commands you type and the Skm cursor. One of the main advantages of using IRIS Explorer in this mode is that Skm output is separated from general IRIS Explorer standard output, for instance from modules. This makes it easier to keep track of what you have typed in Skm.
This window stores a list of commands previously entered in the Skm Command Input window. You can use the arrow keys to scroll up and down the list (you can also use the arrow keys, with the same effect, in the Skm Command Input window). When using the Command History Window, the currently selected item in the history list will be replicated in the Skm Command Input window. To re-run this command you can either ‘double-click’ on the return/enter key here or alternatively a single return/enter in the Skm Command Input window will execute the command.
This tells you what state Skm is currently in, the possibilities are:
This means Skm is ready to accept input. Type away!
This means you have already typed something into Skm but have not finished entering the Skm command. A Skm command is complete when the number of left parentheses matches the number of right parentheses. The integer in the bracket represents the number of unclosed right parentheses.
This means Skm is busy. Further input will not be accepted until the interpreter is ready.
This is where you type Skm commands. Like other text input areas you can cut and paste text out of and into the Skm Command Input. Press <Return> or <Enter> to pass the command input to the interpreter. Each command line will be stored in the Skm Command History Window. A single Skm command can be split over more than one command line.