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

Timestamp:

Oct 7, 2004, 9:55:20 AM (22 years ago)

Author:

eugene

Message:

moved back some things around which I moved earlier (coordinates)

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.128 2004-10-07 18:16:09 eugene Exp $
+%%% $Id: psLibSDRS.tex,v 1.129 2004-10-07 19:55:20 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -1154 +1154 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{Basic Data Collections}
+\section{Basic Data Types and Collections}
 
 We require general data containers, so that associated values (e.g.\
@@ -2715 +2715 @@
 
 \tbd{this section is being deprecated and the equivalent of these
-functions are being moved to FITS I/O Functions.}
+functions are being moved to FITS I/O Functions.  I will leave this
+section here until others may read the section on FITS I/O.}
 
 \begin{verbatim}
@@ -3081 +3082 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\subsubsection{Convolution}
+\subsection{Convolution}
 
 Convolution will be an essential operation for the IPP.  For example,
@@ -3090 +3091 @@
 PSF-matching.
 
-\subsubsubsection{Kernel definition}
+\subsubsection{Kernel definition}
 
 In order to perform a convolution, we need to define the convolution
@@ -3140 +3141 @@
 be exchanged.
 
-\subsubsubsection{Generation of a convolution kernel}
+\subsubsection{Generation of a convolution kernel}
 
 Given a list of values (e.g., shifts made in the course of OT
@@ -3165 +3166 @@
 function shall continue.
 
-\subsubsubsection{Convolve an image with the kernel}
+\subsubsection{Convolve an image with the kernel}
 
 Given an input image and the convolution kernel,
@@ -3473 +3474 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\subsection{Regions}
+
+In many places, we need to refer to a rectangular area.  We define a
+structure to represent a rectangle:
+\begin{verbatim}
+typedef struct {
+  float x0;
+  float x1;
+  float y0;
+  float y1;
+} psRegion;
+psRegion *psRegionAlloc (float x0, float x1, float y0, float y1);
+\end{verbatim}
+
+\begin{verbatim}
+psRegion *psRegionFromString (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{psRegion} structure.
+
 \subsection{Metadata}
 \label{sec:metadata}
@@ -3911 +3933 @@
 \S\ref{sec:configgrammar}.
 
+\subsection{FITS I/O Functions}
+
+We need a variety of I/O functions between the disk and certain of our
+PSLib data structures.  We need the ability to access FITS headers,
+images and tables (both ASCII and Binary).  We define here the FITS
+I/O functions, all of which are currently specified as wrappers to
+functions within CFITSIO.  CFITSIO provides a wide range of utilities
+which we do not feel are particularly appropriate as part of a generic
+I/O library, such as assumptions about names which change the data
+interpretation, etc.  We are defining our calls to avoid the hidden
+'features'.  The CFITSIO functions which are wrapped should in general
+be the most basic versions.
+
+\begin{verbatim}
+typedef struct {
+    fitsfile fd;
+} psFits;
+\end{verbatim}
+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).
+
 \subsubsection{FITS Header I/O Functions}
 
@@ -3939 +3983 @@
 for the primary header unit).
 
+\begin{verbatim}
+bool psFitsWriteHeader(psMetadata *output, const char *filename);
+bool psFitsReadHeaderPtr(psMetadata *output, const psFits *fd);
+\end{verbatim}
+Write metadata into the header of a FITS image file.  \tbd{where?}
+\tbd{consistency check?}  \tbd{function to remove non-FITS header
+entries?}  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...}
+
+\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.
+
+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}.  
+ 
+\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}.
+
 \subsubsection{FITS Table I/O Functions}
 
@@ -3988 +4095 @@
 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}
+\tbd{need to have corresponding table write functions...}
+
+\subsection{Detector and Sky Coordinates}
 
 Both detector and sky positions will be used extensively in the IPP.