Changeset 9721

Timestamp:

Oct 23, 2006, 5:08:59 PM (20 years ago)

Author:

Paul Price

Message:

Updating FPA and HDU section to match implementation: major changes.

File:

• trunk/doc/modules/CameraImages.tex (modified) (3 diffs)

trunk/doc/modules/CameraImages.tex

@@ -303 +303 @@
 correct, the function shall return \code{true}.
 
+\subsubsection{Levels}
+
+The level within an FPA hierarchy may be specified by an enumerated
+type:
+\begin{datatype}
+typedef enum {
+    PM_FPA_LEVEL_NONE,                  ///< No particular level specified
+    PM_FPA_LEVEL_FPA,                   ///< Level corresponds to an FPA
+    PM_FPA_LEVEL_CHIP,                  ///< Level corresponds to a Chip
+    PM_FPA_LEVEL_CELL,                  ///< Level corresponds to a Cell
+    PM_FPA_LEVEL_READOUT                ///< Level corresponds to a Readout
+} pmFPALevel;
+\end{datatype}
+
+The following functions are provided to convert between the enumerated type
+and string representation of the level:
+\begin{prototype}
+const char *pmFPALevelToName(pmFPALevel level ///< Level enum
+                            );
+pmFPALevel pmFPALevelFromName(const char *name ///< Level name
+                             );
+\end{prototype}
+
+The string representations are \code{FPA}, \code{CHIP}, \code{CELL}
+and \code{READOUT} (case insensitive).
+
+\subsubsection{Flags}
+
+The following functions are provided to set and check the \code{file_exists}
+and \code{data_exists} status flags within the FPA hierarchy:
+\begin{prototype}
+bool pmFPASetFileStatus(pmFPA *fpa,     ///< FPA for which to set status
+                        bool status     ///< Status to set
+                       );
+bool pmChipSetFileStatus(pmChip *chip,  ///< Chip for which to set status
+                         bool status    ///< Status to set
+                        );
+bool pmCellSetFileStatus(pmCell *cell,  ///< Cell for which to set status
+                         bool status    ///< Status to set
+                        );
+bool pmFPACheckFileStatus(const pmFPA *fpa ///< FPA for which to check status
+                         );
+bool pmChipCheckFileStatus(const pmChip *chip ///< Chip for which to check status
+                          );
+bool pmCellCheckFileStatus(const pmCell *cell ///< Cell for which to check status
+                          );
+bool pmFPASetDataStatus(pmFPA *fpa,     ///< FPA for which to set status
+                        bool status     ///< Status to set
+                       );
+bool pmChipSetDataStatus(pmChip *chip,  ///< Chip for which to set status
+                         bool status    ///< Status to set
+                        );
+bool pmCellSetDataStatus(pmCell *cell,  ///< Cell for which to set status
+                         bool status    ///< Status to set
+                        );
+\end{prototype}
+
+The following functions set the \code{process} flag within the FPA
+hierarchy, either selecting a component for processing, or excluding
+it from processing:
+\begin{prototype}
+bool pmFPASelectChip(pmFPA *fpa,        ///< FPA containing the chip of interest
+                     int chipNum,       ///< Chip number to select
+                     bool exclusive     ///< Process this chip exclusive of the others?
+                    );
+bool pmChipSelectCell(pmChip *chip,     ///< Chip containing the cell of interest
+                      int cellNum,      ///< Cell number to select
+                      bool exclusive    ///< Process this cell exclusive of the others?
+                     );
+int pmFPAExcludeChip(pmFPA *fpa,        ///< FPA containing the chip of interest
+                     int chipNum        ///< Chip number to exclude
+                    );
+int pmChipExcludeCell(pmChip *chip,     ///< Chip containing the chip of interest
+                      int cellNum       ///< Cell number to exclude
+                     );
+\end{prototype}
+
+The \code{Select} functions, set the specified component to be the
+only component (at that level) to be processed if \code{exclusive} is
+\code{true}.  A negative value for the component number is valid, and
+if \code{exclusive} is \code{true}, de-selects all components at the
+appropriate level.
+
+
+\subsubsection{Finding a component by name}
+
+A component may be found by its symbolic name (the concepts
+\code{CHIP.NAME} or \code{CELL.NAME}, as appropriate).  The following
+functions return the index of the component that matches the provided
+name, or -1 if none was found:
+
+\begin{prototype}
+int pmFPAFindChip(const pmFPA *fpa,     ///< FPA in which to find the chip
+                  const char *name      ///< Name of the chip
+                 );
+int pmChipFindCell(const pmChip *chip,  // Chip in which to find the cell
+                   const char *name     // Name of the cell
+                  );
+\end{prototype}
+
 
 \subsection{Header Data Units}
