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

Timestamp:

Jun 8, 2005, 7:16:41 PM (21 years ago)

Author:

eugene

Message:

more section reorganization

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +831 @@
 %
 \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 +932 @@
 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 +1048 @@
 %
 \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 +1107 @@
 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 +1735 @@
 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 +4769 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\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 +5205 @@
 
 \pagebreak 
-\section{Astronomy-Specific Functions}
+\section{Astronomy-Related Functions}
 
 The previous sections of this document defined basic functionality
@@ -5147 +5220 @@
 \item Dates and times
 \item Detector and sky positions
-\item Astronomical Image Containers
 \item Astrometry
 \item Photometry
@@ -6185 +6257 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%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}