Chapter 3
A Guided Tour

 3.1 Starting KAPPA
 3.2 Creating test images
 3.3 Examining images
 3.4 ICL procedures

This Chapter contains simple illustrations of how to use ADAM applications from the ICL command language.

One of the best ways of learning how to use ADAM is to play with one of the applications packages. There are many of these and they are described in Chapter 4. The KAPPA package is used below because it conforms to ADAM conventions and has a lot of useful commands for processing data.

Remember, before you attempt to use ADAM applications from ICL you must initialise ADAM logical names:

    $ ADAMSTART

and start up the ICL language interpreter:

    $ ICL

3.1 Starting KAPPA

KAPPA is made available from within ICL by typing:

    ICL> KAPPA

This loads KAPPA and defines the commands required to run its programs. It also generates the following output:

     Help key KAPPA redefined  
 
     --     Initialised for KAPPA     --  
     --    Version 0.8, 1991 August   --  
 
     Type HELP KAPPA or KAPHELP for KAPPA help  
 
    ICL>

Don’t worry about these messages for the moment. If you now enter:

    ICL> HELP KAPPA

you will get an introduction to the KAPPA Help system:

    HELP  
 
       This is the KAPPA online help system.  It invokes the VMS HELP Facility  
       to display information about a KAPPA command or topic.  If you need  
       assistance using this help library, enter "Using_help" in response to  
       the "Topic?" prompt.  If you need more information about getting help  
       about KAPPA from the ICL level, then enter "Command-line_help".

followed by the prompt:

    Topic?

This is an invitation for you to ask for further information. To find out what subjects are available you simply enter a ‘?’. You may find the following topics particularly useful :

Classified_commands
— displays a list of subject areas as subtopics. Each subtopic lists all KAPPA applications in that classification, and gives their functions.
Summary
— gives a brief description of the function of each application within KAPPA.
Using_Help
— tells you how to use this particular Help system.
<command > param
— describes all the parameters of the particular KAPPA <command>. Subtopics give further details about individual parameters, including their command line position.

You can either enter a subtopic, or press <CR > to get back the ‘Topic?’ prompt. Then you can enter ‘?’ to get the list of topics displayed again, or just press <CR > to get back to the ‘ICL >’ prompt. You can escape from the Help system at any level by entering ctrl/Z.

Now have a look in your ADAM_USER directory:

    ICL> DIR ADAM_USER  
    PROCERR    Procedure DIR not recognized  
    ICL>

The attempt to use the DIR command fails1 because it is only recognized by the DCL command interpreter, and you are talking to the ICL command interpreter. What you need to do is to tell ICL that this is a DCL command. You can do this by preceding the command with a ‘$’ character, thus:

    ICL> $ DIR ADAM_USER

ADAM now creates a subprocess in which to execute the DCL command processor. This is the reason for the delay and the message:

    Creating DCL subprocess

This subprocess is only created once per session; any further DCL commands you issue will be run in the DCL subprocess without any further action from you.

3.2 Creating test images

You can now use KAPPA to create some small images which you can then display and manipulate. The simplest way to create an image is to use command CREFRAME, which you can type in lower case if you like:

    ICL> creframe

After a loading message, the first thing that happens is that you are invited to specify a value for one of the program parameters:

    XDIM - x dimension of output array /64/ >

(If you have used CREFRAME before, you might find the ‘/64/’ in the above line comes out as something else.) This line is typical of the way in which ADAM asks for parameter values. The first field, in this case ‘XDIM’, is the parameter keyword — the name by which the parameter is known to the user. Then, after the ‘-’ delimiter, comes the second field, in this case ‘x dimension of output array’. This is a brief description of what the parameter means. The third field, in this case ‘/64/’, shows a suggested value for the parameter. If you just press <CR > in response to the prompt, the suggested value will be taken as the value you wish to specify for that parameter. Sometimes a suggested value will not be displayed in a prompt. In this case you must specify a value.