@@ -507 +607 @@
 
 
-
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-
-
-
-
-
-\subsection{Detector Coordinate Transformations}
-
-\tbd{The implementation of this section may change slightly if the
-coordinate transformations in the focal plane hierarchy are pushed
-into the metadata --- the math shouldn't change, just how the values
-are accessed.}
-
-\begin{figure}
-\psfig{file=pics/CameraLayout,width=5.5in}
-\caption{Camera Pixel Layout\label{CameraLayout}}
-\end{figure}
-
-These container levels also include in their definition the
-information needed to transform the coordinates in one of the levels
-to the coordinate system relevant at the higher levels.
-
-The data structures define the basic coordinate relationships between
-all of these data elements.  A set of offsets for each level in the
-data hierarchy specifies the location of the particular set of pixels
-in the next level of the hierarchy.  This is illustrated in
-Figure~\ref{CameraLayout}.  These offsets may be used to define the
-complete camera layout in the approximating assumption that all pixels
-in the camera are laid out on a single linear pixel grid.  This
-approximate is sufficient for many basic operations.  For more detail,
-the precise astrometric relationship between each level of the
-hierarchy may also be made available in the metadata of the data
-structures.
-
-In practice, a single readout from a detector may represent only a
-subset of the complete set of pixels addressed by the {\it cell}.  The
-readout may also have binning applied in both of the two dimensions.
-There may also be overscan and pre-scan regions in the set of pixels.
-Finally, the readout direction is not always the same for all detector
-amplifiers.  As shown in Figure~\ref{CameraLayout}, these different
-concepts are represented in the data hierarchy.  The coordinate of the
-origin of the data grid for one level of the hierarchy in the grid of
-the containing hierarchy is defined for each data level.  For example,
-the origin of the coordinates for a single chip are located in the
-camera grid at \code{pmChip.cell0,row0}.  The \code{pmReadout} data
-level has additional information to specify the details of the readout
-process.  The elements \code{pmReadout.colBins,rowBins} specify the
-binning factor in the two dimensions, while the sign indicates the
-parity of the specific readout (readout direction).  Note that the
-value of \code{pmReadout.col0,row0} must be assigned in such a way
-that it represents the coordinate of the origin pixel in the actual
-image: the overscan or pre-scan pixels must be accounted for.  Putting
-all of these element together, we can see that the pixel coordinates
-in the camera grid may be determined from the pixel coordinates in the
-image grid from the following relationship:
-
-\begin{verbatim}
-pmFPA(cell,row) = pmChip.cell0,row0 + pmCell.cell0,row0 + pmReadout.cell0,row0 + 
-                  pmReadout.cellParity,rowParity * pmReadout.cellBins,rowBins * 
-                  psImage.data(cell,row)
-\end{verbatim}
-
-\subsection{Input/Output of a Focal Plane Hierarchy}
-
-Data sources and output targets may be specified in the Camera
-Configuration file.  These targets may consist of explicitly named
-files, or they may define rules by which the names are constructed,
-using other information available to the configuration system.  The
-following function provides a mechanism with which the name rules are
-selected and interpretted
-\begin{prototype}
-char *pmConfigNameFromRule (char *rule, psMetadata *camera, *psMetadata *arguments, psMetadata *header);
-\end{prototype}
-
-The \code{rule} defines a name in the \code{camera} metadata.  The
-rule defines the output value of a new name.  The rule may include
-elements which are looked up from the camera configuration
-information, the supplied command-line arguments, or the header of the
-current file.  The following lookups rules are define:
-\begin{verbatim}
-{CELL.NAME} : pmCell.concepts:CELL.NAME
-{CHIP.NAME} : pmChip.concepts:CHIP.NAME
-{EXTNAME}   : value of EXTNAME in header
-{INPUT}     : value of INPUT from camera config
-{OUTPUT}    : value of OUTPUT from camera config
-\end{verbatim}
-
-
-We specify two functions to construct a focal plane hierarchy from a
-camera configuration and read from a FITS file.  These two operations
-are decoupled so that the big investment of memory from the read only
-occurs when it is necessary.
-
-\begin{prototype}
-pmFPA *pmFPAConstruct(const psMetadata *camera);
-bool pmFPADatabase(pmFPA *fpa, psDB *db);
-bool pmFPARead(pmFPA *fpa, psFits *fits);
-bool pmFPAWrite(psFits *fits, pmFPA *fpa);
-\end{prototype}
-
-\code{pmFPAConstruct} shall construct a focal plane hierarchy from a
-\code{camera} configuration.  The resultant \code{pmFPA} and its
-lower-down components shall be ready for to read a FITS file into it
-by setting \code{filename} and \code{extname} in the \code{file}
-pointers at the appropriate levels.
-
-\code{pmFPADatabase} shall set the \code{database} of the \code{file}
-pointers within the hierarchy to the supplied \code{db}.
-
-\code{pmFPARead} shall read a \code{fits} file (the contents of which
-are described by the previous \code{camera} configuration) into an
-extant \code{fpa}, for those components which don't already
-\code{exist} and are marked to be \code{process}ed.  This involves
-reading the headers and pixels into the \code{pmFile}, ingesting all
-the concepts for that level, and making subimages for the
-\code{readout->image} (from \code{CELL.TRIMSEC}) and
-\code{readout->bias} (from \code{CELL.BIASSEC}).
-
-\code{pmFPAWrite} shall write those elements focal plane hierarchy
-(\code{fpa}) that \code{exist} and are marked to be \code{process}ed
-to the specified \code{fits} file, returning \code{true} upon success
-and \code{false} otherwise.  If the provided \code{fits} file is
-\code{NULL}, the information within the \code{pmFile *image}
-components is used for the output.  The \code{fpa} should contain
-sufficient information with which to write the FITS images.
-
-\tbd{Following the reworking of the focal plane hierarchy in April
-2006, much of this document needs to be updated.  I'm including the below
-before I forget them --- PAP.}
-
-\begin{prototype}
-bool pmReadoutReadNext(pmReadout *readout, psFits *fits, int z, int numRows);
-bool pmCellRead(pmCell *cell, psFits *fits, psDB *db);
-bool pmChipRead(pmChip *chip, psFits *fits, psDB *db);
-bool pmFPARead(pmFPA *fpa, psFits *fits, psDB *db);
-\end{prototype}
-
-\tbd{Explanation here.}
-
-Here's a demonstration of the use of \code{pmReadoutReadNext}:
-\begin{verbatim}
-    pmReadout *readout = pmReadoutAlloc(cell);
-    for (int z = 0; pmReadoutReadNext(readout, inFile, z, 100); z++) {
-        do {
-            somethingWithTheReadout(readout);
-        } while (pmReadoutReadNext(readout, inFile, z, 2048));
-    }
-    psFree(readout);
-\end{verbatim}
-
-
-\subsubsection{Mask and weight input/output}
-
-We carry mask and weight images, since these are useful for downstream
-processing.  A mask value of zero for a pixel shall indicate that the
-pixel is not suspect.  The weight images shall be the variance (the
-square of the standard deviation).
-
-We desire to access the mask and weight images without specifying a
-particular file name.  We introduce the \code{SUPPLEMENTARY} metadata
-entry in the camera configuration file, which allows identification of
-the location for the mask and weight images, based on the value of
-some of the ``concepts'':
-
-\begin{verbatim}
-# How to get the supplementary stuff: mask and weight
-SUPPLEMENTARY   METADATA
-        MASK.SOURCE     STR     FILE                    # Source type for mask: EXT | FILE
-        MASK.NAME       STR     {FPA.NAME}_mask.fits    # Name for mask extension or filename
-        WEIGHT.SOURCE   STR     EXT                     # Source type for weight: EXT | FILE
-        WEIGHT.NAME     STR     {CELL.NAME}_weight.fits # Name for weight extension or filename
-END
-\end{verbatim}
-
-How the mask (or weight) image is stored is specified by the
-\code{MASK.SOURCE} (or \code{WEIGHT.SOURCE}) keyword.  The images may
-be stored either in the same file as the pixels with a different
-extension name (\code{EXT}), or they may be stored in a different file
-with the same extension name (\code{FILE}).  The name of the file or
-extension is specified by the \code{MASK.NAME} (or \code{WEIGHT.NAME})
-keyword, with strings within curly brackets interpreted as concepts
-that must be evaluated and replaced.
-
-\begin{prototype}
-pmFPAReadMask(pmFPA *fpa, psFits *fits);
-pmFPAWriteMask(psFits *fits, pmFPA *fpa);
-pmFPAReadWeight(pmFPA *fpa, psFits *fits);
-pmFPAWriteWeight(psFits *fits, pmFPA *fpa);
-\end{prototype}
-
-\code{pmFPAReadMask} and \code{pmFPAReadWeight} are very similar to
-\code{pmFPARead}, except that they shall read the \code{mask} and
-\code{weight} elements (respectively) of the \code{pmReadout}s
-comprising the \code{fpa}.
-
-\code{pmFPAWriteMask} and \code{pmFPAWriteWeight} is very similar to
-\code{pmFPAWrite}, but it shall write the \code{mask} and
-\code{weight} elements (respectively) of the \code{pmReadout}s
-comprising the \code{fpa}.
-
-We also provide functions to generate the mask and weight images:
-\begin{prototype}
-bool pmCellDetectorMask(pmCell *cell);
-bool pmCellDetectorWeight(pmCell *cell);
-\end{prototype}
-
-\code{pmCellPhotonMask} shall set the mask pixels based on the
-\code{CELL.SATURATION} and \code{CELL.BAD} concepts.
-\code{pmCellPhotonWeight} shall set the weight image based on the
-photon statistics using the \code{CELL.GAIN} and \code{CELL.READNOISE}
-concepts.
-
-\subsection{Iteration}
-
-Often we will desire to perform a function on all cells in the focal
-plane, or all chips, etc.  Since this is a common operation, we
-provide an iterator that performs the mind numbing part:
-
+\subsection{FPA Construction}
+
+The following function creates the FPA hierarchy on the basis of the
+camera configuration.  The \code{FPA} entry in the camera
+configuration specifies the chips (each of type \code{STR}) with their
+component cells listed as the corresponding values (whitespace
+separated).  The FPA hierarchy is created devoid of any input/output
+sources (i.e., HDUs).
+\begin{prototype}
+pmFPA *pmFPAConstruct(const psMetadata *camera ///< The camera configuration
+                     );
+\end{prototype}
+
+Input/output sources may be specified within the hierarchy by
+providing information that allows the position of the new HDU to be
+determined (not only the level, but which component of that level);
+this may be done in two ways.  The first is through a \code{pmFPAview}
+that corresponds to the HDU position; this is appropriate when
+creating an output file of known format.  The second is by providing
+the primary header of an input file, from which the HDU position(s)
+can be inferred (using the \code{FILE} information within the camera
+format configuration); this is useful for adding input sources.  In
+both cases, the camera format configuration is required in order to
+describe how the FPA is laid out in terms of disk files.
+
+\begin{prototype}
+bool pmFPAAddSourceFromView(pmFPA *fpa,   ///< The FPA
+                            const pmFPAview *phuView, ///< The view, corresponding to the PHU
+                            const psMetadata *format ///< Format of file
+                           );
+pmFPAview *pmFPAAddSourceFromHeader(pmFPA *fpa, ///< The FPA
+                                    psMetadata *phu, ///< Primary header of file
+                                    const psMetadata *format ///< Format of file
+                                   );
+\end{prototype}
+
+As an aid to development, we have a function that prints to a file
+stream a representation of the FPA, including its headers and
+concepts, if desired.
+
+\begin{prototype}
+void pmFPAPrint(FILE *fd,               ///< File descriptor to which to print
+                const pmFPA *fpa,       ///< FPA to print
+                bool header,            ///< Print headers?
+                bool concepts           ///< Print concepts?
+               );
+\end{prototype}
+
+
+\subsection{FPA Reading and Writing}
+
+\subsubsection{Reading headers}
+
+The following functions read the headers, if the HDU is at the
+appropriate level.  The functions return \code{true} if they
+successfully read the header, or if the header had already been read.
+The functions do not iterate to lower levels.
+\begin{prototype}
+bool pmFPAReadHeader(pmFPA *fpa,        ///< FPA for which to read header
+                     psFits *fits       ///< FITS file handle
+                    );
+bool pmChipReadHeader(pmChip *chip,     ///< Chip for which to read header
+                      psFits *fits      ///< FITS file handle
+                     );
+bool pmCellReadHeader(pmCell *cell,     ///< Cell for which to read header
+                      psFits *fits      ///< FITS file handle
+                     );
+\end{prototype}
+
+\subsubsection{Reading pixels}
+
+The following functions iterate over the component cells, reading the
+pixels, converting them to \code{F32}, allocating readouts, and
+ingesting concepts:
+\begin{prototype}
+bool pmCellRead(pmCell *cell,           // Cell to read into
+                psFits *fits,           // FITS file from which to read
+                psDB *db                // Database handle, for "concepts" ingest
+               );
+bool pmChipRead(pmChip *chip,           // Chip to read into
+                psFits *fits,           // FITS file from which to read
+                psDB *db                // Database handle, for "concepts" ingest
+               );
+bool pmFPARead(pmFPA *fpa,              // FPA to read into
+               psFits *fits,            // FITS file from which to read
+               psDB *db                 // Database handle, for "concepts" ingest
+              );
+\end{prototype}
+
+The following functions perform the same as the above functions, but
+read the pixels into the \code{mask} or \code{weight} elements of the
+readout.
+\begin{prototype}
+bool pmCellReadMask(pmCell *cell,           // Cell to read into
+                    psFits *fits,           // FITS file from which to read
+                    psDB *db                // Database handle, for "concepts" ingest
+                   );
+bool pmChipReadMask(pmChip *chip,           // Chip to read into
+                    psFits *fits,           // FITS file from which to read
+                    psDB *db                // Database handle, for "concepts" ingest
+                   );
+bool pmFPAReadMask(pmFPA *fpa,              // FPA to read into
+                   psFits *fits,            // FITS file from which to read
+                   psDB *db                 // Database handle, for "concepts" ingest
+                  );
+bool pmCellReadWeight(pmCell *cell,           // Cell to read into
+                      psFits *fits,           // FITS file from which to read
+                      psDB *db                // Database handle, for "concepts" ingest
+                     );
+bool pmChipReadWeight(pmChip *chip,           // Chip to read into
+                      psFits *fits,           // FITS file from which to read
+                      psDB *db                // Database handle, for "concepts" ingest
+                     );
+bool pmFPAReadWeight(pmFPA *fpa,              // FPA to read into
+                     psFits *fits,            // FITS file from which to read
+                     psDB *db                 // Database handle, for "concepts" ingest
+                    );
+\end{prototype}
+
+
+The above functions all read the pixels, at least a cell at a time.
+The following function reads the pixels for a readout incrementally.
+Multiple calls to this function moves through a readout within a cell
+incrementally.  It is required to pass the readout previously acquired
+(or a newly-allocated one) in order to preserve state information
+(where the read is at).  Only a maximum of \code{numRows} rows are
+read at a time.  Returns \code{true} if pixels are read, and
+\code{false} otherwise.  To facilitate looping, no error is generated
+for reading a plane that doesn't exist.  Note that this function
+doesn't put pixels in the HDU.  It is therefore \textbf{not
+compatible} with \code{pmCellWrite}, \code{pmChipWrite}, and
+\code{pmFPAWrite} (or any function that uses or creates an HDU, for
+that matter).  \code{pmReadoutWriteNext} should be used to write the
+data that's read by this function.  This function is intended for
+reading in many readouts into memory at once (e.g., for stacking)
+where the input is not written out.
+\begin{prototype}
+bool pmReadoutReadNext(pmReadout *readout, // Readout into which to read
+                       psFits *fits,    // FITS file from which to read
+                       int z,           // Readout number/plane; zero-offset indexing
+                       int numRows      // The number of rows to read
+                      );
+\end{prototype}
+
+\subsubsection{Writing pixels and headers}
+
+The following functions write the appropriate hierarchy level to a
+FITS file, if one exists at that level.  The function generates
+CELL.TRIMSEC, CELL.BIASSEC and the HDU pixels if required (see
+\code{pmHDUGenerate}).  A blank (i.e., image-less header) is written
+only if specifically requested.  The function writes the concepts to
+the various locations, and then the HDU to the FITS file.  This
+function should be called at the beginning of the output cell loop
+with \code{blank=true} in order to produce the correct file structure.
+\begin{prototype}
+bool pmCellWrite(pmCell *cell,          ///<  Cell to write
+                 psFits *fits,          ///<  FITS file to which to write
+                 psDB *db,              ///<  Database handle for "concepts" update
+                 bool blank             ///<  Write a blank PHU?
+                );
+bool pmChipWrite(pmChip *chip,          ///<  Chip to write
+                 psFits *fits,          ///<  FITS file to which to write
+                 psDB *db,              ///<  Database handle for "concepts" update
+                 bool blank,            ///<  Write a blank PHU?
+                 bool recurse           ///<  Recurse to lower levels?
+                );
+bool pmFPAWrite(pmFPA *fpa,             ///<  FPA to write
+                psFits *fits,           ///<  FITS file to which to write
+                psDB *db,               ///<  Database handle for "concepts" update
+                bool blank,             ///<  Write a blank PHU?
+                bool recurse            ///<  Recurse to lower levels?
+               );
+\end{prototype}
+
+
+The following function is the companion to \code{pmReadoutReadNext},
+as it writes a readout to a FITS file, perhaps incrementally (if it
+has been read in using \code{pmReadoutReadNext}).  It relies on the
+FITS header to specify how many image planes there are, and the width
+and height.
+\begin{prototype}
+bool pmReadoutWriteNext(pmReadout *readout, ///< Readout to write
+                        psFits *fits,   ///<  FITS file to which to write
+                        int z           ///<  Image plane to write
+                       );
+\end{prototype}
+
+
+\subsubsection{HDU Generation}
+
+The write functions for the FPA hierarchy use \code{pmHDUWrite}, which
+assumes that the images in the readouts are subimages of the pixels in
+the HDU structure.  If this is not the case, the HDU pixels can be
+generated using some simple assumptions.
+
+The following function generate an HDU (with \code{CELL.TRIMSEC},
+\code{CELL.BIASSEC} and pixels) for a cell with pixels.  They splice
+the images and overscans together without regard for \code{CELL.X0}
+and \code{CELL.Y0} (for a proper mosaic, see \code{pmFPAMosaic}),
+though they should respect \code{CELL.READDIR} (so that the bias and
+trim sections match properly).  A warning may be generated (by the
+concept write functions) after running these functions if the bias and
+trim sections are specified in the camera format by default values
+rather than in the header.  Failure of these functions is often due to
+a bad camera format file.
+\begin{prototype}
+bool pmHDUGenerateForCell(pmCell *cell  ///< The cell for which to generate an HDU
+                         );
+bool pmHDUGenerateForChip(pmChip *chip  ///< The chip for which to generate an HDU
+                         );
+bool pmHDUGenerateForFPA(pmFPA *fpa     ///< The fpa for which to generate an HDU
+                        );
+\end{prototype}
+
+These functions are primarily intended for private use (by the write
+functions) within the Modules, but may be used by the user if desired.
+
+\subsection{Masks and Weights}
+
+Pixel mask values are defined with the following enumerated type:
 \begin{datatype}
