Common Keywords

This suite has many common keywords and much common functionality. We describe briefly now some of the common keywords, although not all the programs in the suite use them in all possible ways. Refer to the individual help files to see what each program offers. Specific uses by cgspec will be described in Chapter 18. Note that minimum match is usually accepted for the value of keywords. The keywords usually default to the same value in each program, but you should again refer to the help files for details.

• The keyword in takes a list of input images as its arguments. These images are displayed or used in the display in some way indicated by the keyword type.

• The keyword type indicates how the images given in the in keyword will be displayed. These two keywords are in one to one ncorrespondence with each other. Possible values are pixel (display image as a pixel map representation, formerly called a grey scale, but now full colour is available), contour (display image as a contour map), box (display image as little boxes, where the size of the box is proportional to the value of the pixel, and it is hollow for positive and solid for negative values), amplitude and angle (display these two images as line vectors). In addition, type can take on the value mask. In this case, the relevant image given in the keyword in is not displayed, but its pixel blanking mask is applied to all the other images which are being displayed.

• The standard MIRIAD keyword region is used to select the region of the images for display. It interacts with the keyword chan (see below) which allows you to group planes (or channels) together onto separate subplots. The region selected applies to all the input images and they must all have the same size on the first 2 axes. However, you can input a mix of 3-D and 2-D images. If you input more than one 3-D image, they must all have the same size on the third axis. Any 3-D region selection indicated with the region keyword is applied only to the 3-D images that you input. An example of this usage would be overlaying a continuum image on each channel of a spectral line cube.

• The keyword xybin allows you to spatially bin up (average) pixels, or to pick out pixels at regular increments. This can be very handy for displaying large images, especially if you are making a hard copy on a postscript printer where the printer resolution does not merit retaining the individual pixels. Using this keyword can make the postscript file much smaller and print much faster.

  You can bin up the two spatial axes of an image independently, and you can enter up to 4 values, 2 for each axis specifying the increment and binning size. As an example, xybin=4,4,3,1 would bin up the image by 4 pixels in the x direction and pick out every third pixel in the y direction. If the binning size is not unity, it must equal the increment.