For the purposes of this example it is sensible to choose a small array size, say 10×10. Thus, the suggested value of ‘64’ is not what you want and you must specify the value you require by entering the value ‘10’:

    XDIM - x dimension of output array /64/ > 10

The parameter system then accepts this value as the value of the parameter XDIM. Once you press <CR >, the system will present you with a prompt for another parameter value:

    YDIM - y dimension of output array /64/ >

This prompt is similar to the previous one, and the suggested value is ‘64’ as before. Specify the value ‘10’ again:

    YDIM - y dimension of output array /64/ > 10

The system now presents you with the following lines:

    GS = Gaussians, RR = Random 0 to 1, RL = Random from Min to Max,  
    RA = Ramp across image, FL = Flat, BL = Blank,  
    GN = Gaussian noise with standard deviation about the mean,  
    RP = Poissonian noise about mean.  
    TYPED - Type of data to be generated /’GS’/ >

The first four indicate the codes you can enter in response to the parameter prompt and the meanings attached to them. The last is a prompt in the same format as the previous prompts with a suggested value of ‘GS’. In this case, the input required is a character string rather than an integer — you can usually tell what type of input is required from the format of the suggested value. For this illustration, generate an array that is simple in structure to make it easy to follow what is going on. Choose an image in the form of a ‘ramp’ — this is an array whose pixel values rise or fall steadily from left to right or from top to bottom. The code is ‘RA’:

    TYPED - Type of data to be generated /’GS’/ > ra

You may wonder why the suggested value is surrounded by quotes but the supplied value is not. In fact, the supplied value should strictly be ’RA’, but it is permissible to omit the quote characters as long as there is no ambiguity in doing so2.

The next line to appear is:

    LOW - Lower limit for data >

This time the suggested value field (the ‘/.../’ bit) is missing. Whether it is present or not depends on how the programmer has used the parameter system and whether or not he thinks a suggested value is appropriate. Because no suggested value is given, you need to enter a value — use ‘1’ for the lower limit and ‘10’ for the upper limit:

    LOW - Lower limit for data > 1  
    HIGH - Upper limit for data > 10

The next prompt is:

    DIRN - Direction of ramping /1/ >

This time you have suggested value again, but what does the number mean? You can find out by entering ‘?’:

    DIRN - Direction of ramping /1/ > ?

The system will explain that ‘1’ generates pixels which increase from left to right, ‘2’ generates pixels which increase from right to left, ‘3’ bottom to top, and ‘4’ top to bottom. Choose the suggested value ‘1’ by just pressing <CR >:

    DIRN - Direction of ramping /1/ >

The next prompt to appear is:

    OUTPIC - Image for output data >

Here there is no suggested value, so you must enter your own. The response required is a name for the generated image; call it RAMP1:

    OUTPIC - Image for output data > ramp1  
    ICL>

After ‘ramp1’ is entered the program generates the required image, so there may be a slight delay. The ‘ICL >’ prompt indicates that the CREFRAME command has completed its task and has returned control to the command language processor. The generated image will be called ‘RAMP1’ and will be stored in a file called RAMP1.SDF in your default directory — take a look, you will find it is there.

If you now generate three more 10×10 images containing different types of ramp, you can display and process them in various ways. Each time you want to create a new image using CREFRAME, you must enter the name of the program as a command:

    ICL> creframe  
    XDIM - x dimension of output array /10/ >

Notice that the second and all subsequent times you run an application program, there is no delay while it is loaded; the response is almost immediate. This is one of the main advantages of running applications from ICL. Notice also that the suggested value has changed from ‘64’ to ‘10’ — the parameter system has remembered the value you last entered for XDIM; this is called its ‘current value’. (The current values of parameters used by KAPPA commands are stored in the file KAPPA.SDF in your ADAM_USER directory.) Thus, you can just press <CR > to accept the suggested value. Generating the next image is going to be easy, isn’t it?

    YDIM - y dimension of output array /10/ >  
    GS = Gaussians, RR = Random 0 to 1, RL = Random from Min to Max,  
    RA = Ramp across image, FL = Flat, BL = Blank,  
    GN = Gaussian noise with standard deviation about mean,  
    RP = Poissonian noise about mean.  
    TYPED - Type of data to be generated /’GS’/ >

