.help contour Aug91 plot
.ih
NAME
contour -- draw a contour plot of an image
.ih
USAGE
contour image
.ih
PARAMETERS
.ls image
Two dimensional image or image section to be contoured.
.le
.ls floor = INDEF
Minimum value to be contoured.  If \fBfloor = INDEF\fR, the data minimum is
used for the floor.
.le
.ls ceiling = INDEF
Maximum value to be contoured.  If \fBceiling = INDEF\fR, the data maximum
is used for the ceiling.
.le
.ls zero = 0
Greyscale value of the zero contour, i.e., the value of a zero point shift
to be applied to the image data before plotting.  Does not affect the values
of the floor and ceiling parameters.
.le
.ls ncontours = 0
Number of contours to be drawn.  If 0, the contour interval may be specified,
otherwise 20-30 nicely spaced contours are drawn.  A maximum of 40 contours
can be drawn.
.le
.ls interval = 0
Contour interval.  If 0, a contour interval is chosen which places 20 to 30
contours spanning the intensity range of the image.
.le
.ls nhi = -1
If -1, highs and lows are not marked.  If 0, highs and lows are marked
on the plot.  If 1, the intensity of each pixel is marked on the plot.
.le
.ls dashpat = 528
Dash pattern for negative contours.
.le
.ls device = "stdgraph"
Output device (\fBstdgraph\fR, \fBstdplot\fR, or the name of a physical
device).
.le
.ls xres = 64, yres = 64
The input image is block averaged or subsampled to this resolution.
.le
.ls preserve = yes
If \fBpreserve\fR = yes, the aspect ratio of the image is preserved when 
achieving the resolution specified by \fBxres\fR and \fByres\fR.
.le
.ls subsample = no
The resolution specified by \fBxres\fR, \fByres\fR is achieved by block 
averaging unless \fBsubsample = yes\fR.
.le
.ls perimeter = yes
A \fIcrtpict\fR perimeter is drawn around the contour plot with labeled
tickmarks.
.le
.ls label= yes
By default, the value of each major contour is embedded in the contour
line.  This can be disabled by setting \fBlabel=no\fR.
.le
.ls vx1 = 0.0, vx2 = 0.0, vy1 = 0.0, vy2 = 0.0
The device viewport, in normalized device coordinates (from 0.0 to 1.0
inclusive).  If not specified by the user,
\fBcontour\fR automatically centers the plot on the device viewport.
.le
.ls fill = no
Fill the output viewport regardless of the device aspect ratio?
.le
.ls title = "imtitle"
A title to be centered above the plot.  The user can specify a title string;
the default string is the image title.
.le
.ls append = no
Append to an existing plot?
.le
.ih
DESCRIPTION
Contours are traced, smoothed with splines under tension, and optionally printed
with embedded intensity labels.  Positive contours are printed as solid
lines and negative contours as dashed lines.  The plot is generated
by the NCAR \fBconrec\fR utility, using \fBdashsmth\fR to smooth the
contours and draw dashed lines.  

To speed up the contouring, the resolution of the image to be plotted can
be decreased to \fBxres\fR by \fByres\fR.
When \fBpreserve\fR = yes, \fBcontour\fR 
automatically reduces the image in both directions by the same factor, which
is the larger of [ncolumns / xres or nlines / yres]. If the
aspect ratio is not being preserved, the x and y dimensions are independently
reduced to the specified resolution.
No reduction is done if \fBxres\fR and \fByres\fR = 0, if the input image is 
an image section, or if the image is smaller than \fBxres\fR by \fByres\fR.

If the device viewport (plotting area) is not set by the user,
\fIcontour\fR automatically
sets a viewport centered on the output device.  The default value of
\fBfill=no\fR means the viewport will be adjusted so that equal
numbers of image pixels in x and y will occupy equal lengths when plotted.
That is, when \fBfill = no\fR, a unity aspect ratio is enforced, and square 
images are represented as square plots regardless of the device aspect ratio.
On devices with non square full device viewports (e.g., the vt640), a 
square image will appear extended when \fBfill\fR = yes.  To completely
fill the device viewport with contour lines, disable perimeter drawing
and enable fill, and nothing but the contour map will be drawn.

Contour plots may be overlaid on a displayed image by setting the output
\fBdevice\fR to "imd" for image display and the contouring parameters
\fBfill\fR and \fBperimeter\fR to "yes" and "no" respectively. By default
green contours will be drawn on the image display. Other choices for
\fBdevice\fR are "imdr", "imb", "imdy", "imdw" and "imdg" for red, blue,
yellow, white and green output contours respectively.

.ih
EXAMPLES
1. Draw a contour plot of a 512 square image on the graphics terminal.
With the default values for \fBxres\fR and \fByres\fR, the image
would automatically be block averaged by a factor of 8 in x and y.

    cl> contour crab.5009

2. The plot could be output to the plotter as a background job:

    cl> contour crab.5009 device=stdplot &

3. Place a ceiling at an intensity value of 500 to cut out a noise spike.
The plot has been moved to the lower left corner of the display.

    cl> cont crab.5009 ceil=500 vx1=.1 vx2=.6 vy1=.1 vy2=.6

4. Overlay a contour plot of an image on the same image displayed on the
display device. Note that the CONTOUR parameters \fBfill\fR and \fBperimeter\fR
must be on and off respectively, the \fBfill\fR parameter should be specified
for the DISPLAY task to ensure the image fills the frame buffer in the 
same way.

.nf
    cl> display m51 1 fill+
    cl> cont m51 fill+ per- device=imd
.fi
.ih
TIME REQUIREMENTS
The time required for \fIcontour\fR depends on the number of contours
being drawn - that is, the size and smoothness of the intensity array.
A 512 square image of "average" smoothness, with x and y resolution equal to
64, requires about 22 cpu seconds with block averaging.  Using subsampling
rather than block averaging, \fIcontour\fR takes 16 seconds.  A noisy
picture will be plotted more quickly if block averaged rather than
subsampled.
.ih
BUGS
If block averaging is used the precision with which a contour is drawn
will be no better than the blocking factor.  For example, if a contour
map drawn with a block averaging factor of 8 is overlaid on an image of
a starfield, contours drawn around stars in the field may not appear to
be centered.  If this is a problem the solution is to increase the plotting
resolution using the \fIxres\fR and \fIyres\fR parameters.

It should be possible to have list input as well as image section input.
.ih
SEE ALSO
surface, display, imdkern, imexamine
.endhelp
