2 Beginners

 2.1 Unix setup
 2.2 Starting Figaro
 2.3 Getting help
 2.4 Looking at a spectrum
 2.5 Looking at an image
 2.6 Image display in monochrome
 2.7 Paper copies
 2.8 Examining data
 2.9 Doing simple things

2.1 Unix setup

In order to run any Starlink software, your Unix startup must be adapted appropriately. If you work at a Starlink site, chances are that your site manager has already taken care of this.

It is necessary that you use a Unix shell similar to the C shell. A Unix shell is a command line interpreter between you and the Unix operating system. When you log into the Unix system one or another shell will be started for you, namely the one that is your ‘login shell’. The most basic Unix shell is the Bourne shell ‘sh’, but the most common interactive shell is the C shell ‘csh’. Some system administrators may try to educate you to use more fashionable shells like ‘korn’ or ‘bash’.

The Starlink startup scripts all assume that you use the C shell, but a similar, enhanced shell is ‘tcsh’, and this is what probably most users of Starlink software have as their login shell.

When you login, the login shell will execute two scripts in your home directory. One is ‘.cshrc’, or Tc shell users may have a similar file ‘.tcshrc’ instead. The second startup script is ‘.login’.

What you have to do to make Starlink software work, is to include one command in each of these two files. In ‘.cshrc’ or ‘.tcshrc’ you insert the line

  source /star/etc/cshrc

and in ‘.login’ you insert the equivalent

  source /star/etc/login

Figaro and other Starlink packages use a common mechanism for providing input values to, and obtaining output values from, individual applications. This so-called ‘parameter system’ allows values to be passed between related applications, saves un-necessary typing and assists the applications in suggesting sensible default values. The details are not germane here, but files containing the parameter values passed between applications need to be kept somewhere. By default these files reside in a subdirectory of your home directory called (for historical reasons) ‘adam’. This directory is created automatically the first time that you run a Figaro (or other Starlink) application. However, you can create it manually if you prefer. You can choose to use a different directory by adding a command to your ‘.login’ script. Say, you want to use directory ‘parameters’ under your home directory, then add

  % setenv ADAM_USER $HOME/parameters

Similarly, Figaro, and other Starlink packages, use the ‘Applications Graphics Interface’ (AGI) to pass graphical information between related applications, allowing them to inter-operate smoothly. The associated files are created in your home directory by default. However, again you can specify their location by adding a line to your ‘.login’ script. For example

     setenv AGI_USER $HOME/graphics

It is a good idea to delete these files occasionally, since they grow ever bigger and mainly contain old, useless information. The files are called ‘agi_ <host >.sdf’ and there is one for each machine you have used for Starlink graphics.

2.2 Starting Figaro

There are three different ways of running Figaro:

These alternatives are described individually below. Each has its advantages. If you plan to make only fairly straightforward use of Figaro then it may be simplest to run it from the Unix shell.

2.2.1 Starting Figaro from the Unix shell

To start Figaro from the Unix shell simply type:

  % figaro

and it responds with a message similar to this:

   ----------- Initialising for  Figaro ------------
                General data reduction
              Version 5.6-1 19 September 2002
  
            Type "fighelp figaro" for help
        or "fighelp news" for news on changes
  
   Type "showme sun86" to browse HTML documentation
  
   Use "abbrev" and "noabbrev" to turn parameter name
   abbreviation on and off.

Once you have given this Figaro startup command you have about 200 new commands at your disposal, the Figaro commands (or Figaro applications; In Figaro, and other Starlink packages, commands are often referred to as ‘applications’ because each command corresponds to an application program which performs some data reduction task). Each Figaro application can be invoked by two different commands. One is simply a name describing the application, the other the same name prefixed by ‘fig_’. E.g. the commands ‘istat’ and ‘fig_istat’ invoke the same application. The reason for this apparent duplication is that some common command names can also be used in other packages. The ‘fig_’ prefix allows the Figaro commands to be specified unambiguously.

The Unix shell has some disadvantages in running Figaro commands. The most annoying feature is that so-called meta-characters like ()[]’" have special meaning to the Unix shell. If you need these characters to pass information in the command line to the Figaro command, then you have to take extra steps to make sure the information makes it through the interpretation by the Unix shell. See Section 3.1.5 for further details.

Of less importance is that the Unix shell does not have floating point variables and arithmetics, and that it has no knowledge of the parameter system used by Figaro commands. Such features are rarely needed; once you get used to handling the shell meta-characters, you should be all right with the Unix shell.

2.2.2 Starting Figaro from ICL

Figaro can also be run from Starlink’s Interactive Command Language (ICL). ICL is a command line interface which has intimate knowledge of the parameter system and of the command line syntax of Figaro commands. When your procedures get really tricky, ICL is probably a better command line interface than the Unix shell. But even in every-day use, ICL saves you masking all those Unix shell meta-characters.

You start ICL with the shell command

  % icl

Unlike the Figaro startup command, which only defines new commands for the Unix shell, this starts a new process, a new shell if you like. It is thus no big surprise that the prompt string changes to ‘ICL >’.

From this shell you start Figaro with

  ICL> figaro

which will respond with the familiar message

   ----------- Initialising for  Figaro ------------
                General data reduction
             Version 5.6-1 19 September 2002
  
             Type  "help figaro" for help
  
   Type "showme sun86" to browse HTML documentation
  
   Use "abbrev" and "noabbrev" to turn parameter name
   abbreviation on and off.

The 200-odd Figaro commands are now at your disposal. However, only the short names without the ‘fig_’ prefix are available.

There is a demonstration procedure, which is intended as a test of the installation, but the script itself can give you hints about writing your own ICL procedures and about the syntax for command line parameters. To execute it, you need an X windows display.

To run the demo type:

  ICL> load $FIG_DIR/demo

To run the Specdre demo, which demonstrates how the Specdre Extension is used to e.g. gather fit results and pass them on to other applications, type

  ICL> load $FIG_DIR/demo_specdre

Once in ICL, you can initialise further packages, such as KAPPA

  ICL> kappa

Any additional initialisation may write a message to the terminal that some ‘key has been redefined’. This message indicates that the same command name is used in different packages and probably for quite different purposes. The latest initialisation overrides previous ones, and if you are using several packages it might be important to initialise them in the correct order.

2.2.3 Starting Figaro from IRAF

IRAF is a powerful and comprehensive package for reducing and analysing optical astonomical data. It was developed at the National Optical Astronomy Observatory (NOAO) in Tucson, Arizona and is now in widespread use around the world. Users run IRAF applications from a command line interface called CL. It is also possible to run Figaro from CL. There are (at least) two reasons for wanting to do so:

The Figaro and standard IRAF applications can inter-operate, so a given dataset can be processed using a mixture of Figaro and standard IRAF applications.

Figaro and IRAF intrinsically use different data formats (the Figaro formats are described in Section 3.2). However, when Figaro is run from the IRAF CL the system is set up so that the Figaro applications automatically convert to and from the IRAF format on input and output respectively. Thus, you will see only data files in the native IRAF format. This conversion happens automatically and invisibly and as a user you will not normally need to be concerned about how it is done. However, one caveat that you should be aware of is that the native Figaro format is more ‘capable’, in the sense that it can contain more auxiliary information such as quality arrays, error arrays, etc. than the IRAF format. Thus, when datasets are written using the IRAF format some of this auxiliary information can be lost.

The procedure to run Figaro from within IRAF is as follows.

(1)
First start IRAF following the normal procedure at your site. The precise details differ between sites. SG/12 gives some general guidance. However, you should check with your site manager to get the specific instructions for your site.
(2)
From within IRAF CL simply type:
  cl> figaro

(here ‘cl>’ is the CL prompt, not something that you type in). A welcome message and list of commands will be displayed and the Figaro applications can simply be run.

