Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 361) +++ trunk/doc/pslib/psLibSDRS.tex (revision 362) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.23 2004-04-01 08:54:37 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.24 2004-04-01 09:14:20 eugene Exp $ \documentclass[panstarrs]{panstarrs} @@ -1949,5 +1949,7 @@ 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); +psFloatArray *psImageSlice(psFloatArray *out, psImage *input, + int x, int y, int nx, int ny, + int direction, const psStats *stats); \end{verbatim} @@ -1962,5 +1964,7 @@ specified by \code{psStats stats}. \begin{verbatim} -psFloatArray *psImageCut(psFloatArray *out, psImage *input, float xs, float ys, float xe, float ye, float dw, const psStats *stats); +psFloatArray *psImageCut(psFloatArray *out, psImage *input, + float xs, float ys, float xe, float ye, float dw, + const psStats *stats); \end{verbatim} @@ -1973,5 +1977,7 @@ stats} \begin{verbatim} -psFloatArray *psImageRadialCut(psFloatArray *out, psImage *input, float x, float y, float radius, float dr, psStats *stats); +psFloatArray *psImageRadialCut(psFloatArray *out, psImage *input, + float x, float y, float radius, float dr, + psStats *stats); \end{verbatim} @@ -1980,16 +1986,10 @@ Rebin image to new scale. A new image is constructed in which the dimensions are reduced by a factor of \code{scale} $\le 1$ (it is an -error for \code{scale} $> 1$). The output image represents a -one-to-one mapping of the pixels in the input image, except for edge -effects. Each pixel in the output image is derived from the -statistics of the corresponding input image pixels based on the -statistics specified by \code{psStats stats}. \tbd{interpolation?} -\begin{verbatim} -psImage * -psImageRebin(psImage *out, ///< Image to output, or NULL - const psImage *input, ///< rebin this image - float scale, ///< rebinning scale: doutput = scale*dinput - const psStats *stats ///< defines statistics used to find output values - ); +error for \code{scale} $> 1$). The output image is generated from all +input image pixels. Each pixel in the output image is derived from +the statistics of the corresponding set of input image pixels based on +the statistics specified by \code{psStats stats}. +\begin{verbatim} +psImage *psImageRebin(psImage *out, psImage *input, float scale, psStats *stats); \end{verbatim} @@ -1997,13 +1997,9 @@ output image must contain all of the pixels from the input image in their new frame. Pixels in the output image which do not map to input -pixels should be set of \tbd{value}. The center of rotation is always +pixels should be set to \tbd{value}. The center of rotation is always the center pixel of the image. The rotation is specified in the sense that a positive angle is an anti-clockwise rotation. \begin{verbatim} -psImage * -psImageRotate(psImage *out, ///< Image to output, or NULL - const psImage *input, ///< rotate this image - float angle ///< rotate by this amount anti-clockwise (degrees) - ); +psImage *psImageRotate(psImage *out, psImage *input, float angle); \end{verbatim} @@ -2015,23 +2011,12 @@ set to the value given by \code{exposed}. \begin{verbatim} -psImage * -psImageShift(psImage *out, ///< Image to output, or NULL - const psImage *input, ///< shift this image - float dx, ///< shift by this amount in x - float dy, ///< shift by this amount in y - float exposed ///< set exposed pixels to this value - ); -\end{verbatim} - -Roll image by an integer number of pixels in either direction. The -output image is the same dimensions as the input image. Edge pixels -wrap to the other side (no values are lost). -\begin{verbatim} -psImage * -psImageRoll(psImage *out, ///< Image to output, or NULL - const psImage *input, ///< roll this image - int dx, ///< roll this amount in x - int dy ///< roll this amount in y - ); +psImage *psImageShift(psImage *out, psImage *input, float dx, float dy, float exposed); +\end{verbatim} + +Roll image by an integer number of pixels (\code{dx,dy}) in either +direction. The output image is the same dimensions as the input +image. Edge pixels wrap to the other side (no values are lost). +\begin{verbatim} +psImage *psImageRoll(psImage *out, psImage *input, int dx, int dy); \end{verbatim} @@ -2041,38 +2026,26 @@ determined are specified by \code{psStats stats}. \begin{verbatim} -psStats * -psImageGetStats(const psImage *input, ///< image (or subimage) to calculate stats - psStats *stats ///< defines statistics to be calculated & target - ); +psStats *psImageGetStats(psImage *input, psStats *stats); \end{verbatim} Construct a histogram from an image (or subimage). The histogram to -generate is specified by \code{psHistogram hist}. -\begin{verbatim} -psHistogram * -psImageHistogram(psHistogram *hist, ///< input histogram description & target - const psImage *input ///< determine histogram of this image - ); -\end{verbatim} - -Fit a 2-D polynomial surface to an image. The input structure -\code{coeffs} contains the desired order and terms of interest. -\tbd{how do we specify the renormalization?} -\begin{verbatim} -psPolynomial2D * -psImageFitPolynomial(const psImage *input, ///< image to fit - psPolynomial2D *coeffs ///< coefficient structure carries in desired terms & target - ); -\end{verbatim} - -Evaluate a 2-D polynomial surface to image pixels. Given the input -polynomial coefficients, return an image generated on the basis of the -input image pixels which evaluates the polynomial for all pixels in -the image.a -\begin{verbatim} -int -psImageEvalPolynomial(const psImage *input, ///< image to fit - const psPolynomial2D *coeffs ///< coefficient structure carries in desired terms - ); +generate is specified by \code{psHistogram hist} (see +section~\ref{histogram}). +\begin{verbatim} +psHistogram *psImageHistogram(psHistogram *hist, psImage *input); +\end{verbatim} + +Fit a 2-D Chebychev polynomial surface to an image. The input +structure \code{coeffs} contains the desired order and terms of +interest. +\begin{verbatim} +psPolynomial2D *psImageFitPolynomial(psImage *input, psPolynomial2D *coeffs); +\end{verbatim} + +Evaluate a 2-D polynomial surface for the image pixels. Given the +input polynomial coefficients, set the image pixel values on the basis +of the polynomial function. \tbd{return value?} +\begin{verbatim} +int psImageEvalPolynomial(psImage *input, psPolynomial2D *coeffs); \end{verbatim} @@ -2087,6 +2060,6 @@ 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 -1 -representing the PHU, 0 the first extension, etc). This function must +extname (matching the EXTNAME keyword) or by the extnum value (with 0 +representing the PHU, 1 the first extension, etc). This function must generate an error and return \code{NULL} if any of the specified parameters are out of range for the data in the image file, if the @@ -2094,15 +2067,7 @@ one-dimensional. \begin{verbatim} -psImage * -psImageReadSection(psImage *output, ///< place data in this structure for output - int x, ///< starting x coord of region - int y, ///< starting y coord of region - int nx, ///< x size of region (-1 for full range) - int ny, ///< y size of region (-1 for full range) - int z, ///< plane of interest - const char *extname, ///< MEF extension name ("PHU" for primary header) - int extnum, ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1) - const char *filename ///< file to read data from - ); +psImage *psImageReadSection(psImage *output, + int x, int y, int nx, int ny, int z, + char *extname, int extnum, char *filename); \end{verbatim} @@ -2112,61 +2077,37 @@ \begin{verbatim} psImage * -psImageFReadSection(psImage *output, ///< place data in this structure for output - int x, ///< starting x coord of region - int y, ///< starting y coord of region - int dx, ///< x size of region (-1 for full range) - int dy, ///< y size of region (-1 for full range) - int z, ///< plane of interest - const char *extname, ///< MEF extension name ("PHU" for primary header) - int extnum, ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1) - FILE *f ///< file descriptor to read data from - ); -\end{verbatim} - -\TBD{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} - -Write an image section to named file, which may exist. This +psImageFReadSection(psImage *output, + int x, int y, int nx, int ny, int z, + char *extname, int extnum, FILE *f); +\end{verbatim} +\tbd{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} + +Write an image section to the named file, which may exist. 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. -\begin{verbatim} -psImage * -psImageWriteSection(psImage *input, ///< image to write out - int x, ///< starting x coord of region - int y, ///< starting y coord of region - int z, ///< plane of interest - const char *extname, ///< MEF extension name ("PHU" for primary header) - int extnum, ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1) - const char *filename ///< file to write data to - ); -\end{verbatim} - -Write an image section to file descriptor. -\begin{verbatim} -psImage * -psImageFWriteSection(psImage *input, ///< image to write out - int x, ///< starting x coord of region - int y, ///< starting y coord of region - int z, ///< plane of interest - const char *extname, ///< MEF extension name - int extnum, ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1) - FILE *f ///< file descriptor to write data to - ); -\end{verbatim} - -\TBD{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} +created. +\begin{verbatim} +psImage *psImageWriteSection(psImage *input, + int x, int y, int z, + char *extname, int extnum, char *filename); +\end{verbatim} + +Write an image section to file descriptor as above: +\begin{verbatim} +psImage *psImageFWriteSection(psImage *input, + int x, int y, int z, + char *extname, int extnum, FILE *f); +\end{verbatim} +\tbd{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} Read header data from a FITS image file into a \code{psMetaData} -structure. If the named extension does not exist, the function should -return an error. -\begin{verbatim} -psMetadata * -psImageReadHeader(psMetadata *output, ///< read data to this structure - const char *extname, ///< MEF extension name ("PHU" for primary header) - int extnum, ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1) - const char *filename ///< file to read from - ); +structure (see section~\ref{metadata}. The \code{extname} and +\code{extnum} parameters specify the extension of interest as above. +If the named extension does not exist, the function should return an +error. +\begin{verbatim} +psMetadata *psImageReadHeader(psMetadata *output, char *extname, int extnum, char *filename); \end{verbatim} @@ -2174,45 +2115,22 @@ structure. \begin{verbatim} -psMetadata * -psImageFReadHeader(psMetadata *output, ///< read data to this structure - const char *extname, ///< MEF extension name ("PHU" for primary header) - int extnum, ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1) - FILE *f ///< file descriptor to read from - ); +psMetadata *psImageFReadHeader(psMetadata *output, char *extname, int extnum, FILE *f); \end{verbatim} \subsubsection{Image Pixel Manipulations} -Perform a 2-D FFT on the specified image. The returned image is of -type \code{psComplex}. -\begin{verbatim} -psImage * -psImageFFT(psImage *output, ///< Output image - const psImage *input, ///< image to FFT - int direction ///< FFT direction - ); -\end{verbatim} - Clip image values outside of range to given values. All pixels with -values $<$ min are set to the value vmin. All pixels with values $>$ -max are set to the value vmax. -\begin{verbatim} -int -psImageClip(psImage *input, ///< clip this image - float min, ///< clip pixels with values < min - float vmin, ///< set min-clipped pixels to vmin - float max, ///< clip pixels with values > max - float vmax ///< set max-clipped pixels to vmax - ); -\end{verbatim} - -Clip NaN image pixels to given value. Pixels with NaN, +Inf or -Inf -values are set to the specified value. Returns the number of clipped -pixels. -\begin{verbatim} -int -psImageClipNaN(psImage *input, ///< clip this image & target - float value ///< set nan pixels to this value - ); +values \code{< min} are set to the value \code{vmin}. All pixels with +values \code{> max} are set to the value \code{vmax}. Returns the +number of clipped pixels. +\begin{verbatim} +int psImageClip(psImage *input, float min, float vmin, float max, float vmax); +\end{verbatim} + +Clip \code{NaN} image pixels to given value. Pixels with \code{NaN}, +\code{+Inf} or \code{-Inf} values are set to the specified value. +Returns the number of clipped pixels. +\begin{verbatim} +int psImageClipNaN(psImage *input, float value); \end{verbatim} @@ -2220,16 +2138,10 @@ the \code{image} which correspond to the pixels in \code{overlay} with values derived from the values in \code{image} and \code{overlay} -based on the given operator. Valid operators are ``='' (set image -value to overlay value), ``+'' (add overlay value to image value), -``-'' (subtract overlay from image), ``*'' (multiply overlay times -image), ``/'' (divide image by overlay). -\begin{verbatim} -int -psImageOverlaySection(psImage *image, ///< input image & target - const psImage *overlay, ///< image to overlay - int x0, ///< x offset of overlay subimage - int y0, ///< y offset of overlay subimage - const char *operator ///< overlay operation - ); +based on the given operator \code{op}. Valid operators are \code{=} +(set image value to overlay value), \code{+} (add overlay value to +image value), \code{-} (subtract overlay from image), \code{*} +(multiply overlay times image), \code{/} (divide image by overlay). +\begin{verbatim} +int psImageOverlaySection(psImage *image, psImage *overlay, int x0, int y0, char *op); \end{verbatim}