MAPPLOT

MAPPLOT is a program for displaying images produced by the VLBI program package. It can display any images in standard FITS-format files (including those produced by CLEAN, MODMAP, and VLBMEM). It can produce contour maps, grey-scale or color images, or ruled-surface plots.

Contents

Example

The following example makes a contour map on the default X-Window display and then makes a copy in a file PLOT.LIS for printing on a PostScript printer.


$ MAPPLOT
MAPFILE="[SCRATCH]MAP.SU1"
PLOTFILE = "/XWIN"
PLEV=1
LEVS=-5,5,10,15,20,50
BEAM
TITLE = "17th iteration"
/
PLOTFILE="PLOT.LIS/VPS"
/
EXIT
/
$

Parameters

All filenames and parameters are specified in the usual keyword=value format. To display a picture, type a slash (/); to leave the program, type the end-of-file character (control-Z in VMS, control-D in Unix) or use the EXIT parameter.

General Parameters

MAPFILE = "filename"
specifies the name of the input file. Several files can be displayed in one run of MAPPLOT. The default file name is "MAP". [In VMS, a logical name assignment can be used to specify the input file, e.g., DEFINE MAP CITSCR:[TJP]MAP345.DAT.]
PLOTFILE = "filename"
specifies the device for graphics output, "/scr/tjp/plot/PS" or "/GR" or "PLOT.LIS/VERS". All plots are sent to the same device until a new value is specified for PLOTFILE. If PLOTFILE is not specified, MAPPLOT will prompt for a device specification.
NPXY = nx, ny
Use this parameter to plot several pictures on one page. nx is the number of pictures across the width of the page, ny the number vertically; e.g., NPXY=2,1 to display two maps side-by-side.
STYLE = "code"
STYLE may be "C" for a contour map, "G" for a grey-scale or color intnesity map, "CG" for both superimposed, or "S" for ruled-surface plot. [Either the equals sign or the quotation marks can be omitted, but not both.]
XRANGE = i1,i2 YRANGE = j1,j2
These two parameters control how much of the map is displayed. The values are pixel numbers, in range 1 to dimension of map. The default, obtained by XRANGE=0,0 or YRANGE=0,0 displays the whole of the map. In images made with CLEAN, MODMAP, or AIPS tasks (and probably most FITS images), the X pixel number increases from left to right and the Y pixel number increases from bottom to top; i.e., the (1,1) pixel is displayed in the lower left corner.
UNITS = string
If the image is a standard sky image with the two axes being angles on the sky (e.g., RA and DEC), this parameter can be used to force the axes to be labelled in specific units. The options are UNITS = "MAS", "MILLIARCSEC", "ARCSEC", "ARCMIN", "DEGREE", "RAD". The default (a blank string) causes MAPPLOT to choose units automatically, depending on the size of the image. If the axes are not angles on the sky, MAPPLOT will use the units specified in the image header.
SHIFT = dx,dy (default 0,0)
This parameter changes the coordinate system of the map. The image displayed is unchanged, and unshifted on the paper; however, the coordinate labels are shifted by (dx,dy). The units of dx and dy are milliarcsec. The point in the image (usually the map center) that is labelled (0,0) if SHIFT is not specified is labelled (dx,dy) when SHIFT is applied. SHIFT only applies to an image in which the axes are RA and DEC, and only when LTYPE=4 (labelling relative to center) is specified. One application of shift might be to center the coordinate system on the brightest component rather than the arbitrary map center.

Parameters for Grey-Scale or Color Images

PALETTE = number
A number of fixed pseudo-color palettes are available. The default is PALETTE=1, which produces an image with intensity mapped to grey-scale shades. The options are:
  1. Grey scale, running from white to black.
  2. `Rainbow': blue-green-yellow-orange-red.
  3. `Heat': black to white through shades of orange and yellow.
  4. `IRAF': color bands.
  5. `AIPS': color bands.
  6. Try it and see.
BLACK = b-level WHITE = w-level
These parameters are used when STYLE = "G" is specified. They control the range of image values that are for grey-scale or color images. (The names BLACK and WHITE only make sense for grey scale, though!) b-level and w-level are expressed as fractions of the peak brightness on the map. Pixels with values in this range are mapped onto the color palette by linear interpolation; pixels outside this range take the extreme colors. Note that BLACK may be either less than or greater than WHITE; BLACK=WHITE is not allowed.

When using PALETTE=1, the default values (BLACK=1, WHITE=0) are such that all negative and zero values are plotted white, and the maximum of the map is black. The scale can be inverted by specifying BLACK=0, WHITE=1. To accommodate negative values, you might want, say, BLACK=-1, WHITE=1. I hope to find a more user-friendly way to adjust the palette in a future version of MAPPLOT.

