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.