CONTOUR(L) CONTOUR(L)
11 July 1991
NAME
contour - contour plot program for X-windows and Postscript
SYNOPSIS
contour [-o options-file] [-Pprinter] [-s scale] [-cstep step-size] [-
nsteps #steps] [-lines #linetypes] [-zlog] [-exp] [-expand_mesh] [-
expand_cont] [-join joinlevel] [-label] [-slice level] [-tl "toplabel"]
[-xl "xlabel"] [-yl "ylabel"] [-e] [-g] [-l] [-clip] [-ps] [-print] [-
noplot] [-xt #xticks] [-yt #yticks] [-xlog] [-ylog] [-xar] [-yar] [-ar]
[-xyratio xyratio] [-3D 3Dcontour_file] contour_file contour-file ...
DESCRIPTIONS
Contour is a program for drawing contour plots on X11 windows. The
program will also produce a POSTSCRIPT plot which can be dumped out to
an APPLE Laserwriter or equivalent POSTSCRIPT-compatible printer.
Contour reads in data on a 3D surface from a contour-file and
manipulates that data according to options specified either in the
command-line or in an options-file. The plot-file can be compressed
(see compress(1)); compressed files will be uncompressed
automatically. The program then draws contours on a screen or dumps
the contours to a POSTSCRIPT file.
DATA FORMATS
The 3D surface input data consists of z-values of the 3D surface,
arranged on a regular rectangular grid of size (xmax - xmin) x (ymax -
ymin). The data file format is shown below.
Data File Format (contour-file)
xmin xmax ymin ymax
nxpts nypts
z1
z2
..
..
..
In the above, xmin, xmax, ymin and ymax are lower and upper bounds of
the grid, and nxpts and nypts are the number of grid divisions in x
and y. The z-values are arranged by column and row, i.e.
z[0,0], z[0,1], z[0,2], ... z[0,j]
z[1,0], z[1,1], z[1,2], ... z[1,j]
...
z[i,0], z[i,1], z[i,2], ... z[i,j]
As an example, the data-set shown below defines a rectangular grid
bounded by xmin=0.0, xmax=2.0, ymin=0.0 and ymax=1.0. There are 5
grid-divisions in x and 3 in y, corresponding to a square grid of 0.5
units in width. The first z-value specified corresponds to
(x,y)=(0.0,0.0), and z(0.5,1.0)=2.0 (third row, 2nd column).
0.0 2.0 0.0 1.0
5 3
1.0 1.0 1.0 1.0 1.0
1.0 2.0 1.0 2.0 1.0
1.0 2.0 1.0 2.0 1.0
- 1 - Formatted: June 17, 2025
CONTOUR(L) CONTOUR(L)
11 July 1991
The rectangular mesh above is subdivided into smaller triangles for
the contour calculation. Contour also accepts as input a list of
triangles, specified in pdraw(L) format, i.e.,
Data File Format (3D plot-file)
xmin xmax ymin ymax zmin zmax
ncurves
4.0
x1 y1 z1
x2 y2 z2
x3 y3 z3
x1 y1 z1
4.0
x1 y1 z1
x2 y2 z2
x3 y3 z3
x1 y1 z1
..
..
The files in this data-format are specified using the [-3D] flag in
the command-line. Note that each file in this data-format must be
preceded by the [-3D] flag.
MODUS OPERANDI
Upon starting up the program, contour will read in the data stored in
the contour-file and will then find the maximum and minimum z-values
of the surface. It will then prompt for a contour step-size (i.e. the
contour increments), and read in any plotting options specified either
in the command line or in the options-file. The contour step-size or
number of contours may also be defined in the command-line using the
[-cstep] or [-nsteps] options. The plot will then be drawn on the
screen if possible. The X11-plot is killed by clicking in the plot
window with the mouse, or by pressing the keyboard character "q" in
the plot window. Upon exiting X11, the user will be prompted as to
whether or not the POSTSCRIPT plot is to be sent to a printer. Note
that if the program is unable to open the X11 window (e.g DISPLAY not
set), it will automatically write a POSTSCRIPT plot to a file. More
than one input data-file may be specified on the commandline. The [-
cstep], [-nsteps], [-lines] and [-zlog] commandline options may be
respecified for each input file. For example,
contour -cstep 0.2 -zlog infile0 -cstep 0.1 infile1
overlays a log plot on a linear plot.
OPTIONS
-o options-file
reads plotting options from the file options-file. Each option
specification consists of a keyword and its corresponding value.
The parser recognizes only a limited set of keywords; their
values are either numbers, quoted strings, or the words
"on","off","true","false". Keywords may be in upper or lower
case. All the words in the option specification must be on the
same line. The pound sign (#) indicates that the remainder of
- 2 - Formatted: June 17, 2025
CONTOUR(L) CONTOUR(L)
11 July 1991
the line is a comment to be ignored by the parser.
List of Options (options-file) xlabel "LABEL" #[default = "X-
AXIS"] - for the x-label
ylabel "LABEL" #[default = "Y-AXIS"] - for the y-label
toplabel "LABEL" #[default = "CONTOUR PLOT"]-
for the top-label
printer "PRINTER" #[default = $PRINTER]- define
the printer
grid on/off #[default = off] - draws a grid
equalscale on/off #[default = on]- for equal x-y
scaling
landscape on/off #[default = off] - print in
landscape mode
clip on/off #[default = on] - clips the picture
postscript on/off #[default = on]- for
postscript (PS) plot
printplot on/off #[default = off]- print PS
file automatically
noplot on/off #[default = off] - don't draw graphics plot
xticks [1 - 20] #[default = 4]- no. of x-
divisions
yticks [1 - 20] #[default = 4]- no. of y-
divisions
xlog on/off #[default = off] - x-axis in log-scale
ylog on/off #[default = off] - y-axis in log-scale
autorange on/off #[default = on]- automatic
axis ranging
xautorange on/off #[default = on]- automatic x-
axis ranging
yautorange on/off #[default = on]- automatic y-
axis ranging
scale [0.1 - 1.0] #[default = 1.00]- scales the
PS plot
cstep [step-size] #[default = 0.0]- contour step
size
nsteps [1 - 50] #[default = 0]- number of
contour steps
expand_cont on/off #[default = off]- draw 3D
contours
expand_mesh on/off #[default = off]- draw 3D mesh
expand on/off #[default = off] - draw 3D contours and mesh
contlabel on/off #[default = on]- for contour
labels
joinlevel high/low #[default = off]- for joining
open curves
linetypes [1 - 3] #[default = 2]- no. of contour
linetypes
slice [contour-level] #[default = off] - single
contour slice
- 3 - Formatted: June 17, 2025
CONTOUR(L) CONTOUR(L)
11 July 1991
-Pprinter
specifies which printer to which to send the postscript plot.
The current default sets the printer name to the environment
variable $PRINTER. If this variable is not set, then the printer
used is the lp550M printer in 550M Cory (or whatever printer is
hardcoded during compile-time).
-s scale
sets a plot scale factor. This is used only for POSTSCRIPT
plotting.
-cstep step-size
defines the contour step-size. If this is not defined, the
program prompts for the step-size. This option may be
respecified for each input data-file.
-nsteps number of steps
defines the number of contour steps. If this is not defined, the
program prompts for the step-size. This option may be
respecified for each input data-file.
-lines linetypes
defines the number of linetypes for the contour plot. Valid
values range from 1-3. The default is to use 2 linetypes; major
contours are solid while minor contours are dashed. This option
may be respecified for each input data-file.
-zlog
informs the program that the z-values specified in the input file
are to be plotted in logarithmic scale. Use this option to plot
data with large range, e.g. 1.0e10 < z < 1.0e15. This option may
be respecified for each input data-file.
-exp is equivalent to specifying both -expand_cont and -expand_mesh.
-expand_cont
prints out the 3D (x,y,z) values of the contours to the file
image.cont.3D. If the 3D plotting program pdraw(L) is available,
contour will make a system call to pdraw to plot this data-file.
-expand_mesh
prints out the 3D (x,y,z) values of the triangular mesh (used
internally for contour calculation) to the file image.cont.3D.
If the 3D plotting program pdraw(L) is available, contour will
make a system call to pdraw to plot this data-file.
-j joinlevel
causes contour curves to be joined where possible. This is done
by defining a boundary layer around the rectangular border, and
setting the z-value of that boundary layer at either the maximum
or minimum z-value. joinlevel = HIGH or high sets the border z-
- 4 - Formatted: June 17, 2025
CONTOUR(L) CONTOUR(L)
11 July 1991
value to its maximum value: this is useful for plots which have
high average z-values. joinlevel = LOW or low sets the border
z-value to its minimum value: this is useful for plots which have
low average z-values.
-label
suppresses the contour labels.
-slice level
forces the program to compute the contours at a single value of
z, specified by level. The contours will be written to the file
image.cont. The output data is organized in drawplot(L) plot
format.
-xlabel "xlabel"
-ylabel "ylabel"
-tlabel "toplabel"
specifies the strings for the plot labels.
-e causes the x and y grids to be drawn with non-equal scales. The
default is to have equal-scales, i.e. the x and y lengths are
equal for equal x and y units.
-g forces a grid to be drawn.
-l prints the postscript plot in landscape mode (rotated).
-clip
forces no clipping within the plot boundary. The default is to
automatically clip at the boundary.
-print
sends the POSTSCRIPT lot to the printer automatically.
-ps turns off the postscript plotting mode. This can also be done by
setting the POSTSCRIPT environment variable to OFF. e.g. %
setenv POSTSCRIPT off
-noplot
prevents plots on the graphics display. This, with the -print
and -cstep options, is very useful for batch-mode operations: the
program draws a postscript file and sends it to the printer
automatically without user-intervention.
-xticks xticks
sets the number of ticks on the x-axis to xticks. This option
also turns off automatic ranging of the x-axis.
- 5 - Formatted: June 17, 2025
CONTOUR(L) CONTOUR(L)
11 July 1991
-yticks yticks
sets the number of ticks on the y-axis to yticks. This option
also turns off automatic ranging of the y-axis.
-ar forces no automatic ranging of the x and y axes. Without this
option, automatic ranging is set ON, and the program tries to
select the best axis-scales possible for both the x and y-axes.
-xar forces no automatic ranging of the x axis. Without this option,
automatic ranging is set ON for the x-axis, and the program tries
to select the best axis-scales possible for the x-axis. The x-
autorange option is also turned off when xticks is defined in the
option-file or in the commandline.
-yar forces no automatic ranging of the y axis. Without this option,
automatic ranging is set ON for the y-axis, and the program tries
to select the best axis-scales possible for the y-axis. The y-
autorange option is also turned off when yticks is defined in the
option-file or in the commandline.
-xlog
-ylog
draws the x-axis or y-axis on a log scale. NOTE: these options
do not work correctly yet!
-xyratio xyratio
is very useful for setting the plot size ratio, i.e. the ratio of
the plot-height (y) to the plot-width (x). Normally,
xyratio=0.75, but this is ignored because the program tries to
recompute the size of the plot to satisfy equalscaling of the x
and y axes. However, when -xyratio is specified in the command-
line, equalscaling is turned off, and the plot is sized as
described above. One application of this option is if the user
wants to fit a plot into a 6inch by 3inch area; the user then
specifies "contour -xyratio 0.5" and adjusts the scale factor
until the plot fits.
-3D specifies the plotfile to be of pdraw(L) format. As such, the
plotfile should consist of triangles only. For example, "contour
-3D curves.plot.3D" will produce contour plots of the 3D plotfile
curves.plot.3D.
host:display
opens a window on the given host and display
-d host:display
=geometry
- 6 - Formatted: June 17, 2025
CONTOUR(L) CONTOUR(L)
11 July 1991
-geom geometry
-rv
-bw border-width
-bd border-color
-fg foreground-color
-bg background-color
-fn font-name
sets input options for the X-window system.
BUGS
Xlog and ylog options don't work yet; this is more due to the problems
of specifying and interpolating on a logarithmic mesh. Also sparse
data-sets (contour meshes with few gridpoints) produce jagged curves,
due to the linear interpolation. Contour meshes must be regular;
there should be a way to specify non-regular rectangular meshes.
AUTHOR
Kenny K.H. Toh (ktoh@td2cad.intel.com)
FILES
dataplot.ps temporary POSTSCRIPT file
image.cont file produced by -slice level option
image.cont.3D file produced by -exp, -expand_cont, -expand_mesh
options.
SEE ALSO
drawplot(L), pdraw(L)
- 7 - Formatted: June 17, 2025
