Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 1539) +++ trunk/doc/pslib/psLibSDRS.tex (revision 1554) @@ -1,3 +1,3 @@ -%%% $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,14 +3031,9 @@ \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,11 +3041,9 @@ 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,38 +3052,46 @@ \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,63 +3102,8 @@ \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,5 +3656,4 @@ 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;