Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 4166) +++ trunk/doc/pslib/psLibSDRS.tex (revision 4178) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.270 2005-06-09 00:40:48 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.271 2005-06-09 05:16:41 eugene Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -831,13 +831,16 @@ % \begin{prototype} -void psTrace(const char *facil, int level,...); +void psTrace(const char *facil, int level, const char *fmt,...); +void psTraceV(const char *facil, int level, const char *fmt, va_list ap); \end{prototype} % -where the last argument is a printf-style formatting code and possible -arguments to that formatting statement, to be implemented using the -\code{vprintf} functions. This command specifies the name of the -facility to which the message belongs (\code{facil}), the trace level -for this message in that facility (\code{level}) and the message -itself. +where the \code{fmt} argument is a printf-style formatting code +followed by possible arguments to that formatting statement, to be +implemented using the \code{vprintf} functions. This command +specifies the name of the facility to which the message belongs +(\code{facil}), the trace level for this message in that facility +(\code{level}) and the message itself. The \code{psTraceV} version of +the command accepts a \code{va_list} argument list rather than a +variable number of arguments. The trace level for any facility may be set at any time with the @@ -929,12 +932,64 @@ functions, effectively resetting all trace levels to 0. - -The trace may optionally be written to a file on specifying a filename -with \code{psTraceSetDestination}: -\begin{prototype} -void psTraceSetDestination(FILE *fp); -\end{prototype} -If the \code{fp} is \code{NULL}, then the trace is sent to standard -output, otherwise it is sent to the specified file pointer. +The trace may optionally be written to a file or other output +destination with \code{psTraceSetDestination}: +\begin{prototype} +void psTraceSetDestination(int fd); +\end{prototype} +If the \code{fd} is 0, then the trace is sent to standard output, +otherwise it is sent to the specified file descriptor. A call to +\code{psTraceSetDestination} automatically closes the file descriptor. + +The corresponding function +\begin{prototype} +int psTraceGetDestination(); +\end{prototype} +returns the current trace destination file descriptor. If the +destination has not been defined by the user, the descriptor for +\code{stdout} is returned. + +The trace output format is controlled with the function: +% +\begin{prototype} +bool psTraceSetFormat(const char *fmt); +\end{prototype} +% +which expects a string consisting of the letters \code{H} (host), +\code{L} (level), \code{M} (message), \code{N} (name), and \code{T} +(time). The default is \code{THLNM}, which produces trace messages in +the form: +\begin{verbatim} +YYYY-MM-DD hh:mm:ssZ | hostname | L | name + The message goes here + and is indented by 4 spaces. +\end{verbatim} +where \code{YYYY}, \code{MM}, \code{DD}, \code{hh}, \code{mm}, and +\code{ss} are the year, month (Jan is 01), day of the month, hours +(0--23), minutes, and seconds when the trace message was received. Note +that the timestamp is in ISO order, and that the timezone is GMT +(hence the \code{Z}). The \code{hostname} is returned by +\code{gethostname}, \code{L} is a character associated with the level +(\code{A}, \code{E}, \code{W}, and \code{I} for \code{PS_LOG_ABORT}, +\code{PS_LOG_ERROR}, \code{PS_LOG_WARN}, and \code{PS_LOG_INFO} +respectively. Other levels are represented numerically (\code{5} +etc.). The other two fields, \code{facil} and \code{msg}, are the +arguments to \code{psTrace}. The \code{msg} is placed on a new line +(allowing the \code{name} to fill the rest of the previous line), +with each line indented by 4 spaces. An example message is: +% +\begin{verbatim} +2004:02:24 20:14:18Z | alibaba.IfA.Hawaii.Edu | I | example.utils.helloWorld + Hello world, + it's me calling. +\end{verbatim} +% +The possible order of the format entries is fixed and not determined +by the order of the letters used in \code{psTraceSetFormat}. Selecting +an output format with fewer than the complete set of 5 entries simply +removes those entries from the output messages. + +Specifying a \code{fmt} of \code{NULL} turns off logging (equivalent +to calling \code{psLogSetDestination(PS_LOG_TO_NONE)}, whereas if the +\code{fmt} is \code{""}, then the format reverts to the default. \subsubsection{Message Logging} @@ -993,16 +1048,19 @@ % \begin{prototype} -bool psLogSetDestination(const char *dest); -\end{prototype} -% -The destination string consists of a URL in the form -\code{protocol:location}. The \code{protocol} value may be -\code{file}, to send the log to a local file named by the value of -\code{location}. Future expansion may allow the logger to send -messages to an IP logger, with a protocol to be defined later. Three -other special values are allowed for the \code{dest} parameter -(without specifying a protocol): \code{stderr} and \code{stdout}, -which write to \code{stderr} and \code{stdout} respectively, and -\code{none} to turn off logging. +bool psLogSetDestination(int fd); +\end{prototype} +% +If the \code{fd} is 0, then the log is sent to standard output, +otherwise it is sent to the specified file descriptor. A call to +\code{psLogSetDestination} automatically closes an open file +descriptor. + +The corresponding function +\begin{prototype} +int psLogGetDestination(); +\end{prototype} +returns the current log destination file descriptor. If the +destination has not been defined by the user, the descriptor for +\code{stdout} is returned. The output format is controlled with the function: @@ -1049,4 +1107,21 @@ to calling \code{psLogSetDestination(PS_LOG_TO_NONE)}, whereas if the \code{fmt} is \code{""}, then the format reverts to the default. + +The following utility opens an output file descriptor for use by the +trace and log facilities. +\begin{prototype} +int psMessageDestination (const char *dest); +\end{prototype} +% +The destination string consists of a URL in the form +\code{protocol:location}. The \code{protocol} value may be +\code{file}, to send the log to a local file named by the value of +\code{location}. Future expansion may allow the logger to send +messages to an IP logger, with a protocol to be defined later. Three +other special values are allowed for the \code{dest} parameter +(without specifying a protocol): \code{stderr} and \code{stdout}, +which return the file descriptors for \code{stderr} and \code{stdout} +respectively, and \code{none} which returns the special descriptor to +turn off logging. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1660,4 +1735,78 @@ output of this function is a region with negative upper limits replaced by their corrected value appropriate to the given image. + +\subsubsection{Image 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{datatype} +typedef struct { + int x; // x coordinate + int y; // y coordinate +} psPixelCoord; + +typedef struct { + psU32 n; // Number in use + const psU32 nalloc; // Number allocated + psPixelCoord *data; // The pixel coordinates +} psPixels; +\end{datatype} + +\begin{prototype} +psPixels *psPixelsAlloc(psU32 nalloc); +psPixels *psPixelsRealloc(psPixels *pixels, psU32 nalloc); +\end{prototype} + +\code{psPixelsAlloc} and \code{psPixelsRealloc} provide dynamic +allocation and reallocation in a manner analogous to those provided +by \code{psVectorAlloc} and \code{psVectorRealloc}. + +\begin{prototype} +psImage *psPixelsToMask(psImage *out, const psPixels *pixels, psRegion region, unsigned int maskVal); +psPixels *psPixelsFromMask(psPixels *out, const psImage *mask, unsigned int maskVal); +\end{prototype} + +\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} containing 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 the event that \code{mask} is +\code{NULL}, the function shall generate an error and return +\code{NULL}. + +\begin{prototype} +psPixels *psPixelsCopy(psPixels *out, const psPixels *pixels); +psPixels *psPixelsConcatenate(psPixels *out, const psPixels *pixels); +\end{prototype} + +\code{psPixelsCopy} shall copy the contents of \code{pixels} to the +\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}. + +\code{psPixelsConcatenate} shall concatenate the \code{pixels} onto +\code{out}. In the event that \code{out} is \code{NULL}, the function +performs a \code{psPixelsCopy}, returning the copy. 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). \subsection{Math Casting} @@ -4620,80 +4769,4 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Image 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{datatype} -typedef struct { - int x; // x coordinate - int y; // y coordinate -} psPixelCoord; - -typedef struct { - psU32 n; // Number in use - const psU32 nalloc; // Number allocated - psPixelCoord *data; // The pixel coordinates -} psPixels; -\end{datatype} - -\begin{prototype} -psPixels *psPixelsAlloc(psU32 nalloc); -psPixels *psPixelsRealloc(psPixels *pixels, psU32 nalloc); -\end{prototype} - -\code{psPixelsAlloc} and \code{psPixelsRealloc} provide dynamic -allocation and reallocation in a manner analogous to those provided -by \code{psVectorAlloc} and \code{psVectorRealloc}. - -\begin{prototype} -psImage *psPixelsToMask(psImage *out, const psPixels *pixels, psRegion region, unsigned int maskVal); -psPixels *psPixelsFromMask(psPixels *out, const psImage *mask, unsigned int maskVal); -\end{prototype} - -\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} containing 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 the event that \code{mask} is -\code{NULL}, the function shall generate an error and return -\code{NULL}. - -\begin{prototype} -psPixels *psPixelsCopy(psPixels *out, const psPixels *pixels); -psPixels *psPixelsConcatenate(psPixels *out, const psPixels *pixels); -\end{prototype} - -\code{psPixelsCopy} shall copy the contents of \code{pixels} to the -\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}. - -\code{psPixelsConcatenate} shall concatenate the \code{pixels} onto -\code{out}. In the event that \code{out} is \code{NULL}, the function -performs a \code{psPixelsCopy}, returning the copy. 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). - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - \subsection{Vector and Image Arithmetic} \label{sec:arithmetic} @@ -5132,5 +5205,5 @@ \pagebreak -\section{Astronomy-Specific Functions} +\section{Astronomy-Related Functions} The previous sections of this document defined basic functionality @@ -5147,5 +5220,4 @@ \item Dates and times \item Detector and sky positions -\item Astronomical Image Containers \item Astrometry \item Photometry @@ -6185,76 +6257,8 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5 -\subsection{Photometry} - -\tbd{This section is to be deferred, and for now consists only of -place holders, with no functional items.} - -Photometric observations are performed in an instrumental photometric -system, and must be related to other photometric systems. We -require a data structure which defines a photometric system, as well -as a structure to define the transformation between photometric -systems. - -The photometric system is defined by the psPhotSystem structure. -A photometric system is identified by a human-readable \code{name} -(ie, SDSS.g, Landolt92.B, GPC1.OTA32.r). Each photometric system is -given a unique identifier \code{ID}. Observations taken with a -specific camera, detector, and filter represent their own photometric -system, and it may be necessary to perform transformations between -these systems. Photometric systems associated with observations from -a specific camera/detector/filter combination can be associated with -those components. -\begin{datatype} -typedef struct { - const int ID; ///< ID number for this photometric system - const char *name; ///< Name of photometric system - const char *camera; ///< Camera for photometric system - const char *filter; ///< Filter used for photometric system - const char *detector; ///< Detector used for photometric system -} psPhotSystem; -\end{datatype} - -The following structure defines the transformation between two -photometric systems. -\begin{datatype} -typedef struct { - psPhotSystem src; ///< Source photometric system - psPhotSystem dst; ///< Destination photometric system - psPhotSystem pP, pM; ///< Primary color reference - psPhotSystem sP, sM; ///< Secondary color reference - float pA, sA; ///< Color offset for references - psPolynomial3D transform; ///< Transformation from source to destination -} psPhotTransform; -\end{datatype} - -The transformation between two photometric systems may depend on the -airmass of the observation and on the colors of the object of -interest. For a specific observation, such a transformations can be -defined as a polynomial function of the color of the star and the -airmass of the observations. If sufficient data exists, the -transformation between the photometric systems may include more than -one color, constraining the curvature of the stellar spectral energy -distributions. This latter term may be significant for stars which -are highly reddened, for example. Derived photometric quantities may -have been corrected for airmass variations, in which case only color -terms may be measurable. The structure defines the transformation -between a source photometric system (\code{src}) and a target -photometric system (\code{dst}). The photometric system of a primary -color is defined by \code{pP, pM} such that the color is constructed -as $pP - pM$. A secondary color is defined by \code{sP, sM}. For -both, a reference color is specified (\code{pA, sA}): the polynomial -transformation terms refer to colors in the form $pP - pM - pA$. The -transformation is specified as a 3D polynomial. For a star of -magnitude $M_{\rm src}$ in the source photometric system, with -additional magnitude information in the other systems $M_{\rm pP}$, -$M_{\rm pM}$, $M_{\rm sP}$, $M_{\rm sM}$, observed at an airmass of -$z$, the magnitude of the star in the target system $M_{\rm dst}$ is -given by: $M_{\rm dst} = M_{\rm src} + transform(z, M_{\rm pP} - -M_{\rm pM} - pA, M_{\rm sP} - M_{\rm sM} - sA)$. - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% Astronomical Images and Astrometry -\include{psLibSDRS_Astrom} +% \include{psLibSDRS_Astrom} \subsection{Astronomical objects}