-typedef bool (*pmFPAIterateFunc)(pmFPA *fpa, pmChip *chip, pmCell *cell);
+typedef enum {
+    PM_MASK_CLEAR   = 0x00,   ///< The pixel is not masked
+    PM_MASK_TRAP    = 0x01,   ///< The pixel is a charge trap.
+    PM_MASK_BADCOL  = 0x02,   ///< The pixel is a bad column.
+    PM_MASK_SAT     = 0x04,   ///< The pixel is saturated.
+    PM_MASK_BAD     = 0x08,   ///< The pixel is low
+    PM_MASK_FLAT    = 0x10,   ///< The pixel is non-positive in the flat-field.
+    PM_MASK_MARK    = 0x20,   ///< The pixel is marked as temporarily ignored
+    PM_MASK_EXT1    = 0x40,   ///< This mask value is not used
+    PM_MASK_EXT2    = 0x80,   ///< This mask value is not used
+} pmMaskValue;
 \end{datatype}
-\begin{prototype}
-bool pmFPAIterateChips(pmFPA *fpa, pmFPAIterateFunc func);
-bool pmFPAIterateCells(pmFPA *fpa, pmFPAIterateFunc func);
-\end{prototype}
-
-\code{pmFPAIterateChips} shall iterate through all chips (that
-\code{exist} and are marked to be \code{process}ed) in the \code{fpa},
-calling the iterator function, \code{func}, for each (with
-\code{cell=NULL}).  \code{pmFPAIterateCells} shall iterate through all
-cells (that \code{exist} and are marked to be \code{process}ed) in all
-chips (that \code{exist} and are marked to be \code{process}ed),
-calling the iterator function for each.
-
-
-\subsection{Selecting elements of the hierarchy for processing}
-
-\begin{prototype}
-bool pmFPASelectChip(pmFPA *fpa, int chipNum);
-int pmFPAExcludeChip(pmFPA *fpa, int chipNum);
-\end{prototype}
-
-These functions are provided to set the \code{process} booleans within
-an \code{fpa} so that only certain chips within the FITS file are read
-in.
-
-\code{pmFPASelectChip} shall set \code{valid} to \code{true} for the
-specified chip number (\code{chipNum}), and all other chips shall have
-\code{valid} set to \code{false}.  In the event that the specified
-chip number does not exist within the \code{fpa}, the function shall
-return \code{false}.
-
-\code{pmFPAExcludeChip} shall set \code{valid} to \code{false} only
-for the specified chip number (\code{chipNum}).  In the event that the
-specified chip number does not exist within the \code{fpa}, the
-function shall generate a warning, and perform no action.  The
-function shall return the number of chips within the \code{fpa} that
-have \code{valid} set to \code{true}.
-
-\tbd{Provide a richer set of functions: select by extension, extname,
-cell, options to invalidate all / validate all, etc}
-
-
-\subsection{Mosaicking}
-
-\begin{prototype}
-bool pmFPAMorph(pmFPA *toFPA, pmFPA *fromFPA, bool positionDependent, int chipNum, int cellNum);
-\end{prototype}
-\code{pmFPAMorph} shall morph the \code{fromFPA} focal plane hierarchy
-to the \code{toFPA} focal plane hierarchy.  This allows us to write
-the pixels out using a different (though consistent) camera
-configuration.  In the event that the \code{toFPA} has different
-levels than the \code{fromFPA}, only the chip and cell specified by
-\code{chipNum} and \code{cellNum} shall be written; if the levels are
-the same, these numbers are ignored.  This function shall break apart
-pixel regions or splice them together where required in order to
-satisfy the demands of the \code{toFPA}.  How the image and overscan
-regions are spliced together depends on the value of
-\code{positionDependent}: If \code{positionDependent} is \code{true},
-then the overscan regions go to the low end of the spliced image if $i
-< N/2$, and to the high end of the spliced image if $i >= N/2$, where
-$i$ (zero-offset) is the cell number, and $N$ is the total number of
-cells; if \code{positionDependent} is \code{false}, then the overscan
-regions all go to the high end of the spliced image.  Care should be
-taken to check the \code{CELL.READDIR}, so the orientation of the
-overscan regions is known.  If the bias and trim sections are
-specified by headers in the \code{toFPA}, these shall be updated
-appropriately; otherwise, the function is permitted to fail with a
-suitable error message, in which case it shall return \code{false}.
-
-\tbd{Don't code pmFPAMorph --- it's tricky, and maybe unnecessary.}
-
-\begin{prototype}
-int pmChipMosaic(pmChip *chip, int xBinChip, int yBinChip);
-\end{prototype}
-
-\code{pmChipMosaic} shall mosaic the cells within the provided
-\code{chip}.  The mosaicking shall take into account the offsets of
-the cells on the chip (\code{CELL.X0,CELL.Y0}), the cell binning
-(\code{CELL.XBIN,CELL.YBIN}) and the desired (absolute, i.e., relative
-to the physical pixels) binning level (\code{xBinChip,yBinChip}).  The
-component cells and readouts shall be replaced with a single cell and
-readout containing the mosaic.  \code{file} pointers within the
-hierarchy and the concepts shall be updated.
-
+
+\tbd{It would be nice to have a system of registering symbolic names
+for mask values at run time.}
+
+The following functions use the readout image and certain concepts to
+provide the mask and weight values.  There are two cases.  The first
+is that of ``setting'' the mask/weight, where the mask/weight that
+produced is temporary --- it is not added to the HDU.  This is
+intended for when the user is iterating using pmReadoutReadNext, in
+which case the HDU can't be generated.  The second case is that of
+``generating'' the mask/weight, where the mask/weight that is produced
+is suitable for output (complete with HDU entry); this is intended for
+most operations.
+
+In both cases, the mask is formed by identifying pixels are saturated
+(at or above \code{CELL.SATURATION}) or bad (at or below
+\code{CELL.BAD}); while the weights (actually variances) are
+calculated using photon statistics from the cell gain
+(\code{CELL.GAIN}) and read noise (\code{CELL.READNOISE})
+
+\begin{prototype}
+bool pmReadoutSetMask(pmReadout *readout ///< Readout for which to set mask
+                     );
+bool pmReadoutSetWeight(pmReadout *readout ///< Readout for which to set weight
+                       );
+bool pmReadoutGenerateMask(pmReadout *readout ///< Readout for which to generate mask
+                          );
+bool pmReadoutGenerateWeight(pmReadout *readout ///< Readout for which to generate weight
+                            );
+\end{prototype}
+
+The following functions are intended for convenience, generating a
+mask and weight map for a readout or cell:
+\begin{prototype}
+bool pmReadoutGenerateMaskWeight(pmReadout *readout ///< Readout for which to generate mask and weights
+                                );
+bool pmCellGenerateMaskWeight(pmCell *cell ///< Cell for which to generate mask and weights
+                             );
+\end{prototype}
+
+
+\subsection{Copying: Converting between formats}
+
+The following functions copy components of an FPA hierarchy to a
+different representation of the same camera These functions are useful
+for converting between different representations of the same camera.
+For example, between Megacam "RAW" (one amp per extension) and Megacam
+"SPLICED" formats (two amps = 1 chip per extension, spliced together).
+Components are spliced together as necessary.
+
+\begin{prototype}
+bool pmFPACopy(pmFPA *target,           ///< The target FPA
+               const pmFPA *source      ///< The source FPA, to be copied
+              );
+bool pmChipCopy(pmChip *target,         ///< The target chip
+                const pmChip *source    ///< The source chip, to be copied
+               );
+bool pmCellCopy(pmCell *target,         ///< The target cell
+                const pmCell *source    ///< The source cell, to be copied
+               );
+\end{prototype}
+
+The following functions are similar, except that the pixels are not
+copied (although images of sufficient size are allocated in the
+target), and the \code{CELL.XBIN} and \code{CELL.YBIN} are changed
+according to the provided binning factors.  These functions are
+intended for binning a camera, where the user will do the binning.
+
+\begin{prototype}
+bool pmFPACopyStructure(pmFPA *target,   ///< The target FPA
+                        const pmFPA *source, ///< The source FPA, to be copied
+                        int xBin, int yBin ///< Binning factors in x and y
+                       );
+bool pmChipCopyStructure(pmChip *target, ///< The target chip
+                         const pmChip *source, ///< The source chip, to be copied
+                         int xBin, int yBin ///< Binning factors in x and y
+                        );
+bool pmCellCopyStructure(pmCell *target, ///< The target cell
+                         const pmCell *source, ///< The source cell, to be copied
+                         int xBin, int yBin ///< Binning factors in x and y
+                        );
+\end{prototype}
+
+
+\subsection{Mosaicking: Converting between cameras}
+
+The following functions mosaic cells within the appropriate hierarchy
+component into a single cell within the target (which must have only a
+single cell).  These functions are therefore useful for converting to
+a different camera, which is generally a false representation of the
+physical camera; in this manner, one can obtain an image of the chip
+or FPA on the sky.  Cells are placed on the chip according to the
+\code{CELL.X0} and \code{CELL.Y0} offsets.  The mosaicking is done so
+as to avoid performing a deep copy of the pixels, if possible.
+
+\begin{prototype}
+bool pmChipMosaic(pmChip *target,       // Target chip --- may contain only a single cell
+                  const pmChip *source  // Source chip whose cells will be mosaicked
+                 );
+bool pmFPAMosaic(pmFPA *target,         // Target FPA --- may contain only a single chip with a single cell
+                 const pmFPA *source    // FPA whose chips and cells will be mosaicked
+                );
+\end{prototype}
+
+
+\subsection{FPA Files}
+
+\tbd{EAM to provide from the following files:
+pmFPAfileDefine.h
+pmFPAfileFitsIO.h
+pmFPAfile.h
+pmFPAfileIO.h
+pmFPA_MANAPLOT.h
+pmFPA_JPEG.h
+}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Astrometry}
+
+\tbd{EAM needs to update this section.}
 
 Astrometry is a basic functionality required for the IPP that will be
