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 /** 00091 \brief Computes the Julian date from GPS time 00092 00093 \author Glenn D. MacGougan (GDM) 00094 \date 2007-11-29 00095 \since 2005-08-22 00096 \return TRUE(1) if successful, FALSE(0) otherwise. 00097 00098 \b REFERENCES \n 00099 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00100 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00101 */ 00102 BOOL TIMECONV_GetJulianDateFromGPSTime( 00103 const unsigned short gps_week, //!< GPS week (0-1024+) [week] 00104 const double gps_tow, //!< GPS time of week (0-604800.0) [s] 00105 const unsigned char utc_offset, //!< Integer seconds that GPS is ahead of UTC time, always positive [s] 00106 double* julian_date //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days] 00107 ); 00108 00109 /** 00110 \brief Computes the Julian date from UTC time 00111 00112 \author Glenn D. MacGougan (GDM) 00113 \date 2007-11-29 00114 \since 2005-08-22 00115 \return TRUE(1) if successful, FALSE(0) otherwise. 00116 00117 \remarks 00118 - Verified calculation using http://aa.usno.navy.mil/data/docs/JulianDate.html, 00119 a Julian Date Converter and http://wwwmacho.mcmaster.ca/JAVA/JD.html, 00120 another online converter tool. \n 00121 00122 \b REFERENCES \n 00123 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00124 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00125 */ 00126 BOOL TIMECONV_GetJulianDateFromUTCTime( 00127 const unsigned short utc_year, //!< Universal Time Coordinated [year] 00128 const unsigned char utc_month, //!< Universal Time Coordinated [1-12 months] 00129 const unsigned char utc_day, //!< Universal Time Coordinated [1-31 days] 00130 const unsigned char utc_hour, //!< Universal Time Coordinated [hours] 00131 const unsigned char utc_minute, //!< Universal Time Coordinated [minutes] 00132 const float utc_seconds, //!< Universal Time Coordinated [s] 00133 double* julian_date //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days] 00134 ); 00135 00136 00137 00138 00139 /** 00140 \brief Computes GPS time from the Julian date 00141 00142 \author Glenn D. MacGougan (GDM) 00143 \date 2007-11-29 00144 \since 2005-08-22 00145 \return TRUE(1) if successful, FALSE(0) otherwise. 00146 00147 \b REFERENCES \n 00148 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00149 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00150 */ 00151 BOOL TIMECONV_GetGPSTimeFromJulianDate( 00152 const double julian_date, //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days] 00153 const unsigned char utc_offset, //!< Integer seconds that GPS is ahead of UTC time, always positive [s] 00154 unsigned short* gps_week, //!< GPS week (0-1024+) [week] 00155 double* gps_tow //!< GPS time of week [s] 00156 ); 00157 00158 /** 00159 \brief Computes UTC time from the Julian date 00160 00161 \author Glenn D. MacGougan (GDM) 00162 \date 2007-11-29 00163 \since 2005-08-22 00164 \return TRUE(1) if successful, FALSE(0) otherwise. 00165 00166 \b REFERENCES \n 00167 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00168 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00169 */ 00170 BOOL TIMECONV_GetUTCTimeFromJulianDate( 00171 const double julian_date, //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days] 00172 unsigned short* utc_year, //!< Universal Time Coordinated [year] 00173 unsigned char* utc_month, //!< Universal Time Coordinated [1-12 months] 00174 unsigned char* utc_day, //!< Universal Time Coordinated [1-31 days] 00175 unsigned char* utc_hour, //!< Universal Time Coordinated [hours] 00176 unsigned char* utc_minute, //!< Universal Time Coordinated [minutes] 00177 float* utc_seconds //!< Universal Time Coordinated [s] 00178 ); 00179 00180 /** 00181 \brief Computes GPS time from UTC time 00182 00183 \author Glenn D. MacGougan (GDM) 00184 \date 2007-11-29 00185 \since 2005-08-22 00186 \return TRUE(1) if successful, FALSE(0) otherwise. 00187 00188 \remarks 00189 (1) The utc offset is determined automatically from a look up table 00190 00191 \b REFERENCES \n 00192 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00193 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00194 */ 00195 BOOL TIMECONV_GetGPSTimeFromUTCTime( 00196 unsigned short utc_year, //!< Universal Time Coordinated [year] 00197 unsigned char utc_month, //!< Universal Time Coordinated [1-12 months] 00198 unsigned char utc_day, //!< Universal Time Coordinated [1-31 days] 00199 unsigned char utc_hour, //!< Universal Time Coordinated [hours] 00200 unsigned char utc_minute, //!< Universal Time Coordinated [minutes] 00201 float utc_seconds, //!< Universal Time Coordinated [s] 00202 unsigned short* gps_week, //!< GPS week (0-1024+) [week] 00203 double* gps_tow //!< GPS time of week (0-604800.0) [s] 00204 ); 00205 00206 00207 /** 00208 \brief Computes GPS time from RINEX time. RINEX time looks like UTC 00209 but it is GPS time in year, month, day, hours, minutes, seconds. 00210 00211 \author Glenn D. MacGougan (GDM) 00212 \date 2007-12-07 00213 \since 2007-12-07 00214 \return TRUE(1) if successful, FALSE(0) otherwise. 00215 00216 \remarks 00217 - There is no UTC offset to apply 00218 - The RINEX time system must be the GPS Time system to use this function. 00219 00220 \b REFERENCES \n 00221 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00222 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00223 - RINEX version 2.11, (http://www.aiub-download.unibe.ch/rinex/rinex211.txt) 00224 */ 00225 BOOL TIMECONV_GetGPSTimeFromRinexTime( 00226 unsigned short utc_year, //!< Universal Time Coordinated [year] 00227 unsigned char utc_month, //!< Universal Time Coordinated [1-12 months] 00228 unsigned char utc_day, //!< Universal Time Coordinated [1-31 days] 00229 unsigned char utc_hour, //!< Universal Time Coordinated [hours] 00230 unsigned char utc_minute, //!< Universal Time Coordinated [minutes] 00231 float utc_seconds, //!< Universal Time Coordinated [s] 00232 unsigned short* gps_week, //!< GPS week (0-1024+) [week] 00233 double* gps_tow //!< GPS time of week (0-604800.0) [s] 00234 ); 00235 00236 00237 /** 00238 \brief Computes UTC time from GPS time 00239 00240 \author Glenn D. MacGougan (GDM) 00241 \date 2007-11-29 00242 \since 2005-08-22 00243 \return TRUE(1) if successful, FALSE(0) otherwise. 00244 00245 \remarks 00246 - The utc offset is determined automatically from a look up table 00247 00248 \b REFERENCES \n 00249 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00250 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00251 */ 00252 BOOL TIMECONV_GetUTCTimeFromGPSTime( 00253 unsigned short gps_week, //!< GPS week (0-1024+) [week] 00254 double gps_tow, //!< GPS time of week (0-604800.0) [s] 00255 unsigned short* utc_year, //!< Universal Time Coordinated [year] 00256 unsigned char* utc_month, //!< Universal Time Coordinated [1-12 months] 00257 unsigned char* utc_day, //!< Universal Time Coordinated [1-31 days] 00258 unsigned char* utc_hour, //!< Universal Time Coordinated [hours] 00259 unsigned char* utc_minute, //!< Universal Time Coordinated [minutes] 00260 float* utc_seconds //!< Universal Time Coordinated [s] 00261 ); 00262 00263 00264 00265 /** 00266 \brief This function is a look up table to determine the UTC offset from the Julian Date. 00267 00268 \author Glenn D. MacGougan (GDM) 00269 \date 2007-11-29 00270 \since 2005-08-22 00271 \return TRUE(1) if successful, FALSE(0) otherwise. 00272 00273 \remarks 00274 - This function must be updated when the next UTC *utc_offset step occurs. Current max is (13). 00275 00276 \b REFERENCES \n 00277 - Raquet, J. F. (2002), GPS Receiver Design Lecture Notes. Geomatics Engineering, 00278 University of Calgary Graduate Course. \n 00279 00280 \b "Offset Table" \n 00281 UTCOffset, UTC Date, Julian Date [days] \n 00282 0, Jan 06 1980 00:00:00.0, 2444244.5000 \n 00283 1, Jul 01 1981 00:00:00.0, 2444786.5000 \n 00284 2, Jul 01 1982 00:00:00.0, 2445151.5000 \n 00285 3, Jul 01 1983 00:00:00.0, 2445516.5000 \n 00286 4, Jul 01 1985 00:00:00.0, 2446247.5000 \n 00287 5, Jan 01 1988 00:00:00.0, 2447161.5000 \n 00288 6, Jan 01 1990 00:00:00.0, 2447892.5000 \n 00289 7, Jan 01 1991 00:00:00.0, 2448257.5000 \n 00290 8, Jul 01 1992 00:00:00.0, 2448804.5000 \n 00291 9, Jul 01 1993 00:00:00.0, 2449169.5000 \n 00292 10, Jul 01 1994 00:00:00.0, 2449534.5000 \n 00293 11, Jan 01 1996 00:00:00.0, 2450083.5000 \n 00294 12, Jul 01 1997 00:00:00.0, 2450630.5000 \n 00295 13, Jan 01 1999 00:00:00.0, 2451179.5000 \n 00296 14, Jan 01 2006 00:00:00.0, 2453736.5000 \n 00297 */ 00298 BOOL TIMECONV_DetermineUTCOffset( 00299 double julian_date, //!< Number of days since noon Universal Time Jan 1, 4713 BCE (Julian calendar) [days] 00300 unsigned char* utc_offset //!< Integer seconds that GPS is ahead of UTC time, always positive [s], obtained from a look up table 00301 ); 00302 00303 /** 00304 \brief Determines the number of days in a month, given the month and year. 00305 00306 \author Glenn D. MacGougan (GDM) 00307 \date 2007-11-29 00308 \since 2005-08-22 00309 \return TRUE(1) if successful, FALSE(0) otherwise. 00310 00311 \b REFERENCES \n 00312 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00313 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00314 */ 00315 BOOL TIMECONV_GetNumberOfDaysInMonth( 00316 const unsigned short year, //!< Universal Time Coordinated [year] 00317 const unsigned char month, //!< Universal Time Coordinated [1-12 months] 00318 unsigned char* days_in_month //!< Days in the specified month [1-28|29|30|31 days] 00319 ); 00320 00321 00322 /** 00323 \brief Determines if the given year is a leap year 00324 00325 \author Glenn D. MacGougan (GDM) 00326 \date 2007-11-29 00327 \since 2005-08-22 00328 \returns TRUE(1) if the given year is a leap year, FALSE(0) otherwise 00329 00330 - Hofmann-Wellenhof, B., H. Lichtenegger, and J. Collins (1994). GPS Theory and 00331 Practice, Third, revised edition. Springer-Verlag, Wien New York. pp. 38-42 \n 00332 */ 00333 BOOL TIMECONV_IsALeapYear( const unsigned short year ); 00334 00335 00336 /** 00337 \brief Determines the day of year given the year, month, and day 00338 00339 \author Glenn D. MacGougan (GDM) 00340 \date 2007-11-29 00341 \since 2005-08-22 00342 \return TRUE(1) if successful, FALSE(0) otherwise. 00343 00344 \remarks 00345 (1) Performed independant comparison with http://www.mbari.org/staff/coletti/doytable.html 00346 */ 00347 BOOL TIMECONV_GetDayOfYear( 00348 const unsigned short utc_year, // Universal Time Coordinated [year] 00349 const unsigned char utc_month, // Universal Time Coordinated [1-12 months] 00350 const unsigned char utc_day, // Universal Time Coordinated [1-31 days] 00351 unsigned short* dayofyear // number of days into the year (1-366) [days] 00352 ); 00353 00354 00355 /** 00356 \brief Determines the GPS time of the start of a day from the day of year and the year. 00357 00358 \author Glenn D. MacGougan (GDM) 00359 \date 2007-12-07 00360 \since 2007-12-07 00361 \return TRUE(1) if successful, FALSE(0) otherwise. 00362 */ 00363 BOOL TIMECONV_GetGPSTimeFromYearAndDayOfYear( 00364 const unsigned short year, // The year [year] 00365 const unsigned short dayofyear, // The number of days into the year (1-366) [days] 00366 unsigned short* gps_week, //!< GPS week (0-1024+) [week] 00367 double* gps_tow //!< GPS time of week (0-604800.0) [s] 00368 ); 00369 00370 00371 00372 #ifdef __cplusplus 00373 } 00374 #endif 00375 00376 00377 #endif // _C_TIMECONV_H_