Changeset 6829

Timestamp:

Apr 11, 2006, 11:24:07 AM (20 years ago)

Author:

eugene

Message:

added new functions created for psModules

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (3 diffs)
• psLibSDRS.tex (modified) (17 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.201 2006-04-04 03:30:29 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.202 2006-04-11 21:24:07 eugene Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -866 +866 @@
 \end{itemize}
 
-\subsection{Changes from Revistion 19 (21 Feb 2006) to Revision 20 (?? ??? 2006)}
+\subsection{Changes from Revistion 19 (21 Feb 2006) to Revision 20 (11 Apr 2006)}
 
 \begin{itemize}
@@ -884 +884 @@
   psFitsWriteTable}.  Added \code{psFitsHeaderFromImage,
   psFitsHeaderFromTable}.  See bug 733.
-\end{itemize}
+
+\item Added \code{psLine} functions
+\item Added \code{psEllipse} functions
+\item Added \code{psStringSplit}
+\item Added \code{psStringStrip}
+\item Added \code{psMetadataPrint} % added FILE *
+\item Added \code{psMetadataItemTransfer}
+\item Added \code{psFitsWriteHeaderNotImage}
+\item Added \code{psImageFlip} % x and y in same function
+\item Added \code{psImageJpeg} functions
+\item Added \code{psMetadataItemParse} functions
+\item Added \code{psImageBicube} functions
+\item Added \code{psRegionIsBad}
+\item Added \code{psRegionIsNaN}
+\item Added \code{psSparse} functions.
+
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.390 2006-04-04 03:29:03 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.391 2006-04-11 21:24:07 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -11 +11 @@
 \project{Pan-STARRS Image Processing Pipeline}
 \organization{Institute for Astronomy}
-\version{19}
+\version{20}
 \docnumber{PSDC-430-007}
 
@@ -50 +50 @@
 17 & 2005 Oct 18 & draft for cycle 9 \\ \hline
 18 & 2005 Dec 06 & draft for cycle 10 \\ \hline
+19 & 2005 Feb 21 & draft for cycle 11 \\ \hline
+20 & 2005 Apr 11 & draft for cycle 12 \\ \hline
 \RevisionsEnd
 
@@ -906 +908 @@
 similarly, except it shall prepend to the \code{dest} string.
 
-A further useful function is:
+Other string manipulation functions are listed below.
 
 \begin{prototype}
@@ -916 +918 @@
 one of the characters in \code{splitters}.  Split strings of zero
 length should not be included in the output list.
+
+String whitespace from head and tail of string:
+\begin{prototype}
+int psStringStrip (char *string);
+\end{prototype}
+
+\subsubsection{Fixed-Length Lines}
+
+We define the \code{psLine} structure to carry a pre-allocated block
+to store a character string.  The interfaces are similar to
+\code{psString}, but allow for the container to be allocated initially
+upfront with a specified length.  They are used to force a
+fixed-length line.
+
+\begin{datatype}
+// structure to carry a dynamic string
+typedef struct {
+    int NLINE;                  // allocated length
+    int Nline;                  // current lenght
+    char *line;                 // character string data
+} psLine;
+\end{datatype}
+
+The following function allocates a line object of length Nline.
+\begin{prototype}
+psLine *psLineAlloc (int Nline);
+\end{prototype}
+
+The following function initializes or re-initializes the line, setting
+the current length to zero and setting the string data values to 0.
+If the function is passed \code{NULL}, the function returns \code{false}.
+\begin{prototype}
+bool psLineInit (psLine *line);
+\end{prototype}
+
+The following function appends a line segment to the string, returning
+\code{false} if the new segment would overflow the allocated string
+length.
+\begin{prototype}
+bool psLineAdd (psLine *line, char *format, ...);
+\end{prototype}
 
 \subsubsection{Type information}
@@ -2852 +2895 @@
 \end{prototype}
 
+The following utility functions simplify further the selection of
+elements from the metadata.  These functions convert the data
+associated with the supplied metadata item to the desired type if
+possible. Conversions between types are performed as needed, and
+default values are returned for the integer and floating point types
+if the data is not available (0 for int, \code{NaN} for float).
+
+\begin{prototype}
+psF32 psMetadataItemParseF32(psMetadataItem *item);
+psF64 psMetadataItemParseF64(psMetadataItem *item);
+psS32 psMetadataItemParseS32(psMetadataItem *item);
+psString psMetadataItemParseString(psMetadataItem *item);
+\end{prototype}
+
+
 Items may be retrieved from the metadata by their entry position.  The
 value of which specifies the desired entry in the fashion of
@@ -2899 +2957 @@
 \end{prototype}
 
+A complete metadata structure may be printed to the given file
+descriptor with the following command, where the level represents the
+desired indentation
+\begin{prototype}
+bool psMetadataPrint(FILE *fd, const psMetadata *md, int level);
+\end{prototype}
+
 There will be occasions when we want to perform a deep copy of a
 \code{psMetadata}, for example, to generate a new and independent FITS
