- 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.