• The keyword chan is used to allow you to group the planes (or channels) that you selected with the keyword region onto separate subplots of the plotting page. The first value you give is the channel increment to step through the image in. The second value is the number of channels to average, for each sub-plot. For example, chan=5,3 would average groups of 3 planes together, starting 5 channels apart such as 1-3, 6-8, 11-13 and so on.

  The channels available are those designated by the region keyword. A new group of channels (sub-plot) is started if there is a discontinuity in the region selected channels (such as region=image(10,20),image(22,30). The combination of the region and chan determines how many sub-plots there will be.

• The keywords slev and levs (or lev1, lev2, levs3 in cgdisp -- it can draw up to 3 contour maps at once) indicate at what values the contours should be drawn. The first value of slev can be p or a, indicating percentage or absolute levels. The second value of slev is a scale factor to multiply the contour levels given in levs by. For example, slev=p,1 and levs=-1,1,2,4,8,16 would draw contours at -1%, 1%, 2%, 4%, 8% and 16% of the peak value in the image. On the other hand, slev=a,0.001, levs=3,5,10 would draw contours at values of 0.003, 0.005, 0.01.

• The keword range is used to control the way in which pixel intensities are mapped onto the colour lookup table of the device for pixel map representations ( type=pixel. Its use varies somewhat from task to task, but the basic functionality is the same; see the individual help files for details. See also options=fiddle which provides an interactive way to interact with the lookup tables.

  The first two values indicate the range of pixel values (intensities) to map onto the lookup table. Pixels with values outside this range will be represented with the colour of the nearest extremum. Thus, if the image was being displayed with a simple linear black and white transfer function on an interactove device, range= -0.2 , 2.0 would cause all pixels with values below -0.2 to come out black, all pixels with values greater than 2.0 to come out white, and all pixels in between that range to have shades of grey from black to white.

  The third argument of range allows you to specify a transfer function so that the pixel values can be mapped onto the lookup table in some way other than linearly. Allowed values are lin,sqr,log,heq for linear, square root, logarithmic and histogram equalization transfer functions. Histogram equalization can be very handy for images which have a lot of dynamic range. What this does is use the device colour levels for pixel values which occur the most often.

  The fourth argument of range is an integer between 1 and 9 specifying the type of lookup table. The available tables are 1 (b&w), 2 (spectrum colours), 3 (linear pseudo colour), 4 (floating zero colour contours), 5 (fixed zero colour contours), 6 (rgb), 7 (background) 8 (heat) and 9 (absolute b&w) . If you enter a negative integer, then the reversed lookup table is displayed.

  Fixed zero colour contours fix a colour boundary (blue-green) at 0 intensity, with 4 colour pairs ([light blue, light green], [dark blue, dark green], [purple,yellow], [black,orange]) distributed positive and negative of 0. There are then two more colours (read and white) for the remaining positive intensity values. Once you have arranged the colour pairs so that they define the noise level, the red and white colours quickly show you the true signal. You need to use options=fiddle to get the scaling to the noise level right.

  Note that in cgdisp , you can enter a group of 4 values for each subplot that is drawn. This is useful for hardcopy output, in that you can have an individual scaling and lookup tables for each subplot. For example, you may have made a ``cube'' with unlike quantities in different planes (total intensity, polarized intensity, fractional polarization, rotation measure etc) and it would be impossible to display them all with just one set of 4 values for the range keyword.

  The following figure shows the possible colour table types for a simple image. The colour bars or wedges show the differences most clearly.

  

• The keyword device indicates the PGPLOT device upon which the plot will be drawn.

• The keyword nxy takes two values, which are the number of subplots in the x and y directions on the page (dictated by the chan keyword).

• The keyword labtyp specifies what units the axes will be labelled in. It can take two values and they can be different.

  Possible values are:

  • hms for a label in H M S.S (e.g. for RA)

  • dms for a label in D M S.S (e.g. for DEC)

  • arcsec for a label in arcsecond offsets

  • arcmin for a label in arcminute offsets

  • absdeg for a lable in degrees

  • reldeg for a label in degree offsets

  • abspix for a label in pixels

  • relpix for a label in pixel offsets

  • abskms for a label in km/s

  • relkms for a label in km/s offsets

  • absghz for a label in GHz

  • relghz for a label in GHz offsets

  • absnat for a label in natural units as given by the axis label.

  • relnat for a label in offset natural coordinates

  • none for no label and no numbers or ticks on the axis

  All the offsets are with respect to the reference pixel. Note that you are expected to match your values with the order of the axes. For example, if you asked for labtyp=abskms,dms, it is expected that the first two axes of the image are velocity and declination. You will get rude messages if this is not the case.

• The keyword csize gives you control over the size of characters on the plot such as axis labels, or annotation text. These are given as factors of the default PGPLOT character size csize=1.0, which gives a character about 1/40 of the maximum dimension of the view surface. See the help files for details on what you can control in which program.

• The keyword options offers a variety of enrichment options for each program. There are a few that are common to most of the programs in this suite.
  • Option wedge causes a labelled colour bar or wedge to be drawn, showing the mapping between pixel intensity and colour.

  • Option fiddle invokes the interactive lookup table fiddler. This is mouse (or keyboard) driven, and instructions are given the in the window from which you invoked the program. basically, it is tree structured, with one branch to select different colour lookup tables, and one branch to modify the transfer function. You can swap between these branches.

    This option allows you to cycle through all of the same colour tables offered by keyword range (see above), and reverse them if desired. You can cycle through all of the same pre-defined transfer functions that are available with keyword range (see above).

    In addition, there is an interactive linear transfer function fiddle mode, where you can change the slope and offset of the linear transfer function. When you invoke the different transfer function modes, you get a little plot in the bottom right corner showing you what the transfer function is doing.

    Note that if you are plotting on a hard-copy device such as a postscript file, this option is then activated with keyboard inputs. You have the usual ability to cycle through lookup tables and transfer functions, but you do not get the interactive linear transfer function fiddler for obvious reasons. This gives you the same functionality as you could have obtained with the keyword range.

  • Option grid extends the coordinate ticks into a full grid. Minor ticks are excluded with this option.

  • The option unequal instructs the software to fill the plotting page maximally. By default, is trys to make the scales of the x and y axes the same. It is important that you use this option when you are displaying unlike quantities such as a velocity-DEC diagram, as the efforts to make equal scales will go wrong here.

  • Option relax instructs these programs not to be concerned if the axis descriptors for the input images are different. The axis sizes still have to be the same though. Use this one with great care, and its only useful if you are labelling the axes with abspix or relpix types.

  • When you are displaying multiple subplots, with each subplot being a different channel or plane from a 3-D image, the options 3value and 3pixel instruct the software to write the coordinate value and pixel value of the displayed subplot in its top left hand corner. You can use either or both of these.

  • The option full will cause a full set of plot annotation to be written at the bottom of each page of the plot. This includes things like coordiante information, contour levels, pixel map representation intensity ranges and so on.