Index: /trunk/doc/pslib/psLibADD.tex =================================================================== --- /trunk/doc/pslib/psLibADD.tex (revision 1553) +++ /trunk/doc/pslib/psLibADD.tex (revision 1554) @@ -1,3 +1,3 @@ -%%% $Id: psLibADD.tex,v 1.24 2004-08-16 19:12:54 eugene Exp $ +%%% $Id: psLibADD.tex,v 1.25 2004-08-17 01:56:41 eugene Exp $ \documentclass[panstarrs]{panstarrs} @@ -644,12 +644,17 @@ Correct time representation is critical in astronomical software. -PSLib uses the \code{psTime} structure to represent all time -values. This structure represents a time which is equivalent to TAI -(International Atomic Time) and has the following properties: -\begin{itemize} -\item it represents both seconds and microseconds -\item the seconds are continuous (no leap seconds) -\item the zero reference point is \tbd{1970/01/01,00:00:10} UTC. -\end{itemize} +PSLib uses the \code{psTime} structure to represent all time values. +This structure represents a time which is consists of seconds and +fractions of seconds in a time system defined by the \code{psTimeType} +element \code{type}. Two possible time systems are currently +available: TAI and UTC. Both are defined in terms of the reference +epoch 1970-01-01T00:00:00Z, but with minor modifications for +leap-seconds as needed. The first represenatation, TAI (International +Atomic Time), has seconds of uniform length and no leap seconds. The +exact zero reference is 1970/01/01,00:00:10 UTC. The second +representations is UTC, which has seconds of uniform length and +leap-seconds as needed to adjust it to remain within 0.9 seconds of +the Earth's rotation. It has a zero-point of exactly +1970/01/01,00:00:00 UTC. Julian Day (JD) and Modified Julian Day (MJD) are both continuous time @@ -708,4 +713,19 @@ \end{verbatim} +The conversion from a time and longitude to local mean sidereal time +is performed using the SLA Lib function \code{sla_GMST}. This +function requires the value $\Delta$ UT1 = UTC - UT1. The value of +$\Delta$ UT1 may be determined from the following site in real time: + +\code{ftp://maia.usno.navy.mil/ser7/ser7.dat} + +In addition, the long-term values may be determined from the table +found at: \code{ftp://maia.usno.navy.mil/ser7/finals.all}. See also +the web page \code{http://maia.usno.navy.mil/}. The most significant +accuracy requirements are for the current value when calculating the +LST. For this purpose, the table above (\code{ser7.dat}), which +provides predictions over a 2 month period, must be made available +locally to PSLib and updated regularly. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -842,16 +862,36 @@ \subsubsection{Projections} -We implement three types of projections, {\em zenithal} and {\em -cylindrical} and {\em pseudocylindrical} projections. These three -require slightly different handling. Our representations are based on -the treatment of projections presented by +We implement three types of projections: {\em zenithal}, {\em +cylindrical} and {\em pseudocylindrical}, each requiring slightly +different handling. Our representations are based on the treatment of +projections presented by \href{http://www.cv.nrao.edu/fits/documents/wcs/wcs.all.ps}{Greisen \& -Calabretta (1995, ADASS, 4, 233)}. +Calabretta (1995, ADASS, 4, 233)}. In all of these projections, we +are converting from a spherical coordinate $\alpha,\delta$ to a linear +(2-D) coordinate $x_p,y_p$. The projection is defined by the +projection type, the projection center ($\alpha_p, \delta_p$) and the +the plate scales in the $x_p$ and $y_p$ directions ($\rho_x,\rho_y$). + +In the structure, \code{psProjection}, the projection type is defined +by the element \code{type}, the projection center $\alpha_p,\delta_p$ +is defined by the elements \code{R,D}, and the plate scales, +$\rho_x,\rho_y$, are defined by the elements \code{Xs,Ys}. The plate +scales are applied independently to the $x$ and $y$ coordinates to +convert them to the corresponding linear units (ie, pixels): +% +\begin{eqnarray} +x_p & = & \rho_x x \\ +y_p & = & \rho_y y \\ +\end{eqnarray} +% +In the discussions below, we ignore this last step (or first step, +depending on the direction of the conversion). \paragraph{Zenithal Projections} The {\em zenithal} projections are defined relative to a set of -spherical coordinates whose pole is the center of the projection -($\alpha_p, \delta_p$, or \code{psProjection.R, psProjection.D}). In +spherical coordinates with pole at the center of the projection +($\alpha_p, \delta_p$), and which thus represents a coordinate system +rotated relative to the coordinate system of $\alpha, \delta$. In this spherical coordinate system, the coordinate of longitude is labeled $\phi$, and has domain of $-\pi < \phi \le \pi$, while the @@ -859,37 +899,10 @@ $0 \le \theta \le \pi$. -For zenithal projections (e.g.\ Gnomonic and Orthographic) the -following hold: -% -\begin{eqnarray} -x & = & R_\theta \sin \phi \\ -y & = & -R_\theta \cos \phi -\end{eqnarray} -% -and -% -\begin{eqnarray} -R_\theta & = & \sqrt{x^2 + y^2} \\ -\phi & = & {\rm arg} (-y,x) -\end{eqnarray} -% -The coordinates $x,y$ above are defined to be in angular units (ie, -radians). The plate scales ($\rho_x, \rho_y$ = \code{psProjection.Xs, -psProjection.Ys}) are applied independently to the $x$ and $y$ -coordinates to convert them to the corresponding linear units (ie, -pixels): -% -\begin{eqnarray} -x_p & = & \rho_x x \\ -y_p & = & \rho_y y \\ -\end{eqnarray} - For an arbitrary projection center, it is necessary to convert the spherical coordinates to be projected ($\alpha,\delta$) to the -projection spherical coordinate system coordinates ($\phi, \theta$) -from which $x,y$ may be calculated using the relationships above, -given a prescription for $R_\theta$. In practice, we construct the -following useful trigonometric relationships between $\phi$ and -$\theta$ which may be employed in the equations of $x,y$ above: +projection spherical coordinate system coordinates ($\phi, \theta$). +In practice, we construct the following useful trigonometric +relationships between $\phi$ and $\theta$ which may be employed in the +equations of $x,y$ below: % \begin{eqnarray} @@ -907,17 +920,27 @@ \end{eqnarray} % +For zenithal projections, the linear coordinates are related to +$\phi,\theta$ by: +% +\begin{eqnarray} +x & = & R_\theta \sin \phi \\ +y & = & -R_\theta \cos \phi +\end{eqnarray} +% +and the inverse: +% +\begin{eqnarray} +R_\theta & = & \sqrt{x^2 + y^2} \\ +\phi & = & {\rm arg} (-y,x) +\end{eqnarray} +% +The coordinates $x,y$ above are defined to be in angular units (ie, +radians). + From these relationships, we can calculate $\alpha, \delta$ as: % \begin{eqnarray} -\alpha - \alpha_p & = & arg (\sin \alpha, \cos \alpha) \\ -\delta & = & arcsin (sin \delta) \\ -\end{eqnarray} -% -The necessary relationships for $\phi$ are equivalent for all zenithal projections: -% -\begin{eqnarray} -R_\theta & = & \sqrt{x^2 + y^2} \\ -\sin \phi & = & x / R_\theta \\ -\cos \phi & = & -y / R_\theta \\ +\alpha - \alpha_p & = & \arctan (\sin \alpha, \cos \alpha) \\ +\delta & = & \arcsin (\sin \delta) \\ \end{eqnarray} % @@ -933,6 +956,6 @@ x & = & \frac{\cos \theta \sin \phi}{\sin \theta} \\ y & = & \frac{-\cos \theta \cos \phi}{\sin \theta} \\ -\sin \theta & = & \zeta / \sqrt (1 + \zeta^2) \\ -\cos \theta & = & 1 / \sqrt (1 + \zeta^2) \\ +\sin \theta & = & \zeta / \sqrt{1 + \zeta^2} \\ +\cos \theta & = & 1 / \sqrt{1 + \zeta^2} \\ \end{eqnarray} @@ -958,18 +981,17 @@ coincident with the pole of the spherical coordinates. These projections are particularly used for full-sky representations, and -are only defined for projection centers with $\delta_c = 0$. In this +are only defined for projection centers with $\delta_p = 0$. In this spherical coordinate system, the coordinate of longitude is labeled $\phi$, and has domain of $-\pi < \phi \le \pi$, while the latitude, measured from the pole, is labeled $\theta$ and has domain $0 \le -\theta \le \pi$. The projection center longitude, $\alpha_c$ +\theta \le \pi$. The projection center longitude, $\alpha_p$ corresponds to $\phi = 0$, thus the value of $\phi$ is determined as -$\alpha - \alpha_c$ for all such projections. The terms -$\alpha_c,\delta_c$ are equivalent to the elements -\code{psProjection.R} and \code{psProjection.D}. +$\alpha - \alpha_p$ for all such projections. \subparagraph{Cartesian} -The Cartesian projection (``CAR'') is a very simple cylindrical with -the following relationships between $x,y$ and $\phi,\theta$: +The Cartesian projection (``CAR'') is a very simple cylindrical +projection with the following relationships between $x,y$ and +$\phi,\theta$: \begin{eqnarray} @@ -985,15 +1007,15 @@ x & = & \phi \\ y & = & \ln \left( \tan (\pi/4 + \theta/2) \right) \\ -{\rm and}\hspace{1cm} \theta & = & 2 \arctan \left( e^y \right) - \pi/2^\circ +{\rm and}\hspace{1cm} \theta & = & 2 \arctan \left( e^y \right) - \pi/2 \end{eqnarray} \subparagraph{Hammer-Aitoff} -The Hammer-Aitoff projection is a pseudocylindrical projection, and is defined: - -\begin{eqnarray} -x & = & 2 \alpha \cos \theta \sin \frac{\phi}{2} \\ -y & = & \alpha \sin \theta \\ -{\rm where}\hspace{1cm} \alpha^{-1} & \equiv & \sqrt{\frac{1}{2}\left(1 + \cos \theta \cos \frac{\phi}{2} \right)} +The Hammer-Aitoff projection(``AIT'') is a pseudocylindrical projection, and is defined: + +\begin{eqnarray} +x & = & 2 \zeta \cos \theta \sin \frac{\phi}{2} \\ +y & = & \zeta \sin \theta \\ +{\rm where}\hspace{1cm} \zeta^{-1} & \equiv & \sqrt{\frac{1}{2}\left(1 + \cos \theta \cos \frac{\phi}{2} \right)} \end{eqnarray} @@ -1001,5 +1023,5 @@ \begin{eqnarray} -\phi & = & 2 {\rm arg} (2z^2 - 1, x z) \\ +\phi & = & 2 {\rm \arctan} (2z^2 - 1, x z) \\ \theta & = & \arcsin (yz) \\ {\rm where}\hspace{1cm} z & \equiv & \sqrt{1 - (x/2)^2 - y^2} Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 1553) +++ /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;