campat man page
NAME
campat - a utility for creating CAM-8 pattern files for 2
dimensional experiments
SYNOPSIS
campat [ -Dname=def ]
DESCRIPTION
Reads a series of commands from standard input which
direct the construction of a two dimensional cam-space.
Writes the resulting ".pat" file on standard output. See
the COMMANDS section below for more info.
The input is processed by the C-language pre-processor
/lib/cpp with the flags '-B', '-P' and '-Dcampat' set. Any
flags begining with '-D' are also passed to cpp.
/* So, c-style comments, like this, are ok to use */
// as are as c++-style comments, like this one
Also, #include, #define and #ifdef macros will work, and
the macro "campat" is defined for reference.
USAGE EXAMPLES
This utility is not really intended to read from the key-
board; it is expected that the standard input will be read
from a file. The convention is that these files have the
suffix ".8p". Usually CAM-8 patterns are stored as
.pat.gz files. Thus a common usage of the campat program
might be:
example% campat < foo.8p | gzip > foo.pat.gz
COMMANDS
Commands to the campat program consist of a single line of
text with a command keyword and parameters to the command
separated by whitespace. Each command which is executed
by campat must be on a single line, which is distict from
the other commands, but, it is possible to quote newlines,
with a backslash character. Thus:
command parameter1 \
parameter2
is the same as:
command parameter1 parameter2
There are a whole passel of commands which campat recog-
nizes, and future versions may have even more. Currently,
the following commands are recognized:
point Point rectangle oval
line edge boundary polygon
pat_file pbm_file mask_pbm
size
The size command specifies the dimensions of the space for
the experiment. It takes two arguments, the x-size and
the y-size. Execution of the size command clears a new
space in the workstation memory, so it should precede all
other commands. The default size is 512 by 512 sites. To
create a 1024 X 1024 space, for instance, the input should
begin with:
size 1024 1204
bitpattern
The bitpattern command specifies the pattern of bits which
will be written into the cam-space. Every time the pro-
gram 'writes' a site, the bits in that site are changed
according to the pattern specified by this command.
For example, drawing a square into the cam-space might
draw zeros into bit 3 of every site, and write ones into
bit 4 of 30% of the sites in the square.
The format of the command is the word "bitpattern" fol-
lowed by 16 symbols. For instance, it might be used like
this:
bitpattern %10 + x - \
=13 - x x \
x x x x \
x x x x \
Each symbol corresponds to a different bitplane, starting
with 0 and ending with 15. Each of the 16 entries can have
one of four meanings.
A "+" or "-" character means that every drawn site have
a 1 or a 0, on that bitplane, respectively.
An "x" means that each bit-site drawn will be left
unchanged from the value which it contained previ-
ously.
A string of the form "%70" means that drawn region will
contain 70% 1's and 30% 0's on the given bitplane.
The distribution of ones is uniform and random.
will contain zeros.
A string of the form "60" will be treated as if it were
"%60".
The bitpattern command need not be broken onto separate
lines, this is only done to improve readablilty. If there
are not 16 symbols after the command, it will change the
pattern entries for the bitplanes which are redefined, and
the rest of the pattern entries will be unchanged. Thus,
bitpattern - -
bitpattern +
is equivalent to:
bitpattern + -
Bitpattern
The Bitpattern command (note capital B) prints the current
pattern onto standard error. This is really for debugging
purposes only. For instance:
Bitpattern
will print something like this onto stderr:
Pat: %10 %50 + - + - =50 %50 x x x x x x x x.
point
The point command draws to a single point in the cam-
space. It has two parameters, x and y. It is used like
this:
point 100 130
Point
The Point command (note capital P) prints the current con-
tents of a point in the cam-space onto standard error.
This is for debugging and diagnostic purposes only. For
instance:
Point 10 20
Will print something like this onto stderr:
point (10,20) currently (high low) (5 A)
rectangle
The rectangle command draws a rectangle into the cam-
space. It has four parameters: x1, y1, x2, y2, which
specify the corners of the rectangle. It is used like
this:
rectangle 10 10 200 150
oval
The oval command draws an oval into the cam-space. It has
inscribed into the rectangle,) It is used like this:
oval 10 10 200 150
line
The line command draws a straight line segment into the
cam-space. It has four parameters: x1, y1, x2, y2, which
specify the endpoints of the line. The algorithm for
drawing the line considers sites to be four-connected,
rather than eight-connected. which can produce surprising
results in some experiments.
4-connected line:
**
***
***
8-connected line:
*
**
**
edge
The edge command draws a series of connected line segments
into the cam-space. It takes an even number of parameters:
x1, y1, ... xn, yn. The closing line from xn, yn to x1,
y1 is not drawn.
boundary
The boundary command draws a series of connected line seg-
ments into the cam-space. It takes an even number of
parameters: x1, y1, ... xn, yn. The closing line from xn,
yn to x1, y1 is drawn.
polygon
The polygon command draws a filled polygon into the cam-
space. It takes an even number of arguments: x1, y1 ...
xn, yn, which are the verticies of the polygon. The edges
are connected in the order in which they are specified and
a site is considered "inside" the polygon if a ray start-
ing at that point crosses an odd number of edges. This
means that there can be points which are interior to the
polygon, but are not drawn. In other words, four corners
of a square can either be a square, or a "bow-tie",
depending on the order in which they are specified.
Warning: Bit-patterns which use the =nn format are not
guaranteed to work correctly with polygons. If a bitplane
is set to =nn in the bit-pattern then the distribution of
sites will be nn divided by the size (in sites) of the
bounding box of the polygon.
pat_file
The pat_file command takes one argument, the name of a
pattern file which has previously been written to disk.
This file should be the same size space as the current
space being defined or bad, undocumented things will hap-
pen. This feature is provided so that users can write
things using the campat program into a space which was
created by some other means.
pat_file mara.pat
In theory, if the file name provided is "-", the pattern
will be read from standard input. I have no idea if this
feature works, or is remotely useful.
pbm_file
The pbm_file command take three parameters, the name of a
bitmap file in the pbm format, and x, y coordinates. Any
point which is black in the bitmap will be drawn into the
cam-space.
Warning: Bit-patterns which use the =nn format are not
guaranteed to work correctly with pbm_file commands. If a
bitplane is set to =nn in the bit-pattern, then the dis-
tribution of sites will be nn divided by the size (in
sites) of the bitmap.
mask_pbm
The mask_pbm command takes either zero or one argument.
It specifies a bit map which acts as a mask for all draw-
ing routines. If the command is used with no parameter,
then no masking is done.
Any time a site is drawn, the actual site will be effected
only if the location of that site modulo the size of the
masking bitmap is black in the bitmap. For instance, an
easy way to draw a checkerboard pattern using campat would
be to define a bitmap as follows:
P1
# check.pbm
4 4
1 0 0 0
0 0 0 0
0 0 1 0
0 0 0 0
After this file is saved as check.pbm, include the com-
mand:
mask_pbm check.pbm /* load a checkerboard bitmap */
rect 10 10 20 30 /* draw a checked rectangle */
mask_pbm /* put the mask back to normal
*/
BUGS
The implementation of the campat program is a mondo-
kludge. It was only inteded to be a first generation pro-
totype. Future implementations will hopefully be much
cleaner. Please report all bugs to magnus@mit.edu.
There are many features which ought to be in the campat
program, which are not. If you think of one, send it to
the author and it might get included in the next release.
Things already on the wish-list include:
A more powerful method of specifying patterns.
More than 2 dimensions.
A direct interface to the CAM, rather than to a file.
A fast way to do non-uniform drawing into the cam-
space.
A graphical interface.
A real parser.
When using the polygon, mask_pbm, or pbm_file commands,
bit-patterns which use the =n syntax do not work cor-
rectly. This is because the n sites which are selected
are chosen by the output of an emulated linear feedback
shift register, and the size of the space to be drawn is
not computed at site generation time. This bug could be
fixed, but it would take twice as long to execute any of
these commands. It isn't expected that the =n syntax
would be very useful with these commands anyway. I'll fix
this bug if anyone needs it fixed.