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

Timestamp:

Apr 27, 2005, 10:30:42 AM (21 years ago)

Author:

eugene

Message:

final for cycle 6, includes changes for psRegion

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +2650 @@
 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 +2718 @@
 
 \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 +2749 @@
                        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 +2784 @@
                      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 +2924 @@
 
 \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 +2938 @@
 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 +3146 @@
 
 \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 +3154 @@
 \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 +3188 @@
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\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 +5153 @@
 \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,