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

Timestamp:

Jun 14, 2005, 4:58:05 PM (21 years ago)

Author:

Paul Price

Message:

Updated psFits stuff --- added some functions, and changed some too

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.288 2005-06-15 01:19:11 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.289 2005-06-15 02:58:05 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -3542 +3542 @@
 \begin{datatype}
 typedef struct {
-    fitsfile fd;
+    fitsfile fd;                   // cfitsio structure
+    bool writable;                 // Is the file writable?
 } psFits;
 \end{datatype}
 We begin by defining a datatype to wrap the CFITSIO \code{fitsfile}
 structure.  This is necessary to allow repeated access to the data in
-a file without multiple open commands (which are expensive).
+a file without multiple open commands (which are expensive).  Write
+operations are only permitted if \code{writable} is \code{true}.
 
 \subsubsection{FITS File Manipulations}
 
 \begin{prototype}
-psFits *psFitsOpen(const char *filename);
-\end{prototype}
-
-Opens a FITS file and positions the pointer to the PHU.
+psFits *psFitsOpen(const char *filename, const char mode);
+\end{prototype}
+
+Opens a FITS file and positions the pointer to the PHU.  The file is
+opened in the requested \code{mode}, which may be one of \code{r}
+(read only) \code{r+} (read and write), \code{rw} (alias for
+\code{r+}) or \code{w} (create new file for writing).
 
 \begin{prototype}
@@ -3587 +3592 @@
 
 \begin{prototype}
+bool psFitsMoveEnd(psFits *fits);
+\end{prototype}
+
+Moves the pointer to the end of the file, so that a new extension may
+be written.
+
+\begin{prototype}
 int psFitsGetExtNum(const psFits* fits);
 \end{prototype}
@@ -3597 +3609 @@
 
 Returns the number of HDUs in the file.
+
+\begin{prototype}
+bool psFitsDeleteExtNum(psFits *fits, int extnum, bool relative);
+bool psFitsDeleteExtName(psFits *fits, const char *extname);
+\end{prototype}
+
+These functions are similar to \code{psFitsMoveExtNum} and
+\code{psFitsMoveExtName} except that they delete the specified
+extension.  The file pointer is left pointing to where the extension
+was before deletion.
+
+\begin{prototype}
+bool psFitsTruncate(psFits *fits);
+\end{prototype}
+
+Deletes all extensions after the position of the file pointer.
 
 \begin{datatype}
@@ -3652 +3680 @@
 Write metadata into the header of a FITS image file.  The header is
 written at the current HDU.
+
+\begin{prototype}
+psMetadata *psFitsHeaderFromImage(psMetadata *header, psImage *image, const char *extname);
+psMetadata *psFitsHeaderFromTable(psMetadata *header, psArray *table, const char *extname);
+\end{prototype}
+
+These functions update the given \code{header} to be compatible with
+the supplied \code{image} (updating \code{BITPIX, NAXIS1, NAXIS2} or
+\code{table} (an array of \code{psMetadata}), and change the
+\code{EXTNAME} header to \code{extname}.
+
+\begin{prototype}
+bool psFitsHeaderValidate(psMetadata *header);
+\end{prototype}
+
+\code{psFitsHeaderValidate} shall validate the supplied \code{header}
+so that it is in compliance to the FITS standard for header keyword
+names and types.  The contents should be changed to conform to the
+FITS standard where possible by truncating names and adding (where
+missing) those keywords required by FITS (e.g., \code{SIMPLE}).  If
+the resulting \code{header} conforms to the FITS standard, the
+function shall return \code{true}; otherwise the function shall return
+\code{false}.
 
 \subsubsection{FITS Image I/O Functions}
@@ -3692 +3743 @@
 
 \begin{prototype}
-bool psFitsWriteImage(psFits *fits, const psMetadata *header, const psImage *input, int depth);
+bool psFitsWriteImage(psFits *fits, psMetadata *header, const psImage *input, int depth,
+                      const char *extname);
 \end{prototype}
 Create a new image based on the dimensions specified for the image and
@@ -3701 +3753 @@
 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.
+operation and 1 for an error.  If \code{extname} is not \code{NULL},
+the \code{EXTNAME} in the \code{header} shall be updated to be
+\code{extname} before writing.
 
 \subsubsection{FITS Table I/O Functions}