Examples

Let us continue with some examples of usage if these programs.

• cginit initializes a PGPLOT device. Its only input is the keyword device. Most interactive PGPLOT devices are ephemeral, so that cginit is not useful for them. However, the PGPLOT /xs X window is persistent, so cginit is useful for it.

• cgdisp can display (simultaneously) contours, pixel map representations (i.e. images or ``grey scales''), vectors and boxes (pixels are displayed as filled [positive values] or hollow [negative values] boxes with size proportional to the pixel value) on a PGPLOT device. Up to three contour plots, one pixel map, one vector plot and one box plot may be displayed in multi-panel plots of multi-channel images. It also offers a ``mask'' image type, which is not displayed, but its blanking mask is applied to all the images that are. cgdisp can also display labelled overlay locations (plotted as boxes, stars, circles, ellipses, lines or see-through) may be specified from an ascii text file.

  We will just give a few examples of some common things that you might like to do with it.

  1. In the first example, cgdisp bins an image up by 2 pixels in the x and y directions, and then displays the image as a pixel map representation on a persistent X window. The transfer function wedge is drawn to the right and then you enter the interactive cursor driven fiddle loop. cgdisp then draws some overlay crosses on the plot (the overlay file format is described in the help file) and draws the beam size in the bottom right corner of the plot. The plot is annotated with useful information at the bottom and all four axes are labelled in arcsecond offsets from the reference pixel.

     

  2. The second example contours channels in the velocity range -100 to 100 km/s from two 3-D images (cubes); each channel is put on a separate sub-plot (but both cubes go on the same sub-plot) on the page and annotated with its velocity. Only every third pixel from the central 40 by 60 arcsec is displayed. The two cubes must have the same axis descriptors; i.e. the same axis dimensions and increments etc. The selected channels are binned up such that five channels are averaged together. However, the increment between the start group of each set of binned channels is 10. Thus, the displayed channel width will be one half of the displayed channel increment (they could of course be equal if you wish). The first cube is contoured via percentage levels, the second via absolute levels. The second cube's contours are drawn with a thicker linewidth. The two cubes could be from different spectral-lines, for example.

     Finally, a histogram equalized pixel map representation of a continuum image is overlaid on each channel sub-plot. As the output file is a disk file (a colour post-script file) we have used the range keyword to specify the desired lookup table (rainbow colours; fourth argument of keyword) and transfer function (histogram equalzation; third argument of keyword). Alternatively, we could still have used the interactive fiddle to do these things as the dialogue is keyboard driven for non-interactive devices. In fact, if we had set a transfer function via the range keyword and then invoked the interactive fiddle, we could have applied another transfer function to the already histogram equalized image !

     The options keyword is used to ask for an intensity wedge so that the map of colour to intensity can be seen. It is also used to ask for a full coordinate grid on the plot instead of just ticks as well as to annotate the plot with information about the images. Finally it is also used to ask for the value of the third axis (usuallt velocity or frequency) to be written in the corner of each subplot.

     When you ask cgdisp to display a mix of 2-D and 3-D images, the region (keyword region) that you specify applies equally to the first two dimensions of all images. However, any third axis region information that you give ( e.g. region=image(10,120)) applies only to the 3-D images, and is ignored for the 2-D image. Finally, if you ask for more sub-plots than can be fitted on the page, then the program will advance to a new page (you will be prompted to hit the carriage return key if your are plotting on an interactive device) when needed.

     

  3. This third example shows how to display a position-velocity image. You could produce such an image by reordering a cube with reorder

     into velocity-x-y order. You could then look at one or several planes of this cube. Normally, cgdisp tries to display with equal x and y scales. This equality is worked out using the linear axis descriptors. Equal scales are meaningless when displaying unlike axes, so you should set options=unequal.

     

  4. This fourth example is a polarimetry display. It is common practice to display these images by way of a pixel map representation and/or contours for the total intensity, and vectors for the (fractional) polarised intensity at the specified position angles. The length of the vectors are proportional to the (fractional) polarised intensity. Here is an example of how to do this sort of polarimetric plot, where in this case the total intensity is displayed as both contours and a grey scale. The contours are displayed as multiples of the rms of the noise (you input the rms) in this case, although you can also use percentage-of-the-peak contours (this is controlled by the slev keyword -- see the help file). You may need to fiddle with the keyword vecfac which allows you to scale the lengths of the vectors, and also specifies whether you draw a vector for each pixel or leave some of them out. The default is to draw a vector every second pixel and to scale the vectors so that the longest one takes up 1/20 of the plot. You can display any combination of the images ( e.g. vectors only), but you must give both the vector position angle and amplitude images.

     

  5. The final example is also polarimetry display. Displaying rotation measure images as a pixel map is sometimes unsatisfying, as the sign changes, if any, can be hard to see. Similarly, contours can be pretty useless as the RM distribution is often very unsmooth. cgdisp offers the image type ``box'' whereupon each pixel is displayed as a small box. Positive pixel values are shown as a solid box, and negative pixel values as a frame only. The size of the box is proportional to the values of the pixel, so that this method is not so useful if you have RMs close to zero. By default, the boxes are scaled so that there is a little gap between adjacent boxes. You can control the boz sizes with the keyword boxfac which gives an extra scale factor to multiply the box widths. This keyword also gives the x and y increments (in pixels) across the image at which to plot the boxes.

     In this example, we also overlay contours of total intensity. In addition, a global blanking mask is appplied to both images.

     

• One drawback to the current TV server programs is that you cannot read the image pixel value and location with the cursor ( xmtv goes part way to this, see Chapter 3). The task cgcurs is similar to cgdisp except that it is less flexible in terms of what it can display, but it does offer an interactive capability with the cursor. You can read image pixel locations and values, compute statistics over a region defined by the cursor, and define polygonal spatial regions that can be output into a text file for use in other programs (using the region=@ file facility). In addition, cgcurs can be used to generate text files in a format suitable (almost) for input to cgdisp and cgspec as overlay files.

  cgcurs only displays pixel maps or contour plots, and only one image at a time. You can invoke all of cgcurs ' cursor options in the one run if you wish. You can also display many channels in the same way as cgdisp ; in this case, the cursor options are invoked after each sub-plot (channel) is drawn. The following example shows how to display all pixels in the x direction, but only every third pixel in the y direction (who knows why you might do this), activate the interactive lookup table fiddler, read some image values with the cursor, mark their locations on the plot, and output them into a text file (called `cgcurs.cur') for use as an overlay file in cgdisp . In addition, the option to evaluate some statistics in a region defined by the cursor is also activated.

  

• The task cgslice allows you to generate 1-D cuts (slices) through a 2-D image and then fit Gaussians to these slices. You can define many slices with the cursor or input their positions via a text file. In addition, you can display many channels from an image, and generate slices differently from each channel. Like cgcurs , cgslice only displays one image (which could be 3-D of course) at a time via a pixel map or a contour plot. You can save the slice locations, values and model fits in text files.

  In the example, we make slices from 9 channels of a cube, one channel at a time. We then fit Gaussians plus a baseline to them and output the fits into a text file.