@@ -2917 +2982 @@
 the \code{out} metadata, or a new \code{psMetadata} if \code{out} is
 \code{NULL}.
+
+The following functio copies a single metadata item from one
+psMetadata to another:
+\begin{prototype}
+bool psMetadataItemTransfer (psMetadata *out, // Destination: copy is placed here
+                             psMetadata *in,  // Source: item comes from here
+                             char *key        // key to identify the metadata item
+    );
+\end{prototype}
 
 \subsubsection{Configuration files}
@@ -3719 +3793 @@
 The width of the square is thus \code{2radius + 1}.
 
+The following fucntions provide tests of the validity of
+\code{regions}
+\begin{prototype}
+bool psRegionIsBad(psRegion region);
+bool psRegionIsNaN (psRegion region);
+\end{prototype}
+
 \pagebreak 
 
@@ -4132 +4213 @@
 Write metadata into the header of a FITS image file.  The header is
 written at the current HDU.
+
+\begin{prototype}
+bool psFitsWriteHeaderNotImage(psFits *fits, const psMetadata *header);
+\end{prototype}
+This function creates a header for a 0 length image.  The resulting
+header shall have \code{NAXIS = 0}.  Any \code{NAXISi} elements
+present in the header shall be maintained as reference data.
 
 \begin{prototype}
@@ -5200 +5288 @@
 place.
 
+The following function flips the given image in the x and/or y
+direction.  Note that a request for both an x and a y flip is
+identical to a 180\degree\ rotation.
+\begin{prototype}
+psImage *psImageFlip(psImage *image,  // Image to flip
+                     bool xFlip,
+                     bool yFlip);
+\end{prototype}
+
 \subsubsection{Image Pixel Extractions}
 
@@ -5251 +5348 @@
 subimage, the \code{region} argument refers to parent coordinates.
 
-The input region is collapsed in the direction perpendicular to that
+The pixel region defined by the coordinate pair \code{start} \&
+\code{stop} 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
@@ -5258 +5356 @@
 for which the corresponding \code{mask} pixel matches \code{maskVal}
 are excluded from operations.  If \code{coords} is not \code{NULL},
-the calculated coordinates along the slice are returned in this
-array of pixels.  Only one of the statistics choices may be specified,
+the calculated coordinates along the slice are returned in this array
+of pixels.  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},
@@ -5271 +5369 @@
                      const psImage *mask, 
                      psMaskType maskVal,
-                     psRegion region,
+                     psPlane *start,
+                     psPlane *stop,
                      unsigned int nSamples, 
                      psImageInterpolateMode mode);
@@ -5592 +5691 @@
 datatype.  The return value shall be the number of pixels overlaid.
 
+\subsubsection{Image Local Bicube}
+
+The following functions provide interpolations of image data values
+based on bicubic interpolation.
+
+This function fits a 2D 2nd order polynomial to the 9 pixels centered
+on the coordinate x,y.
+\begin{prototype}
+psPolynomial2D *psImageBicubeFit (psImage *image, int x, int y);
+\end{prototype}
+
+This function detemines the min (or max) of the special 2D 2nd order
+polynomial representing the fit to 9 pixels of an image.
+\begin{prototype}
+psPlane psImageBicubeMin (psPolynomial2D *poly);
+\end{prototype}
+
+\subsubsection{JPEG operations}
+
+The following functions and structures are used to convert an image in
+memory to a output JPEG file.  These functions allow the user to
+define a color map (from a list of predefined color maps) and to
+define the dynamic range of the translation from data values to JPEG
+color values.  
+
+The representation of a JPEG colormap is given by the following structure:
+\begin{datatype}
+typedef struct {
+    psString name;
+    psVector *red;
+    psVector *green;
+    psVector *blue;
+} psImageJpegColormap;
+\end{datatype}
+The colormap is just a translation from a \code{psImage} data value to
+a JPEG image data value.  The colormap may be used to construct either
+single channel or multichannel images.
+
+The following function allocates, but does not specify, a JPEG colormap:
+\begin{prototype}
+psImageJpegColormap *psImageJpegColormapAlloc ();
+\end{prototype}
+
+The following function sets the colormap values based on the named
+colormap.  Currently defined colormaps have the names \code{greyscale}
+(or \code{grayscale}), \code{-grayscale} (or \code{-greyscale}),
+\code{rainbow}, \code{heat}.
+\begin{prototype}
+psImageJpegColormap *psImageJpegColormapSet (psImageJpegColormap *map, char *name);
+\end{prototype}
+
+The following function writes out the specified image as a JPEG file
+using the supplied colormap.  The output goes to the specified
+filename.  This function performs a single-channel JPEG conversion
+(the values of the single image determine the colors).
+\begin{prototype}
+bool psImageJpeg (psImageJpegColormap *map, psImage *image, char *filename, float min, float max);
+\end{prototype}
+
 \subsubsection{Mask operations}
 
