OVERLAY: Draw contours over a Greyscale Image (PostScript)

Form: OVERLAY ibuf [IBOX=b] [cbuf] [CBOX=b] [PROF] [PROF=n]
[Z=zero] [L=span] [CLIP] [POSITIVE] [NOBIN] [LEVELS=(c1,c2,c3,...)] [LOW=f] [RATIO=f] [DIFF=f]
[NC=n] [FID=f] [CTHRESH=f] [DASH] [LTYPE=n] [LWEIGHT=f] [COLOR=c] [COLOR=r,g,b]
[EXACT] [TITLE] [BAR=xxx] [COMMENT] [COMMENT=xxx] [SCALE=s] [CEN=r,c] [LAND] [MACRO=xxx] [FILE=xxx]
[NOAXES] [NOBAR] [LARGE] [INFO] [WIND=w,h] [ORIGIN=x,y] [PAGE=L,S] [COPIES=n]
ibuf
the buffer containing the grayscale image
IBOX=
only consider the pixels of the grayscale image within IBOX
cbuf
the buffer containing the contour image
CBOX=
only consider the pixels of the contour image within CBOX
PROF
instead of a contour image, draw the current best fit isophotes in the PROFILE common block
PROF=n
Only draw every Nth isophote in the PROFILE common block
Keywords controlling the grayscale image appearance:
Z=zero
Zero point of the intensity mapping. Default value is 0.0
L=span
Span of the intensity mapping. If none is specified, the default value will be taken to be 4 times the image mean.
CLIP
Prevent roll-over of the intensity mapping. Default is no clipping.
POSITIVE
Make the hardcopy White-on-Black background. Default is Black-on-White (conventional photonegative).
NOBIN
Suppresses autobinning if the image is larger than about 512x512 pixels. Default is autobinning.
Keywords controlling the contour map
LEVELS=(c1,c2,c3,...)
set the levels explicitly. Up to 40 contours may be given on the command line.
LOW=c0
Lowest contour to be drawn
DIFF=f
Difference between contour levels (equally spaced contours)
RATIO=f
Ratio between contours (for log-spaced contours). RATIO and DIFF are mutually exclusive
NC=n
Limit the number of contours drawn using LOW/DIFF or LOW/RATIO to N (up to a maximum of 100).
FID=f
Define a fiducial contour. Levels above this value are drawn with the default line type, below are dashed, and the fiducial contour itself is drawn with a heavier line weight. Default fiducial is the zero contour.
CTHRESH=f
All contours with intensity above this level will be drawn in reverse color (default: white). Provides a means for rudimentary contour "visibility" against saturated colors on the grayscale. Default is uniform color.
DASH
All contours are to be drawn as dashed (not just those below the fiducial level). Default is solid lines above fiducial.
LTYPE=n
Draw contours with LickMongo line type N (see table below)
LWEIGHT=f
Draw contours with line weight F (Default is 0.5)
COLOR=c
Draw contours with color C. Default is black. A color table is given below.
COLOR=r,g,b
Draw contours with the RGB color given. 0 <= RGB <= 1. Allows for arbitrary colors (or shades of gray).
EXACT
Contours are drawn using a slow contour-following algorithm. Default: fast rastering algorithm.
Keywords affecting the axes of the plot
TITLE
Put a title (in FITS header OBJECT card for the grayscale image) on the plot.
BAR=XXX
Label the intensity scaling bar with string "xxx" to indicate the units. Default label is "Intensity".
COMMENT
Print a comment line on the plot. Comment lines may
COMMENT=
be up to 64 characters long.
SCALE=s
Pixel scale in units/pixel for the image. The axis ticks will be in these units rather than pixels (default). The origin is assumed to be the image center unless the CEN=(r,c) keyword is used.
CEN=(r,c)
The center of the image in pixels for use with the SCALE=s keyword. Default center is the image array center, unless PROF or PROF= was called, then the isophote center is used
MACRO=xxx
External file with LickMongo commands to be executed after the plot is completed. Provides a facility for customizing axes and adding annotation.
LAND
Orient the plot in landscape mode. Default is Portrait.
FILE=xxx
Direct the PostScript Image into a file named xxx. By default, OVERLAY writes the image into IMAGE.PS in the current working directory.
NOAXES
Supress plotting of coordinates axes on the image.
NOBAR
Supress plotting of the intensity scaling bar
LARGE
Expand the plot as large as possible for the given paper size while still preserving the 1:1 axis aspect ratio.
INFO
Write in a line of auxilliary info along the bottom of the page in small type.
Advanced Output Format Control
WIND=(w,h)
The maximum possible size of the plotting window in inches. This defines the largest region that OVERLAY will try to fit the image into. Defaults:
Portrait: 6" x 6"
Landscape: 8" x 5"
Must be smaller than the paper dimensions (see PAGE).
ORIGIN=(x,y)
origin of the plotting window in inches, measured from the lower left-hand corner of the page. X is horizontal, and Y is vertical. Default centers the window.
PAGE=(L,S)
physical size of the paper in inches. "L" = long dimension, "S" = short dimension. Default: (11,8.5) Used if making a plot for an odd-sized paper printer.
COPIES=n
Number of copies to print. Default is 1 copy. Makes the generation of multiple 1st generation copies efficient.
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):