WEDGE
when this parameter is specified, MAPPLOT puts an annotated grey-scale or color wedge in the lower margin (if STYLE=G).

Parameters for Contour Maps

PLEV = p CLEV = c LEVS = l1,l2,l3... (up to 20 levels)
LEVS specifies up to 20 contour levels in units of the contour interval. The contour interval may be specified as EITHER a percentage of the peak (PLEV), or in the units of the map (CLEV). CLEV is only used if PLEV is zero. If you do not specify LEVS (or specify all zero values), the program will use default values of +/- 1, 2, 4, 8, ..., 512. In conjunction with the default value of PLEV (5%), this gives contours at +/- 5, 10, 20, 40, 80% of maximum. Negative contours are dashed. If you make more than one plot in a single run of MAPPLOT, and you want to draw fewer contours than in the previous plot, you will have to specify dummy zero values for LEVS to override the levels established previously; e.g.,

First run: 5 levels: LEVS = 1,5,10,15,20

Second run: 3 levels: LEVS = 1,25,50,0,0

If you do not specify the extra ",0,0" the levels used will be 1,25,50,15,20.

Parameters for Ruled-Surface Plots

ANGLE = x
specifies the elevation angle (in degrees) from which the surface is to be viewed. The default is 25 degrees. 0 gives a profile, 90 gives a plan view (not very useful).

General Plotting Parameters

FONT = n
specifies the font to be used for annotating the plot (1 = normal, 2 = roman, 3 = italic, 4 = script); default = 1.
LINEWIDTH = n
specifies the linewidth to be used when plotting. The default (1) is recommended for most devices; 2 or 3 gives good results on laser printers.
CONTLW = n
specifies the linewidth to be used for contours (if a different value from LINEWIDTH is required).
COLORS = c1, c2, c3, c4, c5, c6
specifies the color indices to be used for (1) annotation, (2) positive contours, (3) negative contours, (4) grey-scale, (5) upper surface of STYLE=S plots, (6) lower surface of STYLE=S plots. The defaults are 9, 1, 2, 1, 5, 2 which normally makes negative contours red. Specify 1,1,1,1,1,1 to produce a monochrome plot (black on white or white on black).

Annotation Parameters

