.TH PLOT3 5 BRL-CAD
.\"                        P L O T 3 . 5
.\" BRL-CAD
.\"
.\" Copyright (c) 2005-2012 United States Government as represented by
.\" the U.S. Army Research Laboratory.
.\"
.\" Redistribution and use in source (Docbook format) and 'compiled'
.\" forms (PDF, PostScript, HTML, RTF, etc), with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code (Docbook format) must retain the
.\" above copyright notice, this list of conditions and the following
.\" disclaimer.
.\"
.\" 2. Redistributions in compiled form (transformed to other DTDs,
.\" converted to PDF, PostScript, HTML, RTF, and other formats) must
.\" reproduce the above copyright notice, this list of conditions and
.\" the following disclaimer in the documentation and/or other
.\" materials provided with the distribution.
.\"
.\" 3. The name of the author may not be used to endorse or promote
.\" products derived from this documentation without specific prior
.\" written permission.
.\"
.\" THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
.\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
.\" USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\".\".\"
.SH NAME
plot3 \- 3-D and color graphic plotting interface
.SH DESCRIPTION
Files of this format are produced by programs
such as
.IR pixhist3d-pl (1),
using the routines
described in
.IR  libplot3\^ (3)
and are interpreted for various devices
by standard programs described in
.IR  plot\^ (1G),
as well as additional programs such as
.IR pl-fb (1).
The format of output from
.IR libplot3
differs from that of
.IR libplot
only in the addition of 3-D primatives and color.
A graphics file is a stream of plotting instructions.
Each instruction consists of an \s-1ASCII\s+1 letter
usually followed by bytes of binary information.
The instructions are executed in order.
A point is designated by
four bytes representing
the
.B x
and
.B y
values;
each value
is a signed 16-bit integer.
These integers are written with the most significant
byte first.
Three-dimensional data have an additional
.B z
value, which is assumed to be zero
for two-dimensional instructions.
The last designated point in an
.BR l ,
.BR m ,
.BR n ,
.BR p ,
.BR L ,
.BR M ,
.BR N ,
or
.B P
instruction becomes the ``current point''
for the next instruction.
.PP
Each of the following descriptions begins with the name
of the corresponding routine in
.IR  libplot3\^ (3).
.TP 3
.B  m
move:  The next four bytes give a new current point.
.TP
.B  n
cont:  Draw a line from the current point to
the point given by the next four bytes.
See
.IR  plot (1G).
.TP
.B  p
point:  Plot the point given by the next four bytes.
.TP
.B  l
line:  Draw a line from the point given by the next
four bytes to the point given by the following four bytes.
.TP
.B  t
label:  Place the following \s-1ASCII\s0 string so that its
first character falls on the current point.
The string is terminated by a new-line.
.TP
.B  a
arc:  The first four bytes give the center, the next four give the
starting point,
and the last four give the end point of a circular arc.
The least significant coordinate of the end point is
used only to determine the quadrant.
The arc is drawn counter-clockwise.
.TP
.B  c
circle:  The first four bytes give the center of the circle,
the next two the radius.
Circles and arcs are not supported on all devices.
.TP
.B  e
erase:  Start another frame of output.
.TP
.B  f
linmod:  Take the following string, up to a new-line,
as the style for drawing further lines.
The styles are
``dotted'',
``solid'', ``longdashed'', ``shortdashed'', and ``dotdashed''.
Effective only
for the
.B \-T4014
and
.B \-Tver
options of
.IR plot\^ (1G)
(\s-1TEKTRONIX\s+1 4014 terminal and Versatec plotter).
.TP
.B  s
space:  The next four bytes give
the lower left corner of the plotting area;
the following four give the upper right corner.
The plot will be magnified or reduced to fit
the device as closely as possible.
.PP
The following were added at BRL.
Three-dimensional primitives have their
.B z
values ignored when displayed on
two-dimensional devices.
.TP 3
.B  C
color:  The next three bytes give respectively
the intensities (0..255) of the three color components
(additive colors red, green, and blue if a terminal;
subtractive colors cyan, magenta, and yellow if hardcopy)
to be used for subsequent plotting.
The initial color is assumed to be (255,255,255),
which is white on a terminal and black on hardcopy.
Color specifications are ignored for black-and-white devices.
.TP
.B  M
3move:  The next six bytes give a new current point.
.TP
.B  N
3cont:  Draw a line from the current point to
the point given by the next six bytes.
See
.IR  plot\^ (1G).
.TP
.B  P
3point:  Plot the point given by the next six bytes.
.TP
.B  L
3line:  Draw a line from the point given by the next
six bytes to the point given by the following six bytes.
.TP
.B  S
3space:  The next six bytes give
the minimum corner of the plotting area;
the following six give the maximum corner.
The plot will be magnified or reduced to fit
the device as closely as possible.
.TP
.B  F
3flush:
.TP
.B  x
double_point:  The double-precision version of point.
.TP
.B  v
double_line:  The double-precision version of line.
.TP
.B  o
double_move:  The double-precision version of move.
.TP
.B  q
double_cont:  The double-precision version of cont.
.TP
.B  w
double_space:  The double-precision version of space.
.TP
.B  i
double_circle:  The double-precision version of circle.
.TP
.B  r
double_arc:  The double-precision version of arc.
.TP
.B  W
double_3space:  The double-precision, 3_D version of space.
.TP
.B  X
double_3point:  The double-precision, 3_D version of point.
.TP
.B  O
double_3move:  The double-precision, 3_D version of move.
.TP
.B  Q
double_3cont:  The double-precision, 3_D version of cont.
.TP
.B  V
double_3line:  The double-precision, 3_D version of line.
.PP
Space settings that exactly fill the plotting area
with unity scaling appear below for
devices supported by the filters of
.IR  plot\^ (1G).
The upper limit is just outside the plotting area,
except for the Megatek which displays the
entire range of possible coordinates.
In every case the plotting area is taken to be square;
points outside may be displayable on
devices whose face is not square.
.PP
.RS
.PD 0
.TP 18
.SM
DASI \*S300
space(0, 0, 4096, 4096);
.TP
.SM
DASI \*S300s
space(0, 0, 4096, 4096);
.TP
.SM
DASI \*S450
space(0, 0, 4096, 4096);
.TP
\s-1TEKTRONIX\s+1 4014
space(0, 0, 3120, 3120);
.TP
Versatec plotter
space(0, 0, 2048, 2048);
.TP
Megatek display
space(-32768, -32768, 32767, 32767);
.PD
.RE
.SH SEE ALSO
libplot3(3),
plot(3),
plot(5).
.br
graph(1G), plot(1G) in the
\f2\s-1UNIX\s+1 System User Reference Manual\fR.
.SH AUTHOR
Douglas A. Gwyn made the 3-D and color extensions to UNIX-plot.
.SH BUG REPORTS
Reports of bugs or problems should be submitted via electronic
mail to <devs@brlcad.org>.