Color Codes
Code Color Code Color
  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:

Line-Type Codes
LTYPE Style    
  Solid    
1 Dotted    
2 Short Dash    
3 Long Dash    
4 Dot / Short Dash    
5 Dot / Long Dash    
6 Short Dash / Long Dash    

Examples:

OVERLAY 1 2 Z=0. L=100. CLIP LOW=30. RATIO=1.5 SCALE=0.32 FILE=n1068.ps
Plots the image in buffer 1 as a grayscale map with values running from 0. to 100.0 rendered as white-to-black, and draws on top of that figure the image in buffer 2 as a contour map with contours running from 30.0 an spaced geometrically every factor of 1.5 in intensity. The axes are scaled as 0.32 arcseconds/pixel referenced to buffer 1, with the origin (0,0) assumed to be the center of buffer 1. The output is directed to a file called n1068.ps in the current working directory for later printing at the user's discretion (there is no autoprinting).
OVERLAY 1 1 Z=0. L=100. CLIP LOW=20. DIFF=20. SCALE=0.32 FILE=graycon.ps
This plots the image as a grayscale, with the given Z and L, and then plots on top of this the image intensity contours, starting at 20 and spaced every 20 intensity units. The scale is 0.32 arcsec/pixel and the origin (0,0) is the image center. Output is sent to a file called graycon.ps (old AIPS users will recognize this kind of figure)
OVERLAY 1 PROF=3 Z=0. L=1000. CLIP FILE=isofit.ps
The image in buffer 1 is rendered as a grayscale plot between intensities (0:1000), and the current best-fit isophotes stored in the PROFILE common block are superimposed. For clarity, only every third isophote is plotted (including the first and last isophote). The output file is called "isofit.ps".
OVERLAY 1 PROF=3 Z=0. L=1000. CLIP CTHRESH=1000. FILE=isofit.ps
Same as (3) above, but now all best-fit isophotes with a mean surface brightness >= 1000. are plotted as white lines to make them visible against the black image pixels in the center.
OVERLAY 1 IBOX=2 4 CBOX=1 Z=0. L=1000. CLIP LEVELS=(.1,.2,.3,.5,.7,.9)
SCALE=0.51 CEN=(AXR,AXC) FILE=hacon.ps
The parts of buffer 1 within box 2 are rendered as a grayscale map between intensities (0:1000), with the contour levels of the parts of buffer 4 within box 1 are superimposed. The axes are scaled to 0.51 arcseconds/pixel, with the image center given by the results of a recent AXES calculation stored in the AXR and AXC variables (see AXES).
OVERLAY 1 IBOX=2 4 CBOX=1 Z=0. L=1000. CLIP LEVELS=(.1,.2,.3,.5,.7,.9)
NOAXES MACRO=hacon.mgo FILE=hacon.ps
Same as (5) except now no axes are drawn by OVERLAY, and instead the external LickMongo macro file "hacon.mgo" in the current working directory is used to draw the axes and put on custom labels. Output is directed to the PostScript file hacon.ps.
OVERLAY 1 PROF=3 Z=0. L=1000. CLIP FILE=isofit.ps COLOR=3
LTYPE=2
Same as (3) above, but this user has a color PostScript device, and is plotting the best-fit isophotes as dashed green lines (no accounting for taste).
OVERLAY 1 PROF=3 Z=0. L=1000. CLIP FILE=isofit.ps COLOR=.7,.7,.7
LTYPE=2
Having the plot made in (7) thrown back by his co-authors, the user now draws the best-fit isophotes as 70% gray dashed lines.