Index: /trunk/doc/pslib/ChangeLogSDRS.tex =================================================================== --- /trunk/doc/pslib/ChangeLogSDRS.tex (revision 6828) +++ /trunk/doc/pslib/ChangeLogSDRS.tex (revision 6829) @@ -1,3 +1,3 @@ -%%% $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,5 +866,5 @@ \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,3 +884,19 @@ 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} Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 6828) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 6829) @@ -1,3 +1,3 @@ -%%% $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,5 +11,5 @@ \project{Pan-STARRS Image Processing Pipeline} \organization{Institute for Astronomy} -\version{19} +\version{20} \docnumber{PSDC-430-007} @@ -50,4 +50,6 @@ 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,5 +908,5 @@ 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,4 +918,45 @@ 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,4 +2895,19 @@ \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,4 +2957,11 @@ \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,4 +2982,13 @@ 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,4 +3793,11 @@ 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,4 +4213,11 @@ 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,4 +5288,13 @@ 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,5 +5348,6 @@ 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,6 +5356,6 @@ 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,5 +5369,6 @@ const psImage *mask, psMaskType maskVal, - psRegion region, + psPlane *start, + psPlane *stop, unsigned int nSamples, psImageInterpolateMode mode); @@ -5592,4 +5691,63 @@ 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,4 +6010,83 @@ \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,4 +6346,56 @@ 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} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%