@@ -5852 +6010 @@
 \end{prototype}
 
+\subsubsection{Sparse Matrices}
+
+Very large matrices (N elements $> 1000$) can be very time consuming
+to manipulate.  A certain class of matrices, sparse matrices, are
+amenable to iterative solutions even when extremely large (100,000s of
+elements).  The following functions define structures to efficiently
+represent sparse matricies, to add elements to those matrices, and to
+perform linear algebra with them. 
+
+\begin{datatype}
+typedef struct {
+    psVector *Aij;
+    psVector *Bfj;
+    psVector *Qii;
+    psVector *Si;
+    psVector *Sj;
+    int Nelem;
+    int Nrows;
+} psSparse;
+\end{datatype}
+
+The above structure contains the following elements, describing a
+sparse matrix equation of the form $A \bar{x} = \bar{Bf}$:
+\begin{itemize}
+\item the vector \code{Aij} contains the populated elements of the matrix
+\item the vector \code{Bfj} contains the elements of the vector Bf
+\item the vector \code{Qii} contains the diagonal elements of Aij
+\item the vector \code{Si} contains the i-index values of Aij
+\item the vector \code{Sj} contains the j-index values of Aij
+\item the element \code{Nelem} defines the total number of elements in
+matrix \code{Aij}
+\item the element \code{Nrows} defines the size of the matrix \code{Aij}
+\end{itemize}
+
+The following structure defines constraints to limit the range of the
+value matrix equation solution:
+\begin{datatype}
+typedef struct {
+    double paramDelta;
+    double paramMin;
+    double paramMax;
+} psSparseConstraint;
+\end{datatype}
+
+The following function allocates a sparse matrix structure:
+\begin{prototype}
+psSparse *psSparseAlloc (int Nrows, int Nelem);
+\end{prototype}
+
+The following function adds a new matrix element.  The user should
+only add elements above the diagonal.
+\begin{prototype}
+void psSparseMatrixElement (psSparse *sparse, int i, int j, float value);
+\end{prototype}
+
+The following function define a new sparse matrix equation vector element:
+\begin{prototype}
+void psSparseVectorElement (psSparse *sparse, int i, float value);
+\end{prototype}
+
+The following function performs the operation ``matrix times vector''
+on a sparse matrix and a vector:
+\begin{prototype}
+psVector *psSparseMatrixTimesVector (psVector *output, psSparse *matrix, psVector *vector);
+\end{prototype}
+
+The following function re-sorts a sparse matrix to have all elements
+in index order rather than insertion order.  The user must call this
+function before attempting to solve, but after populating, the matrix and vector:
+\begin{prototype}
+void psSparseResort (psSparse *sparse);
+\end{prototype}
+
+The following function iteratively solves the equation $A \bar{x} =
+\bar{Bf}$.  For the value of $\bar{x}$, a good starting guess is the vector $\bar{Bf}$
+\begin{prototype}
+psVector *psSparseSolve (psVector *guess, psSparseConstraint constraint, psSparse *sparse, int Niter);
+\end{prototype}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -6109 +6346 @@
 Poisson distribution with the given \code{mean} using
 \code{gsl_ran_poisson}.
+
+\subsection{Ellipse Shape Functions}
+
+Astronomical objects are frequently decomposed into components
+represented by a radial function modified by an elliptical contour.
+There are a few ways in which the elliptical shape information can be
+represented depending on the circumstance in which it is used.  The
+structures and functions in the section provide tools for converting
+between the elliptical representations.  We provide three structures
+representing three ways in which the elliptical shape is represented.
+Like the \code{psRegion}, these datatypes and their supporting
+functions do not use allocators.
+
+This structure represents an ellipse by its major and minor axis
+lengths and the orientation angle.
+\begin{datatype}
+typedef struct {
+    double major;
+    double minor;
+    double theta;
+} psEllipseAxes;
+\end{datatype}
+
+This structure represents an elliptical Gaussian by the second moments
+measured for that Gaussian.  
+\begin{datatype}
+typedef struct {
+    double x2;
+    double y2;
+    double xy;
+} psEllipseMoments;
+\end{datatype}
+
+This structure represents an ellipse by the components of the
+cartesian coordiante equation: $(s_x x)^2 + (s_y y)^2 + s_{x,y} x y =
+R$
+\begin{datatype}
+typedef struct {
+    double sx;
+    double sy;
+    double sxy;
+} psEllipseShape;
+\end{datatype}
+
+The following functions provide conversions between the elliptical
+shape representations:
+
+\begin{prototype}
+psEllipseAxes psEllipseMomentsToAxes (psEllipseMoments moments);
+psEllipseShape psEllipseAxesToShape (psEllipseAxes axes);
+psEllipseAxes psEllipseShapeToAxes (psEllipseShape shape);
+\end{prototype}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%