@@ -860 +1005 @@
 We require structures to contain each of the above transformations as
 well as the pixel data.
-
-\subsection{Position Finding}
-
-We require functions to return the structure containing given
-coordinates.  For example, we want the chip that corresponds to the
-focal plane coordinates $(p,q) = (-1.234,+5.678)$.  These routines
-handle the one-to-many problem --- i.e., for one given focal plane
-coordinate, there are many chips that this coordinate may be
-correspond to; these functions will select the correct one. 
-%
-\begin{verbatim}
-pmCell *pmCellInFPA (const psPlane *coord, const pmFPA *fpa);
-pmChip *pmChipInFPA (const psPlane *coord, const pmFPA *fpa);
-pmCell *pmCellInChip(const psPlane *coord, const pmChip *chip);
-\end{verbatim}
-
-\subsection{Conversion Functions}
-
-We require functions to convert between the various coordinate frames
-(Section~\ref{sec:coordinateFrames}).  The hierarchy of the coordinate
-frames and the transformations between each are shown in
-Figure~\ref{fig:coco}.  The functions that employ the transformations
-are shown in Figure~\ref{fig:cocoFunc}.  In addition to
-transformations between each adjoining coordinate frame in the
-hierarchy, we also require higher-level functions to convert between
-the Cell and Sky coordinate frames; these will simply perform the
-intermediate steps.
-
-\begin{figure}
-\psfig{file=../pslib/pics/coordinateFrames,height=7in,angle=-90}
-\caption{The coordinate systems in the \PS{} IPP, and the relation
-between each by transformations contained in the appropriate
-structures.}
-\label{fig:coco}
-\end{figure}
-
-\begin{figure}
-\psfig{file=../pslib/pics/coordinateConv,height=7in,angle=-90}
-\caption{Conversion between coordinate systems by PSLib.}
-\label{fig:cocoFunc}
-\end{figure}
-
-We specify the following functions to convert between coordinates in
-one type of frame to another type of frame.  The first group consist
-of unambiguous transformations: from the coordinates in a low-level
-frame to the coordinates in the containing higher-level frame, of
-which only one exists.  In all of these functions, the output
-coordinate structure may be \code{NULL} or may be supplied by the
-calling function.  In the former case, the structure must be
-allocated; in the latter case, the supplied structure must be used.
-
-\begin{verbatim}
-psPlane *pmCoordCellToChip (psPlane *out, const psPlane *in, const pmCell *cell);
-% astrometry comes from cell (no need for parent)
-\end{verbatim}
-which converts coordindates \code{in} on the specified \code{cell} to
-the coordinates on the parent chip.
-
-\begin{verbatim}
-psPlane *pmCoordChipToFPA (psPlane *out, const psPlane *in, const pmChip *chip);
-% astrometry comes from chip (no need for parent)
-\end{verbatim}
-which converts the coordinates \code{in} on the specified \code{chip}
-to the coordinates on the parent FPA.
-
-\begin{verbatim}
-psPlane *pmCoordFPAToTP(psPlane *out, const psPlane *in, float color, float mag, const pmFPA *fpa);
-% astrometry comes from FPA (no need for parent)
-\end{verbatim}
-which converts coordinates \code{in} on the specified focal plane
-\code{fpa} to tangent plane coordinates, applying the appropriate
-distortion terms.  The \code{color} and magnitude (\code{mag}) of the
-source is necessary in order to perform the distortion between the
-focal plane and the tangent plane.
-
-\begin{verbatim}
-psSphere *pmCoordTPToSky(psSphere *out, const psPlane *in, const psProjection *projection);
-\end{verbatim}
-which converts the tangent plane coordinates \code{in} to (RA,Dec) on
-the sky, using the specified \code{projection}.
-
-% astrometry comes from cell
-\begin{verbatim}
-psPlane *pmCoordCellToFPA(psPlane *out, const psPlane *in, const pmCell *cell);
-\end{verbatim}
-which performs the single-step conversion between Cell coordinates
-\code{in} and FPA coordinates.
-
-% astrometry comes from cell,chip,fpa (PARENT IS NEEDED HERE)
-\begin{verbatim}
-psSphere *pmCoordCellToSky(psSphere *out, const psPlane *in, float color, float mag, const pmCell *cell);
-\end{verbatim}
-which converts coordinates on the specified cell to (RA,Dec).  This
-transformation must be performed using the intermediate stage
-transformations of Cell to Chip, Chip to FPA, FPA to Tangent Plane,
-Tangent Plane to Sky.  The information needed for each of these
-transformations is available in the \code{.parent} elements of
-\code{pmCell} and \code{pmChip}, and the \code{pmFPA.projection}.  The
-\code{color} and magnitude (\code{mag}) of the source is necessary in
-order to perform the distortion between the focal plane and the
-tangent plane.
-
-% astrometry comes from cell (no need for parent)
-\begin{verbatim}
-psSphere *pmCoordCellToSkyQuick(psSphere *out, const psPlane *in, const pmCell *cell);
-\end{verbatim}
-which uses the 'quick-and-dirty' transformation to convert coordinates
-on the specified cell to (RA,Dec).  This transformation should use the
-locally linear transformation specified by the element
-\code{pmCell.toTP}.  Although the accuracy of this transformation
-is lower than the complete transformation above, the calculation is
-substantially faster as it only involves linear transformations.
-
-The following functions convert from high-level frames to the
-coordinates of contained lower-level frames.  
-
-\begin{verbatim}
-psPlane *pmCoordSkyToTP(psPlane *out, const psSphere *in, const psProjection *projection);
-\end{verbatim}
-which converts (RA,Dec) coordinates \code{in} to tangent plane coords
-using the specified \code{projection}.
-
-\begin{verbatim}
-psPlane *pmCoordTPToFPA(psPlane *out, const psPlane *in, float color, float mag, const pmFPA *fpa);
-\end{verbatim}
-which converts the tangent plane coordinates \code{in} to focal plane
-coordinates.  The \code{color} and magnitude (\code{mag}) of the
-source is necessary in order to perform the distortion between the
-focal plane and the tangent plane.
-
-\begin{verbatim}
-psPlane *pmCoordFPAToChip (psPlane *out, const psPlane *in, const pmChip *chip);
-\end{verbatim}
-which converts the specified FPA coordinates \code{in} to the
-coordinates on the given Chip.  The specified chip need not contain
-the input coordinate.  To find the chip which contains a particular
-coordinate, the function \code{pmChipInFPA}, defined above, should be
-used.
-
-\begin{verbatim}
-psPlane *pmCoordChipToCell (psPlane *out, const psPlane *in, const pmCell *cell);
-\end{verbatim}
-which converts the specified Chip coordinate \code{in} to the
-coordinate on the given Cell.  The specified Cell need not contain the
-input coordinate.  To find the cell which contains a particular
-coordinate, the function \code{pmCellInChip}, defined above, should be
-used.
-
-\begin{verbatim}
-psPlane *pmCoordSkyToCell(psPlane *out, const psSphere *in, float color, float mag, pmCell *cell);
-\end{verbatim}
-which directly converts (RA,Dec) \code{in} to coordinates on the
-specified cell.  The specified cell need not contain the input
-coordinates.  The \code{color} and magnitude (\code{mag}) of the
-source is necessary in order to perform the distortion between the
-focal plane and the tangent plane.
-
-\begin{verbatim}
-psPlane *pmCoordSkyToCellQuick(psPlane *out, const psSphere *in, pmCell *cell);
-\end{verbatim}
-which directly converts (RA,Dec) \code{in} to coordinates on the
-specified cell.  The specified cell need not contain the input
-coordinates.  This transformation should use the locally linear
-transformation specified by the element \code{pmCell.toTP}.
-Although the accuracy of this transformation is lower than the
-complete transformation above, the calculation is substantially faster
-as it only involves linear transformations.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{FITS World Coordinate System}