Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 3773) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 3774) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.208 2005-04-27 19:59:04 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.209 2005-04-27 20:30:42 eugene Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -2650,35 +2650,59 @@ listed below, and fall into several categories. +\subsubsection{Image 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; +\end{verbatim} +This structure is used in psLib as an abbreviation for the four +floats, and is defined statically. Functions which accept or return a +\code{psRegion} shall do so by value, not by pointer. + +We define two functions to set and return the value of a +\code{psRegion}. The first defines the region by the corner +coordinates. The second 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. + +\begin{verbatim} +psRegion psRegionSet (float x0, float x1, float y0, float y1); +psRegion psRegionFromString (char *region); +\end{verbatim} + +All functions which use a psRegion must interpret the definition of +$(x0,y0)$ and $(x1,y1)$ in the same way. The coordinate $(x0,y0)$ +defines the starting pixel in the region. The coordinate $(x1,y1)$ +defines the outer bound of the region. The size of the region is +$(x1-x0,y1-y1)$. If either $x1$ or $y1$ is less than or equal to 0, +the value is added to the image dimensions ($Nx + x1$). Thus a region +\code{[0:0,0:0]} refers to the full image array, while +\code{[0:-10,0:-20]} trims the last 10 colums and the last 20 rows. + \subsubsection{Image Structure Manipulation} \begin{verbatim} -psImage *psImageSubset(psImage *image, int x0, int y0, int x1, int y1); +psImage *psImageSubset(psImage *image, psRegion region); \end{verbatim} Define a subimage of the specified area of the given image. This function must raise an error if the requested subset area lies outside of the parent image and return \code{NULL}. The argument \code{image} -is the parent image, \code{x0, y0} specify the starting pixel of the -subraster, and \code{x1,y1} specify the extent of the desired -subraster. Note that the row and column of this ``upper right-hand -corner'' are \textit{NOT} included in the region. In the event that -\code{x1} or \code{y1} are negative, they shall be interpreted as -being relative to the size of the parent image in that dimension. The -entire subraster must be contained within the raster of the parent -image. Note that the \code{refCounter} for the parent should be -incremented. This function must be defined for the following types: -\code{psU8}, \code{psU16}, \code{psS8}, \code{psS16}, \code{psF32}, -\code{psF64}, \code{psC32}, \code{psC64}. - -\begin{verbatim} -psImage *psImageSubsection(psImage *image, const char *section); -\end{verbatim} -Similar to \code{psImageSubset}, but uses an image \code{section}, of -the form \code{[x1:x2,y1:y2]}. If the image section is not fully -contained within the input \code{image}, then the function shall -generate an error and return \code{NULL}. Note that the -\code{refCounter} for the parent should be incremented. This function -must be defined for the following types: \code{psU8}, \code{psU16}, -\code{psS8}, \code{psS16}, \code{psF32}, \code{psF64}, \code{psC32}, -\code{psC64}. +is the parent image, \code{region.x0, region.y0} specify the starting +pixel of the subraster, and \code{region.x1,region.y1} specify the +extent of the desired subraster. Note that the row and column of this +``upper right-hand corner'' are \textit{NOT} included in the region. +In the event that \code{x1} or \code{y1} are negative, they shall be +interpreted as being relative to the size of the parent image in that +dimension. The entire subraster must be contained within the raster +of the parent image. Note that the \code{refCounter} for the parent +should be incremented. This function must be defined for the +following types: \code{psU8}, \code{psU16}, \code{psS8}, \code{psS16}, +\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. \begin{verbatim} @@ -2694,13 +2718,14 @@ \begin{verbatim} -psImage *psImageTrim(psImage *image, int x0, int y0, int x1, int y1); +psImage *psImageTrim(psImage *image, psRegion region); \end{verbatim} Trim the specified \code{image} in-place, which involves shuffling the pixels around in memory. The region to be kept is defined by the -lower-left corner, \code{x0,y0}, and the upper-right corner, -\code{x1,y1}. Note that the row and column of the ``upper right-hand -corner'' are \textit{NOT} included in the region. In the event that -\code{x1} or \code{y1} are negative, they shall be interpreted as -being relative to the size of the parent image in that dimension. +lower-left corner, \code{region.x0,region.y0}, and the upper-right +corner, \code{region.x1,region.y1}. Note that the row and column of +the ``upper right-hand corner'' are \textit{NOT} included in the +region. In the event that \code{region.x1} or \code{region.y1} are +negative, they shall be interpreted as being relative to the size of +the parent image in that dimension. The function shall generate an error if the specified region is @@ -2724,18 +2749,19 @@ const psImage *mask, unsigned int maskVal, - int x0, int y0, int x1, int y1, + psRegion region, psImageCutDirection direction, const psStats *stats); \end{verbatim} Extract pixels from rectlinear region to a vector (array of floats). -The output vector contains either \code{x1-x0} or \code{y1-y0} -elements, based on the value of the direction: e.g., if -\code{direction} is \code{PS_CUT_X_POS}, there are \code{x1-x0} -elements. The region to be ``sliced'' is defined by the lower-left -corner, \code{x0,y0}, and the upper-right corner, \code{x1,y1}. Note -that the row and column of the ``upper right-hand corner'' are -\textit{NOT} included in the region. In the event that \code{x1} or -\code{y1} are negative, they shall be interpreted as being relative to -the size of the parent image in that dimension. +The output vector contains either \code{region.x1-region.x0} or +\code{region.y1-region.y0} elements, based on the value of the +direction: e.g., if \code{direction} is \code{PS_CUT_X_POS}, there are +\code{region.x1-region.x0} elements. The region to be ``sliced'' is +defined by the lower-left corner, \code{region.x0,region.y0}, and the +upper-right corner, \code{region.x1,region.y1}. Note that the row and +column of the ``upper right-hand corner'' are \textit{NOT} included in +the region. In the event that \code{region.x1} or \code{region.y1} +are negative, they shall be interpreted as being relative to the size +of the parent image in that dimension. The input region is collapsed in the direction perpendicular to that @@ -2758,21 +2784,18 @@ const psImage *mask, unsigned int maskVal, - float x0, - float y0, - float x1, - float y1, + psRegion region, unsigned int nSamples, psImageInterpolateMode mode); \end{verbatim} -Extract pixels along a line segment, \code{(x0,y0)} to \code{(x1,y1)}, -on the image to a vector of the same data type. The line segment is -sampled \code{nSamples} times, hence the output vector contains -\code{nSamples} elements. The interpolation method used to derive the -output vector value at each sample along the line segment is specified -by \code{mode}. If the \code{mask} is non-\code{NULL}, then pixels -for which the corresponding mask value is \code{maskVal} are not -included in the interpolation. This function must be defined for the -following types: \code{psS8}, \code{psU16}, \code{psF32}, -\code{psF64}. +Extract pixels along a line segment, \code{(region.x0,region.y0)} to +\code{(region.x1,region.y1)}, on the image to a vector of the same +data type. The line segment is sampled \code{nSamples} times, hence +the output vector contains \code{nSamples} elements. The +interpolation method used to derive the output vector value at each +sample along the line segment is specified by \code{mode}. If the +\code{mask} is non-\code{NULL}, then pixels for which the +corresponding mask value is \code{maskVal} are not included in the +interpolation. This function must be defined for the following types: +\code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}. \begin{verbatim} @@ -2901,7 +2924,13 @@ \begin{verbatim} -psImage *psImageTransform(psImage *output, psArray **blankPixels, const psImage *input, - const psImage *inputMask, int inputMaskVal, const psPlaneTransform *outToIn, - const psRegion *region, const psPixels *pixels, psImageInterpolateMode mode, +psImage *psImageTransform(psImage *output, + psArray **blankPixels, + const psImage *input, + const psImage *inputMask, + int inputMaskVal, + const psPlaneTransform *outToIn, + const psRegion region, + const psPixels *pixels, + psImageInterpolateMode mode, double exposedValue); \end{verbatim} @@ -2909,7 +2938,7 @@ transformation. The size of the transformed image is defined by the supplied \code{output} image, if non-\code{NULL}, or the \code{region} -otherwise (size \code{region->x1 - region->x0} by \code{region->y1 - -region->y0}, with \code{out->x0 = region->x0} and \code{out->y0 = -region->y0}). +otherwise (size \code{region.x1 - region.x0} by \code{region.y1 - +region.y0}, with \code{out->x0 = region.x0} and \code{out->y0 = +region.y0}). If the \code{inputMask} is non-\code{NULL}, those pixels in the @@ -3117,5 +3146,5 @@ \begin{verbatim} -psImage *psPixelsToMask(psImage *out, const psPixels *pixels, const psRegion *region, unsigned int maskVal); +psImage *psPixelsToMask(psImage *out, const psPixels *pixels, const psRegion region, unsigned int maskVal); psPixels *psMaskToPixels(psPixels *out, const psImage *mask, unsigned int maskVal); \end{verbatim} @@ -3125,7 +3154,7 @@ \code{maskVal}. The \code{out} image shall be modified if supplied, or allocated and returned if \code{NULL}. The size of the output -image shall be \code{region->x1 - region->x0} by \code{region->y1 - -region->y0}, with \code{out->x0 = region->x0} and \code{out->y0 = -region->y0}. In the event that either of \code{pixels} or +image shall be \code{region.x1 - region.x0} by \code{region.y1 - +region.y0}, with \code{out->x0 = region.x0} and \code{out->y0 = +region.y0}. In the event that either of \code{pixels} or \code{region} are \code{NULL}, the function shall generate an error and return \code{NULL}. @@ -3159,25 +3188,4 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\subsection{Image 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{Vector and Image Arithmetic} @@ -5145,7 +5153,7 @@ \begin{verbatim} psPlaneTransform *psPlaneTransformInvert(psPlaneTransform *out, const psPlaneTransform *in, - psRegion *region, int nSamples); + psRegion region, int nSamples); psPlaneTransform *psPlaneTransformCombine(psPlaneTransform *out, const psPlaneTransform *trans1, - const psPlaneTransform *trans2, psRegion *region, + const psPlaneTransform *trans2, psRegion region, int nSamples); bool psPlaneTransformFit(psPlaneTransform *trans, const psArray *source, const psArray *dest,