Index: trunk/doc/pslib/psLibSDRS.tex
===================================================================
--- trunk/doc/pslib/psLibSDRS.tex	(revision 3340)
+++ trunk/doc/pslib/psLibSDRS.tex	(revision 3420)
@@ -1,3 +1,3 @@
-%%% $Id: psLibSDRS.tex,v 1.184 2005-02-28 21:36:35 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.185 2005-03-15 03:00:57 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -2846,13 +2846,21 @@
 
 \begin{verbatim}
+// Transform an image --- different from current version, nothing major
+psImage *psImageTransform(psImage *output, psPixels **blankPixels, const psImage *input,
+                          const psImage *inputMask, int inputMaskVal, const psPlaneTransform *outToIn,
+			  const psRegion *region, const psPixels *pixels, psImageInterpolateMode mode,
+			  double exposedValue);
+\begin{verbatim}
 psImage *psImageTransform(psImage *output, const psImage *input, const psImage *inputMask, int inputMaskVal,
                           const psPlaneTransform *outToIn, const psImage *combineMask, int combineMaskVal);
 \end{verbatim}
 Transform the \code{input} image according the supplied
-transformation.  In the event that the \code{output} is \code{NULL},
-the smallest possible image capable of containing the entire
-transformed \code{input} image is to be returned; otherwise only the
-image size specified in the \code{output} image is to be used.  If the
-\code{inputMask} is not \code{NULL}, those pixels in the
+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}).
+
+If the \code{inputMask} is non-\code{NULL}, those pixels in the
 \code{inputMask} matching \code{inputMaskVal} are to be ignored in the
 transformation.  The \code{inputMask} must be of type \code{psU8}, and
@@ -2862,9 +2870,12 @@
 in the output image --- note that this is the reverse of what might be
 naively expected, but it is what is required in order to use
-\code{psImagePixelInterpolate}.  If \code{combineMask} is not
-\code{NULL}, then those pixels that match \code{combineMaskVal} are
-not transformed.  \code{combineMask} must be of type \code{psU8} and
-of the same size as the \code{output}, otherwise the function shall
-generate an error and return \code{NULL}.  This function must be
+\code{psImagePixelInterpolate}.  If \code{pixels} is non-\code{NULL},
+then only those pixels in the output image are transformed; otherwise,
+the entire image is generated.  The interpolation is performed using
+the specified interpolation \code{mode}.  Where a pixel in the output
+image does not correspond to a pixel in the input image (or all
+appropriate pixels in the input image are masked), the value shall be
+set to \code{exposed}, and the pixel added to the list of
+\code{blankPixels} for return to the user.  This function must be
 capable of handling the following types for the \code{input} (with
 corresponding types for the \code{output}): \code{psF32},
@@ -4875,4 +4886,25 @@
 the fit shall be rejected.
 
+\paragraph{Derivatives}
+
+In order to simply calculate which pixels in one coordinate frame
+overlap those in another coordinate frame tied by a
+\code{psPlaneTransform}, we need to calculate the derivative of a
+transformation with respect to each coordinate.
+
+\begin{verbatim}
+psPlane *psPlaneTransformDeriv(psPlane *out, const psPlaneTransform *transformation, const psPlane *coord);
+\end{verbatim}
+
+\code{psPlaneTransformDeriv} shall return the derivatives of the
+\code{transformation} at the specified coordinates, \code{coord}.
+Both the derivatives with respect to $x$ and $y$ shall be returned.
+If \code{out} is non-\code{NULL}, it shall be modified and returned;
+otherwise a new \code{psPlane} shall be allocated and returned.  In
+the event that either \code{transformation} or \code{coord} are
+\code{NULL}, the function shall generate an error and return
+\code{NULL}.
+
+
 \subsubsection{Celestial Coordinate Conversions}
 
@@ -5032,4 +5064,87 @@
 %%% Astronomical Images and Astrometry
 \include{psLibSDRS_Astrom}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Pixel Lists}
+
+Usually an image mask is the best way to carry information about what
+pixels mean what.  However, in the case where the number of pixels in
+which we are interested is limited, it is more efficient to simply
+carry a list of pixels.  An example of this is in the image
+combination code, where we want to perform an operation on a
+relatively small fraction of pixels, and it is inefficient to go
+through an entire mask image checking each pixel.
+
+\begin{verbatim}
+typedef struct {
+    psVector *x;			// x coordinate
+    psVector *y;			// y coordinate
+} psPixels;
+\end{verbatim}
+
+Of course, the size of each of the vectors should match.  In the event
+that they do not match, any function which detects the problem shall
+generate a warning and use the size of the shorter of the vectors as
+the size.  The order in which the pixels are kept is not considered
+important.
+
+\begin{verbatim}
+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}
+
+\code{psPixelsToMask} shall return an image of type U8 with the
+\code{pixels} lying within the specified \code{region} set to the
+\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
+\code{region} are \code{NULL}, the function shall generate an error
+and return \code{NULL}.
+
+\code{psMaskToPixels} shall return a \code{psPixels} consisting of the
+coordinates in the \code{mask} that match the \code{maskVal}.  The
+\code{out} pixel list shall be modified if supplied, or allocated and
+returned if \code{NULL}.  In hte event that \code{mask} is
+\code{NULL}, the function shall generate an error and return
+\code{NULL}.
+
+\begin{verbatim}
+psPixels *psPixelsConcatenate(psPixels *out, const psPixels *pixels);
+\end{verbatim}
+
+\code{psPixelsConcatenate} shall concatenate \code{pixels} onto
+\code{out}.  In the event that \code{out} is \code{NULL}, a new
+\code{psPixels} shall be allocated, and the contents of \code{pixels}
+simply copied in.  If \code{pixels} is \code{NULL}, the function shall
+generate an error and return \code{NULL}.  The function shall take
+care to ensure that there are no duplicate pixels in \code{out} (since
+the order in which the pixels are stored is not important, the values
+may be sorted, allowing the use of a faster algorithm than a linear
+scan).
+
+\begin{verbatim}
+psPixels *psPixelsTransform(psPixels *out, const psPixels *input, const psPlaneTransform *inToOut);
+\end{verbatim}
+
+\code{psPixelsTransform} shall generate a list of pixels in the output
+coordinate frame that overlap the \code{input} pixels in the input
+coordinate frame through the specified transformation, \code{inToOut}.
+Note that this is more complicated than simply transforming the
+\code{input} pixels, but requires the evaluation of the derivatives of
+the transformation in order to obtain the list of all pixels in the
+output coordinate frame that possibly overlap the pixel in the input
+coordinate frame (assuming that $x' + \Delta x' = f(x) + \Delta x
+\times \partial f(x) / \partial x$, where $x'$ is the coordinate in
+the output coordinate frame, $\Delta x'$ is the size of the region in
+the output coordinate frame in the positive direction that overlaps
+the input pixel, $x$ is the coordinate in the input coordinate frame,
+$f(x)$ is the transformation from the input to the output coordinate
+frames, and $\Delta x$ is the size of a pixel; care should be taken
+with half-pixel problems).  In the event that \code{input} or
+\code{inToOut} are \code{NULL}, the function shall generate an error
+and return \code{NULL}.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%