Changeset 2300 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

Nov 7, 2004, 2:43:20 PM (22 years ago)

Author:

eugene

Message:

bugzilla mods

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (12 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +11 @@
 \project{Pan-STARRS Image Processing Pipeline}
 \organization{Institute for Astronomy}
-\version{08}
+\version{09}
 \docnumber{PSDC-430-007}
 
@@ -41 +41 @@
 
 \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 +1939 @@
 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 +1955 @@
 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 +2173 @@
 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 +2241 @@
 
 \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 +2478 @@
 \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 +3819 @@
 \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 +3875 @@
 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 +3936 @@
 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 +4102 @@
 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}