There are various points which it is useful to be aware of when running Figaro, or other Starlink applications, from within CL. The details are discussed in SUN/217.

2.2.4 Inter-operability between Figaro and other packages

Figaro applications can inter-operate with applications in various other packages. Running Figaro from the IRAF CL (see the previous section) allows Figaro to inter-operate with IRAF applications.

Figaro applications can also inter-operate with the applications in most other Starlink packages. The most widely useful are probably those in the general purpose image processing package KAPPA (see SUN/95). To start both Figaro and KAPPA from the Unix shell simply type:

  % figaro
  % kappa

In both cases the start-up messages have been omitted for brevity. The order of the two commands is not important. The applications in both Figaro and KAPPA are now available and to a large extent they inter-operate.

The procedures to run the packages from ICL or to inter-operate with other Starlink packages are similar.

2.3 Getting help

Since you are reading this, you obviously found one way of getting help with Figaro. There are different sorts of help you can get:

2.3.1 Help from within the Unix shell

From the Unix shell you can get help from the on-line help library. Use the command

  % fighelp

and navigate through the hierarchy of information in the help library. You can also specify topics and sub-topics as command parameters. The command

  % fighelp istat

returns

  ISTAT
  
       *********************************************************************
       *                             I S T A T                             *
       *  ISTAT examines an image, or a rectangular subset of an image or  *
       *  spectrum, and outputs a number of statistics about it, such as   *
       *  maximum and minimum value, mean and sigma, etc.  The results     *
       *  are used to set Figaro user variables, so can be used by Figaro  *
       *  procedures.  There are a number of examples in the documentation *
       *********************************************************************
  
    Additional information available:
  
    PARAMETERS            SOURCE_COMMENTS

Often the most extensive and interesting information is in the sub-topic ‘source_comments’.

The command

  % fighelp istat para image

returns

  ISTAT
    PARAMETERS
      IMAGE
            TYPE    FILE
            NAME    IM(AGE)
            OPTIONS INPUT
            PROMPT  "(IMage) Name of image to examine"
            TEXT    ------------------------------------------------
                    IMAGE is the name of the image (or spectrum) for
                    which statistics are to be determined.
                    ------------------------------------------------

You can also get ‘run-time’ help: When a command prompts you for some additional information and you have no idea what it’s on about, try responding with a question mark. You will then get some help on that parameter of that command, and are re-prompted for the parameter. Observe this:

  % istat
  IMAGE - (IMage) Name of image to examine /@demo/ > ?
  
  ISTAT
    PARAMETERS
      IMAGE
            TYPE    FILE
            NAME    IM(AGE)
            OPTIONS INPUT
            PROMPT  "(IMage) Name of image to examine"
            TEXT    ------------------------------------------------
                    IMAGE is the name of the image (or spectrum) for
                    which statistics are to be determined.
                    ------------------------------------------------
  
  IMAGE - (IMage) Name of image to examine /@demo/ >
  XSTART - (XStart) First X value to be used /0.5/ >
  XEND - (XEnd) Last X value to be used /2039.5/ >
  
  X-range 1 (0.5000) to 2040 (2039.5)
  Total (over 2040 pixels) = 37751.6
  Max   = 764.51   in pixel (849,1)
  Min   = -0.12577 in pixel (149,1)
  Mean  = 18.506
  Sigma = 48.3061
2.3.2 Help from within ICL

From ICL you can get help from the on-line help library. Use the command

  ICL> help figaro

Help on the commands is also available by giving them as the topic, use e.g. ‘help istat’, not ‘help figaro istat’. Topics other than commands (news, classified list of commands) are available only as follows:

  ICL> help figaro
    ...
  Topic? class exam
  
  Classified
    Examination
        HIST       Produce histogram of data value distribution in an image
        ICUR       Inspect an image with cursor
        IGCUR      Use cursor to show x, y and data values
        ILIST      List the data in an image (or spectrum)
        ISTAT      Provides some statistics about an image (max, min etc.)

Run-time help is available in the same way as from the Unix shell.

