
\section{Camera Data Organization \& Camera Geometry}

We require several utility functions to define the geometry of the
detectors in a camera and to specify the organization of the camera
data in real FITS images.  The camera data organization is defined in
a set of \code{psMetadata} structures, and may be stored on disk in
the file format parsed by \code{psMetadataParseConfig}.

PSLib defines a hierarchy of data structures related to the
organization of the pixels in a camera.  These structures, starting
from the top level, follow the sequence \code{psFPA}, \code{psChip},
\code{psCell}, \code{psReadout}, \code{psImage}.  Each lower level
structure is carried as an array in the higher level.  The containers
as defined by PSLib include functions which specify the astrometric
relationships between these levels, and provide a single
\code{psMetadata} container pointer for each level.  In this section,
we define the type of metadata is stored in these metadata containers
and how the image headers are parse to define the data hierarchy in
memory.  

\subsection{Coordinate Transforms and Header Data}
\tbd{The algorithms for three functions in this section are not
  well-defined.  Do not code yet.}

Astrometric and geometric information about an image from a camera may
be represented in a variety of ways.  A crude representation of the
pixel geometry is specified in many image headers using the IRAF-style
region keywords \code{DATASEC}, \code{DETSEC}, etc.  These keywords
are used to define the location of a single image's pixels in the
frame of the full mosaic of detectors in the assumption that the
mosaic can be represented as a single uniform grid of pixels.  An
alternative set of keywords have been used in cases where multiple
cells are saved together in a single FITS image extension.  More
sophisticated astrometric representations require elements to define
projections, scaling, distortion, etc.  Several versions of header
keywords have been used to represent these astrometric
transformations.  In this section, we define three functions to
interpret a collection of image headers and construct the appropriate
offset and/or astrometry parameters.

\begin{prototype}
bool pmFPADefineOffsets(psFPA fpa);
bool pmFPADefineWCS(psFPA fpa);
bool pmFPADefineWCSfromOffsets(psFPA fpa);
\end{prototype}

The first function takes a \code{psFPA} structure which has been
populated with header and camera configuration metadata in the
appropriate locations as discussed above.  Using the information in
the camera config metadata and the headers, the function sets the
values for the elements \code{psChip.col0,row0},
\code{psCell.col0,row0}, \code{psReadout.col0,row0},
\code{psReadout.colParity,rowParity}, and
\code{psReadout.colBinning,rowBinning}.  This information is
determined by examining the regions defined by the following names.

% how do we handle the CCDSUM keyword case?
\begin{verbatim}
psCell.metadata:CELL:CCDBIN1 $\rightarrow$ psReadout.colBins
psCell.metadata:CELL:CCDBIN2 $\rightarrow$ psReadout.rowBins

DETSEC from psCell.metadata:CELL:DETSEC
CCDSEC from psCell.metadata:CELL:CCDSEC
DATASEC from psCell.metadata:CELL:DATASEC

if (DETSEC.x0 > DETSEC.x1) then psReadout.colParity = -1
if (DETSEC.y0 > DETSEC.y1) then psReadout.rowParity = -1
\end{verbatim}

The second function examines the contents of the headers of the chips
and cells and constructs the collection of astrometric coordinate
transformations.. 

The third function uses the offset information and the basic telescope
pointing information to construct a approximate guess at the
astrometric coefficients based on the detector geometry.

\begin{figure}
\begin{center}
\psfig{file=CameraLayout,width=5.5in}
\caption{Camera Pixel Layout\label{CameraLayout}}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
\psfig{file=CameraRegionKeywords.ps,width=5.5in}
\caption{Camera Region Keyword Definitions\label{CameraRegionKeywords}}
\end{center}
\end{figure}

\subsection{Chip \& Cell from FITS File}
\tbd{the algorithm for the function in this section is not
  well-defined.  do not code yet}.

When loading data from disk, it is may be necessary to use the
information in the DATASEC and DETSEC entries to determine which part
of the image should be read.  If the data is stored in a chip-based
format, then the data for each cell corresponds to only a fraction of
the pixels stored in a single image extension.  We specify the
following function to perform the correct read of data from a FITS
file into the corresponding \code{psCell} entry respecting the
boundaries of the cells within chip-based images.

\begin{prototype}
psReadout *pmReadoutLoad(psReadout *input, psFits *f, psCell *cell, int plane);
\end{prototype}

