Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page et2lst_c

Table of contents

Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries

#### Procedure

       et2lst_c ( ET to Local Solar Time )

       void et2lst_c ( SpiceDouble        et,
                       SpiceInt           body,
                       SpiceDouble        lon,
                       ConstSpiceChar   * type,
                       SpiceInt           timlen,
                       SpiceInt           ampmlen,
                       SpiceInt         * hr,
                       SpiceInt         * mn,
                       SpiceInt         * sc,
                       SpiceChar        * time,
                       SpiceChar        * ampm )

#### Abstract

       Compute the local solar time for a given ephemeris epoch `et'
       for an object on the surface of a body at a specified longitude.

#### Required_Reading

       TIME

#### Keywords

       TIME

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       et         I   Epoch in seconds past J2000 epoch.
       body       I   ID-code of the body of interest.
       lon        I   Longitude of surface point (RADIANS).
       type       I   Type of longitude "PLANETOCENTRIC", etc.
       timlen     I   Available room in output time string.
       ampmlen    I   Available room in output `ampm' string.
       hr         O   Local hour on a "24 hour" clock.
       mn         O   Minutes past the hour.
       sc         O   Seconds past the minute.
       time       O   String giving local time on 24 hour clock.
       ampm       O   String giving time on A.M./ P.M. scale.

#### Detailed_Input

       et          is the epoch expressed in TDB seconds past
                   the J2000 epoch at which a local time is desired.

       body        is the NAIF ID-code of a body on which local
                   time is to be measured.

       lon         is the longitude (either planetocentric or
                   planetographic) in radians of the site on the
                   surface of body for which local time should be
                   computed.

       type        is the form of longitude supplied by the variable
                   lon. Allowed values are "PLANETOCENTRIC" and
                   "PLANETOGRAPHIC".  Note the case of the letters
                   in type is insignificant. Both "PLANETOCENTRIC"
                   and "planetocentric" are recognized. Leading and
                   trailing blanks in type are not significant.

       timlen      is the maximum allowed length of the output time string.
                   This length must large enough to hold the time string
                   plus the terminator. If the output string is expected to
                   have x characters, timlen needs to be x + 1.

       ampmlen     is the maximum allowed length of the output `ampm' string.
                   This length must large enough to hold the apmpm string
                   plus the terminator. If the output string is expected to
                   have x characters, ampmlen needs to be x + 1.

#### Detailed_Output

       hr          is the local "hour" of the site specified at the epoch
                   `et'. Note that an "hour" of local time does not have the
                   same duration as an hour measured by conventional clocks.
                   It is simply a representation of an angle. See
                   -Particulars for a more complete discussion of the meaning
                   of local time.

       mn          is the number of "minutes" past the hour of the local
                   time of the site at the epoch `et'. Again note that a
                   "local minute" is not the same as a minute you would
                   measure with conventional clocks.

       sc          is the number of "seconds" past the minute of the local
                   time of the site at the epoch `et'. Again note that a
                   "local second" is not the same as a second you would
                   measure with conventional clocks.

       time        is a string expressing the local time on a "24 hour"
                   local clock.

       ampm        is 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.

#### Parameters

       None.

#### Exceptions

       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 are 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 the `type' input string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       7)  If the `type' input string has zero length, the error
           SPICE(EMPTYSTRING) is signaled.

       8)  If any of the `time' or `ampm' output string pointers is null,
           the error SPICE(NULLPOINTER) is signaled.

       9)  If any of the `time' or `ampm' output strings has length less
           than two characters, the error SPICE(STRINGTOOSHORT) is
           signaled, since the output string is too short to contain one
           character of output data plus a null terminator.

#### Files

       Suitable SPK and PCK files must be loaded prior to calling this
       routine so that the bodyfixed position of the sun relative to `body'
       can be computed.

       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.

#### Particulars

       This routine returns the local solar time at a user
       specified location on a user specified body.

       Let SUNLNG be the planetocentric longitude (in degrees) of
       the sun as viewed from the center of the body of interest.

       Let SITLNG be the planetocentric longitude (in degrees) of
       the site for which local time is desired.

       We define local time to be 12 + (SITLNG - SUNLNG)/15

       (where appropriate care is taken to map ( SITLNG - SUNLNG )
       into the range from -180 to 180).

       Using this definition, we see that from the point of view
       of this routine, local solar time is simply a measure of angles
       between meridians on the surface of a body. Consequently,
       this routine is not appropriate for computing "local times"
       in the sense of Pacific Standard Time. For computing times
       relative to standard time zones on earth, see the routines
       timout_c and str2et_c.

       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 furnsh_c.

#### Examples

       The numerical results shown for this example may differ across
       platforms. The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, and the machine
       specific arithmetic implementation.

       1) The following code example illustrates how to compute the
          local time at a site on Mars with planetographic longitude
          +326.17 deg at epoch `et'.

          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
                naif0012.tls                  Leapseconds

             \begindata

                KERNELS_TO_LOAD = ( 'de421.bsp',
                                    'pck00010.tpc',
                                    'naif0012.tls'  )

             \begintext

             End of meta-kernel

          Example code begins here.

          /.
             Program et2lst_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main ()
          {
             #define META            "et2lst_ex1.tm"

             #define TIMLEN          51
             #define AMPMLEN         51
             #define MARS            499
             #define TYPE            "PLANETOGRAPHIC"

             SpiceChar               ampm  [ AMPMLEN ];
             SpiceChar               time  [ TIMLEN  ];
             SpiceChar             * utcstr;

             SpiceDouble             dlon;
             SpiceDouble             et;
             SpiceDouble             rlon;

             SpiceInt                hr;
             SpiceInt                mn;
             SpiceInt                sc;

             /.
             Load the kernels.
             ./
             furnsh_c ( META );

             dlon   =  326.17;
             rlon   =  dlon * rpd_c();
             utcstr = "2002 SEP 02 00:00:00";

             str2et_c ( utcstr, &et );

             et2lst_c ( et,  MARS, rlon, TYPE, TIMLEN, AMPMLEN,
                        &hr, &mn,  &sc,  time, ampm             );

             printf ( "The local time at Mars %6.2f degrees "
                      "planetographic longitude:\n", dlon       );
             printf ( "   at UTC %s, LST = %s\n", utcstr, ampm  );

             return ( 0 );
          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, the output was:

          The local time at Mars 326.17 degrees planetographic longitude:
             at UTC 2002 SEP 02 00:00:00, LST = 03:25:35 A.M.

#### Restrictions

       1)  This routine relies on being able to determine the name of the
           bodyfixed 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
           bodyfixed frame name. See the FRAMES Required Reading for more
           details on specifying this relationship.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       W.L. Taber          (JPL)

#### Version

       -CSPICE Version 2.0.1, 01-NOV-2021 (JDR)

           Edited the header to comply with NAIF standard. Added
           example's meta-kernel. Reformatted example's solution.

       -CSPICE Version 2.0.0, 03-NOV-2005 (NJB)

           Bug fix: treatment of planetographic longitude has been
           updated 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
           (see -Particulars above).

       -CSPICE Version 1.0.0, 02-SEP-2002 (NJB) (WLT)

#### Index_Entries

       Compute the local time for a point on a body.

#### Link to routine et2lst_c source file et2lst_c.c

    Fri Dec 31 18:41:06 2021