2.3.3 Help via the WWW

The most comprehensive help for Figaro is the extended, hypertext version of SUN/86 available via the WWW. To access this document on a Starlink system simply type

  % showme sun86

Otherwise use URL

http://www.starlink.ac.uk/star/docs/sun86.htx/sun86.html

Figaro also has a WWW ‘home page’ at URL

http://www.starlink.ac.uk/figaro/

2.3.4 Asking for advice

If you cannot find the information that you need or if you think that you have found an error in Figaro then you can contact Starlink for advice and assistance. In the first instance you should send an e-mail message to username

  starlink@jiscmail.ac.uk

2.4 Looking at a spectrum

Suppose you have a data file ‘a_file.sdf’ with a spectrum, i.e. a one-dimensional data set and want to plot is on an X display. This is probably the most commonly used Figaro command, and it is called ‘splot’. Many command names begin with an ‘s’ for spectrum or with an ‘i’ for image. However, before we can plot anything, we need to tell Figaro what our plotting device is.

Consider the following sequence of commands:

  % xdisplay
  ICL> soft xw
  ICL> splot a_file accept


pict
Figure 1: Example GWM spectrum.


The first command is necessary if your X display ‘server’ is not the same as the ‘client’ machine running Figaro for you. It passes the remote client the identity of the local server. You have to declare ‘xdisplay’ each time you log onto the remote client.

Conversely, you may also have to reveal the identity of the remote client to the local server, say with an ‘xhost’ command. Otherwise the remote client may not be allowed use the local server as a display.

The second command tells Figaro which graphics device you want to use. ‘xw’ is an abbreviation for ‘xwindows’. Together with the information from ‘xdisplay’ this is sufficient to open the window. You should now get a display window on your screen, and a box with the word ‘PGPLOT’ in the centre is drawn into the window. You need to give the ‘soft’ command only once. Figaro will always remember that you want to use the device ‘xw’.

The third command finally displays the spectrum contained in the file ‘a_file.sdf’. Data files can have names ending with ‘.sdf’ or ‘.dst’. They must not contain any additional periods. The Figaro commands know about this, and must not be given this file name extension.

Don’t worry about the size of this window. By default you get about 700 by 500 pixels, usually big enough to read the axis labels.

The word ‘accept’ looks like a parameter to the ‘splot’ command. Actually you can use it on any command. It prevents the command from prompting you for information that it can guess itself.

Now consider this more complex sequence of commands. It achieves the same thing, basically.

  % xdisplay abc.inter.net
  % xmake xwindows -g 400x300 -bg green -fg blue
  ICL> splot spectrum=a_file whole=f
  XSTART - (XStart) First X-value to be plotted /0.5/ > 3.25
  XEND - (XEnd) Last X-value to be plotted /2043.5/ > 3.4
  AUTOSCALE - (AUtoscale) Scale so all of spectrum fits? /NO/ > y
  LABEL - (LABel) Label for plot /’’/ > Plotting a spectrum
  HARDCOPY - (HArdcopy) Produce plot as a hard copy? /NO/ >


pict
Figure 2: A spectrum in a GWM window.


The ‘xdisplay’ command now tells the remote client explicitly what the Internet host name of the local server is. This is necessary when you log on indirectly, via a third host.

There is also an extra ‘xmake’ command to create the display window explicitly. This way, we can tell it the size and shape of the window, and the colours for background and lines. You can make your personal preference permanent by specifying resources for ‘xmake’ in your ‘.Xdefaults’ file. If you look at the paper copy or on a black/white display, you will notice that this is not a good choice of colours, since the grey values for blue and green are rather similar.

‘xmake’ is paired with a command ‘xdestroy’, which you can use to get rid of the graphics window. That is necessary before you ‘xmake’ it with different parameters, or when you have too many windows on your display.

The ‘splot’ command is different in a number of ways. Before, we had given the input data set as the first parameter. When we are not sure about the sequence of parameters, we can specify them by name. For most Figaro commands that work on spectra as opposed to images, the input data are specified in the parameter called ‘spectrum’.

