Changeset 3420

Timestamp:

Mar 14, 2005, 5:00:57 PM (21 years ago)

Author:

Paul Price

Message:

Added psPixels structure, psPixelsToMask, psMaskToPixels,
psPixelsConcatenate and psPixelsTransform. Modified psImageTransform
in preparation for image combination. Added psPlaneTransformDeriv.

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (2 diffs)
• psLibSDRS.tex (modified) (5 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.72 2005-02-28 21:37:15 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.73 2005-03-15 03:00:52 price Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -481 +481 @@
   from a file.
 \item \code{psMetadataAddV} changed to use \code{va_list} parameter (bug 312).
-\end{itemize}
+\item Added \code{psPixels} structure, \code{psPixelsToMask},
+  \code{psMaskToPixels}, \code{psPixelsConcatenate} and
+  \code{psPixelsTransform}.
+\item Modified \code{psImageTransform} in preparation for image combination.
+\item Added \code{psPlaneTransformDeriv}.
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +2846 @@
 
 \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 +2870 @@
 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 +4886 @@
 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 +5064 @@
 %%% 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}.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%