\chapter{Data formats}\label{data}

There are three main kinds of files\index{File} supported directly by this
software for storing and retrieving information relevant to \cam\
experiments.  If you wish to manipulate these files from other
languages (for example, to perform data analysis or pattern generation
using a more familiar or appropriate language than Forth) this
information on data formats should be helpful.

\section{Plane pattern files}

Plane pattern files have a default extension of \prog{PAT}, and are
always a multiple of 8K bytes.  These files contain no header
information: the number of bit-planes that are stored as a pattern (1,
2, 3, or 4) is determined entirely by the file size (8192, 16384,
24576, or 32768 bytes).\index{File/pattern}

All data corresponding to a single bit-plane is stored contiguously:
the first byte of each 8K record corresponds to the eight bits on the left
end of the top row of \cam's screen.  Subsequent bytes within this
record are mapped in a left-to-right, top-to-bottom order (the first
32 bytes correspond to the top row, the next 32 to the next row,
etc.).  Note that within each byte, the least significant bit of the
byte appears as the leftmost on the screen, with the more significant
bits appearing at consecutive locations {\sl to its right}.  This may
be the opposite of what you expect from ordinary arithmetic notation.

See \prog{IMAGE>FILE}\index{IMAGE.FILE{\tt IMAGE>FILE}} in the glossary for a
discussion of how 8K records are mapped onto planes.

\section{Table files}

The lookup tables used by \cam\ may be saved to or restored from disk\index{File/table}
%(see \prog{FILE\char"3E TAB}\index{FILE.TAB{\tt FILE\char"3E TAB}} and
%\prog{TAB\char"3E FILE}\index{TAB.FILE{{\tt TAB\char"3E FILE}}} in the glossary).
(see \prog{FILE>TAB}\index{FILE.TAB{\tt FILE>TAB}} and \prog{TAB>FILE}\index{TAB.FILE{\tt TAB>FILE}} in the glossary).
The default extension for table files is \prog{TAB}.  Each
lookup table is exactly 4096 bytes long and contains only table data:
no header data is included.  Neighborhood and run-cycle information
must be provided separately.  Each byte in a table file (default
extension is \prog{.TAB}) contains information for 8 subtables
(columns).  Bit positions 0, 2, 4, and 6 refer to the regular tables
for planes 0, 1, 2, and 3 respectively; positions 1, 3, 5, and 7 refer
to the auxiliary tables for planes 0, 1, 2, and 3 respectively.  Each
entry (byte) corresponds to a particular set of input values (see
Table~\ref{eq.neigh}).  For example, entry \prog{000} refers to the
case when all neighbors return zeros; entry \prog{FFF} (hex) refers to
the case when all neighbors return ones.

\section{Data files}

The default extension for data files is \prog{DAT}.\index{File/data}
16-bit values stored in or retrieved from such files using
\prog{PUT-DATA} and \prog{GET-DATA} appear in consecutive locations,
each value consisting of two bytes (the low-order byte is stored in a
position closer to the beginning of the file than the high-order byte).
Data files in this implementation are always padded to be a multiple of
1K (1024) bytes in length---you may want to start your file with a count
of data items if this is a variable quantity.



