The OVERLAY command creates a PostScript file displaying one image as a grayscale map with a contour map of a second image superimposed upon it. Contours can be from an image in a VISTA buffer or the output of one of the VISTA isophote fitting routines (e.g., PROFILE). OVERLAY has many keywords, most an amalgamation of the basic keywords used by the POSTIT and CONTOUR commands. The PostScript file is written into the user's current working directory, named either "image.ps" or the name given by the user with the FILE= keyword. PostScript files generated by OVERLAY conform closely to both the general and "encapsulated" PostScript standards, and so may be printed on most PostScript laser printers (both monochrome and color), or included in documents or other programs that can import PostScript image files. We suggest using a workstation PostScript "previewer" program (of which the GhostView program provided public domain by the Free Software Foundation is an excellent choice) will save much time and wasted paper.
One barrier to making this routine fully general is a lack of a fully developed standard for specifying the mapping from pixels to some kind of world coordinate system (e.g., RA and Dec) in FITS format images. To get around this problem for the present time, OVERLAY makes some restrictive assumptions about the relatives spatial scaling and registration of the two images. For argument, we will call the buffer that contains the image to be rendered as a grayscale map as the "gray image", and the buffer with the image to be rendered as a contour map as the "contour image". Eventually, the FITS WCS conventions will become common enough to implement them here.
The first assumption is that while the gray and contour images do not have to have the same sizes in pixels, they are assumed to map into the exact same region in world coordinates. Thus, given a 300x300 pixel gray image that spans 30-arcseconds on a side, if the contour image is 512x512 pixels in size, it will be assumed that 512 pixels maps into 30-arcseconds as well (or, put another way, will assume that the pixel scale of the contour buffer is 300/512 times that of the gray image).
The second assumption is that the two images have the same aspect ratio. This is trivial if both images are square (buffer sizes of 300x300 and 512x512 pixels, respectively, for example). If they are NOT square, then OVERLAY assumes that the gray image will define the box, and that the contour image fits snugly into it. In other words, the contour image is not allowed to overflow the gray image. When there is an argument about sizes, the gray image is the reference (and wins by default).
The third assumption is that the two buffers are perfectly aligned (or registered) spatially. Thus if the gray image is a B-band image and the contour image is a K-band image, it assumes the stars will line up perfectly when the arrays are overlaid.
These assumptions can be controlled by a judicious choice of boxes. The IBOX= keyword specifies the box to use for the gray image, and the CBOX= keyword is used for the contour image. A further trick is to pick one image as the fiducial and shift the other image to line up. For example, if overlaying a radio map with a strong nuclear peak on an optical image of a galaxy, shift both images so that the centroid falls exactly on the center of a pixel. Remember that the registration of the images by this program is assumed to be on an integer grid.
Black contours drawn against a black pixels are not too effective. To provide a first-cut at getting around this problem the user can set the CTHRESH= keyword to an intensity value in the contour buffer above which the color of the contours is reversed (i.e., drawn as white). This improves the contour "visibility" against a dark background. At present, the LickMongo contour "image model" does not make it easy to compare the two images and choose the color dynamically (volunteers?). All contours with value above the indicated threshold are drawn in reverse color, while contours below this value are drawn as black.
A further aid to improving visibility is the NC= keyword that is used to limit the number of contours drawn when the LOW= and DIFF=/RATIO= keyword pairs are used to specify the contour levels. This suppresses the drawing of many high-level contours (e.g., for bright stars when the primary contouring object is some faint extended source). Such contours can crowd together, blotting out any underlying features. At present, the ultimate limit is 100 contours. Restricting the number of contours drawn can also reduce the size of the final PostScript file by eliminating unnecessary high levels.
PROFILE Plotting
Using OVERLAY with the PROF or PROF=n keywords is the PostScript analog of the TVPROF command. In this case, PROF is used in place of a buffer with a contour image (note that PROF and a contour image buffer are mutually exclusive). The profile parameters to be plotted as elliptical isophotes are taken from the PROFILE common block, either loaded using one of the fitting programs like PROFILE, or loaded from a SAVE'd profile computation with the GET command.
The optional argument of the PROF keyword tells OVERLAY to only plot every Nth isophote for clarity. If the CTHRESH= keyword is given, the color of the isophote will be reversed if the value of the mean surface brightness of that counter is greater than or equal to CTHRESH. This allows the user to plot inner contours that would otherwise get lost against the dark inner galaxy as white lines, making them "visible". A fancier contour visibility algorithm will take more time to come up with (volunteers?).
Axis Plotting
A number of keywords are provided to allow customization of the plotting axes. These are identical in function to those familiar from the POSTIT and CONTOUR commands. By default, the pixel coordinates of the gray image are used. The SCALE= and CEN= keywords can be used to specify an image scale (arcseconds/pixel) and fidicual image center (coordinates in (R,C) corresponding to (0,0) in arcseconds), again referenced to the gray image. If the PROF keyword is used to overlay best-fit isophotes, the CEN= keyword will be overridden by the isophote centers stored in the PROFILE common block, if and only if the SCALE= keyword is given. The NOAXIS keyword will suppress plotting of any axes, only drawing a box around the gray image.
A more sophisticated option for customizing the axes, and for adding labels or other annotation is the MACRO= keyword that executes LickMongo plotting commands stored in an external file. See the help file for the POSTIT command for some details on how this is used.
Additional commands are provided for changing the size and orientation of the plot on the paper. These are identical to the keywords given in the POSTIT command, and described in detail there.
Special Goodies
Users with access to color PostScript printers can define contours in colors, either using the COLOR=n keyword to select a preset color, or COLOR=r,g,b to roll your own custom color. Users without this facility can cheat and use the COLOR=r,g,b keyword to make contours a shade of gray different then black, enhancing their visibility against a dark background (within limits imposed by your printer engine). The preset colors are as follows (same table as CONTOUR):
| Code | Color | Code | Color |
| 0 | background | 4 | Blue |
| 1 | foreground | 5 | Yellow |
| 2 | Red | 6 | Magenta |
| 3 | Green | 7 | Cyan |
RGB colors are specified with 0<=R,G,B<=1, and to make a shade of gray, all three color levels are specified the same. For example, a 50% gray color is COLOR=0.5,0.5,0.5, and 50% red would be COLOR=0.5,0.,0.
Different line types or line widths may be chosen using the LTYPE= and LWEIGHT= keywords. The default line width is LWEIGHT=0.5, whereas LWEIGHT=1.0 is equivalent to the weight of the axes drawn around the image box. The LTYPE code is a standard LickMongo line style code:
| LTYPE | Style | ||
| 0 | Solid | ||
| 1 | Dotted | ||
| 2 | Short Dash | ||
| 3 | Long Dash | ||
| 4 | Dot / Short Dash | ||
| 5 | Dot / Long Dash | ||
| 6 | Short Dash / Long Dash |
Examples: