Changeset 1663

Timestamp:

Aug 30, 2004, 3:32:34 PM (22 years ago)

Author:

Paul Price

Message:

Added parameters to psKernelGenerate, and synched image region
specification for psImageSubset, psImageTrim, psImageReadSection and
psImageSlice.

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (1 diff)
• psLibSDRS.tex (modified) (7 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -263 +263 @@
 \item Changed the order of some \code{psList} function arguments to
   match that of \code{psMetadata}.
-
+\item \code{psLogSetDestination} return type changed to \code{bool}.
+\item \code{psImage.nChildren} and \code{.children} changed to
+  \code{psArray *children}.
+\item Added extra input parameters to \code{psKernelGenerate}:
+  \code{psVector *tShifts} and \code{bool relative}.
+\item Synched \code{psImageSubset}, \code{psImageTrim},
+  \code{psImageReadSection} and \code{psImageSlice} to use a
+  consistent region specification: \code{x0,y0,x1,y1}, where \code{x1}
+  and \code{y1} are exclusive, and may be negative.
 \end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.95 2004-08-30 21:48:03 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.96 2004-08-31 01:32:34 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -2300 +2300 @@
 
 \begin{verbatim}
-psImage *psImageSubset(const psImage *image, int nx, int ny, int x0, int y0);
+psImage *psImageSubset(const psImage *image, int x0, int y0, int x1, int y1);
 \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{nx,ny} specify the dimensions of the
-desired subraster, and \code{x0, y0} specify the starting pixel of the
-subraster.  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}.
+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}
@@ -2340 +2344 @@
 \end{verbatim}
 Trim the specified \code{image} in-place, which involves shuffling the
-pixels around in memory.  The pixels in the region
-\code{[x0:x1,y0:y1]} (inclusive) shall consist the output image.
+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.
 
 The function shall generate an error if the specified region is
@@ -2356 +2364 @@
 } psImageCutDirection;
 
-psVector *psImageSlice(psVector *out,
-                       psVector *coords,
-                       const psImage *input,
-                       const psImage *mask,
-                       unsigned int maskVal,
-                       unsigned int x,
-                       unsigned int y,
-                       unsigned int nx,
-                       unsigned int ny,
-                       psImageCutDirection direction,
-                       const psStats *stats);
+psVector *psImageSlice(psVector *out, psVector *coords, const psImage *input,
+                       const psImage *mask, unsigned int maskVal, int x0, int y0,
+                       int x1, int y1, psImageCutDirection direction, const psStats *stats);
 \end{verbatim}
 Extract pixels from rectlinear region to a vector (array of floats).
-The output vector contains either \code{nx} or \code{ny} elements,
-based on the value of the direction: e.g., if \code{direction} is
-\code{PS_CUT_X_POS}, there are \code{nx} elements.  The input region
-is collapsed in the perpendicular direction, and each element of the
-output vectors is derived from the statistics of the pixels at that
-direction coordinate.  The statistic used to derive the output vector
-value is specified by \code{stats}.  If \code{coords} is not
-\code{NULL}, the calculated coordinates along the slice are returned
-in this vector.  Only one of the statistics choices may be specified,
-otherwise the function must return an error.  This function must be
-defined for the following types: \code{psS8}, \code{psU16},
-\code{psF32}, \code{psF64}.
+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 input region is collapsed in the direction perpendicular to that
+specified by \code{direction}, and each element of the output vectors
+is derived from the statistics of the pixels at that direction
+coordinate.  The statistic used to derive the output vector value is
+specified by \code{stats}.  If \code{coords} is not \code{NULL}, the
+calculated coordinates along the slice are returned in this vector.
+Only one of the statistics choices may be specified, otherwise the
+function must return an error.  This function must be defined for the
+following types: \code{psS8}, \code{psU16}, \code{psF32},
+\code{psF64}.
 
 \begin{verbatim}
@@ -2569 +2577 @@
 
 \begin{verbatim}
-psImage *psImageReadSection(psImage *output, int x0, int y0, int nx, int ny, int z, 
+psImage *psImageReadSection(psImage *output, int x0, int y0, int x1, int y1, int z, 
                             const char *extname, int extnum, const char *filename);
 \end{verbatim}
@@ -2575 +2583 @@
 wrapper to the FITS library function.  The input parameters allow a
 full image or a subimage to be read.  The starting pixel of the region
-is specified by \code{x,y}, while the dimensions of the requested
-region are specified by \code{nx,ny}.  A negative value for either of
-\code{nx} or \code{ny} specifies the size of the region to be read
-counting down from the end of the array.  In other words, the implied
-value of \code{nx} is:
-\begin{verbatim}
-nx = (nx > 0) ? nx : image.ncols - x + nx;
-\end{verbatim}
+is specified by \code{x0,y0}, while the upper right-hand corner of the
+requested region is specified by \code{x1,y1}.  A negative value for
+either of \code{x1} or \code{y2} specifies the size of the region to
+be read counting down from the end of the array.
+
 If the native image is a cube, the value of z specifies the requested
 slice of the image.  The data is read from the extension specified by
@@ -2971 +2976 @@
 The API shall be the following:
 \begin{verbatim}
-psKernel *psKernelGenerate(const psVector *xShifts, const psVector *yShifts);
+psKernel *psKernelGenerate(const psVector *tShifts, const psVector *xShifts,
+                           const psVector *yShifts, bool relative);
 \end{verbatim}
 
 The vectors \code{xShifts} and \code{yShifts}, which are a list of
-shifts relative to some starting point, will be supplied by the user.
-The elements of the vectors should be of an integer type; otherwise
-the values shall be truncated to integers.  The output kernel shall be
-normalized such that the sum over the kernel is unity.
-
-If the vectors are not of the same number of elements, then the
+shifts made at the times \code{tShifts}, are used to construct the
+appropriate kernel.  If \code{relative} is \code{true}, then each
+shift is to be interpreted relative the shift made before; if
+\code{relative} is \code{false}, then the shifts are to be interpreted
+relative to some starting point.  The elements of the vectors should
+be of an integer type; otherwise the values shall be truncated to
+integers.  The output kernel shall be normalized such that the sum
+over the kernel is unity.
+
+If the vectors are not all of the same number of elements, then the
 function shall generate a warning shall be generated, following which,
 the longer vector trimmed to the length of the shorter, and the