Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 2006) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 2007) @@ -1,3 +1,3 @@ -%%% $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,5 +1154,5 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Basic Data Collections} +\section{Basic Data Types and Collections} We require general data containers, so that associated values (e.g.\ @@ -2715,5 +2715,6 @@ \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,5 +3082,5 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Convolution} +\subsection{Convolution} Convolution will be an essential operation for the IPP. For example, @@ -3090,5 +3091,5 @@ PSF-matching. -\subsubsubsection{Kernel definition} +\subsubsection{Kernel definition} In order to perform a convolution, we need to define the convolution @@ -3140,5 +3141,5 @@ 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,5 +3166,5 @@ 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,4 +3474,25 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\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,4 +3933,26 @@ \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,4 +3983,67 @@ 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,35 +4095,7 @@ 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.