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

Timestamp:

Oct 7, 2004, 8:16:09 AM (22 years ago)

Author:

eugene

Message:

added FITS I/O routines, modified existing image/header I/O funcs
added psRectangle

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.127 2004-10-07 03:14:26 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.128 2004-10-07 18:16:09 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -2714 +2714 @@
 \subsubsection{Image I/O Functions}
 
+\tbd{this section is being deprecated and the equivalent of these
+functions are being moved to FITS I/O Functions.}
+
 \begin{verbatim}
 psImage *psImageReadSection(psImage *output, int x0, int y0, int x1, int y1, int z, 
@@ -3779 +3782 @@
 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, 
@@ -3786 +3792 @@
 \code{psMetadata} structure.
 
+\tbd{this function is being deprecated and the equivalent is being
+moved to FITS I/O Functions.}
 
 \subsubsection{Configuration files}
@@ -3902 +3910 @@
 A BNF-like grammar of the configuration file is contained in
 \S\ref{sec:configgrammar}.
+
+\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
+\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).
+
+\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
+\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
+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);
+\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.
+
+\subsection{Rectangles}
+
+In many places, we need to refer to a rectangular area.  We define a
+structure to represent a rectangle:
+\begin{verbatim}
+typedef struct {
+  psS32 x0;
+  psS32 x1;
+  psS32 y0;
+  psS32 y1;
+} psRectangleS32;
+\end{verbatim}
+
+\begin{verbatim}
+typedef struct {
+  psF32 x0;
+  psF32 x1;
+  psF32 y0;
+  psF32 y1;
+} psRectangleF32;
+psRectangle *psRectangleAlloc (float x0, float x1, float y0, float y1);
+\end{verbatim}
+
+\begin{verbatim}
+psRectangle *psRectangleFromString (char *region);
+\end{verbatim}
+This function converts the IRAF description of a region in the form
+\code{[x0,x1:y0,y1]}, used for header entries such as \code{BIASSEC},
+into the corresponding \code{psRectangle} structure.
 
 \subsection{Detector and sky positions}