Next, we have specified the ‘whole’ parameter as false, so that this time we can choose only part of the spectrum to be displayed. We also left out the ‘accept’ keyword, that is why the command asks us a number of questions while it runs.

2.5 Looking at an image

2.5.1 The ‘image’ command

Suppose you have a data file ‘a_file.sdf’ with an image, i.e. a two-dimensional data set and want to plot is on an X display. This is one of the most common actions in Figaro. Most users will use the ‘image’ command for this purpose. In general it uses a different display window than where most other plots go. The idea is that most plots are line plots and their device is selected with the command ‘soft’. But ‘image’ should display at least in grey, if not in false colours. So you have to specify the imaging device separately, although it can be the same actual device as the ‘soft’ device.

Consider the following sequence of commands:

  % xdisplay
  ICL> idev xw
  ICL> colour grey
  ICL> image a_file accept

If you are not familiar with the necessities of using X windows over the computer network, see Section 2.4.

The second command tells Figaro which graphics device you want to use. ‘xw’ is an abbreviation for ‘xwindows’. Together with the information from ‘xdisplay’ this is sufficient to open the window. You should now get a display window on your screen, and a box with the words ‘PGPLOT imaging’ in the centre is drawn into the window. You need to give the ‘idev’ command only once. Figaro will always remember that you want to use the device ‘xw’.

The third command changes the display window to show various levels of grey as representation of the image data values. A new display window may have an undefined ‘colour lookup table’, or a different plot command may have changed the lookup table. The ‘colour’ command with parameter ‘grey’ always brings it back to normal.

The fourth command finally displays the image contained in the file ‘a_file.sdf’. Data files can have names ending with ‘.sdf’ or ‘.dst’. They must not contain any additional periods. The Figaro commands know about this, and must not be given this file name extension.


pict
Figure 3: An example of an image displayed in a GWM window.


The keyword ‘accept’ prevents the command from prompting you for information that it can guess itself. Unfortunately, you don’t know what it did guess, and you might never learn how you can exert more control over the display.

2.5.2 Advanced use of ‘image’

Now consider this more complex sequence of commands.

  % xdisplay abc.inter.net
  % xmake xwindows -g 400x300 -c 128
  
  ICL> image image=a_file prompt
  HARDCOPY - Use "hard" devices rather than imaging device /FALSE/ >
  IDEV /’xw’/ >
  ERASE - Erase screen before display /FALSE/ > t
  YSTART - First Y value to be displayed /1/ > min
  YEND - Last Y value to be displayed /256/ > max
  XSTART - First X value to be displayed /1/ > min
  XEND - Last X value to be displayed /256/ > max
  LOG - Display using logarithmic scaling /FALSE/ >
  OPTIMIZE - Amount of histogram optimisation (0 to 1) /0.5/ > 0
  AUTOSCALE - Calculate display limits automatically /TRUE/ >
  NEGATIVE - Set limits to give a negative image /FALSE/ > t
  XPLACES - Number of sub-displays across screen in X /1/ >
  YPLACES - Number of sub-displays across screen in Y /1/ >
  ASPECT - Maintain correct aspect ratio for image? /TRUE/ >
  IMARRAY /0/ >
  IMFILE /’’/ >
  
  ICL> image a_file negative=t
  ERASE - Erase screen before display /FALSE/ >
  YSTART - First Y value to be displayed /1/ > 173
  YEND - Last Y value to be displayed /256/ > 191
  XSTART - First X value to be displayed /1/ > 94
  XEND - Last X value to be displayed /256/ > 117
  OPTIMIZE - Amount of histogram optimisation (0 to 1) /0/ >
  AUTOSCALE - Calculate display limits automatically /TRUE/ >
  XPLACES - Number of sub-displays across screen in X /1/ > 0
  XORIGIN - Origin of display in X in display pixels /0/ > 250
  YORIGIN - Origin of display in Y in display pixels /0/ > 150
  XPIXELS - Number of display pixels to use in X /149/ >
  YPIXELS - Number of display pixels to use in X /149/ >
  ASPECT - Maintain correct aspect ratio for image? /TRUE/ >