LTYPE = n
specifies how the plot is to be labeled: specify: [Other values for LTYPE used by the AIPS task CNTR are not implemented in MAPPLOT.]
BEAM
if this parameter is specified, the elliptical FWHM contour of the restoring beam will be drawn in the lower left corner of the plot; this does not apply to MEM maps and other images which do not have restoring beams.
BPOS = x,y
if this parameter is not specified, the beam ellipse (requested by parameter BEAM) is drawn in the lower-left corner of the plot; BPOS can be specified to control where the ellipse is plotted. The beam will be centered at position (x,y) in the map coordinate system (usually the coordinates are milliarcsec).
CHARSIZE = x1, x2
specifies the character size to be used in annotating the plot, as a multiple of the default size. The first number is used for axis labels, title, etc.; the second number is used for the additional annotation at the bottom of the page. The defaults are 1.0, 0.6. Size 1.0 gives characters that are about 1/40 of the height of the plot.
MARK = x, y, symbol
A single point on the image can be identified with a graph marker, centered on the point. The image point is specified by (x,y) in the image coordinate system (e.g., arcsec). The marker shape is specified by `symbol': the number of a PGPLOT graph marker in range 1-32.
TITLE = "Line1","Line2"
two text strings to be written above the plot (outside the frame). In both lines you may use the following codes to insert information as desired: The default is TITLE = "", "%s %t %f %d", i.e, the upper line is blank, and the lower line gives source name, telescope name, frequency, and date. If you just want to omit the telescope name, try TITLE = "","%s %f %d". You can do more complicated things, e.g., TITLE = "Source %s observed on %d", "with array %t at %w". You can also use the PGPLOT codes for changing font, e.g. TITLE = "\frSource = \fi%s","".
TOPLEFT = "Text"
TOPRIGHT = "Text"
BOTLEFT = "Text"
BOTRIGHT = "Text"
Arbitrary text strings can be written in the corners of the plot (inside the frame). The %-codes described under TITLE are active in these parameters also.
LABEL1 = x, y, "Text"
if specified, the supplied text string (up to 48 characters) is written in the plot with its lower left corner at coordinate position (x,y). Up to eight such labels can be written by specifying parameters LABEL1, LABEL2, LABEL3, ... LABEL8. Note that the units of the (x,y) coordinates must be those in which MAPPLOT labels the map. Thus for LTYPE=6, they are pixels; for other values of LTYPE, they are angular coordinates (usually milliarcsec). For surface plots, (x,y) are measured from (0,0) in the lower left corner to (1,1) in the upper right corner.
Z, H0, Q0, BARLENGT
If requested, a linear scale bar is drawn in the lower right corner of the map. This is controlled by the parameters Z, H0, Q0, and BARLENGT. If Z is not specified (or is zero or negative) no scale bar is drawn: Example: Z = 0.518 H0 = 100 Q0 = 0.5 BAR = 50
NOTITLE
this parameter suppresses the axis labels (Relative R.A. etc.).
ANNOT
this parameter controls the annotation that appears at the bottom of the page. ANNOT=1 (the default) requests full annotation; ANNOT=0 suppresses the file name and date and time (which should be omitted in a plot designed for publication); ANNOT=-1 suppresses the annotation entirely.
OPAQUE
If this parameter is specified (with no value or a non-negative value), the annotation that is written on top of the image (e.g., with TOPLEFT) is ``opaque'': it erases underlying parts of the image. This may make annotation easier to read if the underlying image is complex.

Overlaying Plots

OVERLAY (default -1)
If this parameter is specified with a positive or zero value, or no value, then the current image is plotted on top of the previous image in the same coordinate frame, shifting the image as necessary to align the two coordinate systems. OVERLAY is reset to the default (-1, no overlay) for each group of parameters. OVERLAY must not be specified on the first plot (there is nothing to overlay). If SHIFT is used with OVERLAY, the image is actually shifted relative to the coordinate frame.
Example: to display two contour maps on top of each other in different colors, with a possible shift of the coordinate system:
  MAP = map1.fits		! name of first image file
  PLOT = /xw
  /				! first image is displayed as usual
  OVERLAY			! request an overlay image
  MAP = map2.fits		! name of second image file
  COLOR(2) = 7			! request different color for contours
  SHIFT = -2.3,1.2		! shift the center of this image to
				! coincide with that of the first image
				! (some trial and error may be needed)
  TITLE = "",""			! suppress title and annotation
  ANNOT = -1
  /				! second image is displayed as an overlay
Caution: An OVERLAY image also overlays the annotation, so you may want to suppress this as in this example. There aren't many checks that what you're doing is sensible; e.g., overlaying a contour plot on a mesh diagram will probably not work. Do not use grey-scale for the overlay: grey-scale images are opaque!

Window Parameters

LRTB = x1,x2,y1,y2,...
a list of up to 80 numbers, representing 20 rectangular windows. These are defined in exactly the same way as for CLEAN. If LRTB is provided (i.e., non-zero) MAPPLOT will draw the windows on the plot.
SETWINDOW
specify this switch to request interactive window editing. (Do not specify it with a hardcopy device or a batch job.) If SETWINDOW is specified (i.e., a value greater than or equal to zero, or no value), then after drawing the plot MAPPLOT will go into interactive mode. In this mode, you can add new windows or delete some or all of those specified via LRTB.

Setting Windows

MAPPLOT can be used to draw windows on the screen which can then be used as LRTB parameters in CLEAN. To enter the window-editing mode, specify parameter SETWINDOW.

To delete a window, position the cursor in the window and type D (or click the middle mouse button on a workstation). MAPPLOT erases the window outline by overwriting in black. If the cursor is in more than one window, only one (a random one) will be deleted.

To add a window, position the cursor at one corner and type A (or click the left button); then position it at the opposite corner and type A again (or click the left button again). MAPPLOT draws the outline of the window.

To exit from this mode, type X or click the right mouse button. You are returned to MAPPLOT parameter input, with the new window list set as the default. You can see the current windows by typing SHOW LRTB. The current windows are also saved in a file called lrtb.par, in KEYIN format. This file can be input to CLEAN or MAPPLOT by typing "@lrtb".

Alternatively, exit by typing S (save). In this case, you will be asked to supply a file name.

To exit without writing a file or updating the windows, type Q (quit).

Annotation

The plot generated by MAPPLOT can be annotated in three places: above the plot, below the plot, and within the plot.

The annotation at the top of the plot consists of the two lines of text supplied with parameter TITLE, left justified. The first line is blank by default, and the second contains the object name (FITS parameter OBJECT), the telescope name (FITS parameter TELESCOP), the frequency, and the date of observation (FITS parameter DATE-OBS).

The annotation at the bottom of the page consists of four or five lines of text giving:

  1. The maximum of the image, in the image units (e.g., Jy/beam).
  2. The contour levels in percent of the maximum (these are the contours actually plotted; contours that were requested but not plotted because they fall outside the range of the image are not listed).
  3. The FWHM dimensions and position angle of the "clean beam" (if appropriate).
  4. The file name of the image.
  5. The version of MAPPLOT, username, date and time.
The annotation can be suppressed by specifying ANNOT=-1. ANNOT=0 suppresses the last two lines only. By default (ANNOT=1) annotation is enabled.

Up to four "legends" can be written within the frame of the plot, in the upper left, upper right, lower left, and lower right corners. The text for these legends can be supplied with parameters TOPLEFT, TOPRIGHT, BOTLEFT, and BOTRIGHT. By default, both these strings are blank. It is also possible to write labels at specific places within the frame using the LABEL1, LABEL2, LABEL3, ... LABEL8 parameters.

If the image header includes the clean beam parameters, the FWHM contour of the clean beam will be drawn on the plot if the parameter BEAM is specified. By default, the beam is drawn in the lower left corner of the plot. To place the beam at some other position, use parameter BPOSITION=x,y: x and y are the coordinates of the center of the beam in the coordinate system of the image (typically milliarcsec, with x increasing from right to left and y increasing from bottom to top).

History

Version 1.0: ? - (TJP).
Version 1.1: 1983 May 24 - add FONT, LINEWIDTH (TJP).
Version 2.0: 1984 Jan 23 - change map format to FITS, and remove special Grinnell plotting (TJP).
Version 2.1: 1984 Jan 30 - handle default contours better; label MEM maps correctly; add LTYPE and BEAM parameters.
Version 2.2: 1984 Jun 28 - fix to recognize AIPS-like coordinates RA---SIN and DEC--SIN (TJP).
Version 2.3: 1985 Jun 26 - add more info to legend (TJP).
Version 2.4: 1985 Jul 18 - add CHARSIZE parameter (TJP).
Version 2.5: 1985 Nov 24 - add TOPLEFT and NOTITLE parameters (TJP).
Version 2.6: 1986 Jul 7 - add BPOS parameter (TJP).
Version 2.7: 1986 Jul 28 - add annotation (TJP).
Version 2.8: 1986 Nov 1 - more annotation: TOPRIGHT, ANNOT, CONTLW, NPXY (Tasso Tzioumis).
Version 2.9: 1987 Apr 4 - improved annotation of grey scales; add COLORS (TJP).
Version 3.0: 1988 Apr 15 - changes for Convex (TJP).
Version 3.1: 1988 Jul 20 - add additional labels, enable LTYPE=6 (TJP).
Version 3.2: 1989 Jun 30 - correct bug (beam annotation wrong if beam not plotted) (TJP).
Version 3.3: 1989 Aug 23 - increase maximum array size (TJP).
Version 3.4: 1989 Sep 10 - add WEDGE parameter (TJP).
Version 3.5: 1990 Jan 10 - remove FORMAT=MEM option (MEM maps are now in FITS format).
Version 3.6: 1991 Mar 25 - better placement of beam, change annotation (TJP).
Version 3.7: 1991 Apr 1 - correct minor bug (TJP).
Version 3.8: 1991 Apr 17 - handle rotated maps (TJP).
Version 4.0: 1991 May 14 - add windows (TJP).
Version 4.1: 1991 Dec 23 - add surface option; add more ANNOT, CHARSIZE, COLOR options (TJP).
Version 4.2: 1992 Jul 6 - add FORMAT=INV option (Edward King); add statistics (TJP).
Version 4.3: 1993 Mar 18 - add more LABELx parameters (TJP).
Version 4.4: 1993 Apr 27 - allow longer telescope names (TJP).
Version 4.5: 1993 May 14 - allow user to format legend (TJP).
Version 4.6: 1993 Sep 20 - add linear scale (TJP).
Version 4.7: 1993 Oct 16 - add OPAQUE option (TJP).
Version 4.8: 1993 Nov 8 - add OVERLAY, SHIFT (TJP).
Version 4.9: 1994 Feb 9 - add BOTLEFT, BOTRIGHT (TJP).
Version 4.10: 1994 Mar 14 - handle negative maps better (TJP).
Version 5.0: 1994 Aug 8 - add UNIT parameter to force scaling (TJP).
Version 5.1: 1994 Nov 10 - fix bug (failing to call PGBEG) (TJP).
Version 5.2: 1996 Feb 8 - label bar in kpc if necessary (TJP).
Version 5.3: 1996 Dec 20 - change wedge display (TJP).


Tim Pearson, California Institute of Technology
tjp·astro.caltech.edu