.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents.montreal.qc.ca
.Dd March 25, 2008
.Dt PPMPLOT 1
.Os NetBSD 1.4T
.Sh NAME
.Nm ppmplot
.Nd generate PPM plots of data
.Sh SYNOPSIS
.Nm
.Op Ar directive Ns \&| Ns Ar filename ...
.Sh DESCRIPTION
.Nm
generates PPM files from directives specified on the command line or in
files.  The command line consists of filenames intermixed with plot
directives.  If no filenames are specified, the standard input is read
once the command line has been processed (even if a
.Sq read
directive has been given).  Directives appearing on the command line
are just like directives appearing in files, as described below, except
that each directive name or argument must be exactly one command-line
argument, and all optional arguments must be present.  There is no
explicit disambiguation between directive names and filenames, but no
directive begins with
.Sq Pa \&/
or
.Sq Pa \&./ ,
so it is always possible to ensure a filename is not mistaken for a
directive.  See also the
.Sq read
directive.
.Pp
Files named on the command line contain sequences of plot directives.
Except for comments (which begin with
.Sq \&#
and continue through the next newline), each directive begins with the
first non-whitespace character available and continues until the next
.Sq \&;
or newline.  (Note that comments include their trailing newlines; when
a line ends with a comment, the newline is commented out and cannot act
as a directive terminator.)
.Pp
Most directive arguments are numbers, though a few take strings.  When
reading from the command line, directive argument boundaries are
indicated by command-line argument boundaries, there is no quoting
convention, and semicolon terminators and comments are not supported;
when reading from a file, string arguments support quoting with
\&"\ \&", \&'\ \&', or \&\e (\&\e also quotes characters within \&"" or
\&''); even
.Sq \&;
and
.Sq \&#
may be quoted, and comments are supported.  In the descriptions below,
uppercase indicates metasyntax, with lowercase reserved for keywords.
.Pp
Supported directives:
.Bl -tag -width indent
.It read Ar FILENAME
Reads the named file, processing directives from it.  When done,
continue processing further directives from the source this directive
came from.  This construct may be nested as deeply as available
resources permit.
.It end
Stop processing directives from this source.  If used on the command
line, this also prevents further arguments from being taken as file
names either.
.It clear Ar XSIZE YSIZE Oo
.Ar R
.Op Ar G B
.Oc
.It clear same Oo
.Ar R
.Op Ar G B
.Oc
This clears the plot and, in the first form, sets its size.  (In the
second form, the current size is re-used.)  The optional arguments
specify a colour to clear the plot to; it is interpreted as for an
.Sq fg
directive, and defaults to 0.  This also resets the scaling and
clipping parameters controlled by
.Sq scale ,
.Sq scalewin ,
and
.Sq clipwin
to their default values.
.It size Ar XSIZE YSIZE
.It size same
This is just like
.Sq clear
with the colour defaulted; it never takes a colour.  It exists mainly
for use from the command line (where the optional colour arguments must
be present when using
.Sq clear ) .
.It scale Ar XMIN XMAX YMIN YMAX
.It scale default
Sets scaling.  For further plotting, coordinates run from
.Ar XMIN
to
.Ar XMAX
in the X direction and from
.Ar YMIN
to
.Ar YMAX
in the Y direction.  The default scale is equivalent to
.Sq scale 0 XSIZE 0 YSIZE ,
where XSIZE and YSIZE are as given in the
.Sq size
or
.Sq clear
directive that set the plot's size.  This default scale can be restored
with the
.Ar default
keyword argument.  Pixels are considered to be rectangles, with edges
evenly spaced such that the left edge of the leftmost pixel is X
coordinate
.Ar XMIN
and the right edge of the rightmost pixel is X coordinate
.Ar XMAX ,
with similar remarks (mutatis mutandis) applying to the Y coordinate.
Pixel rectangles include their left and bottom edges but not their
right and top edges (which belong to adjacent pixels).  If
.Ar XMIN
is greater than
.Ar XMAX ,
the X axis is reversed; similarly for Y.  (In particular, you normally
want the Y axis reversed, because most image display programs display
the image in the fourth quadrant, not the first (ie, with (0,0) at the
upper left, not the lower left).  Note that determination of which
pixels a coordinate exactly on a pixel edge belongs to is done in pixel
space; in particular, this means that reversing an axis does not change
which edges belong to which pixels in pixel terms.)
.It scalewin Ar XMIN XMAX YMIN YMAX
.It scalewin default
Normally, the coordinate rectangle specified with
.Sq scale
maps onto the whole plot.  The
.Sq scalewin
directive changes this, giving a rectangle in pixel space to which maps
the
.Sq scale
directive's rectangle in input coordinate space.  The pixel-space
rectangle specified does not need to bear any particular relation to
the pixel-space rectangle constituting the plot; this is used to set
the coordinate transformation and has nothing to do with anything else.
As for
.Sq scale ,
.Ar XMIN
may be greater than
.Ar XMAX
and
.Ar YMIN
may be greater than
.Ar YMAX ;
if this is so, the corresponding axis is reversed compared to what it
normally would be.  The
.Sq default
form restores the default scale window, which as if
.D1 scalewin 0 XSIZE 0 YSIZE
had been specified, where
.Ar XSIZE
and
.Ar YSIZE
refer to the
.Sq size
setting in effect.  The arguments (to
.Sq scalewin )
may be floats.
.It clipwin Ar XMIN XMAX YMIN YMAX
.It clipwin default
Normally, anything drawn is not clipped (except for clipping to the
plot, of course).
.Sq clipwin
specifies a rectangle in pixel space; anything outside this rectangle
is not drawn, even if it falls inside the plot.  The arguments must be
integers; the
.Pf \&* Ns Ar MAX
arguments are the coordinates of the first pixel outside the clip
window, not of the last pixel inside it.  While
.Ar XMIN
may be greater than or equal to
.Ar XMAX
and
.Ar YMIN
may be greater than or equal to
.Ar YMAX ,
doing that is not normally useful, because is causes everything to be
clipped away.  The default clip window is the whole plot, as if
.Dq clipwin 0 XSIZE 0 YSIZE
were in effect; this state can be restored with the
.Sq default
form.  The specified rectangle need not be entirely contained within
the plot, but the effective clip rectangle is, of course, always the
intersection of the specified rectangle with the plot area.
.It window Ar XMIN XMAX YMIN YMAX
.It window default
.Sq window
is equivalent to specifying both
.Sq scalewin
and
.Sq clipwin
with the same arguments.  (In particular, this means the arguments must
meet the restrictions for both
.Sq scalewin
and
.Sq clipwin . )
.It fg Ar R Op Ar G B
Sets the colour of plotted points.  If only one argument is given, it
is a greyscale value; if three are given, they are an RGB triple (which
is treated as a greyscale value if all three values are the same).
Values run from 0 to 255 and must be integers.  If the background and
all plotted points are greyscale 0 or greyscale 1, a PBM file is
output by default; otherwise, the default output type is PGM or PPM
(depending on whether any non-greyscale colours are used).  The default
foreground is greyscale 1.  See the
.Sq type
directive for how to override the output type.
.It bg Ar R Op Ar G B
Sets the background colour.  Arguments are as for
.Sq fg ;
the default background is greyscale 0.  Note that very few operations
actually use the background colour; what you think of as the background
is most likely specified on the
.Sq clear
command (qv).
.It type Op Ar TYPE
Sets the output file type, overriding the default (see the
.Sq fg
directive for a description of the default type).  TYPE can be
.Sq pbm ,
.Sq pgm ,
or
.Sq ppm
to specify what kind of output file is to be generated, or
.Sq default
to specify that the default is to be used.  If a PBM file is explicitly
specified and non-PBM colours are used, any non-black pixel comes out
as white; if a PGM file is explicitly specified and non-greyscale
colours are used, they are converted to greyscale using the usual
\&.299r\&+.587g\&+.114b formula.  If more than one
.Sq type
directive applies to a plot, the one that takes effect is the last one
specified.
.It op Op Ar OP
Sets the operation used to combine plotted points with data already
there.
.Ar OP
is a string naming a combination method:
.Bl -tag -width indent
.It set
The new data replaces the old.
.It min
The minimum of the old data and the new is used, independently for each
primary.
.It max
The maximum of the old data and the new is used, independently for each
primary.
.El
.It point Ar X Y
Draws a point at the pixel containing
.Pf ( Ar X Ns , Ns Ar Y ) .
.It line Ar X1 Y1 X2 Y2
Draws a line from
.Pf ( Ar X1 Ns , Ns Ar Y1 )
to
.Pf ( Ar X2 Ns , Ns Ar Y2 ) .
This is almost, but not quite, the same as drawing a line from the
pixel containing
.Pf ( Ar X1 Ns , Ns Ar Y1 )
to the pixel containing
.Pf ( Ar X2 Ns , Ns Ar Y2 ) ;
the difference lies in exactly where the jaggies fall.
.It rect Ar X1 Y1 X2 Y2
Draws a solid rectangle, aligned with the coordinate axes, two of whose
corners are the pixels containing
.Pf ( Ar X1 Ns , Ns Ar Y1 )
and
.\" Why does this drop the trailing dot?!
.Pf ( Ar X2 Ns , Ns Ar Y2 ) .
You can also think of the arguments as being xmin, ymin, xmax, ymax,
but there actually is no requirement that, for example,
.Ar X1
be less than
.Ar X2 .
Because of the rules for where pixel boundaries fall, for some
applications you may find it easier to get the results you want by
specifying the whole plot on the
.Sq rect
directive and using the clip window to control the rectangle which
actually gets drawn.
.It font Ar FILENAME
Specifies a font file to be used for text.  The default is to use a
built-in fixed-width font.  The
.Ar FILENAME
must name either a BDF file as used by the X Window System or a PBM
file reminiscent of the ones used by
.Xr pbmtext 1
(but different in detail).  See the
.Sx FONT FILE
section below for details.  To explicitly specify use of the built-in
font,
.Ar FILENAME
can be a single
.Sq \&- .
.It text Ar X Y Xo
.Op Ar FLAG Op ...
.Op string
.Ar STRING
.Xc
Plots text.  The
.Ar STRING
to be plotted is the first argument that's not recognized as a
.Ar FLAG ;
to disambiguate if the string is, or might be, a flag name, the
.Sq string
marker may be given.
.Ar X
and
.Ar Y
specify a pixel (the pixel that would be plotted if a
.Sq point
directive were given those coordinates).  The text is formatted into a
rectangle containing pixels at some locations, a rectangle containing
an anchor point; the rectangle is transformed as described below, then
the anchor point is placed on the specified pixel and the pixels are
plotted.  The rectangle also has top, bottom, left, and right margins.
By default, the top margin is placed above the first line's baseline by
a distance equal to the font's ascent, the bottom margin is placed
below the last line's baseline by a distance equal to the font's
descent, the left margin is the minimum of all characters' origins' X
coordinates, and the right margin is the maximum of all characters'
advance points' X coordinates.  Note that these definitions have
nothing to do with where pixels fall; for example, the top margin may
be above, below, or at the top pixel plotted (but see the
.Sq bboxmargin
flag, below).
.Pp
Note that, in contrast to most Unix text-handling tools, newline is
considered a line separator, not a line terminator; if the string has a
trailing newline, it will produce a trailing blank line (which may or
may not be visible in the result, depending on various options).
.Pp
By default, the text is formatted left-justified, the anchor point is
the intersection of the baseline of the last line and the left margin,
and only glyph pixels, pixels that are part of character glyphs, are
plotted.  After any explicitly specified transformations, but before
plotting, the rectangle is reversed about the X axis if the combination
of the
.Sq scale
and
.Sq scalewin
systems negates the X axis; similarly, but independently, for Y.  (This
causes text to come out right way up when, as recommended under the
.Sq scale
directive, the Y scale is negated and the image is displayed using a
fourth-quadrant image display program.)
.Pp
These defaults can be overridden by the flags:
.Bl -tag -width indent
.It rectbg
Specifies that pixels within the bounding rectangle (the bounding box
of all the glyph pixels) but which aren't glyph pixels are to be
plotted with the background colour (see the
.Sq bg
directive).
.It rot-cw
.It rot-180
.It rot-ccw
The rectangle of pixels is rotated by 90 degrees clockwise, by 180
degrees, or by 90 degrees counterclockwise, before it is placed.  Since
rectangle placement is defined in terms of the anchor point, rotation
is effectively around the anchor point.
.It swap-x
.It swap-y
.It swap-xy
.It swap-xmy
The rectangle of pixels is reflected in, respectively, the X direction,
the Y direction, about the X\&=Y line, or about the X\&=\&-Y line,
before being placed.  Note also the additional reflections mentioned
above.
.It no-auto-swap
The automatic swapping of X and Y based on the
.Sq scale
and
.Sq scalewin
settings, described above, is suppressed.
.It ljust
Causes the text to be formatted left-justified, meaning that the
origins of the first characters of the lines are at equal X
coordinates.  (This is the default.)  This makes no difference unless
multiple lines of text are involved.
.It rjust
Causes the text to be formatted right-justified, meaning that the
advance points of the last characters of the lines are at equal X
coordinates.  This makes no difference unless multiple lines of text
are involved.
.It centre
(Also
.Sq center . )
.\" Grr, why doesn't the spacefactor pass through the ) correctly?
\& Causes the text to be formatted centred, meaning that the average of
the first character's origin and the last character's advance point,
for each line, are at equal X coordinates.  This makes no difference
unless multiple lines of text are involved.
.It ax-left
Specifies that the anchor point is to be on the left margin.  (This is
the default.)
.It ax-right
Specifies that the anchor point is to be on the right margin.
.It ax-centre
(Also
.Sq ax-center . )
.\" Grr, why doesn't the spacefactor pass through the ) correctly?
\& Specifies that the anchor point is to be midway between the left and
right margins.
.It ay-top
Specifies that the anchor point is to be on the top margin.
.It ay-bottom
Specifies that the anchor point is to be on the bottom margin.
.It ay-baseline
Specifies that the anchor point is to be on the baseline of the last
line of text.  (This is the default.)
.It ay-topbase
Specifies that the anchor point is to be on the baseline of the first
line of text.
.It ay-centre
(Also
.Sq ay-center . )
Specifies that the anchor point is to be midway between the top and
bottom margins.
.It ay-centrebase
(Also
.Sq ay-centerbase . )
Specifies that the anchor point is to be midway between the top and
bottom baselines.
.It bboxmargin
Specifies that the margins are to be computed as the bounding box of
all plotted pixels, rather than as described above.
.El
.Pp
Some of these flags interact in non-simple ways.  Specifically:
.Bl -bullet
.It
The
.Sq rot-cw ,
.Sq rot-180 ,
.Sq rot-ccw ,
.Sq swap-x ,
.Sq swap-y ,
.Sq swap-xy ,
and
.Sq swap-xmy
flags are cumulative.  Conceptually, each operation is applied, in
order, to the rectangle after all previous operations.  For
example, specifying
.Sq rot-cw swap-x
is functionally equivalent to specifying
.Sq swap-y rot-cw .
.It
.Sq ljust ,
.Sq centre ,
and
.Sq rjust
are mutually exclusive; the last one specified wins.
.It
The
.Sq ax-\&*
flags are mutually exclusive; the last one specified wins.
.It
The
.Sq ay-\&*
flags are mutually exclusive; the last one specified wins.
.El
.It output Op Ar FILENAME
Output the plot.  If
.Ar FILENAME
is specified, the plot is written to that file.  Otherwise, a filename
is constructed from the previous plot's filename, by looking for a
number in decimal and, if found, incrementing it; if not, one is
inserted just before the last dot, or at the end if there is no dot.
If no filename is ever specified, it is as if the first
.Sq output
line specified
.Pa plot0001.XXX ,
where XXX is pbm, pgm, or ppm depending on the type of file written.
Note that if a filename is specified, no check is done to avoid, for
example, writing a PPM plot to a
.Pa \&.pbm
file name.  Note also that
.Sq output
does not clear the plot; further directives will plot over what's
already there.  Use
.Sq clear
after writing if you want to clear the plot.
.El
.Sh FONT FILE
A font is specified by giving a pathname containing either a BDF file
from the X Window System (see the X documentation on BDFs) or a PBM
file.  If it's a PBM file, it is constructed in a very specific way.
Each character glyph from 0 through 255 is displayed, padded with at
least one pixel of blank space all around.  (If the font is lacking
some characters, dummies must be provided, though they may be
zero-width or otherwise uninteresting.  Provided they never get
displayed, their contents do not matter.)  These are then lined up with
their baselines aligned, padded with more blank space as necessary to
make them all the same height, and concatenated with one-pixel-wide
bars separating them (as a convenience for humans, these bars may have
one-pixel gaps at the baseline).  Then, one pixel column is added at
the left edge, all blank except for one pixel on the baseline.  Then,
one pixel row is added at the top, all blank except for one pixel above
each character's origin; another pixel row is added at the bottom, all
blank except for one pixel below each character's advance point.
(Blank padding may be needed to the left and right of the glyph, since
these pixels must be within the character cell as determined by the
one-pixel-wide separator bars.)  Note that the one-pixel vertical
separator bars do not run through the top and bottom rows.  It does not
matter whether the file is constructed with white foreground and black
background or the other way around.
.Sh BUGS
Specifying very large or very small values to
.Sq scale
and/or
.Sq scalewin
can produce pixel mis-positioning because of precision loss in
floating-point arithmetic.  No particular attempt is made to avoid or
alleviate this.
.Pp
Specifying zero sizes (min and max values equal) to
.Ar scale
or
.Ar scalewin
may produce divide-by-zero crashes.
.Pp
The
.Sq text
directive makes no attempt to handle fonts with other than Western
writing orders (characters placed left to right, lines placed top to
bottom).
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .