.help calcomp Mar86 plot
.ih
NAME
calcomp -- plot a GKI metacode file on a Calcomp pen plotter
.ih
USAGE
calcomp input
.ih
PARAMETERS
.ls input
Name of input GKI metacode file, file template, or list of files.
.le
.ls device = "calcomp"
Name of the destination plotter (as referenced in graphcap).
.le
.ls generic = no
Ignore remaining kernel dependent parameters -- if yes, then none of the
following parameters will be used; this is automatically the case, for
instance, when using ":.snap calcomp" from cursor mode.
.le
.ls debug = no
Print decoded graphics instructions during processing -- print each GKI 
metacode instruction on standard output.
.le
.ls verbose = no
Print elements of polylines, etc. in debug mode -- if yes, this is essentially
all of the information present in the input metacode file.
.le
.ls gkiunits = no
Print coordinates in GKI rather than NDC units if in debug mode.
.le
.ls xscale = INDEF
X scale in device units per GKI unit; e.g. 0.0003 is 3 ten-thousandths of an
inch per GKI unit on a plotter calibrated in inches; normally a plot is 32767
GKI units wide.  If the plotting task that generated the metacode file generated
a scale, this will be used if xscale is INDEF.  Specify xscale only if you wish
to override the scale in the metacode.
.le
.ls yscale = INDEF
Y scale in device units per GKI unit -- see xscale.
.le
.ls txquality = "normal"
Text quality; "normal" means use the text quality specified in the metacode
file.  "Low" means override the metacode font with the Calcomp symbol font,
while "medium" and "high" use IRAF fonts.  There is little difference in speed
with the different fonts, except if the text is bold, in which case "high"
takes twice as long as "low" or "medium".
.le
.ls lwtype = "ntracing"
Type of line and text width implementation.  "Ntracing" causes the pen plotter
to draw each line or character several times with slight offsets to simulate 
boldness.  "Penchange", if implemented in the local Calcomp library, would
cause the plotter to pause for an operator to change the pen when bold lines
or text are requested.
.le
.ls ltover = no
Line type override, if yes, causes the pen plotter to draw all lines solidly,
rather than as dashed or dotted lines if these are specified in the metacode.
This may be desired for previewing a plot quickly.
.le
.ls lwover = yes
Line width override; causes all lines and text to come out with single width
in order to speed up plotting.  If bold text, axes, etc. are desired and
present in the parent plot, then set lwover = no.
.le
.ls lcover = no
Line color override, if yes, causes the pen plotter to ignore any requests in
the metacode for a colored pen change.  Pen change is not implemented at all
sites with Calcomp plotters.
.le
.ls dashlen = INDEF
Length of the dash in dashed lines in device units, usually inches.  Shorter
dashes usually take longer to plot but may look nicer.  If left INDEF, a
local default from dev$graphcap will be used; a good range is 0.1 to 0.5 inches.
.le
.ls gaplen = INDEF
Length of the gap in dashed or dotted lines, in device units.  Longer gaps 
result in faster plotting at the expense of clarity.  If left INDEF, a local
default from dev$graphcap will be used.  A good range is 0.05 to 0.2 inches.
.le
.ls plwsep = INDEF
Parallel line width separation -- if bold lines are implemented with "lwtype
= ntracing", this is the right-angle distance between adjacent traces.  If
INDEF, a local default is used from the device table dev$graphcap.
.le
.ih
DESCRIPTION
Task \fBcalcomp\fR is an IRAF graphics kernel.  It may be run standalone to
plot a GKI metacode file, or from cursor mode via ":.snap calcomp".

\fBCalcomp\fR may be used to draw any IRAF plot on a Calcomp pen plotter.  It is
only available if the local site has a Calcomp library.  Task \fBcalcomp\fR
is an exact-scaling graphics kernel, unlike the NSPP, or STDPLOT kernel.
This means that if the task that generated the metacode input file passed an
exact scale into the metacode, data can be plotted to a desired precise scale.

The metacode scale may be overridden, or metacode files generated by tasks that
do not implement exact scales may be plotted to a precise scale, by specifying
xscale or yscale.  Note, however, that the only coordinates in a metacode file
are GKI coordinates, usually running from 1 - 32767.  This means that to use
xscale and yscale, the user must calculate the number of inches per GKI unit,
not the number of world or data units per inch.

\fBCalcomp\fR also implements dashed and dotted lines and bold lines and text.
Thus high-quality plots may be produced, at the expense of requiring more time.
If "lwtype=ntracing" and "lwover=no", any bold text or lines in the metacode
file, such as are produced for axes, tickmarks, titles and axis labels by many
IRAF plotting tasks, will appear bold on the Calcomp.  If txquality="low" or
"medium", and bold text is requested, each character will be drawn 5 times --
once in the center position and once to the right, top, left, and bottom of
the original position.  Each of the side positions is drawn "plwsep" inches
from the center.  If txquality="high", bold text is implemented with the same
five tracings plus the four corners upper right, upper left, etc.  For most
applications txquality="normal" or "medium" is adequate for nice-looking
plots.

When drawing data lines bold (only possible if the task originating the 
metacode specifically requested it, not the case for most IRAF plotting
tasks), the bounding parallel line traces are constructed to meet at sharp
points.  This looks fine for line intersections that are not too acute.  If
the intersection angle between two lines is very acute, say less than 5
degrees, the vertex of the parallel lines bounding to the outside may lie
quite a distance away from the actual vertex.  In the limit, if the 
intersection angle is zero, the outer vertex will lie at infinity.  For
this reason, all intersection angles less than 5 degrees are treated as
though they were exactly 5 degrees.
.ih
EXAMPLES
1. Plot a metacode file exactly as is:

    cl> calcomp metacodefile

2. Get the fastest plot you can -- no bold lines or text, no dashed or dotted
lines:

    cl> calcomp metacodefile lwover+ ltover+ txquality=low

3. Get a plot half the size of the original; suppose the original plot had
metacode scales = 0.0003 inches / GKI unit:

    cl> calcomp metacodefile xscale=0.00015 yscale=0.00015

4. Get the highest quality plot you can without having to change pens:

    cl> calcomp metacodefile txqual=high 

5. Get a high-quality plot where you have to change the pen each time the
metacode switches from bold to single-width lines or text:

    cl> calcomp metacodefile txqual=high lwtype=penchange

.ih
TIME REQUIREMENTS
Pen plotters vary considerably in their plotting rates.  At NOAO, plotting a
metacode file from a 1024-pixel image generated by \fBlongplot\fR, overriding
bold lines and text, takes a couple of minutes.  The same plot with txquality
= "medium" can take over twice as long due to bold text, axes, and tick labels.
With txquality = "high", it may take 4 or 5 times as long to plot.

Plots with dashed and dotted, or both, lines may take 2-5 times as long to 
plot as single-width lines.  The slowest of all is to produce plots with
a lot of bold text, or with dashed and dotted AND bold data lines.
.ih
BUGS
When using multiple tracing to simulate bold lines that intersect at very
acute angles, i.e. less than 5 degrees, each bold line will thin slightly
as it approaches the obtuse vertex.
.ih
SEE ALSO
See task \fBlongplot\fR, also in the plot package, for a task designed to
use the \fBcalcomp\fR graphics kernel for exact scaling and/or long, e.g.
spectral, plots.
.endhelp
