Index: trunk/doc/modules/CameraImages.tex =================================================================== --- trunk/doc/modules/CameraImages.tex (revision 6019) +++ trunk/doc/modules/CameraImages.tex (revision 6421) @@ -129,16 +129,12 @@ \begin{verbatim} typedef struct { - // Position on the cell - int col0; // Offset from the left of cell. - int row0; // Offset from the bottom of cell. - int colBins; // Amount of binning in x-dimension and parity (from sign) - int rowBins; // Amount of binning in y-dimension and parity (from sign) // Information + psMetadata *analysis; // Readout-level analysis metadata + pmCell *parent; // Parent cell + // Data psImage *image; // Imaging area of readout psImage *mask; // Mask for image psImage *weight; // Weight for image psList *bias; // List of bias section (sub-)images - psMetadata *analysis; // Readout-level analysis metadata - pmCell *parent; // Parent cell } pmReadout; \end{verbatim} @@ -146,11 +142,9 @@ The constructor for \code{pmReadout} shall be: \begin{verbatim} -pmReadout *pmReadoutAlloc(pmCell *cell); -\end{verbatim} -The constructor shall make an empty \code{pmReadout}. If the parent -\code{cell} is not \code{NULL}, the \code{parent} link is made and the -readout shall be placed in the parent's array of \code{readouts}. The -metadata containers shall be allocated. All other pointers in the -structure shall be initialized to \code{NULL}. +pmReadout *pmReadoutAlloc(void); +\end{verbatim} +The constructor shall make an empty \code{pmReadout}. The metadata +container and the \code{bias} list shall be allocated. All other +pointers in the structure shall be initialized to \code{NULL}. \subsubsection{A Cell} @@ -177,7 +171,4 @@ \begin{verbatim} typedef struct { - // Offset specifying position on chip - int col0; // Offset from the left of chip. - int row0; // Offset from the bottom of chip. // Astrometric transformations psPlaneTransform* toChip; // Transformations from cell to chip coordinates @@ -186,10 +177,15 @@ // Information psMetadata *concepts; // Cache for PS concepts - psMetadata *camera; // Camera information + psMetadata *camera; // Camera information psMetadata *analysis; // Cell-level analysis metadata + bool process; // Do we want to process? + bool exists; // Does the data exist? + // Levels psArray *readouts; // The readouts (referred to by number) pmChip *parent; // Parent chip - bool valid; // Do we bother about reading and working with this cell? - p_pmHDU *hdu; // FITS data + // Sources + pmFile *imageSource; // Image file on disk + pmFile *maskSource; // Mask file on disk + pmFile *weightSource; // Weight file on disk } pmCell; \end{verbatim} @@ -197,14 +193,17 @@ The constructor for \code{pmCell} shall be: \begin{verbatim} -pmCell *pmCellAlloc(pmChip *chip, psMetadata *cameraData, psString name); -\end{verbatim} -The constructor shall make an empty \code{pmCell}. If the parent -\code{chip} is not \code{NULL}, the \code{parent} link is made and the -cell shall be placed in the parent's array of \code{cells}. The +pmCell *pmCellAlloc(psMetadata *cameraData, psString name); +\end{verbatim} +The constructor shall make an empty \code{pmCell}. The \code{readouts} array shall be allocated with a zero size, and the metadata containers constructed. The cell's \code{camera} pointer -shall be set to the provided \code{cameraData}, and the \code{name} -shall be used to set \code{CELL.NAME} in the \code{concepts}. All -other pointers in the structure shall be initialized to \code{NULL}. +shall be set to the provided \code{cameraData}, the \code{exists} +boolean shall be set to \code{false}, the \code{process} boolean shall +be set to \code{true}, and the \code{name} shall be used to set +\code{CELL.NAME} in the \code{concepts}. All other pointers in the +structure shall be initialized to \code{NULL}. + +\tbd{The astrometric transformations will likely disappear into the +analysis metadata in the future.} \subsubsection{A Chip} @@ -224,7 +223,4 @@ \begin{verbatim} typedef struct { - // Offset specifying position on focal plane - int col0; // Offset from the left of FPA. - int row0; // Offset from the bottom of FPA. // Astrometric transformations psPlaneTransform* toFPA; // Transformation from chip to FPA coordinates @@ -233,8 +229,13 @@ psMetadata *concepts; // Cache for PS concepts psMetadata *analysis; // Chip-level analysis metadata + bool process; // Do we want to process? + bool exists; // Does the data exist? + // Levels psArray *cells; // The cells (referred to by name) pmFPA *parent; // Parent FPA - bool valid; // Do we bother about reading and working with this chip? - p_pmHDU *hdu; // FITS data + // Sources + pmFile *imageSource; // Image file on disk + pmFile *maskSource; // Mask file on disk + pmFile *weightSource; // Weight file on disk } pmChip; \end{verbatim} @@ -242,13 +243,16 @@ The constructor for \code{pmChip} shall be: \begin{verbatim} -pmChip *pmChipAlloc(pmFPA *fpa, psString name); -\end{verbatim} -The constructor shall make an empty \code{pmChip}. If the parent -\code{fpa} is not NULL, the \code{parent} link is made and the chip -shall be placed in the parent's array of \code{chips}. The -\code{cells} array shall be allocated with a zero size, and the -metadata containers constructed. The \code{name} shall be used to set -\code{CHIP.NAME} in the \code{concepts}. All other pointers in the -structure shall be initialized to \code{NULL}. +pmChip *pmChipAlloc(psString name); +\end{verbatim} +The constructor shall make an empty \code{pmChip}. The \code{cells} +array shall be allocated with a zero size, the metadata containers +constructed, the \code{exists} boolean shall be set to \code{false}, +the \code{process} boolean shall be set to \code{true}, andhe +\code{name} shall be used to set \code{CHIP.NAME} in the +\code{concepts}. All other pointers in the structure shall be +initialized to \code{NULL}. + +\tbd{The astrometric transformations will likely disappear into the +analysis metadata in the future.} \subsubsection{A Focal Plane} @@ -278,7 +282,10 @@ psMetadata *analysis; // FPA-level analysis metadata const psMetadata *camera; // Camera configuration + // Levels psArray *chips; // The chips - p_pmHDU *hdu; // FITS data - psMetadata *phu; // Primary Header + // Sources + pmFile *imageSource; // Image file on disk + pmFile *maskSource; // Mask file on disk + pmFile *weightSource; // Weight file on disk } pmFPA; \end{verbatim} @@ -289,9 +296,53 @@ \end{verbatim} The constructor shall make an empty \code{pmFPA}. The \code{chips} -array shall be allocated with a zero size, the \code{camera} and -\code{db} pointers set to the values provided, and the \code{concepts} -metadata constructed. All other pointers in the structure shall be -initialized to \code{NULL}. - +array shall be allocated with a zero size, the \code{camera} pointer +set to the value provided, and the \code{concepts} metadata +constructed. All other pointers in the structure shall be initialized +to \code{NULL}. + +\tbd{The astrometric transformations will likely disappear into the +analysis metadata in the future.} + +\subsubsection{Disk files} + +Each of the levels in the hierarchy have a place to hold a +\code{pmFile}, which is the representation of a FITS file and ``header +data unit'': +\begin{datatype} +typedef struct { + const char *filename; // Name of file + psFits *fits; // FITS file + psMetadata *phu; // Primary extension + const char *extname; // Extension name, or NULL + psMetadata *header; // The FITS header, or NULL if primary + psArray *images; // The pixel data + psDB *database; // Database handle for concepts +} pmFile; +\end{datatype} + + +\subsubsection{Links between levels} + +We provide functions to attach readouts, cells and chips with their +parents: +\begin{prototype} +bool pmReadoutParent(pmReadout *readout, pmCell *cell); +bool pmCellParent(pmCell *cell, pmChip *chip); +bool pmChipParent(pmChip *chip, pmFPA *fpa); +\end{prototype} +In the case of \code{pmReadoutParent}, the function shall set the +\code{parent} pointer for the \code{readout} to \code{cell}, and add +the \code{readout} to the array of \code{readouts} in the \code{cell}. +The other cases are similar. \textit{Note that, in order to avoid +infinite loops when freeing, the reference counter should \textbf{not} +be incremented when attaching to the \code{parent} pointer, and the +deallocators should \textbf{not} free the parent.} + +The following functions remove all levels below that specified: +\begin{prototype} +void pmCellFreeReadouts(pmCell *cell); +void pmChipFreeCells(pmChip *chip); +void pmFPAFreeChips(pmFPA *fpa); +\end{prototype} The inclusion of hierarchical links pointing both down (via the @@ -299,27 +350,20 @@ For this reason, we specify a utility function to manage the collection of upward-pointing links: -\begin{verbatim} -bool pmFPACheckParents(pmFPA *fpa); -\end{verbatim} +\begin{prototype} +bool pmFPACheckLinks(pmFPA *fpa); +\end{prototype} This function checks the validity of the \code{parent} links in the -FPA hierarchy. If a \code{parent} link is not set (or not set -correctly), it is corrected, and the function shall return -\code{false}. If all the \code{parent} pointers were correct, the -function shall return \code{true}. - - -Each of the levels in the hierarchy have a place to hold a -\code{p_pmHDU}, which is the disk representation of the image: -\begin{datatype} -typedef struct { - const char *extname; // Extension name, if it corresponds to this level - psMetadata *header; // The FITS header, if it corresponds to this level - psArray *images; // The pixel data, if it corresponds to this level - psArray *masks; // The mask data, if it corresponds to this level - psArray *weights; // The weight data, if it corresponds to this level -} p_pmHDU; -\end{datatype} +FPA hierarchy. If any \code{parent} link in the (entire) hierarchy is +not set (or not set correctly), it is corrected, and the function +shall return \code{false}. If all the \code{parent} pointers were +correct, the function shall return \code{true}. + \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} @@ -380,19 +424,118 @@ \begin{prototype} -pmFPA *pmFPAConstruct(const psMetadata *camera, psDB *db); +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. A \code{db} handle is also provided so -that may be set in the \code{pmFPA}. The resultant \code{pmFPA} and -its lower-down components shall be ready for to read a FITS file into -it by setting the \code{extname} pointers at the appropriate levels to -the appropriate FITS extension name. +\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}. This involves reading the headers and pixels, as -well as ingesting all the concepts. +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. + +\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: + +\begin{datatype} +typedef bool (*pmFPAIterateFunc)(pmFPA *fpa, pmChip *chip, pmCell *cell); +\end{datatype} +\begin{prototype} +bool pmFPAIterate(pmFPA *fpa, bool doCells, pmFPAIterateFunc func); +\end{prototype} + +\code{pmFPAIterate} shall iterate through all chips (that \code{exist} +and are marked to be \code{process}ed) in the \code{fpa}, and if +\code{doCells} is \code{true}, all cells (that \code{exist} and are +marked to be \code{process}ed) in those chips. For each, the function +shall call the iterator function, \code{func}. + + +\subsection{Selecting elements of the hierarchy for processing} \begin{prototype} @@ -401,5 +544,5 @@ \end{prototype} -These functions are provided to set the \code{valid} booleans within +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. @@ -418,11 +561,13 @@ have \code{valid} set to \code{true}. -\tbd{make these functions richer: select by extention, extname, cell, -options to invalidate all / validate all, etc} +\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 @@ -447,28 +592,19 @@ suitable error message, in which case it shall return \code{false}. -\begin{prototype} -bool pmFPAWrite(psFits *fits, pmFPA *fpa); -\end{prototype} - -\code{pmFPAWrite} shall write the focal plane hierarchy, \code{fpa}, -to the specified \code{fits} file, returning \code{true} upon success -and \code{false} otherwise. The \code{fpa} should contain sufficient -information with which to write the FITS images. - -\begin{prototype} -pmFPAWriteMask(psFits *fits, pmFPA *fpa); -\end{prototype} - -\code{pmFPAWriteMask} is very similar to \code{pmFPAWrite}, but it -shall write the \code{mask} elements of the \code{pmReadout}s -comprising the \code{fpa}. - -\begin{prototype} -pmFPAWriteWeight(psFits *fits, pmFPA *fpa); -\end{prototype} - -\code{pmFPAWriteWeight} is very similar to \code{pmFPAWrite}, but it -shall write the \code{weight} elements of the \code{pmReadout}s -comprising the \code{fpa}. +\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. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%