Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 359) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 360) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.21 2004-04-01 04:40:36 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.22 2004-04-01 08:52:29 eugene Exp $ \documentclass[panstarrs]{panstarrs} @@ -1778,5 +1778,4 @@ \begin{verbatim} -/// basic image data structure. typedef struct psImage { psType type; ///< image data type and dimension @@ -1812,10 +1811,14 @@ array is given by the elements \code{(x0,y0)}. The structure may include references to subrasters (\code{children, Nchildren}) and/or -to a containing array (\code{parent}). +to a containing array (\code{parent}). Unless this is image is a +child of another image (represents a subset of the pixels of another +image), the image data is allocated in a contiguous block. We require a variety of functions to manipulate these image structures, including creation, destruction, input, output, and various manipulations of the pixels. The required functions are -listed below. +listed below, and fall into several categories. + +\subsubsection{Image Structure Manipulation} Create an image of a specified width, height, and data type. This @@ -1823,9 +1826,9 @@ to the valid FITS BITPIX types. \begin{verbatim} -psImage * -psImageAlloc (int nx, ///< image width - int ny, ///< image height - psType type) ///< image data type -\end{verbatim} +psImage *psImageAlloc (int nx, int ny, psType type); +\end{verbatim} +where \code{nx} and \code{ny} specify the size of the image and +\code{type} specifies the data type and the image dimensions (which +must be 2). Define a subimage of the specified area of the given image. This @@ -1833,46 +1836,39 @@ outside of the parent image. \begin{verbatim} -/// Create a subimage of the specified area. -psImage * -psImageSubset(psImage *out, ///< Subimage to return, or NULL - const psImage *image, ///< parent image - int nx, ///< subimage width (<= image.nx - x0) - int ny, ///< subimage width (<= image.ny - y0) - int x0, ///< subimage x-offset (0 <= x0 < nx) - int y0 ///< subimage y-offset (0 <= y0 < ny) - ); -\end{verbatim} +psImage *psImageSubset(psImage *out, psImage *image, int nx, int ny, int x0, int y0); +\end{verbatim} +where \code{image} is the parent image, \code{nx,ny} specify the +dimensions of the desired subraster, and \code{x0, y0} specify the +starting pixel of the subraster. The entire subraster must be +contained within the raster of the parent image. An image structure +to populate may be specified by \code{out}, or if this is \code{NULL}, +a new structure is allocated. Free the memory associated with a specific image, including the pixel data. Free the children of the image if they exist. \begin{verbatim} -void -psImageFree(psImage *restrict image ///< free this image - ); -\end{verbatim} - -Free only the pixels for a specified image. -\begin{verbatim} -psImage * -psImageFreePixels(psImage *restrict image ///< Image whose pixels are to be freed - ); -\end{verbatim} - -Free the memory associated with the children of a specific image, -returning the number of children freed. -\begin{verbatim} -int -psImageFreeChildren(const psImage *image ///< free children of this image - ); +void psImageFree(psImage *image); +\end{verbatim} + +Free only the pixels for a specified image: +\begin{verbatim} +psImage *psImageFreePixels(psImage *image); +\end{verbatim} + +Free the image structure memory associated with the children of a +specific image, returning the number of children freed. Do not free +the pixel data: +\begin{verbatim} +int psImageFreeChildren(psImage *image); \end{verbatim} Create a copy of the specified image. If the output target pointer is -not NULL, place the result in the specified structure. -\begin{verbatim} -psImage * -psImageCopy(psImage *output, ///< target structure for output image data - const psImage *input ///< copy this image - ); -\end{verbatim} +not NULL, place the result in the specified structure. The output +image data must be allocated as a single, contiguous block of memory. +\begin{verbatim} +psImage *psImageCopy(psImage *output, psImage *input); +\end{verbatim} + +\subsubsection{Image Pixel Extractions} Extract pixels from rectlinear region to a vector (array of floats). @@ -1883,16 +1879,7 @@ is derived from the statistics of the pixels at that direction coordinate. The statistic used to derive the output vector value is -specified by \code{psStats stats}. -\begin{verbatim} -psFloatArray * -psImageSlice(psFloatArray *out, ///< Vector to output, or NULL - const psImage *input, ///< extract slice from this image - int x, ///< starting x coord of region to slice - int y, ///< starting y coord of region to slice - int nx, ///< width of region in x - int ny, ///< width of region in y - int direction, ///< direction of vector along slice - const psStats *stats ///< defines statistics used to find output values - ); +specified by \code{psStats *stats}. +\begin{verbatim} +psFloatArray *psImageSlice(psFloatArray *out, psImage *input, int x, int y, int nx, int ny, int direction, const psStats *stats); \end{verbatim} @@ -1907,16 +1894,6 @@ specified by \code{psStats stats}. \begin{verbatim} -psFloatArray * -psImageCut(psFloatArray *out, ///< Vector to output, or NULL - const psImage *input, ///< extract cut from this image - float xs, ///< starting x coord of cut - float ys, ///< starting y coord of cut - float xe, ///< ending x coord of cut - float ye, ///< ending y coord of cut - float dw, ///< width of cut - const psStats *stats ///< defines statistics used to find output values - ); - \end{verbatim} - +psFloatArray *psImageCut(psFloatArray *out, psImage *input, float xs, float ys, float xe, float ye, float dw, const psStats *stats); +\end{verbatim} Extract radial annuli data to a vector. A vector is constructed @@ -1928,14 +1905,8 @@ stats} \begin{verbatim} -psFloatArray * -psImageRadialCut(psFloatArray *out, ///< Vector to output, or NULL - const psImage *input, ///< extract profile from this image - float x, ///< center x coord of annulii - float y, ///< center y coord of annulii - float radius, ///< outer radius of annulii - float dr, ///< radial step size of annulii - const psStats *stats ///< defines statistics used to find output values - ); -\end{verbatim} +psFloatArray *psImageRadialCut(psFloatArray *out, psImage *input, float x, float y, float radius, float dr, psStats *stats); +\end{verbatim} + +\subsubsection{Image Geometry Manipulation} Rebin image to new scale. A new image is constructed in which the @@ -1997,4 +1968,6 @@ \end{verbatim} +\subsubsection{Image Statistical Functions} + Determine statistics for image (or subimage). The statistics to be determined are specified by \code{psStats stats}. @@ -2035,4 +2008,6 @@ ); \end{verbatim} + +\subsubsection{Image I/O Functions} Read an image or subimage from a named file. This function is a @@ -2138,4 +2113,6 @@ ); \end{verbatim} + +\subsubsection{Image Pixel Manipulations} Perform a 2-D FFT on the specified image. The returned image is of