Table of contents
CSPICE_ET2LST computes the local solar time for a given ephemeris epoch
`et' for an object on the surface of a body at a specified longitude.
Given:
et the epoch expressed in TDB seconds past the J2000 epoch at which
a local time is desired.
help, et
DOUBLE = Scalar or DOUBLE = Array[N]
body the NAIF ID-code of a body on which local time is to be
measured.
help, body
LONG = Scalar
lon the longitude (either planetocentric or planetographic) in
radians of the site on the surface of body for which local time
should be computed.
help, lon
DOUBLE = Scalar
type the form of longitude supplied by the variable `lon'.
help, type
STRING = Scalar
Allowed values are:
'PLANETOCENTRIC'
'PLANETOGRAPHIC'
Note the case of the letters in `type' is insignificant.
Both 'PLANETOCENTRIC' and 'planetocentric' are
recognized.
the call:
cspice_et2lst, et, body, lon, type, hr, mn, sc, time, ampm
returns:
hr the local "hour" of the site specified at the epoch `et'.
help, hr
LONG = Scalar or LONG = Array[N]
Note that a "hour" of local time does not have the same
duration as a hour measured by conventional clocks. It is simply
a representation of an angle. See the -Particulars section for a
more complete discussion of the meaning of local time.
mn the number of "minutes" past the hour of the local time of the
site at the epoch `et'.
help, mn
LONG = Scalar or LONG = Array[N]
Again note that a "local minute" is not the same as a minute
you would measure with conventional clocks.
sc the number of "seconds" past the minute of the local time of the
site at the epoch `et'.
help, sc
LONG = Scalar or LONG = Array[N]
Again note that a "local second" is not the same as a second
you would measure with conventional clocks.
time a string expressing the local time on a "24 hour" local clock.
help, time
STRING = Scalar or STRING = Array[N]
ampm a string expressing the local time on a "12 hour" local clock
together with the traditional AM/PM label to indicate whether
the sun has crossed the local zenith meridian.
help, ampm
STRING = Scalar or STRING = Array[N]
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) Compute the local time at particular location on Mars, for
several epochs.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: et2lst_ex1.tm
This meta-kernel is intended to support operation of SPICE
example programs. The kernels shown here should not be
assumed to contain adequate or correct versions of data
required by SPICE-based user applications.
In order for an application to use this meta-kernel, the
kernels referenced here must be present in the user's
current working directory.
The names and contents of the kernels referenced
by this meta-kernel are as follows:
File name Contents
--------- --------
de421.bsp Planetary ephemeris
pck00010.tpc Planet orientation and
radii
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'pck00010.tpc' )
\begintext
End of meta-kernel
Example code begins here.
PRO et2lst_ex1
;;
;; Define an arbitrary ephemeris time,
;; (July 4 2004 18:00:00) target body,
;; longitude (rads) and, the type of longitude.
;;
et = 142236064.18399799d
body = 499
lon = 326.17d * cspice_rpd()
type = 'PLANETOCENTRIC'
SIZE = 5
;;
;; Load an SPK and a PCK.
;;
cspice_furnsh, 'et2lst_ex1.tm'
;;
;; Calculate the local solar time defined by the inputs.
;;
cspice_et2lst, et, body, lon, type, $
hr, mn, sc , time, ampm
print, 'Scalar:'
print, 'ET : ', et
print, 'Body : ', body
print, 'Longitude: ', lon
print, 'Type : ', type
print, 'LST Hour : ', hr
print, 'LST Min : ', mn
print, 'LST Sec : ', sc
print, 'LST Time : ', time
print, 'LST AMPM : ', ampm
print
;;
;; Convert the array of ephemeris times 'et' to
;; arrays of local solar time values. 'et' ranges
;; from value 142236064.18399799 in steps of
;; 10000 ephemeris seconds.
;;
et = dindgen(SIZE)*10000.d + 142236064.18399799d
cspice_et2lst, et, body, lon, type, $
hr, mn, sc , time, ampm
print, 'Vector:'
for i=0, (SIZE-1) do begin
print, 'ET : ', et[i]
print, 'LST Hour : ', hr[i]
print, 'LST Min : ', mn[i]
print, 'LST Sec : ', sc[i]
print, 'LST Time : ', time[i]
print, 'LST AMPM : ', ampm[i]
print
endfor
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Scalar:
ET : 1.4223606e+08
Body : 499
Longitude: 5.6927404
Type : PLANETOCENTRIC
LST Hour : 17
LST Min : 29
LST Sec : 33
LST Time : 17:29:33
LST AMPM : 05:29:33 P.M.
Vector:
ET : 1.4223606e+08
LST Hour : 17
LST Min : 29
LST Sec : 33
LST Time : 17:29:33
LST AMPM : 05:29:33 P.M.
ET : 1.4224606e+08
LST Hour : 20
LST Min : 11
LST Sec : 47
LST Time : 20:11:47
LST AMPM : 08:11:47 P.M.
ET : 1.4225606e+08
LST Hour : 22
LST Min : 54
LST Sec : 2
LST Time : 22:54:02
LST AMPM : 10:54:02 P.M.
ET : 1.4226606e+08
LST Hour : 1
LST Min : 36
LST Sec : 16
LST Time : 01:36:16
LST AMPM : 01:36:16 A.M.
ET : 1.4227606e+08
LST Hour : 4
LST Min : 18
LST Sec : 30
LST Time : 04:18:30
LST AMPM : 04:18:30 A.M.
Regarding planetographic longitude
----------------------------------
In the planetographic coordinate system, longitude is defined using
the spin sense of the body. Longitude is positive to the west if
the spin is prograde and positive to the east if the spin is
retrograde. The spin sense is given by the sign of the first degree
term of the time-dependent polynomial for the body's prime meridian
Euler angle "W": the spin is retrograde if this term is negative
and prograde otherwise. For the sun, planets, most natural
satellites, and selected asteroids, the polynomial expression for W
may be found in a SPICE PCK kernel.
The earth, moon, and sun are exceptions: planetographic longitude
is measured positive east for these bodies.
If you wish to override the default sense of positive planetographic
longitude for a particular body, you can do so by defining the
kernel variable
BODY<body ID>_PGR_POSITIVE_LON
where <body ID> represents the NAIF ID code of the body. This
variable may be assigned either of the values
'WEST'
'EAST'
For example, you can have this routine treat the longitude of the
earth as increasing to the west using the kernel variable assignment
BODY399_PGR_POSITIVE_LON = 'WEST'
Normally such assignments are made by placing them in a text kernel
and loading that kernel via cspice_furnsh.
1) This routine defines local solar time for any point on the
surface of the Sun to be 12:00:00 noon.
2) If the `type' of the coordinates is not recognized, the error
SPICE(UNKNOWNSYSTEM) is signaled by a routine in the call tree
of this routine.
3) If the body-fixed frame to associate with `body' cannot be
determined, the error SPICE(CANTFINDFRAME) is signaled by a
routine in the call tree of this routine.
4) If insufficient data is available to compute the location of
the sun in body-fixed coordinates, an error is signaled by a
routine in the call tree of this routine.
5) If the BODY#_PM keyword required to determine the body
rotation sense is not found in the POOL or if it is found but
is not a numeric keyword with at least two elements, the error
SPICE(CANTGETROTATIONTYPE) is signaled by a routine in the
call tree of this routine.
6) If any of the input arguments, `et', `body', `lon' or `type',
is undefined, an error is signaled by the IDL error handling
system.
7) If any of the input arguments, `et', `body', `lon' or `type',
is not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
8) If any of the output arguments, `hr', `mn', `sc', `time' or
`ampm', is not a named variable, an error is signaled by the
Icy interface.
Suitable SPK and PCK files must be loaded prior to calling this
routine so that the body-fixed position of the sun relative to
`body' can be computed. The PCK files must contain the standard
BODY#_PM keyword need by this routine to determine the body
rotation sense.
When the input longitude is planetographic, the default
interpretation of this value can be overridden using the optional
kernel variable
BODY<body ID>_PGR_POSITIVE_LON
which is normally defined via loading a text kernel.
1) This routine relies on being able to determine the name
of the body-fixed frame associated with `body' through the
frames subsystem. If the `body' specified is NOT one of the
nine planets or their satellites, you will need to load
an appropriate frame definition kernel that contains
the relationship between the body id and the body-fixed frame
name. See frames.req required reading for more details
on specifying this relationship.
2) The routine determines the body rotation sense using the PCK
keyword BODY#_PM. Therefore, you will need to a text PCK file
defining the complete set of the standard PCK body rotation
keywords for the body of interest. The text PCK file must be
loaded independently of whether a binary PCK file providing
rotation data for the same body is loaded or not.
3) Although it is not currently the case for any of the Solar
System bodies, it is possible that the retrograde rotation
rate of a body would be slower than the orbital rate of the
body rotation around the Sun. The routine does not account for
such cases; for them it will compute incorrect the local time
progressing backwards.
ICY.REQ
TIME.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.4, 01-NOV-2021 (JDR)
Edited the header to comply with NAIF standard. Added example's
problem statement and required input meta-kernel.
Added -Parameters, -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.0.3, 05-JAN-2011 (EDW)
Corrected header typo, furnsh_c replaced with cspice_furnsh.
-Icy Version 1.0.2, 29-JAN-2009 (EDW)
Minor edits to header text.
Replace argument description comment
"returns with the same order"
with
"returns with the same measure of vectorization"
-Icy Version 1.0.1, 07-NOV-2005 (EDW)
The treatment of planetographic longitude has been
updated in et2lst_c.c to be consistent with the
SPICE planetographic/rectangular coordinate conversion
routines. The effect of this change is that the
default sense of positive longitude for the moon is
now east; also, the default sense of positive
planetographic longitude now may be overridden for
any body.
-Icy Version 1.0.0, 20-SEP-2004 (EDW)
Compute the local time for a point on a body.
|