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_