Wait a minute — last time you specified ‘RA’ as the value of TYPED, but the suggested value has remained ‘GS’ as it was originally. In this case, the suggested value ‘GS’ is generated by the program and the current value is not used. Once again, it all depends on how the parameter system has been used by the programmer — this subject will be considered in more detail in Chapter 14. All you can do is keep a careful eye on the suggested values. Here you must specify ‘RA’ explicitly again in order to generate a ramp:

    TYPED - Type of data to be generated /’GS’/ > ra  
    LOW - Lower limit for data > 1  
    HIGH - Upper limit for data > 10  
    DIRN - Direction of ramping /1/ > 2  
    OUTPIC - Image for output data > ramp2  
    ICL>

This time DIRN has been set to ‘2’ and the image called ‘RAMP2’.

In a similar way, you can now generate images called ‘RAMP3’ and ‘RAMP4’ with DIRN set to 3 and 4 respectively. Notice that the suggested value for DIRN is similar to that for TYPED in that it always has the same value rather than the last used value.

3.3 Examining images

Now that you have generated four images, you can play with them. In order to avoid getting involved with graphics devices at this stage, only commands which will run on any terminal will be used. The first thing to do is to examine their pixel values. There are several ways of doing this with KAPPA; one way is to use the LOOK command:

    ICL> look  
    INPIC - Image to be inspected/@ramp4/ >

The suggested value for the name of the image to be looked at is ‘@ramp4’. The ‘@’ character means ‘an object with the name of’, thus ‘@ramp4’ means ‘an object with the name of ramp4’. In this case the system assumes that any character string you type is the name of a data object; therefore you do not need to precede the name with an ‘@’ symbol. In the example, the system realizes that the value of INPIC should be the name of an image and it remembers that the name of the last image referred to was ‘ramp4’. However, look at ‘ramp1’ first:

    INPIC - Image to be inspected/@ramp4/ > ramp1

LOOK now accesses ‘ramp1’ and displays the following information:

    Title = KAPPA - Creframe  
    Array is 10 by 10 pixels

The title of the image — ‘KAPPA - Creframe’ — was generated by the CREFRAME program, and the array size is 10×10 as expected. This is followed by the next prompt:

    CHOICE - Peep, Examine or List /’Peep’/ >

These are just different ways of listing the pixel values. The suggested value is ‘Peep’, so try that by typing <CR >. You can also accept the suggested values for the next two prompts which specify the central point of the part of the image you are going to peep at:

    XCEN - x centre pixel index of 7x7 box /5/ >  
    YCEN - y centre pixel index of 7x7 box /5/ >

The ‘Peep’ option will display the pixel values within a 7×7 box centred on pixel (XCEN, YCEN). Notice that the program has chosen the centre of the image as the suggested box centre. All the required parameter values have now been entered, so the program proceeds to display the specified box:

          2         3         4         5         6         7         8  
 
    8     2         3         4         5         6         7         8  
    7     2         3         4         5         6         7         8  
    6     2         3         4         5         6         7         8  
    5     2         3         4         5         6         7         8  
    4     2         3         4         5         6         7         8  
    3     2         3         4         5         6         7         8  
    2     2         3         4         5         6         7         8  
 
    ANOTHER - Another inspection ? /YES/ >

Pixel indices are numbered from bottom left. In this case the pixel values are equal to their column number. Unlike CREFRAME, you are not returned to ICL but are given a chance to peep at another part of the image — these decisions are made by the programmer. As the image you are peeping at is highly predictable, do not bother to examine it further but escape from the program by entering:

    ANOTHER - Another inspection ? /YES/ > n  
    ICL >

When a program asks for a ‘YES’ or ‘NO’ value, you can get away with ‘Y’, ‘True’, and ‘T’ for ‘YES’; and ‘N’, ‘False’, and ‘F’ for ‘NO’; regardless of case.

