2 Tutorials

 2.1 From the C-shell
 2.2 From ICL

So the facilities summarised in the introduction sound appealing. Now you want to know how to access them, but the thick manual looks daunting. Actually, most of this manual comprises descriptions of each application. The best way to learn the basics is to try some example sessions.

Login to a colour workstation or X-terminal. Then enter the commands following the prompts shown below. The % is the shell prompt string, which you don’t type. As we go along there will be commentary explaining what is happening and why. Let’s begin.

2.1 From the C-shell

       % kappa

This defines C-shell aliases for each Kappa command, includes the help information, and shows the version number. It need only be issued once per login session. Thus you will see

        KAPPA commands are now available -- (Version 1.0)
        Type kaphelp for help on KAPPA commands

Let’s run a Kappa application. CADD adds a scalar constant to an NDF  file—the Starlink standard data format—to make a new NDF file (usually called an NDF for short). In this case ten is added to the pixels in $KAPPA_DIR/comwest.sdf to create test.sdf in the current directory.

       % cadd $KAPPA_DIR/comwest 10 test

There are three parameters qualifying the CADD command: the names of the input and output NDFs and the constant. Notice that these parameters are separated by spaces. Most applications have a few of these positional parameters, usually the most commonly used. Parameters given on the command line are not subsequently prompted for by the application. Also you see that the NDF file extensions are not given. The .sdf extension indicates that it was created by the Hierarchical Data System (SUN/92), or HDS for short. Note that an arbitrary .sdf file is not necessarily an NDF.

Next we run the statistics task. Here we have not given any parameters. In this case the application will ask for the values of any parameters it needs.

       % stats

The only parameter required is called NDF, and STATS prompts us for it.

       NDF - Data structure to analyse /@test/ >

In this example, STATS wants to know for which NDF we require statistical data. The text between the // delimiters is the suggested default for the parameter. By pressing the carriage return we accept this default as the parameter’s value. Here the suggested default is the name of the NDF created by CADD. (Ignore the @ for the moment—it just tells the application that it is a file.) Kappa remembers the last NDF used or created, and uses it for the suggested default to save typing. Since test is the NDF whose statistics we want we just hit the return key. Again we exclude the .sdf extension. Here is the output from STATS.

          Pixel statistics for the NDF structure /home/scratch/mjc/test
             Title                     : Comet West, low resolution
             NDF array analysed        : DATA
                Pixel sum              : 11851773
                Pixel mean             : 180.8437
                Standard deviation     : 63.47324
                Minimum pixel value    : 13.89063
                   At pixel            : (59, 83)
                   Co-ordinate         : (58.5, 82.5)
                Maximum pixel value    : 255.9375
                   At pixel            : (248, 45)
                   Co-ordinate         : (247.5, 44.5)
                Total number of pixels : 65536
                Number of pixels used  : 65536 (100.0%)

Of course, in your case the current directory will not be /home/scratch/mjc. The NDF title is the unchanged from the $KAPPA_DIR/comwest NDF. This is the normal behaviour for tasks that create a new NDF from an old one; they do, however, have a parameter for changing this default. To alter a defaulted parameter you supply its new value on the command line. Defaulted parameters exist to prevent a long series of prompts where reasonable values can be defined, and hence save time. (However, there is a way of being prompted for all parameters of a command should you wish.)

NDFs may contain three standard arrays—the data array, the data variance and quality. STATS can calculate statistics for any of these. By default, STATS uses the data array, as indicated here.

Next we wish to smooth our data. GAUSMOOTH performs a Gaussian smooth of neighbouring pixels.

       % gausmooth

Again we are prompted with the same suggested default, since we have not created any new NDFs within STATS. Say we don’t want to smooth that NDF, but the original one. We just enter the name of the NDF at the prompt. Notice that we don’t need the @ prefix, since Parameter IN expects a file. (One occasion where you would need it is when the filename is a number, e.g. if your NDF was called 234 you must enter @234, otherwise the parameter system will think you are giving the integer 234. Yes …I know …the parameter system is trying to be too clever.)

       IN - Input NDF /@test/ > $KAPPA_DIR/comwest

