Index: /trunk/doc/modules/CameraImages.tex =================================================================== --- /trunk/doc/modules/CameraImages.tex (revision 9720) +++ /trunk/doc/modules/CameraImages.tex (revision 9721) @@ -303,4 +303,104 @@ 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,317 +607,362 @@ - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - - - - -\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,173 +1005,4 @@ 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}