pict
Figure 4: Advanced use of the IMAGE command.


If you are not familiar with the necessities of using X windows over the computer network, see Section 2.4.

In the first ‘image’ command the keyword ‘prompt’ is used. While ‘accept’ suppresses prompting as far as possible, ‘prompt’ causes any command to ask you everything. This is a good way of learning the capabilities of commands, but it also causes some spurious prompts like the ones for ‘idev’, ‘imarray’, and ‘imfile’. You should just accept the defaults offered for these parameters.

The first thing we learn through the ‘prompt’ keyword is that ‘image’ could have ‘displayed’ to a printer file instead of a screen window.

We chose to erase the window this time. That gets rid of the remainders of the original plain box. Via ‘ystart’/‘yend’ and ‘xstart’/‘xend’ we can select only part of the image to be displayed. Since we want the whole image and are not sure about the offered default, we use the words ‘min’ and ‘max’. This time, we set ‘negative’ true: The image file contains a negative, negating it during display makes is look positive. With ‘xplaces’/‘yplaces’ we could sub-divide the window into an array of sub-windows and display into one of them. We leave ‘aspect’ true so that image pixels are displayed as squares. Otherwise the display would be stretched horizontally to fill the window.

Having displayed the whole image, we now run ‘image’ again, but display only part of it. We also set ‘xplaces’ zero. That means, we can specify the display area in pixels. Since we do not erase this time, the previous full display remains partially visible.

2.5.3 Adding colour

While reading Section 2.5.1 you may have wondered why the command to choose grey levels is called ‘colour’. Because it can be used to load an existing colour lookup table. This can be done before or after ‘image’. To put some colour into the display we already have:

  ICL> colour contour_lut


pict
Figure 5: Adding color to an image.