The description of Parameter FWHM is too brief for us to select a value. So we obtain some help on this parameter, and then GAUSMOOTH reprompts for a value. The smoothed NDF is written to the NDF called testsm in the current directory.

       FWHM - Gaussian PSF full-width at half-maximum /5/ > ?
             FWHM() = _REAL (Read)
                This specifies whether a circular or elliptical Gaussian
                point-spread function is used in smoothing a two-dimensional
                image.  If one value is given it is the full-width at
                half-maximum of a one-dimensional or circular Gaussian PSF.
                (Indeed only one value is permitted for a one-dimensional
                array.)  If two values are supplied, this parameter becomes the
                full-width at half-maximum of the major and minor axes of an
                elliptical Gaussian PSF.  Values between 0.1 and 10000.0 pixels
                should be given.  Note that unless a non-default value is
                specified for the BOX parameter, the time taken to perform the
                smoothing will increase in approximate proportion to the
                value(s) of FWHM.  The suggested default is the current value.
                will increase in approximate proportion to the value of FWHM.
       FWHM - Gaussian PSF full-width at half-maximum /5/ >
       OUT - Output NDF > testsm

Next we want to look at the result of our image processing. The first thing to do is to select an graphics device. The xwindows device becomes the current graphics device and remains so until the next GDSET command. (You may need to enter the xdisplay command (SUN/129) to redirect the output from the host computer to the screen in front you.)

       % gdset xwindows

Now we actually display it on the screen. Some applications have many parameters, and it would be impractical to have to specify all those preceding the ones we wanted to alter. The solution is to specify the parameter by keyword. Here we have requested that the scaling of the data values to colour indices within the graphics device uses the current percentile range. Note that you may abbreviate the options of a menu, such as offered by Parameter MODE, to any unambiguous string.

       % display mode=pe accept
       Data will be scaled from 78.38278 to 235.3536.

If you have just created the window, the image will not look much like the comet, because the existing colour table is poor. If we replace the table with a grey-scale ramp from white to black,

       % lutneg

what happens depends on your workstation hardware and settings. If your graphics system is set to 256 colours (technically, an 8-bit pseudo-colour visual), then the effects of the above LUTNEG command will be immediately visible, and you will see a blurred image of the ubiquitous Comet West on the screen. If, on the other hand, your graphics system is set to 16-bit or 24-bit graphics, then the effects of the LUTNEG command will only become visible when you next display an image. In this case, re-invoking the above DISPLAY command will make the image appear correctly with the requested grey-scale colour table.

The ACCEPT keyword is a very useful feature. It tells an application to accept all the suggested defaults. In this case DISPLAY uses the current NDF and scales between the current percentile limits—10 and 90. The keyword can be abbreviated to double backslash from the shell. Aside: the parameter system actually requires a single backslash. From the shell, however, backslash is a metacharacter, and so must be ‘escaped’ to treat the character literally. One way is to place a \ before each metacharacter. You can escape a series of characters by placing them inside single quotes ’ ’. Other metacharacters to watch out for when using Kappa include []()\"*?$.

Next we want to make the image colourful. There are a number of predefined lookup tables, or you may create and modify your own. Here we’ve given the X-window a ‘warm’ brown-yellow colour table1:

       % lutwarm

If you are not happy with this colour table, you may want to explore a wider range of colour tables using the LUTEDIT command which provides a complete graphical user interface for manipulating and viewing colour tables.

       % lutedit image=$KAPPA_DIR/comwest

2.2 From ICL

ICL is a command language designed for use with Starlink applications, such as Kappa. It is now of some antiquity but is still in use. The main advantages for the Kappa user are that shell metacharacters like []()" need not be escaped; command names may be abbreviated; far fewer executables need be loaded, and therefore it is slightly faster than using the shell when you want to invoke more than a few commands on a busy system; there is a wide selection of intrinsic functions and floating-point arithmetic; and results may be passed between applications via ICL variables. However, in these two demonstrations the command languages are interchangeable apart from the accept backslash.

Let’s start the second example.

       % icl

This starts ICL. System, local and user-defined ICLlogin files are invoked. Here there is only a system login procedure which sets up help on Starlink packages, and commands for setting up definitions for those packages. One of those commands is kappa; it is analogous to the kappa command from the shell. We enter it after receiving the ICL prompt.

You should see something like the following.

      ICL (UNIX) Version 3.1-9 14/02/2000
      Loading installed package definitions...
         - Type HELP package_name for help on specific Starlink packages
         -   or HELP PACKAGES for a list of all Starlink packages
         - Type HELP [command] for help on ICL and its commands
       ICL> kappa
          KAPPA commands are now available (Version 1.0).
          Type ‘help kappa’ or ‘kaphelp’ for help on KAPPA commands.

Now we run an application, ADD, that adds the pixels in $KAPPA_DIR/comwest.sdf to those in $KAPPA_DIR/ccdframec.sdf. Although these images have different dimensions, the intersection is made.

       ICL> add $KAPPA_DIR/comwest $KAPPA_DIR/ccdframec

After the first Kappa command is issued you’ll see an arcane message like this.

       Loading /star/bin/kappa/kappa_mon into kappa_mon11601 (attached)

