.\" 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.org, 2007-09-25
.Dd Septemner 25, 2007
.Dt PNMTARTAN 1
.Os NetBSD 1.4T
.Sh NAME
.Nm pnmtartan
.Nd insert/delete strips in PNM files
.Sh SYNOPSIS
.Nm
.Op Ar directive ...
.Sh DESCRIPTION
.Nm
manipulates PNM files by inserting and/or deleting strips.  (The name
is derived from how easy it is to synthesize patterns reminiscent of
Scottish tartans this way.)
.Pp
A PNM file is read from the standard input.  It is manipulated
according to the directives on the command-line; the resulting file is
written to the standard output.  Directives can be:
.Bl -tag -width indent
.It ins Ns Ar X Ar WHERE Ar COLOUR
This inserts a stripe.  X can be
.Sq x
or
.Sq y
to indicate which coordinate pixels move in; a vertical stripe involves
moving pixels horizontally and thus uses
.Sq x ,
while a horizontal stripe involves moving pixels vertically, and uses
.Sq y .
WHERE specifies the location and width of the stripe.  It can be any of
three forms:
.Bl -tag -width indent
.It Ar NNN Ns \&@ Ns Ar MMM
The stripe is
.Ar NNN
pixels wide, beginning at pixel coordinate
.Ar MMM .
.It Ar NNN Ns \&- Ns Ar MMM
The stripe extends from pixel
.Ar NNN
through pixel
.Ar MMM ,
inclusive.
.It Ar NNN
Equivalent to
.Sq 1@ Ns Ar NNN .
.El
.Pp
COLOUR specifies the colour of the inserted pixels.  If the file is a
PBM file, this must be 0 or 1; for a PGM file, it can be either a small
integer, from 0 through the file's maxval, or a floating-point number
from 0 to 1; for a PPM file, it can be a PGM spec, which produces a
greyscale pixel, or three PGM specs with commas or slashes between
them, specifying the three primaries; for PAM files, it can be a PGM or
PPM spec with a comma or slash and an alpha-channel value.
.It del Ns Ar X Ar WHERE
This deletes a stripe.
.Ar X
specifies the coordinate axis, as for the
.No ins Ns Ar X
forms, and
.Ar WHERE
specifies the stripe to be deleted.  It can be any of the forms listed
for inserting stripes, with the same meanings, or it can be
.Sq Ar NNN\&- ,
which means to delete everything from pixel
.Ar NNN
through the last pixel in the relevant dimension.
.El
.Pp
If multiple directives appear on the command line, they are applied in
the order given.  The coordinate system for each directive is the one
resulting after the application of all previous directives; thus, for
example,
.D1 insx 5@5 0 insx 5@20 0
is equivalent to
.D1 insx 5@25 0 insx 5@5 0
rather than
.D1 insx 5@20 0 insx 5@5 0
because pixel 20 in the second
.Sq insx
is measured after the five pixels are inserted by the first
.Sq insx .
Because of this, it is usually easiest to understand command lines if
operations appear in order of decreasing coordinates affected.
.Pp
It is an error to delete pixels that don't exist, or to insert pixels
at a place that does not abut existing pixels (less than 0, or greater
than the number of pixels in the relevant dimension).
.Sh BUGS
Relatively slow.  A recursive walk of the list of directives is
performed for each pixel processed.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents-montreal.org .