time_conversion.h

Go to the documentation of this file.
00001 /**
00002 \file    time_conversion.h
00003 \brief   GNSS core 'c' function library: converting time information.
00004 \author  Glenn D. MacGougan (GDM)
00005 \date    2007-11-29
00006 \since   2005-07-30
00007 
00008 \b REFERENCES \n
00009 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00010   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00011 - http://aa.usno.navy.mil/data/docs/JulianDate.html - Julian Date Converter \n
00012 - http://aa.usno.navy.mil/faq/docs/UT.html \n
00013 - http://wwwmacho.mcmaster.ca/JAVA/JD.html \n
00014 - Raquet, J. F. (2002), GPS Receiver Design Lecture Notes. Geomatics Engineering, 
00015   University of Calgary Graduate Course. \n
00016 
00017 \b "LICENSE INFORMATION" \n
00018 Copyright (c) 2007, refer to 'author' doxygen tags \n
00019 All rights reserved. \n
00020 
00021 Redistribution and use in source and binary forms, with or without
00022 modification, are permitted provided the following conditions are met: \n
00023 
00024 - Redistributions of source code must retain the above copyright
00025   notice, this list of conditions and the following disclaimer. \n
00026 - Redistributions in binary form must reproduce the above copyright
00027   notice, this list of conditions and the following disclaimer in the
00028   documentation and/or other materials provided with the distribution. \n
00029 - The name(s) of the contributor(s) may not be used to endorse or promote 
00030   products derived from this software without specific prior written 
00031   permission. \n
00032 
00033 THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS 
00034 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
00035 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00036 DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
00037 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00038 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
00039 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
00040 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
00041 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
00042 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
00043 SUCH DAMAGE.
00044 */
00045 
00046 #ifndef _C_TIMECONV_H_
00047 #define _C_TIMECONV_H_
00048 
00049 #ifdef __cplusplus
00050 extern "C" {
00051 #endif
00052 
00053 #include "basictypes.h"
00054 
00055 
00056 /*************************************************************************************************/
00057 // preprocessor constant definitions, any related enumerations and descriptors
00058 
00059 #ifndef SECONDS_IN_DAY
00060 #define SECONDS_IN_DAY (86400.0)
00061 #endif
00062 
00063 #ifndef SECONDS_IN_WEEK
00064 #define SECONDS_IN_WEEK (604800.0)
00065 #endif
00066 
00067 /**
00068 \brief    Obtains the UTC time, GPS time, and Julian date from PC system time.
00069 
00070 \author   Glenn D. MacGougan (GDM)
00071 \date     2006-11-10
00072 \since    2005-08-22
00073 \return   TRUE(1) if successful, FALSE(0) otherwise.
00074 \remarks  (1) Millisecond time is obtained
00075 */
00076 BOOL TIMECONV_GetSystemTime(
00077   unsigned short*     utc_year,     //!< Universal Time Coordinated    [year]
00078   unsigned char*      utc_month,    //!< Universal Time Coordinated    [1-12 months] 
00079   unsigned char*      utc_day,      //!< Universal Time Coordinated    [1-31 days]
00080   unsigned char*      utc_hour,     //!< Universal Time Coordinated    [hours]
00081   unsigned char*      utc_minute,   //!< Universal Time Coordinated    [minutes]
00082   float*              utc_seconds,  //!< Universal Time Coordinated    [s]
00083   unsigned char*      utc_offset,   //!< Integer seconds that GPS is ahead of UTC time, always positive             [s], obtained from a look up table
00084   double*             julian_date,  //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days]
00085   unsigned short*     gps_week,     //!< GPS week (0-1024+)            [week]
00086   double*             gps_tow       //!< GPS time of week (0-604800.0) [s]
00087   );
00088 
00089 
00090 #ifdef WIN32
00091 /**
00092 \brief    Sets the PC time to the UTC time provided.
00093 
00094 \author   Glenn D. MacGougan (GDM)
00095 \date     2008-12-03
00096 \since    2008-12-03
00097 \return   TRUE(1) if successful, FALSE(0) otherwise.
00098 */
00099 BOOL TIMECONV_SetSystemTime(
00100   const unsigned short  utc_year,     //!< Universal Time Coordinated    [year]
00101   const unsigned char   utc_month,    //!< Universal Time Coordinated    [1-12 months] 
00102   const unsigned char   utc_day,      //!< Universal Time Coordinated    [1-31 days]
00103   const unsigned char   utc_hour,     //!< Universal Time Coordinated    [hours]
00104   const unsigned char   utc_minute,   //!< Universal Time Coordinated    [minutes]
00105   const float           utc_seconds   //!< Universal Time Coordinated    [s]
00106   );
00107 #endif
00108 
00109 
00110 /**
00111 \brief    Computes the day of the week from the Julian date.
00112 
00113 \author   Glenn D. MacGougan (GDM)
00114 \date     2008-12-03
00115 \since    2008-12-03
00116 \return   TRUE(1) if successful, FALSE(0) otherwise.
00117 
00118 \b REFERENCES \n
00119 http://en.wikipedia.org/wiki/Julian_day
00120 */
00121 BOOL TIMECONV_GetDayOfWeekFromJulianDate(
00122   const double julian_date,   //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days]
00123   unsigned char *day_of_week  //!< 0-Sunday, 1-Monday, 2-Tuesday, 3-Wednesday, 4-Thursday, 5-Friday, 6-Saturday [].
00124   );
00125 
00126 
00127 /**
00128 \brief    Computes the Julian date from GPS time
00129 
00130 \author   Glenn D. MacGougan (GDM)
00131 \date     2007-11-29
00132 \since    2005-08-22
00133 \return   TRUE(1) if successful, FALSE(0) otherwise.
00134 
00135 \b REFERENCES \n
00136 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00137   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00138 */
00139 BOOL TIMECONV_GetJulianDateFromGPSTime(
00140   const unsigned short    gps_week,      //!< GPS week (0-1024+)             [week]
00141   const double            gps_tow,       //!< GPS time of week (0-604800.0)  [s]
00142   const unsigned char     utc_offset,    //!< Integer seconds that GPS is ahead of UTC time, always positive [s]
00143   double*                 julian_date    //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days]
00144   );
00145 
00146 /**
00147 \brief    Computes the Julian date from UTC time
00148 
00149 \author   Glenn D. MacGougan (GDM)
00150 \date     2007-11-29
00151 \since    2005-08-22
00152 \return   TRUE(1) if successful, FALSE(0) otherwise.
00153 
00154 \remarks
00155 - Verified calculation using http://aa.usno.navy.mil/data/docs/JulianDate.html,
00156   a Julian Date Converter and http://wwwmacho.mcmaster.ca/JAVA/JD.html,
00157   another online converter tool. \n
00158 
00159 \b REFERENCES \n
00160 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00161 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00162 */
00163 BOOL TIMECONV_GetJulianDateFromUTCTime(
00164  const unsigned short     utc_year,      //!< Universal Time Coordinated  [year]
00165  const unsigned char      utc_month,     //!< Universal Time Coordinated  [1-12 months] 
00166  const unsigned char      utc_day,       //!< Universal Time Coordinated  [1-31 days]
00167  const unsigned char      utc_hour,      //!< Universal Time Coordinated  [hours]
00168  const unsigned char      utc_minute,    //!< Universal Time Coordinated  [minutes]
00169  const float              utc_seconds,   //!< Universal Time Coordinated  [s]
00170  double*                  julian_date    //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days]
00171  );
00172 
00173 
00174 
00175 
00176 /**
00177 \brief    Computes GPS time from the Julian date
00178 
00179 \author   Glenn D. MacGougan (GDM)
00180 \date     2007-11-29
00181 \since    2005-08-22
00182 \return   TRUE(1) if successful, FALSE(0) otherwise.
00183 
00184 \b REFERENCES \n
00185 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00186   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00187 */
00188 BOOL TIMECONV_GetGPSTimeFromJulianDate(
00189   const double            julian_date, //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days]
00190   const unsigned char     utc_offset,  //!< Integer seconds that GPS is ahead of UTC time, always positive [s]
00191   unsigned short*         gps_week,    //!< GPS week (0-1024+)            [week]
00192   double*                 gps_tow      //!< GPS time of week [s]
00193   );
00194 
00195 /**
00196 \brief    Computes UTC time from the Julian date
00197 
00198 \author   Glenn D. MacGougan (GDM)
00199 \date     2007-11-29
00200 \since    2005-08-22
00201 \return   TRUE(1) if successful, FALSE(0) otherwise.
00202 
00203 \b REFERENCES \n
00204 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00205   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00206 */
00207 BOOL TIMECONV_GetUTCTimeFromJulianDate(
00208   const double        julian_date,  //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days]
00209   unsigned short*     utc_year,     //!< Universal Time Coordinated    [year]
00210   unsigned char*      utc_month,    //!< Universal Time Coordinated    [1-12 months] 
00211   unsigned char*      utc_day,      //!< Universal Time Coordinated    [1-31 days]
00212   unsigned char*      utc_hour,     //!< Universal Time Coordinated    [hours]
00213   unsigned char*      utc_minute,   //!< Universal Time Coordinated    [minutes]
00214   float*              utc_seconds   //!< Universal Time Coordinated    [s]
00215   );
00216 
00217 /**
00218 \brief    Computes GPS time from UTC time
00219 
00220 \author   Glenn D. MacGougan (GDM)
00221 \date     2007-11-29
00222 \since    2005-08-22
00223 \return   TRUE(1) if successful, FALSE(0) otherwise.
00224 
00225 \remarks
00226 (1) The utc offset is determined automatically from a look up table
00227 
00228 \b REFERENCES \n
00229 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00230   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00231 */
00232 BOOL TIMECONV_GetGPSTimeFromUTCTime(
00233   unsigned short     utc_year,     //!< Universal Time Coordinated    [year]
00234   unsigned char      utc_month,    //!< Universal Time Coordinated    [1-12 months] 
00235   unsigned char      utc_day,      //!< Universal Time Coordinated    [1-31 days]
00236   unsigned char      utc_hour,     //!< Universal Time Coordinated    [hours]
00237   unsigned char      utc_minute,   //!< Universal Time Coordinated    [minutes]
00238   float              utc_seconds,  //!< Universal Time Coordinated    [s]
00239   unsigned short*    gps_week,     //!< GPS week (0-1024+)            [week]
00240   double*            gps_tow       //!< GPS time of week (0-604800.0) [s]
00241   );
00242 
00243 
00244 /**
00245 \brief    Computes GPS time from RINEX time. RINEX time looks like UTC
00246           but it is GPS time in year, month, day, hours, minutes, seconds.
00247 
00248 \author   Glenn D. MacGougan (GDM)
00249 \date     2007-12-07
00250 \since    2007-12-07
00251 \return   TRUE(1) if successful, FALSE(0) otherwise.
00252 
00253 \remarks
00254 - There is no UTC offset to apply
00255 - The RINEX time system must be the GPS Time system to use this function.
00256 
00257 \b REFERENCES \n
00258 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00259   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00260 - RINEX version 2.11, (http://www.aiub-download.unibe.ch/rinex/rinex211.txt)
00261 */
00262 BOOL TIMECONV_GetGPSTimeFromRinexTime(
00263   unsigned short     utc_year,     //!< Universal Time Coordinated    [year]
00264   unsigned char      utc_month,    //!< Universal Time Coordinated    [1-12 months] 
00265   unsigned char      utc_day,      //!< Universal Time Coordinated    [1-31 days]
00266   unsigned char      utc_hour,     //!< Universal Time Coordinated    [hours]
00267   unsigned char      utc_minute,   //!< Universal Time Coordinated    [minutes]
00268   float              utc_seconds,  //!< Universal Time Coordinated    [s]
00269   unsigned short*    gps_week,     //!< GPS week (0-1024+)            [week]
00270   double*            gps_tow       //!< GPS time of week (0-604800.0) [s]
00271   );
00272 
00273 
00274 /**
00275 \brief    Computes UTC time from GPS time
00276 
00277 \author   Glenn D. MacGougan (GDM)
00278 \date     2007-11-29
00279 \since    2005-08-22
00280 \return   TRUE(1) if successful, FALSE(0) otherwise.
00281 
00282 \remarks
00283 - The utc offset is determined automatically from a look up table
00284 
00285 \b REFERENCES \n
00286 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00287   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00288 */
00289 BOOL TIMECONV_GetUTCTimeFromGPSTime(
00290   unsigned short     gps_week,     //!< GPS week (0-1024+)            [week]
00291   double             gps_tow,      //!< GPS time of week (0-604800.0) [s]
00292   unsigned short*    utc_year,     //!< Universal Time Coordinated    [year]
00293   unsigned char*     utc_month,    //!< Universal Time Coordinated    [1-12 months] 
00294   unsigned char*     utc_day,      //!< Universal Time Coordinated    [1-31 days]
00295   unsigned char*     utc_hour,     //!< Universal Time Coordinated    [hours]
00296   unsigned char*     utc_minute,   //!< Universal Time Coordinated    [minutes]
00297   float*             utc_seconds   //!< Universal Time Coordinated    [s]
00298   );
00299 
00300 
00301 
00302 /**
00303 \brief    This function is a look up table to determine the UTC offset from the Julian Date.
00304 
00305 \author   Glenn D. MacGougan (GDM)
00306 \date     2007-11-29
00307 \since    2005-08-22
00308 \return   TRUE(1) if successful, FALSE(0) otherwise.
00309 
00310 \remarks
00311 - This function must be updated when the next UTC *utc_offset step occurs. Current max is (13).
00312  
00313 \b REFERENCES \n
00314 - Raquet, J. F. (2002), GPS Receiver Design Lecture Notes. Geomatics Engineering, 
00315   University of Calgary Graduate Course. \n
00316 
00317 \b "Offset Table" \n
00318 UTCOffset, UTC Date, Julian Date [days] \n
00319 0,    Jan 06 1980 00:00:00.0,    2444244.5000 \n
00320 1,    Jul 01 1981 00:00:00.0,    2444786.5000 \n
00321 2,    Jul 01 1982 00:00:00.0,    2445151.5000 \n
00322 3,    Jul 01 1983 00:00:00.0,    2445516.5000 \n
00323 4,    Jul 01 1985 00:00:00.0,    2446247.5000 \n
00324 5,    Jan 01 1988 00:00:00.0,    2447161.5000 \n
00325 6,    Jan 01 1990 00:00:00.0,    2447892.5000 \n
00326 7,    Jan 01 1991 00:00:00.0,    2448257.5000 \n
00327 8,    Jul 01 1992 00:00:00.0,    2448804.5000 \n
00328 9,    Jul 01 1993 00:00:00.0,    2449169.5000 \n
00329 10,   Jul 01 1994 00:00:00.0,    2449534.5000 \n
00330 11,   Jan 01 1996 00:00:00.0,    2450083.5000 \n
00331 12,   Jul 01 1997 00:00:00.0,    2450630.5000 \n
00332 13,   Jan 01 1999 00:00:00.0,    2451179.5000 \n
00333 14,   Jan 01 2006 00:00:00.0,    2453736.5000 \n
00334 */
00335 BOOL TIMECONV_DetermineUTCOffset(
00336   double julian_date,       //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days]
00337   unsigned char* utc_offset //!< Integer seconds that GPS is ahead of UTC time, always positive             [s], obtained from a look up table
00338   );
00339 
00340 /**
00341 \brief    Determines the number of days in a month, given the month and year.
00342 
00343 \author   Glenn D. MacGougan (GDM)
00344 \date     2007-11-29
00345 \since    2005-08-22
00346 \return   TRUE(1) if successful, FALSE(0) otherwise.
00347 
00348 \b REFERENCES \n
00349 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00350   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00351 */
00352 BOOL TIMECONV_GetNumberOfDaysInMonth(
00353   const unsigned short year,        //!< Universal Time Coordinated    [year]
00354   const unsigned char month,        //!< Universal Time Coordinated    [1-12 months] 
00355   unsigned char* days_in_month      //!< Days in the specified month   [1-28|29|30|31 days]
00356   );
00357 
00358 
00359 /**
00360 \brief    Determines if the given year is a leap year
00361 
00362 \author   Glenn D. MacGougan (GDM)
00363 \date     2007-11-29
00364 \since    2005-08-22
00365 \returns  TRUE(1) if the given year is a leap year, FALSE(0) otherwise
00366 
00367 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 
00368   Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n
00369 */
00370 BOOL TIMECONV_IsALeapYear( const unsigned short year );
00371 
00372 
00373 /**
00374 \brief    Determines the day of year given the year, month, and day
00375 
00376 \author   Glenn D. MacGougan (GDM)
00377 \date     2007-11-29
00378 \since    2005-08-22
00379 \return   TRUE(1) if successful, FALSE(0) otherwise.
00380 
00381 \remarks
00382 (1) Performed independant comparison with http://www.mbari.org/staff/coletti/doytable.html
00383 */
00384 BOOL TIMECONV_GetDayOfYear(
00385  const unsigned short utc_year,    // Universal Time Coordinated           [year]
00386  const unsigned char  utc_month,   // Universal Time Coordinated           [1-12 months] 
00387  const unsigned char  utc_day,     // Universal Time Coordinated           [1-31 days]
00388  unsigned short*      dayofyear    // number of days into the year (1-366) [days]
00389  );
00390 
00391 
00392 /**
00393 \brief    Determines the GPS time of the start of a day from the day of year and the year.
00394 
00395 \author   Glenn D. MacGougan (GDM)
00396 \date     2007-12-07
00397 \since    2007-12-07
00398 \return   TRUE(1) if successful, FALSE(0) otherwise.
00399 */
00400 BOOL TIMECONV_GetGPSTimeFromYearAndDayOfYear(
00401  const unsigned short year,      // The year [year]
00402  const unsigned short dayofyear, // The number of days into the year (1-366) [days]
00403  unsigned short*      gps_week,  //!< GPS week (0-1024+)            [week]
00404  double*              gps_tow    //!< GPS time of week (0-604800.0) [s]
00405  );
00406 
00407  
00408   
00409 #ifdef __cplusplus
00410 }
00411 #endif
00412 
00413 
00414 #endif // _C_TIMECONV_H_
SourceForge.net Logo