Table of contents
CSPICE_ET2UTC converts an input time from ephemeris seconds
past J2000 to Calendar, Day-of-Year, or Julian Date format, UTC.
Given:
et the scalar double precision or N-vector of ephemeris time
expressed as ephemeris seconds past J2000.
help, et
DOUBLE = Scalar or DOUBLE = Array[N]
format the format of the output time string.
help, format
STRING = Scalar
It may be any of the following:
'C' Calendar format, UTC.
'D' Day-of-Year format, UTC.
'J' Julian Date format, UTC.
'ISOC' ISO Calendar format, UTC.
'ISOD' ISO Day-of-Year format, UTC.
prec the number of digits of precision to which fractional seconds
(for Calendar and Day-of-Year formats) or days (for Julian
Date format) are to be computed.
help, prec
LONG = Scalar
If `prec' is zero or smaller, no decimal point is appended to
the output string. If `prec' is greater than 14, it is
treated as 14.
the call:
cspice_et2utc, et, format, prec, utcstr
returns:
utcstr the scalar or N-vector output time strings equivalent to the
input epoch `et', in the specified `format'.
help, utcstr
STRING = Scalar or STRING = Array[N]
Some examples are shown below.
'C' '1986 APR 12 16:31:09.814'
'D' '1986-102 // 16:31:12.814'
'J' 'JD 2446533.18834276'
'ISOC' '1987-04-12T16:31:12.814'
'ISOD' '1987-102T16:31:12.814'
Fractional seconds, or for Julian dates, fractional
days, are rounded to the precision level specified
by the input argument `prec'.
For epochs prior to 1000 A.D. Jan 1 calendar
and day of year formats are returned with the
era (A.D. or B.C.) attached to the year. For
example
'877 A.D. MAR 17 13:29:11.829'
'471 B.C. Jan 01 12:00:00.000'
'471 B.C. 001 // 12:00:00.000'
ISO formats do not support the inclusion of an era.
For years prior to 1 A.D. an error will be signaled
if ISO format has been requested.
`utcstr' returns with the same measure of vectorization (N)
as `et'.
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Convert a single ephemeris time to UTC in Julian Date format, and
an array of ephemeris times to UTC in Calendar format.
Use the LSK kernel below to load the leap seconds and time
constants required for the conversions.
naif0012.tls
Example code begins here.
PRO et2utc_ex1
;;
;; Define an arbitrary ephemeris time.
;;
et = -527644192.5403653d
format = 'J'
prec = 6
SIZE = 5
;;
;; Load a leapseconds kernel.
;;
cspice_furnsh, 'naif0012.tls'
print, 'Ephemeris time Converted UTC time'
print, '--------------------- ---------------------------'
;;
;; Convert the ephemeris time to Julian Date
;; 'format'. Define precision to 6 decimal
;; places.
;;
cspice_et2utc, et, format, prec, utcstr
print, 'Scalar (Julian Date format):'
print, FORMAT='(F21.8,3X,A)', et, utcstr
;;
;; Create an array of ephemeris times beginning
;; at -527644192.5403653 with graduations of 10000.0
;; ephemeris seconds.
;;
et = 10000.d * dindgen( SIZE ) -527644192.5403653d
format = 'C'
;;
;; Convert the array of ephemeris times 'et' to an
;; array of UTC strings, 'utcstr', in calendar
;; 'format'.
;;
cspice_et2utc, et, format, prec, utcstr
print, 'Vector (Calendar format):'
for i=0, (SIZE-1) do begin
print, FORMAT='(F21.8,3X,A)', et[i], utcstr[i]
endfor
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Ephemeris time Converted UTC time
--------------------- ---------------------------
Scalar (Julian Date format):
-527644192.54036528 JD 2445438.006415
Vector (Calendar format):
-527644192.54036528 1983 APR 13 12:09:14.274000
-527634192.54036528 1983 APR 13 14:55:54.274001
-527624192.54036528 1983 APR 13 17:42:34.274001
-527614192.54036528 1983 APR 13 20:29:14.274002
-527604192.54036528 1983 APR 13 23:15:54.274002
This routine handles the task of converting a double precision
representation of an epoch to a character string suitable for
human consumption. The more general routine cspice_timout may also be
used to convert `et' to time strings.
1) If the format for the output string is not recognized, the
error SPICE(INVALIDTIMEFORMAT) is signaled by a routine in the
call tree of this routine.
2) If `prec' is less than or equal to zero, it is treated as
zero. If `prec' is greater than 14, it is treated as 14.
3) If one of the ISO formats is specified (ISOC or ISOD) but the
year corresponding to `et' is prior to 1 A.D. on the Gregorian
Calendar, the error SPICE(YEAROUTOFRANGE) is signaled by a
routine in the call tree of this routine.
4) Epochs prior to 15 Oct, 1582 on the Gregorian calendar (the
calendar commonly used in western societies) are returned in
the "extended" Gregorian Calendar. To convert epochs to the
Julian calendar see the SPICELIB routine GR2JUL.
5) This routine does not attempt to account for variations
in the length of the second that were in effect prior
to Jan 1, 1972. For days prior to that date, we assume
there are exactly 86400 ephemeris seconds. Consequently
the UTC Gregorian calendar strings produced for epochs
prior to Jan 1, 1972 differ from the corresponding
TDB calendar strings by approximately 41.18 seconds.
(TDB Gregorian calendar strings are produced by the
routine cspice_etcal).
6) If a leapseconds kernel has not been loaded prior to calling
this routine, an error is signaled by a routine in the
call tree of this routine.
7) If any of the input arguments, `et', `format' or `prec', is
undefined, an error is signaled by the IDL error handling
system.
8) If any of the input arguments, `et', `format' or `prec', is
not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
9) If the output argument `utcstr' is not a named variable, an
error is signaled by the Icy interface.
A leapseconds kernel must be loaded via cspice_furnsh prior to calling
this routine. The kernel need be loaded only once during a program
run.
None.
ICY.REQ
TIME.REQ
[1] J. Jespersen and J. Fitz-Randolph, "From Sundials to Atomic
Clocks, Understanding Time and Frequency," Dover
Publications, Inc. New York, 1982.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.2, 24-AUG-2021 (JDR)
Edited the header to comply with NAIF standard. Added
example's problem statement and meta-kernel. Reformatted example's
output.
Added -Parameters, -Particulars, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.1.1, 05-FEB-2008 (EDW)
Edited -I/O section, replaced comment
"returns with the same order"
with
"returns with the same measure of vectorization"
-Icy Version 1.1.0, 12-SEP-2004 (EDW)
Added capability to process vector 'et' input
returning a vector 'utcstr' on output.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
ephemeris time to utc
|