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

Timestamp:

Aug 16, 2004, 3:56:41 PM (22 years ago)

Author:

eugene

Message:

cleaned up time handling

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.72 2004-08-14 00:58:46 jhoblitt Exp $
+%%% $Id: psLibSDRS.tex,v 1.73 2004-08-17 01:56:41 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -3031 +3031 @@
 \subsubsection{Overview}
 
-We require a collection of functions to manipulate time data.  These operations
-primarily consist of conversions between specific time formats.  Internally,
-PSLib handles times as struct similar to the POSIX \code{struct timeval} which
-has been extended to track the time system being represented.
-
-Conversion from one time system to another is achived by converting first to
-TAI and then to the destination type.  This allows arbitarily many time system
-to be supported by merely add functions to convert to and from TAI.
-
-\subsubsection{Generic Data Structures}
+We require a collection of functions to manipulate time data.  These
+operations primarily consist of conversions between specific time
+formats.  Internally, PSLib handles times as a structure similar to
+the POSIX \code{timeval} which has been extended to track the time
+system being represented.  
 
 \begin{verbatim}
@@ -3046 +3041 @@
     PS_TIME_TAI,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
     PS_TIME_UTC,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
-    PS_TIME_UT1,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
-    PS_TIME_LST,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian)
 } psTimeType;
 
 typedef struct {
     psU64            sec;           ///< seconds
-    psU32            nsec;          ///< nanoseconds
+    psU32            usec;          ///< microseconds
     psTimeType       type;          ///< type of time
 } psTime;
@@ -3059 +3052 @@
 \subsubsection{Current Date and Time}
 
-A number of functions are provided to get the current time in a particular time
-system.
-
-\begin{verbatim}
-psTime *psGetTAI(void);
-psTime *psGetUTC(void);
-psTime *psGetUT1(void);
-psTime *psGetLST(psF64 longitude);
-psF64 *psGetJD(void);
-psF64 *psGetMJD(void);
-\end{verbatim}
-
-\subsubsection{Automatic Date and Time Type Conversion}
-
-When converting to a time system the source time system is automaticaly
-converted to TAI and then from TAI to the destination type.
-
-\begin{verbatim}
-bool psTimeToTAI(psTimeType type, psTime *time);
-bool psTimeToUTC(psTimeType type, psTime *time);
-bool psTimeToUT1(psTimeType type, psTime *time);
-bool psTimeToLST(psTimeType type, psTime *time);
+Get the current time (in given system):
+
+\begin{verbatim}
+psTime *psTimeGetTime(psTimeType);
+\end{verbatim}
+
+\subsubsection{Time Conversion}
+
+Converting between the \code{psTime} time systems is done with:
+\begin{verbatim}
+psTime *psTimeConvert(psTime *time, psTimeType type);
+\end{verbatim}
+This function may be used to convert between \code{PS_TIME_TAI} and
+\code{PS_TIME_UTC} time representations.  
+
+To convert to or from Local Mean Sidereal Time, it is necessary to
+provide the local longitude as well:
+%
+\begin{verbatim}
+psTime *psTimeToLST(psTime *time, double longitude);
+psTime *psLSTToTime(psTime *time, double longitude);
+\end{verbatim}
+%
+The functions may accept either \code{psTimeType}.  Note that this
+function must supply the value UT1-UTC, which is available externally
+The value UT1-UTC is necessary for this an various other SLALIB
+functions.  The following utility function encapsulates the PSLib
+mechanism to extract the value of UT1-UTC:
+\begin{verbatim}
+double psGetUT1Delta(psTime *time);
+\end{verbatim}
+
+\subsubsection{External Date and Time Formats}
+
+A collection of functions convert from the \code{psTime} types to various
+external formats.  Note that ISO8601 format is "YYYY-MM-DDThh:mm:ss,sZ"
+
+\begin{verbatim}
 psF64 psTimeToJD(psTime *time);
 psF64 psTimeToMJD(psTime *time);
-\end{verbatim}
-
-\subsubsection{Date and Time Formatting}
-
-A collection of functions convert from the \code{psTime} types to various
-external formats.  Note that ISO8601 format is "YYYY-MM-DDThh:mm:ss,sZ"
-
-\begin{verbatim}
-char *psFormatISO8601(psTime *time);
-struct timeval *psFormatTimeval(psTime *time);
+char *psTimeToISOTime(psTime *time);
+struct timeval *psTimeToTimeval(psTime *time);
 \end{verbatim}
 
@@ -3101 +3102 @@
 
 \begin{verbatim}
-psTime *psParseISO8601(psTimeType type, char *input);
-psTime *psParseTimeval(psTimeType type, struct timeval *input);
-\end{verbatim}
-
-\subsubsection{Date and Time System Support}
-
-All \code{psTime} types must be able to be converted to to the TAI type.
-Conversion from one \code{psTime} type to another is achieved by first
-converting to TAI and then to the target type.
-
-\begin{verbatim}
-psTime *psTAIToUTC(psTime *time);
-psTime *psUTCToTAI(psTime *time);
-\end{verbatim}
-
-A utility function provides the current time from the system clock, in correct TAI units:
-
-\begin{verbatim}
-psTime *psTAIToUT1(psTime *time);
-psTime *psUT1ToTAI(psTime *time);
-\end{verbatim}
-
-\begin{verbatim}
-psTime *psTAIToLST(psTime *time, double longitude);
-psTime *psLSTToTAI(psTime *time, double longitude);
-\end{verbatim}
-
-\subsubsection{Utility Functions}
-
-A number of utility functions is needed for type conversion.
-
-\begin{verbatim}
-psTime *psUT1ToGMST00(psTime *time);
-psTime *psGMST00ToUT1(psTime *time);
-\end{verbatim}
-
-\begin{verbatim}
-psTime *psGMST00ToLST(psTime *time, double longitude);
-psTime *psLSTToGMST00(psTime *time, double longitude);
-\end{verbatim}
-
-Conversions to/from Julian Centuries.
-
-\begin{verbatim}
-psF64 psJDToJC(psF64 time);
-psF64 psJCToJD(psF64 time);
-\end{verbatim}
-
-\begin{verbatim}
-psF64 psMJDToJC(psF64 time);
-psF64 psJCToMJD(psF64 time);
-\end{verbatim}
-
-\begin{verbatim}
-unsigned int psGetLeapSeconds(psTime *utc);
-\end{verbatim}
-
-\begin{verbatim}
-double psGetUT1Delta(psTime *tai);
+psTime *psJDToTime(psF64 input);
+psTime *psMJDToTime(psF64 input);
+psTime *psISOTimeToTime(char *input);
+psTime *psTimevalToTime(struct timeval *input);
 \end{verbatim}
 
@@ -3710 +3656 @@
     PS_PROJ_AIT,                        ///< Aitoff projection
     PS_PROJ_PAR,                        ///< Par projection
-    PS_PROJ_GLS,                        ///< GLS projection
     PS_PROJ_NTYPE                       ///< Number of types; must be last
 } psProjectionType;