Changeset 6455 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

Feb 21, 2006, 2:02:00 PM (20 years ago)

Author:

eugene

Message:

minor mods to changes

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (20 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +11 @@
 \project{Pan-STARRS Image Processing Pipeline}
 \organization{Institute for Astronomy}
-\version{18}
+\version{19}
 \docnumber{PSDC-430-007}
 
@@ -2987 +2987 @@
 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 +3251 @@
 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 +3259 @@
 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 +5091 @@
 \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 +5101 @@
 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 +5135 @@
 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 +5147 @@
 
 \subsubsection{Image Pixel Extractions}
-
-\tbd{clarify that subset and trim regions are in the *parent* coords}
 
 \begin{datatype}
@@ -5172 +5168 @@
 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 +5184 @@
                        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 +5194 @@
 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 +5224 @@
 \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 +5231 @@
 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 +5247 @@
 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 +5374 @@
 \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 +5569 @@
 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 +5578 @@
 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 +5594 @@
 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 +5613 @@
 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.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%