It just tells you that the Kappa monolith is being loaded. You’ll see similar messages for each of the three monoliths when they are first wanted.

Since we did not give the name of the destination NDF that will hold the co-added NDFs, ADD prompts for it. Notice that literal parameters are case insensitive.

       OUT - Output NDF / / > demo1
       ICL> ndftrace \
          NDF structure /home/soft2/mjc/alpha_OSF1/kappa/package/demo1:
             Title:  Comet West, low resolution
              No. of dimensions:  2
              Dimension size(s):  256 x 256
              Pixel bounds     :  1:256, 1:256
              Total pixels     :  65536
          Data Component:
              Type        :  _REAL
              Storage form:  PRIMITIVE
              Bad pixels may be present

This shows that the demo1 NDF has the same dimensions as the smaller of the two NDFs.

We were going to display the image on the current graphics device, but then changed our minds. A !! in response to a prompt aborts a task.

       ICL> display demo1
       MODE - Method to define the scaling limits /’PERCENTILES’/ > !!
       !! SUBPAR: Abort (!!) response to prompt for Parameter MODE
       OBEYW unexpected status returned from task "kapview_mon11601", action
       - "DISPLAY"
       ADAMERR  %PAR, Parameter request aborted

Kappa uses the graphics database, which records the positions and extents of graphs and images, collectively called pictures.

       ICL> picgrid 2 1

This instruction divides the display surface into two equally sized pictures, side by side. They are labelled 1 and 2 in the database. Picture 1 is the current picture, in which future pictures are drawn, unless we select a new current picture.

Thus in Picture 1 we display an image of Comet West around which we draw annotated axes. The backslash causes the current scaling method to be used.

       ICL> display comwest axes \
       !! Error accessing file ’/home/scratch/mjc/comwest.sdf’ -
       !     No such file or directory
       !  HDS_OPEN: Error opening an HDS container file.
       !  NDF_ASSOC: Unable to associate an NDF structure with the ’%IN’ parameter.

DISPLAY could not find the a comwest.sdf in the current directory. So there is an error message and we are prompted. This time we remember to add the environment variable.

       IN - NDF to be displayed /@comwest_bas/ > $KAPPA_DIR/comwest
       Data will be scaled from 67.46276 to 226.5568.

An image of Comet West should be visible to the left of the screen.

SHADOW creates an image that appears like a bas-relief. We’ve called the resulting NDF comwest_bas. The backslash causes the current NDF to be the input NDF for SHADOW.

       ICL> shadow out=comwest_bas \

We select the right-hand picture created earlier.

       ICL> picsel 2

As above we display the current NDF, the bas-relief image, with annotated axes on the right of the raw comet image (we do not need to request the axes explicitly this time, since the axes parameter retains the value used in the previous invocation until changed).

       ICL> display border \
       Data will be scaled from -4.721756 to 5.697861.

The relief looks best with a grey-scale colour table. Note that this does not affect the colour of the border. LUTGREY is a procedure which calls a more-general application. Since it is the first procedure we’ve invoked there is a short pause while all the Kappa procedures are compiled and loaded.

       ICL> lutgrey
       Loading procedure file $KAPPA_DIR/kappa_proc.icl

Next we decide to make a hard copy of the bas-relief image. DISPLAY does this and can add a key of grey levels and their corresponding values. The chosen device is ps_l; this overrides the xwindows device for the duration of DISPLAY. If this name isn’t recognised at your site, issue the GDNAMES command for a list of your local device names. Select the landscape PostScript device. We scale between wider limits to reduce the glare.

       ICL> display key=yes device="/PS"
       IN - NDF to be displayed /@comwest_bas/ >
       MODE - Method to define the scaling limits /’SCALE’/ >
       LOW - Low value for display /187.5625/ > 11
       HIGH - High value for display /-183.453125/ > -8.33

DISPLAY does not send your plot to the printer, since this is hardware and node dependent. Therefore, you must issue a shell command from ICL to perform this action. That’s not difficult—just insert a ! before the UNIX command, and in most cases just issue the command as if you were in the shell, like we do below.

       ICL> !lpr -P1 pgplot.ps

Shell aliases may also be used, so if ri equates to rm -i, we could remove any unwanted HDS files. If you don’t have this symbol, as is likely, then you will receive the appropriate error message from ICL.

       ICL> ri *.sdf

That’s the end of the second demonstration. Of course, these introductions have only scratched the surface of what Kappa can do for you. You should look at the classified lists to search for the desired function, and then find more details in the specifications.

If you get stuck or something untoward happens, there is a Hints help topic.

1Again, you will need to re-display the image to see the effects of this command unless your graphics system is set to 256 colours.