There are a number of prepared colour lookup tables. They are ‘.sdf’ files, similar to other data files. By convention their names end in ‘_lut.sdf’, and they are stored in a directory pointed to by the Unix shell environment variable ‘FIGARO_PROG_S’. To see a list of colour tables in that directory:

  % ls $FIGARO_PROG_S/*_lut.sdf

Finally, how do you prevent line graphics from resetting your image display? You will recall that the line graphics device is selected with ‘soft’, while the imaging device is selected with ‘idev’. You can simply choose separate windows. Consider this:

  % xmake xwindows -c 16
  % xmake xwindows2 -c 128
  ICL> soft xw
  ICL> idev x2w

This will separate the output into two windows. There are four windows possible, but notice the different names in ‘xmake’ and ‘soft’/‘idev’. The ‘-c’ options also reduce the line graphics window to the 16 colours reserved for this, and increase the imaging window to 128 colours.

2.6 Image display in monochrome

If for some reason you cannot use ‘image’ to display images, you can still display them as contour plots or as dithered grey plots. This works even when the display window has only two colours, say when you have a b/w X terminal. Like spectral plots (Section 2.4) these plots go to the ‘soft’ device.

  ICL> icont a_file min max min max low=0 high=250 contours=6 accept


pict
Figure 6: Using contours.


  ICL> igrey a_file min max min max low=0 high=250 accept


pict
Figure 7: Monochrome image.


If the display window has more than 16 colours, ‘igrey’ will use those resources and display with true grey levels. It will also reset the window colours to grey. Well, strictly speaking the colours are not grey, but go linearly from the background colour to the foreground colour. If you choose pink and green for fore- and background, you can get quite a hideous composition.

2.7 Paper copies

In order to get paper copies instead of screen plots, you will usually use the ‘hard’ device instead of the ‘soft’ device. (Finally you understand why it’s called the ‘soft’ device!) Similar to the commands ‘soft’ and ‘idev’ there is a command ‘hard’ to tell Figaro once and for all what your hard-copy device is:

  ICL> hard ps_l

The main hard-copy devices these days are PostScript files—files, not printers! This means your plots go into a series of files. The first is called ‘gks74.ps’, the second is ‘gks74.ps.1’, the third ends with ‘.2’, and so on.

It is a bit difficult to keep track of these files. E.g. after you created three files you might delete the second. The fourth plot may then use the free name and appear to be the second plot. Also, if an application erases the graphics device before plotting, you might get two files: If you ‘print’ the first, you may just get a blank sheet of paper from the printer.

You can use ‘ghostscript’ (Unix command ‘gs’; see SUN/197) or, more simply, ‘ghostview’ to view the plots on the screen before you print the wrong one. E.g. type:

     ghostview gks74.ps

There are a number of PostScript devices you can choose from. When ‘hard’ prompts for the device, you can try ‘options’ to get a list of possible replies. The PostScript devices are:

Before you get enthusiastic about Colour PostScript, it is not possible to use the ‘colour’ application in conjunction with a printer device. This is because ‘colour’ would write its own PostScript file and the information does not go into the PostScript files with the actual display. You need something like KAPPA’s command ‘display’, which can load a colour table immediately before displaying the image. In Figaro the only use for Colour PostScript is probably to get coloured line plots where the applications support this.

The difference between the ‘ps’ and ‘epsf’ devices is that the former are complete and intended to be sent to the printer. The latter are incomplete and intended as elements of more elaborate PostScript documents. You could combine several EPSF files into a single PostScript file, or you could include EPSF files as figures in a TEX or LATEX document. The figures would be included during processing with ‘dvips’.

Consider this example:

  ICL> hard epsf_p
  ICL> igrey image1 17 23 130 125 hardcopy=t
  ICL> icont image2 17 23 130 125 hardcopy=t
  % psmerge -e -s0.5x0.5 gks74.ps -s0.5x0.5 gks74.ps.1 > hardcopy.eps


pdfpict
Figure 8: Postscript output.


We choose the portrait orientation for Encapsulated PostScript. This is helpful for later inclusion in a LATEX document, since it is usually printed in portrait orientation as well.

We use ‘igrey’ and ‘icont’ to produce plots of two images that have the same number of pixels per degree on the sky, and we choose the same part of the image. The two applications also use the same part of the display device. You might be tempted to use this sequence for an overlay on the screen, but ‘icont’ will wipe out the plot that ‘igrey’ made.

We use the ‘hardcopy’ keyword to direct the plots to the ‘hard’ device rather than the ‘soft’ device. The result are two files ‘gks74.ps*’.

Instead of printing each on its own piece of paper, we use the ‘psmerge’ utility (see SUN/164) to combine the two into a single figure. ‘psmerge’ can not only combine several EPSF files, it can also scale, shift and rotate each EPSF graphic individually in the process. The ‘-s’ option scales the graphs to half the size in x and in y.

The ‘-e’ option here means that the output is again EPSF rather than PostScript. The idea is that we want to include ‘hardcopy.eps’ in the LATEX version of this document like such:

     ...style[11pt,epsf]{article}
     ...
     \begin{figure}[htb]
     \begin{center}
     \includegraphics{sun86_hard}
     \end{center}
     \end{figure}

We are cheating here, because the GKS EPSF files have an unsuitable ‘BoundingBox:’. You have to edit these files and move one line from the end of the file to the beginning: There are two lines in the EPSF file that begin with ‘%%BoundingBox:’. At the top of the file it says ‘(atend)’ and at the bottom of the file it says e.g. ‘0 0 271 395’. The line at the end must be moved to where the first line is, and the first line must be removed. Since PostScript files contain plain text, you can use the ‘vi’ editor to do this.

Also, this BoundingBox is somewhat too large, it contains not only the graphic but some white space. You can use ‘ghostview’ to display the EPSF file. Its cursor position is constantly displayed, so you can move the cursor to the actual corners of the graph and thus find out better numbers for the BoundingBox.

Instead of ‘igrey’, you can used ‘image’ of course to make use of its histogram optimisation. You will find it very difficult to align it with any contour plot though.

2.7.1 Paper copy by cheating

Many line plot commands have a ‘hardcopy’ keyword to choose between the ‘soft’ and ‘hard’ device, or between the ‘idev’ and ‘hard’ device. However, some don’t and others use both devices for different plots.

If you actually tried to enter ‘options’ as hard device you will have noticed that the list contains the screen devices as well. In fact there is no principal difference between all those devices, each can be selected as ‘soft’, ‘hard’, or ‘idev’ device. The three commands to select the three devices just help Figaro to remember more than one device name and to channel the right output to the right device. You can send your hard-copies to the X screen and your screen plots into a PostScript file!

This is a valid option. If there is an application that sends your favourite plot always to the screen, you can

  ICL> hard ps_l
  ICL> soft ps_l draw=f
  ICL> idev ps_l draw=f

and all your plots go into PostScript files. Note that you should use the ‘draw’ keyword to suppress the creation of an extra page with the frame plotted by ‘soft’ and ‘idev’.

2.8 Examining data

If you have displayed an image with ‘image’ (Section 2.5.1), you can use ‘icur’ to move a cursor over the image. Stop at a point of interest, and you can be told the coordinates and data value of that point.

  ICL> icur
  
  Use mouse to control cursor.
  Press "D" to display pixel data.
  Press space bar to record pixel.
  Press "Q" to exit.
  
    76.00000       143.0000       132.3220
    198.0000       184.0000       115.9024
    214.0000       34.00000       3.863415
  Pixel record #01 at   167    52   167.0000       52.00000
  Pixel record #02 at   155   195   155.0000       195.0000
  Pixel record #03 at    61   211   61.00000       211.0000

On the first three positions ‘d’ was used, on the latter three the space bar. ‘Recording’ a pixel does not tell you its brightness, but the position is stored for future use.

If you used ‘igrey’ or ‘icont’ to display, (Section 2.6), then you can use ‘igcur’ in a similar way to find out about pixels.

Another useful inspection command is ‘istat’. It does not need any display, but works on the data directly.

  ICL> istat a_file accept
  
  Y-range 1 to 256
  X-range 1 to 256
  Total (over 65536.0 pixels) = 8.4904E+6
  Max   = 246.29   in pixel (89,47)
  Min   = 0        in pixel (215,35)
  Mean  = 129.55
  Sigma = 49.3974

2.9 Doing simple things

With Figaro you can not only look at data that happen to be lying around, you can also process data and thus change the contents of data files. The simplest operations are adding or subtracting a constant, or multiplying or dividing a constant into a data set. These four commands are ‘icadd’, ‘icsub’, ‘icmult’, and ‘icdiv’.

  ICL> icadd
  IMAGE - (IMage) Name of image to be added to /@a_file/ >
  FACTOR - (FACtor) Additive constant /1/ > 25
  OUTPUT - (OUTput) Name of resulting image > b_file

If you compare the statistics of the old ‘a_file.sdf’ and the new ‘b_file.sdf’, you will find that 25 has been added to each pixel value.

What happens if you give for ‘output’ the same file name as for ‘image’? In most cases this is possible. You will then not get a second file, but the first file will be modified to contain the new data.

What if you have a spectrum and not an image? Usually that does not matter. When a command asks for the ‘spectrum’ parameter it usually has to be a spectrum. But when it asks for the ‘image’ parameter you can in most cases give a spectrum instead.

You can also use two images as operands instead of an image and a constant. The commands for this are ‘iadd’, ‘isub’, ‘imult’, and ‘idiv’.

  ICL> idiv
  IMAGE - (IMage) Name of first image /@a_file/ >
  IMAGE1 - (IMAGE1) Name of second image > b_file
  OUTPUT - (OUTput) Name of resulting image > a_file

The first operand is overwritten with the result.