Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 6434) +++ trunk/doc/pslib/psLibSDRS.tex (revision 6455) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.383 2006-02-16 18:57:51 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.384 2006-02-22 00:02:00 eugene Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -11,5 +11,5 @@ \project{Pan-STARRS Image Processing Pipeline} \organization{Institute for Astronomy} -\version{18} +\version{19} \docnumber{PSDC-430-007} @@ -2987,6 +2987,5 @@ abbreviate \code{STRING}; valid time types are \code{UTC,UT1,TAI,TT}. -\tbd{May, in the future, require more types, including U8,S16,C64, -which will also necessitate updating the definition of psMetadata.} +\tbd{May, in the future, require more types, including U8,S16,C64.} The value shall follow the type: strings may consist of multiple words, and @@ -3252,6 +3251,5 @@ double psLookupTableInterpolate(const psLookupTable *table, double index, long column); -psVector *psLookupTableInterpolateAll(const psLookupTable *table, - double index, psVector *stats); +psVector *psLookupTableInterpolateAll(const psLookupTable *table, double index); \end{prototype} Both functions shall interpolate the \code{table} at the provided @@ -3261,6 +3259,4 @@ and returned as a \code{psVector}, the type of which shall be \code{PS_TYPE_F64}. - -\tbd{What's the stats for???} If the \code{index} is beyond the range of the \code{table}, @@ -5095,6 +5091,4 @@ \subsubsection{Image Structure Manipulation} -\tbd{clarify that subset and trim regions are in the *parent* coords} - \begin{prototype} psImage *psImageSubset(psImage *image, psRegion region); @@ -5107,14 +5101,17 @@ 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. If the input image is a subimage, the region coordinates -refer to the \em{parent} pixel coordinates. 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}. \tbd{allow this function to saturate on the edges like -psRegionForImage?} +Note that, if the \code{image} is itself a subimage, then the +\code{region} coordinates correspond to coordinates of the parent +image of \code{image}. The only exception to this is in the event +that \code{x1} or \code{y1} are non-positive, in which case they shall +be interpreted as being relative to the upper-bounds of \code{image} +in that dimension. The entire resulting subraster will be contained +within the raster of the input image; if the requested bounds of +region fall beyond the bounds of the input image, they should saturate +on the input image region (in analogy with the behavior of +\code{psRegionForImage}). 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{prototype} @@ -5138,8 +5135,9 @@ 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. \tbd{how is region interpreted if -image is a subimage?} +region. Note that, if the \code{image} is itself a subimage, then the +\code{region} coordinates correspond to coordinates of the parent +image of \code{image}. However, in the event that \code{region.x1} or +\code{region.y1} are negative, they shall be interpreted as being +relative to the upper bounds of the input image in that dimension. The function shall generate an error if the specified region is @@ -5149,6 +5147,4 @@ \subsubsection{Image Pixel Extractions} - -\tbd{clarify that subset and trim regions are in the *parent* coords} \begin{datatype} @@ -5172,7 +5168,9 @@ These two functions extract a single complete \code{row} or \code{column} from the \code{image} and return it to the provided -\code{vector}, allocating it if it is \code{NULL}. These are provided -as fast, simple implementations of data extraction. For more -sophisticated operations, the following two functions should be used. +\code{vector}, allocating it if it is \code{NULL}. If the input image +is a subimage, the \code{row} and \code{column} arguments refer to +parent coordinates. These are provided as fast, simple +implementations of data extraction. For more sophisticated +operations, the following two functions should be used. \begin{prototype} @@ -5186,7 +5184,7 @@ const psStats *stats); \end{prototype} -Extract pixels from rectilinear region to a vector (array of floats). -The output vector contains either \code{region.x1-region.x0} or -\code{region.y1-region.y0} elements, based on the value of the +Extract pixels from a rectilinear region to a vector (array of +floats). 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 @@ -5196,6 +5194,6 @@ 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. \tbd{how is region interpreted - if input is a subimage?} +of the input image in that dimension. If the input image is a +subimage, the \code{region} argument refers to parent coordinates. The input region is collapsed in the direction perpendicular to that @@ -5226,5 +5224,6 @@ \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 +the output vector contains \code{nSamples} elements. If the input image is a +subimage, the \code{region} argument refers to parent coordinates. The interpolation method used to derive the output vector value at each sample along the line segment is specified by \code{mode}. If the @@ -5232,6 +5231,5 @@ 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}. \tbd{how is -region interpreted if input is a subimage?} +\code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}. \begin{prototype} @@ -5249,13 +5247,14 @@ which land within one of a sequence of radii. The radii are centered on the image pixel coordinate \code{x,y}, and are defined by the -sequence of values in the vector \code{radii}. The specific algorithm -which must be used is described in the PSLib ADD (PSDC-430-006). The -statistic used to derive the output vector value is specified by -\code{stats}. Only one of the statistics choices may be specified, -otherwise the function must return an error. If \code{mask} is -non-\code{NULL}, pixels for which the corresponding \code{mask} pixel -matches \code{maskVal} are excluded from operations. This function -must be defined for the following types: \code{psS8}, \code{psU16}, -\code{psF32}, \code{psF64}. +sequence of values in the vector \code{radii}. If the input image is +a subimage, the \code{x,y} arguments refer to parent coordinates. The +specific algorithm which must be used is described in the PSLib ADD +(PSDC-430-006). The statistic used to derive the output vector value +is specified by \code{stats}. Only one of the statistics choices may +be specified, otherwise the function must return an error. If +\code{mask} is non-\code{NULL}, pixels for which the corresponding +\code{mask} pixel matches \code{maskVal} are excluded from operations. +This function must be defined for the following types: \code{psS8}, +\code{psU16}, \code{psF32}, \code{psF64}. \subsubsection{Image Geometry Manipulation} @@ -5375,5 +5374,6 @@ \code{region} (size \code{region.x1 - region.x0} by \code{region.y1 - region.y0}, with \code{out->x0 = region.x0} and \code{out->y0 = -region.y0}). \tbd{is this subimage-safe} +region.y0}). If the input image is itself a subimage, then the region +refers to the parent image coordinates. If the \code{inputMask} is non-\code{NULL}, those pixels in the @@ -5569,5 +5569,7 @@ 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}. \tbd{is this subimage-safe?} +and return \code{NULL}. If \code{out} is not supplied, then the +constructed image is not a subimage. If \code{out} is supplied and is +a subimage, the pixels refer to the parent image coordinates. \code{psMaskToPixels} shall return a \code{psPixels} containing the @@ -5576,5 +5578,6 @@ returned if \code{NULL}. In the event that \code{mask} is \code{NULL}, the function shall generate an error and return -\code{NULL}. +\code{NULL}. If \code{mask} is a subimage, the pixels refer to the +parent image coordinates. \begin{prototype} @@ -5591,5 +5594,6 @@ by combining the existing pixel value and the given \code{maskValue} with a logical operation. The allowed operations are \code{=}, -\code{AND}, \code{OR} and \code{XOR}. \tbd{is this subimage-safe?} +\code{AND}, \code{OR} and \code{XOR}. If \code{image} is a subimage, +the region refers to the parent image coordinates. \begin{prototype} @@ -5609,5 +5613,6 @@ pixel value and the given \code{maskValue} with a logical operation. The allowed operations are \code{=}, \code{AND}, \code{OR} and -\code{XOR}. +\code{XOR}. If \code{image} is a subimage, the coordinates refers to +the parent image coordinates. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%