You can use the LOOK command to examine the pixel values of the other images you have created in a similar way to that shown above. The ‘List’ option gives you the opportunity to store the output in a file:

    ICL> look  
    INPIC - Image to be inspected/@ramp1/ >  
    Title = KAPPA - Creframe  
    Array is 10 by 10 pixels  
 
    CHOICE - Peep, Examine or List /’PEEP’/ > L  
 
    XLOW - x start pixel index of sub-array /1/ >  
    YLOW - y start pixel index of sub-array /1/ >  
    XSIZE - x size of sub-array /10/ >  
    YSIZE - y size of sub-array /10/ >  
    FILENAME - Name of listing file /@LOOKOUT.LIS/ >  
    Listing to LOOKOUT.LIS  
 
    ANOTHER - Another inspection ? /YES/ > n  
    ICL>

Notice in this case that the parameter prompts after that for ‘CHOICE’ differ from those encountered before. This is because you have chosen the ‘List’ option instead of the ‘Peep’ option, and the program needs different information before it can proceed. Accept the suggested values for all the parameters until you come to ‘ANOTHER’ again. This makes things quick and easy for you. The program writes the pixel listing to the file LOOKOUT.LIS which is written in your default directory. You should, therefore, be able to display it on the screen using the DCL ‘TYPE’ command.

    ICL> $ type lookout

will cause the contents of file LOOKOUT.LIS to be displayed on your terminal (in a folded form — not shown here).

3.4 ICL procedures

So far we have used ICL to do simple things like calculate the value of a simple formula and load and use KAPPA. However, ICL can also be used as a programming language in which to write procedures, just as commands of DCL can be stored in a command procedure. This is a very convenient way to extend the range of applications available to you.

Suppose you want to add together (pixel by pixel) the four images you have created to produce a new composite image. This is the sort of problem that can be solved using an ICL procedure. ICL has a lot of functions available, one of which, ‘SNAME’, generates sequential names:

    SNAME(string,n,m)

produces a name which is the concatenation of the ‘string’ with the integer n. A third parameter m specifies a minimum number of digits for the numeric part of the name. Leading zeros are inserted if necessary to produce at least m digits, thus:

    SNAME(’RUN’,3,1)      has the value   RUN3  
    SNAME(’IPCS’,17,3)    has the value   IPCS017

An ICL procedure can be written using this to add a whole series of images together:

    ICL> PROC RAMPADD N  
    RAMPADD> { Add images RAMP1 to RAMPN to form SUM  
    RAMPADD>   ADD RAMP1 RAMP2 SUM TITLE=’Sum of 2 images’  
    RAMPADD>   LOOP FOR I=3 TO (N)  
    RAMPADD>     TITLE = ’Sum of’ & I:2 & ’ images’  
    RAMPADD>     ADD SUM (SNAME(’RAMP’,I,1)) SUM TITLE=(TITLE)  
    RAMPADD>   END LOOP  
    RAMPADD> END PROC  
    ICL>

The line starting PROC tells ICL you wish to write a procedure called RAMPADD which is to have one parameter called N. This will use the KAPPA application ADD to add successive images together in the new image SUM.

You can save this procedure for future use by entering:

    ICL> save rampadd

To run this procedure, use its name as a command and specify the value of the parameter. Thus, to add together the images RAMP1, RAMP2, RAMP3, and RAMP4 enter:

    ICL> rampadd 4  
    ICL>

An ADD statement is executed three times within the procedure, and a suitable title is generated for each image which is created. If you use LOOK to ‘Peep’ at the new image called ‘SUM’, you will see that every pixel has the value ‘22’ as you would expect. Note that four SUM.SDF files have been created. You should PURGE or DELETE them.

End your ICL session by exiting from ICL in the normal way:

    ICL> exit  
    $

You should now be fairly familiar with the style in which ADAM programs are used. More examples of how to use KAPPA are given in SUN/95. ICL procedures are considered in more detail in Chapter 9.

1It is intended to change this soon.

2This is not the right place to become embroiled in a discussion of what is a quite complicated subject — see Chapter 8.