Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 2241) +++ trunk/doc/pslib/psLibSDRS.tex (revision 2300) @@ -1,7 +1,7 @@ -%%% $Id: psLibSDRS.tex,v 1.145 2004-10-29 22:01:19 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.146 2004-11-08 00:43:20 eugene Exp $ \documentclass[panstarrs,spec]{panstarrs} % basic document variables -\title{Pan-STARRS Image Processing Pipeline Library} +\title{Pan-STARRS PS-1 Image Processing Pipeline Library} \subtitle{Supplementary Design Requirements} \shorttitle{PSLib SDRS} @@ -11,5 +11,5 @@ \project{Pan-STARRS Image Processing Pipeline} \organization{Institute for Astronomy} -\version{08} +\version{09} \docnumber{PSDC-430-007} @@ -41,9 +41,9 @@ \DocumentsInternal -PSDC-130-001 & PS-1 Design Reference Mission \\ \hline -PSDC-430-004 & Pan-STARRS IPP C Code Conventions \\ \hline -PSDC-430-005 & Pan-STARRS IPP SRS \\ \hline -PSDC-430-006 & Pan-STARRS IPP ADD \\ \hline -PSDC-430-008 & Pan-STARRS IPP Architecture SDR \\ +PSDC-230-001 & PS-1 Design Reference Mission \\ \hline +PSDC-430-004 & Pan-STARRS PS-1 IPP C Code Conventions \\ \hline +PSDC-430-005 & Pan-STARRS PS-1 IPP Software Requirements Specification \\ \hline +PSDC-430-006 & Pan-STARRS PS-1 IPP Algorithm Design Document \\ \hline +PSDC-430-011 & Pan-STARRS PS-1 IPP System/Subsystem Design Description \\ \hline \DocumentsExternal Posix Standard & Open Group Based Specifications Issue 6, IEEE Std 1003.1, 2003 \\ @@ -1939,5 +1939,5 @@ This function takes the input data in \code{in} (with optional \code{errors} in these values; and with optional masking in -\code{mask}, so that the user may explicitly reject specific entries ) +\code{mask}, so that the user may explicitly reject specific entries) and a \code{psStats} structure, which will be altered and returned. The \code{psStats} structure includes several fields which are used @@ -1955,6 +1955,12 @@ field values must be set by the \code{psStats} constructor. The input vector may be of type \code{psS8}, \code{psU16}, \code{psF32}, -\code{psF64}; the \code{errors} must be of the same type as the -\code{in} vector; the mask must be of type \code{psU8}. +\code{psF64}. The \code{errors} must be of the same type as the +\code{in} vector. If \code{errors} is not \code{NULL}, the +calculation of certain statistics are modified: The sample mean is +calculated using the formula for the weighted mean; the standard +deviation is modified as specified in the ADD; the clipping used for +clipped statistics are modified according to the ADD; the robust +median and quartiles are modified as specified in the ADD. The mask +must be of type \code{psU8}. The \code{psStats} structure is defined with entries for each of the @@ -2167,11 +2173,10 @@ To evaluate the polynomials at specific coordinates, we define: \begin{verbatim} -double psDPolynomial2DEval(double x, double y, const psDPolynomial2D *restrict myPoly); +double psDPolynomial2DEval(const psDPolynomial2D *restrict myPoly, double x, double y); \end{verbatim} In the event that several evaluations are required, we also define: \begin{verbatim} -psVector *psDPolynomial2DEvalVector(const psVector *x, const psVector *y, - const psDPolynomial2D *myPoly); +psVector *psDPolynomial2DEvalVector(const psDPolynomial2D *myPoly, const psVector *x, const psVector *y); \end{verbatim} If the \code{x} and \code{y} vectors do not match the precision of the @@ -2236,8 +2241,7 @@ \begin{verbatim} -float psSpline1DEval(const psSpline1D *spline, float x); -psVector *psSpline1DEvalVector(const psVector *x, const psSpline1D *spline); -\end{verbatim} - +psF64 psSpline1DEval(const psSpline1D *spline, float x); +psVector *psSpline1DEvalVector(const psSpline1D *spline, const psVector *x); +\end{verbatim} \subsubsection{Gaussians} @@ -2474,9 +2478,11 @@ \code{psVectorFitSpline} shall return the spline that best fits the given combination of ordinates (\code{x}) and coordinates (\code{y}). -As for \code{psVectorFitPolynomial1D}, if \code{x} is \code{NULL}, -then the vector index shall be used as the ordinate; and if -\code{yErr} is \code{NULL}, then all the data errors shall be assumed -to be equal. This function must be valid only for types \code{psF32}, -\code{psF64}. +The function shall construct a new \code{psSpline1D} based on domains +determined from \code{x}: the domain boundaries are the data values in +\code{x}. As is the case for \code{psVectorFitPolynomial1D}, if +\code{x} is \code{NULL}, then the index of \code{y} shall be used as +the ordinate; and if \code{yErr} is \code{NULL}, then all the data +errors shall be assumed to be equal. This function must be valid only +for types \code{psF32}, \code{psF64}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3813,17 +3819,17 @@ \code{psMetadata.hash} entries, which are required to have unique keys, would have a single entry with the keyword of the repeated key, -with the value of \code{psMetadataType} set to -\code{PS_META_ITEM_SET}, and the \code{psMetadataItem.items} element -pointing to a \code{psList} pointing to the actual entries. If -\code{psMetadataItemAlloc} is called with the type set to -\code{PS_META_ITEM_SET}, such a repeated key is created. If the data -value passed to \code{psMetadataItemAlloc} (the quantity in ellipsis) -is \code{NULL}, then an empty \code{psMetadataItem} with the given -keyword is created to hold future entries of that keyword. +with the value of \code{psMetadataType} set to \code{PS_META_LIST}, +and the \code{psMetadataItem.data} element pointing to a \code{psList} +containing the actual entries. If \code{psMetadataItemAlloc} is +called with the type set to \code{PS_META_LIST}, such a repeated key +is created. If the data value passed to \code{psMetadataItemAlloc} +(the quantity in ellipsis) is \code{NULL}, then an empty +\code{psMetadataItem} with the given keyword is created to hold future +entries of that keyword. The \code{psMetadataAdd} routine is required to check that all metadata names are unique unless the type is already qualified as -\code{PS_META_ITEM_SET}; in this case the data are added to the -corresponding \code{psMetadataItem.items} list. +\code{PS_META_LIST}; in this case the data are added to the +corresponding \code{psMetadataItem.data} list. \subsubsection{Metadata APIs} @@ -3869,5 +3875,5 @@ Care should be taken not to leak memory when appending an item for which the key already exists in the metadata (and is not -\code{PS_META_ITEM_SET}). +\code{PS_META_LIST}). % \begin{verbatim} @@ -3930,31 +3936,4 @@ void psMetadataItemPrint(FILE *fd, const char *format, const psMetadataItem *md); \end{verbatim} - -\begin{verbatim} -psMetadata *psMetadataReadHeader(psMetadata *output, const char *extname, - int extnum, const char *filename); -\end{verbatim} -Read header data from a FITS image file into a \code{psMetadata} -structure. The \code{extname} and \code{extnum} parameters specify -the extension of interest as above. The data is read from the -extension specified by extname (matching the EXTNAME keyword) or by -the extnum value (with 0 representing the primary header unit (PHU), 1 -the first extension, etc). This function must call \code{psError} and -return \code{NULL} if the specified extension does not exist. If -\code{extname} is not \code{NULL}, \code{extnum} must be set to -1 or -the function shall raise an error. - -\tbd{this function is being deprecated and the equivalent is being -moved to FITS I/O Functions.} - -\begin{verbatim} -psMetadata *psMetadataFReadHeader(psMetadata *output, const char *extname, - int extnum, FILE *f); -\end{verbatim} -Read header data from a FITS image file descriptor into a -\code{psMetadata} structure. - -\tbd{this function is being deprecated and the equivalent is being -moved to FITS I/O Functions.} \subsubsection{Configuration files} @@ -4123,145 +4102,192 @@ a file without multiple open commands (which are expensive). +\subsubsection{FITS File Manipulations} + +\begin{verbatim} +psFits *psFitsAlloc(const char *filename); +\end{verbatim} + +Opens a FITS file at positions the pointer to the PHU. + +\begin{verbatim} +psFits *psFitsMoveExtName(psFits *fits, const char *extname); +\end{verbatim} + +Positions the pointer to the beginning of the specified +\code{extname}. If the \code{extname} does not exist, the function +shall fail. \tbd{is it necessary to return the pointer? can this just +return a status?} + +\begin{verbatim} +bool psFitsMoveExtNum(psFits* fits, int extnum, bool relative); +\end{verbatim} + +Moves the pointer to the beginning of the specified HDU number. If +\code{relative} is TRUE, \code{extnum} represents the number of HDUs +relative to the current HDU. \tbd{Is PHU 0 or -1? is it necessary to +return the pointer? can this just return a status?} + +\begin{verbatim} +int psFitsGetExtNum(psFits* fits); +\end{verbatim} + +Returns the current HDU number (i.e., file position). + +\begin{verbatim} +int psFitsGetSize(psFits* fits); +\end{verbatim} + +Returns the number of HDUs in the file. + +\begin{verbatim} +int psFitsCreateExt(psFits* fits, psFitsType type, const char* name); +\end{verbatim} + +Creates a new HDU on the end of the file with the given extname and +type. The psFits pointer is positioned to the new HDU. \tbd{does +this write data to disk or not?} + +\begin{verbatim} +psFitsType psFitsGetExtType(psFits* fits); +\end{verbatim} + +Gets the current HDU's type (table or image). + \subsubsection{FITS Header I/O Functions} \begin{verbatim} -psMetadata *psFitsReadHeader(psMetadata *output, const char *extname, int extnum, const char *filename); -psMetadata *psFitsReadHeaderPtr(psMetadata *output, const char *extname, int extnum, const psFits *fd); -\end{verbatim} -Read header data from a FITS image file into a \code{psMetadata} -structure. The \code{extname} and \code{extnum} parameters specify -the extension of interest as above. The data is read from the -extension specified by extname (matching the EXTNAME keyword) or by -the extnum value (with 0 representing the primary header unit (PHU), 1 -the first extension, etc). This function must call \code{psError} and -return \code{NULL} if the specified extension does not exist. If -\code{extname} is not \code{NULL}, \code{extnum} must be set to -1 or -the function shall raise an error. The file is either specified as a -named file on disk or by an open \code{psFits} file pointer. - -\begin{verbatim} -psHash *psFitsReadHeaderSet (const char *filename); -psHash *psFitsReadHeaderSetPtr (const psFits *fd); -\end{verbatim} -Load a complete set of headers from a named file or \code{psFits} file -pointer. This function loads the headers from all extensions into a +psMetadata *psFitsReadHeader(psMetadata *out, const psFits *fits); +\end{verbatim} +Read header data into a \code{psMetadata} structure. The data is read +from the current HDU pointed at by the \code{psFits *fits} entry. If +\code{out} is \code{NULL}, a new psMetadata is created. + +\begin{verbatim} +psHash *psFitsReadHeaderSet (psFits *fits); +\end{verbatim} +Load a complete set of headers from the \code{psFits} file pointer. +This function loads the headers from all extensions into a \code{psHash}, each entry of which is a pointer to a \code{psMetadata} structure containing the header data. The hash keys are the \code{EXTNAME} values for each header (with the value of \code{PHU} -for the primary header unit). - -\begin{verbatim} -bool psFitsWriteHeader(psMetadata *output, const char *filename); -bool psFitsWriteHeaderPtr(psMetadata *output, const psFits *fd); +for the primary header unit). At the start of the operation, the file +pointer is rewound to the beginning of the file. At the end, it is +positioned where it started when the function was called. + +\begin{verbatim} +bool psFitsWriteHeader(psMetadata *output, const psFits *fits); \end{verbatim} Write metadata into the header of a FITS image file. The header is -written to the end of the given file. \tbd{Allow for overwriting a -specific header? dangerous in anycase: the header and data must agree -for the file to be valid...} \tbd{consistency check?} \tbd{function -to remove non-FITS header entries?} +written at the current HDU. \subsubsection{FITS Image I/O Functions} \begin{verbatim} -psImage *psFitsReadImageSection(psImage *output, psRegion region, int z, const char *extname, int extnum, const char *filename); -psImage *psFitsReadImageSectionPtr(psImage *output, psRegion region, int z, const char *extname, int extnum, const psFits *fd); -\end{verbatim} -Read an image or subimage from a named file or \code{psFits} file -pointer. This function is a wrapper to the CFITSIO library function. -The input parameters allow a full image or a subimage to be read. The -region to be read is specified by \code{region}. A negative value -for either of \code{region.x1} or \code{region.y1} specifies the -size of the region to be read counting down from the end of the array. -The file pointer version must not make any assumption about the -current position of the file pointer. +psImage *psFitsReadImageSection(psImage *output, psFits *fits, psRegion region, int z); +\end{verbatim} +Read an image or subimage from the \code{psFits} file pointer. This +function is a wrapper to the CFITSIO library function. The input +parameters allow a full image or a subimage to be read. The region to +be read is specified by \code{region}. A negative value for either of +\code{region.x1} or \code{region.y1} specifies the size of the region +to be read counting down from the end of the array. If the native image is a cube, the value of z specifies the requested -slice of the image. The data is read from the extension specified by -extname (matching the EXTNAME keyword) or by the extnum value (with 0 -representing the primary header unit (PHU), 1 the first extension, -etc). This function must call \code{psError} and return \code{NULL} -if any of the specified parameters are out of range for the data in -the image file, if the specified image file does not exist, or the -image on disk is zero- or one-dimensional. This function need only -read images of the native FITS image types (\code{psU8}, \code{psS16}, -\code{psS32}, \code{psF32}, \code{psF64}). The user is expected to -convert the data type as needed with \code{psImageCopy}. +slice of the image. This function must call \code{psError} and return +\code{NULL} if any of the specified parameters are out of range for +the data in the image file, or if the image on disk is zero- or +one-dimensional. This function need only read images of the native +FITS image types (\code{psU8}, \code{psS16}, \code{psS32}, +\code{psF32}, \code{psF64}). The user is expected to convert the data +type as needed with \code{psImageCopy}. \begin{verbatim} -bool psFitsWriteImageSection(const psImage *input, int x, int y, int z, const char *extname, int extnum, const char *filename); -bool psFitsWriteImageSectionPtr(const psImage *input, int x, int y, int z, const char *extname, int extnum, const psFits *fd); -\end{verbatim} -Write an image section to the named file (which may exist) or open -\code{psFits} file pointer. This operation may write a portion of an -image over the existing bytes of an existing image. If the file does -not exist, it should be created. If the specified extension does not -exist, it should be created. If an extension is specified and no PHU -exists, a basic PHU should be created. Care must be taken to -interpret x,y,z in the two cases a) there is already an existing image -and b) there is not an existing image. If the image exists, write the -complete psImage data to the existing image starting at the coordinate -x,y,z. If any of these parameters implies writing pixels outside the -existing data area of the image, return an error (ie, if \code{x + -image.nx >= NAXIS1}, \code{y + image.ny >= NAXIS2}, or \code{z >= -NAXIS3}). If the image does not exist, require x,y,z to be zero. -This function will only write images of the native FITS image types -(\code{psU8}, \code{psS16}, \code{psS32}, \code{psF32}, \code{psF64}). -The user is expected to convert the data type as needed with -\code{psImageCopy}. The return value must be 0 for a successful -operation and 1 for an error. - -\tbd{versions of these functions which do not construct the header, -but instead use a corresponding metadata structure, need to exist}. +bool psFitsWriteImageSection(psFits *fits, const psImage *input, psRegion region, int z); +\end{verbatim} +Write an image section to the open \code{psFits} file pointer. This +operation may write a portion of an image over the existing bytes of +an existing image. Care must be taken to interpret \code{region}, +which specified the output pixels to be written / over-written. If +the combination of \code{region} and the size of \code{psImage *input} +implies writing pixels outside the existing data area of the image, +the function shall return an error (ie, if \code{region.x0 + image.nx +>= NAXIS1}, \code{region.y0 + image.ny >= NAXIS2}, or \code{z >= +NAXIS3}). This function will only write images of the native FITS +image types (\code{psU8}, \code{psS16}, \code{psS32}, \code{psF32}, +\code{psF64}). The user is expected to convert the data type as +needed with \code{psImageCopy}. The return value must be 0 for a +successful operation and 1 for an error. \subsubsection{FITS Table I/O Functions} \begin{verbatim} -void *psFitsReadTableRow (int *nBytes, char *extname, int row, char *filename); -void *psFitsReadTableRowPtr (int *nBytes, char *extname, int row, psFits *fd); -\end{verbatim} -These functions read a single row of the table in the extension -specified by \code{extname}, in the file specified by the given -\code{filename} or \code{psFits} file pointer. The row number to be -read is given by \code{row}. The result is returned as collection of +psMetadata *psFitsReadTableRow (psFits *fits, int row); +\end{verbatim} +This function reads a single row of the table in the extension pointed +at by the \code{psFits} file pointer. The row number to be read is +given by \code{row}. The result is returned as a \code{psMetadata} +collection with elements of the apporpriate types and keys +corresponding to the table column names. The function must apply the +needed byte-swapping on the data in the row based on the description +of the table data in the table header. \tbr{we may need to be more +flexible here: if we call this function repeatedly, it would be more +efficient to pass the corresponding header or keep it somewhere (and +the file pointer location, for that matter).} + +\begin{verbatim} +void *psFitsReadTableRowRaw (int *nBytes, psFits *fits, int row); +\end{verbatim} +This function reads a single row of the table in the extension pointed +at by the \code{psFits} file pointer. The row number to be read is +given by \code{row}. The result is returned as collection of \code{nBytes} bytes allocated by the function. The function must apply the needed byte-swapping on the data in the row based on the description of the table data in the table header. \tbr{we may need - to be more flexible here: if we call this function repeatedly, it - would be more efficient to pass the corresponding header or keep it - somewhere (and the file pointer location, for that matter).} - -\begin{verbatim} -psArray *psFitsReadTableColumn (char *extname, char *colname, char *filename); -psArray *psFitsReadTableColumnPtr (char *extname, char *colname, psFits *fd); -\end{verbatim} -These functions read a single column of the table in the extension -specified by \code{extname}, in the file specified by the given -\code{filename} or \code{psFits} file pointer. The column is -specified by the FITS table column key given by \code{row}. The -result is returned as a \code{psArray}, with one row's worth of data +to be more flexible here: if we call this function repeatedly, it +would be more efficient to pass the corresponding header or keep it +somewhere (and the file pointer location, for that matter).} + +\begin{verbatim} +psArray *psFitsReadTableColumn (psFits *fits, char *colname); +\end{verbatim} +This function reads a single column of the table in the extension +pointed at by the \code{psFits} file pointer. The column is specified +by the FITS table column key given by \code{row}. The result is +returned as a \code{psArray}, with the data from one row of the table +column per array element. + +\begin{verbatim} +psVector *psFitsReadTableColumnNum (psFits *fits, char *colname); +\end{verbatim} +This function reads a single column of the table in the extension +pointed at by the \code{psFits} file pointer. The column is specified +by the FITS table column key given by \code{row} and must be of a +numeric data type. The result is returned as a \code{psVector} of the +appropriate data type, with the data from one row of the table column per array element. \begin{verbatim} -psVector *psFitsReadTableColumnNum (char *extname, char *colname, char *filename); -psVector *psFitsReadTableColumnNumPtr (char *extname, char *colname, psFits *fd); -\end{verbatim} -These functions read a single column of the table in the extension -specified by \code{extname}, in the file specified by the given -\code{filename} or \code{psFits} file pointer. The column is -specified by the FITS table column key given by \code{row}. - -\begin{verbatim} -psArray *psFitsReadTable (int *nBytes, char *extname, char *filename); -psArray *psFitsReadTablePtr (int *nBytes, char *extname, psFits *fd); +psArray *psFitsReadTableRaw (int *nBytes, psFits *fits); \end{verbatim} This function reads the entire data block from a table into the a \code{psArray}, with one element of the array per row. The number of -bytes per row is returned in \code{nBytes}. The result is returned as -a \code{psVector}, which, as a numerical data type, is only valid for -numerical table columns. The function must apply the needed -byte-swapping on the data in each row based on the description of the -table data in the table header. - -\tbd{need to have corresponding table write functions...} +bytes per row is returned in \code{nBytes}. The function must apply +the needed byte-swapping on the data in each row based on the +description of the table data in the table header. + +\begin{verbatim} +psArray *psFitsReadTable (psFits *fits); +\end{verbatim} +This function reads the entire data block from a table into the a +\code{psArray}, with one element of the array per row. Each row is +stored as a \code{psMetadata} collection as described above for +\code{psFitsReadTableRow}. + +\begin{verbatim} +bool psFitsWriteTable(psFits* fits, psArray* table); +\end{verbatim} +Accepts a \code{psArray} of \code{psMetadata} and writes it to the +current HDU. If the current HDU is not a table type, this will fail +and return FALSE. \subsection{Detector and Sky Coordinates}