[Spice_discussion] Solar zenith angle and azimuth

Nat Bachman nathaniel.bachman at jpl.nasa.gov
Wed Jun 30 15:46:21 PDT 2010

Dear Dr. Aye,

Hello, this is from Nat Bachman. I'm a member of
the NAIF team headed by Chuck Acton.

SPICE does not contain a subroutine to
compute solar azimuth and elevation (zenith angle
is the complement of elevation). There are two basic
approaches to the solution:

    1) If you have a "small" number of surface points
       of interest, use the SPICE utility PINPOINT
       to create an SPK file providing locations of
       these points and a frame kernel providing
       topocentric frame specifications. Then
       proceed as you've described.

       PINPOINT is available from the utilities area
       of the NAIF web site at URL


       I've also included below some notes on running PINPOINT
       to generate SPICE kernels for surface points on
       the *Earth*. Most of the discussion applies to Mars,
       but for Mars you won't need the high-precision
       Earth PCK; instead you'd use the either the generic
       NAIF text PCK to provide Mars orientation, or you'd
       use a PCK of your own choosing (perhaps a standard
       one used by your project).

    2) If you have too many surface points for (1)
       to be practical, create at run time the
       necessary surface-point-to-sun vectors
       and topocentric frames for each surface point.

       The surface point to sun vectors can be created by
       subtracting the respective Mars-centered surface
       vectors from the Mars to sun vector; this is valid
       as long as the aberration corrections don't have to
       exact (and for most purposes they need not be).
       Reception-style light time and stellar aberration
       corrections should be used for a realistic approximation
       of the apparent direction to the Sun. Here Mars is
       the observer, the Sun is the target, and the epoch
       is that at which photons are received at the surface
       point. Note that if the illumination at the surface point is
       being observed by a remote sensing instrument, this epoch
       may be the epoch of photon reception at the instrument minus
       one way light time between the instrument and the surface

       Each topocentric frame can be represented by a
       3x3 matrix that converts vectors from the body-fixed
       frame associated with the central body
       to the topocentric frame associated
       with the surface point of interest.

       For a given surface location, the desired
       transformation matrix has as its rows the basis vectors
       of the associated topocentric frame. For all locations
       except at or extremely near the poles, these vectors
       are (listed in the order of computation):

           [Here x denotes the cross product]

           Row 3: (Z-axis) the unit zenith direction vector
                  expressed in the central body's body-fixed,
                  body centered reference frame (IAU_MARS, in
                  your case).
           Row 2: (Y-axis) the zenith direction x the body's north
                  pole direction (0,0,1), scaled to unit length.
           Row 1: (X-axis) Y x Z, scaled to unit length.

           At the poles this definition goes singular.

       It's usually convenient to call the SPICE routine UCRSS to
       obtain a unit-length cross product.

       Usually (and it is done this way in PINPOINT) the zenith direction
       is taken as the direction of increasing altitude in the planetodetic
       coordinate system; this direction is parallel to the normal to
       the central body's reference spheroid that passes through the
       surface point.

       One has to be a bit careful here because the surface
       point might not lie on the reference spheroid. If it does, call
       SURFNM to obtain the surface normal direction. If it doesn't,
       call RECGEO to find the planetodetic coordinates of
       the surface point, next find the point at the same planetodetic
       lon/lat but at zero altitude; convert those coordinates back to
       the rectangular system, and finally call SURFNM to obtain
       the surface normal, which is also the desired zenith direction.
       Note that none of the above works for a truly triaxial reference

       The radii of the reference spheroid can be obtained by calling
       either of the SPICE routines BODVCD or BODVRD; one must first
       have loaded a PCK file that contains the radii.

       With the matrix in hand, left-multiplying the surface-sun vector
       transforms it to the corresponding topocentric frame.

Please let us know if you have further questions.

Best regards,


Using an Earth surface site as an ephemeris object

Note: a list of references is included at the bottom of this

Before creating new kernels, it may be worthwhile
to check the NAIF web site to see whether
the location of interest is covered by kernels
already provided by NAIF:


If the data you need are not available, you can create
the kernels you need by following these steps:

1) Decide on a name and ID code for the site of
interest. In order to enable use of the name in SPICE
API calls, create a text kernel that establishes the
name/ID code mapping. Applications that require this
mapping should load this kernel at run time.
This is done by kernel variable definitions of the

  NAIF_BODY_CODE += nnnnnn

where 'MY_OBJECT_NAME' is replaced by the actual
name enclosed in single quotes, and nnnnnn is replaced
by an integer ID code that doesn't conflict with any
other you or other consumers of your new kernels
will be using. The kernel must start with the \begindata
control sequence (this is supposed to read "backslash
begindata" but might not appear that way, depending on
your e-mail client).

The kernel including these assignments must conform
to the SPICE text kernel format; see the "Intro to Kernels"
tutorial cited under "References" for details.

See the NAIF_IDS Required Reading or tutorial for further details.

2) Use the SPICE utility PINPOINT to create an SPK file
for the site. PINPOINT is available from the NAIF
web site. The PINPOINT user's guide is available from
the web site as well; also, you can make PINPOINT
print out the user's guide text by typing

    pinpoint -help

See the URL


to obtain a PINPOINT executable for your platform.

Create a "definitions file" for your site (see PINPOINT User's Guide).
Normally the reference frame for your site location data should
be ITRF93. For *very* low-accuracy work, the frame IAU_EARTH
can be used. Note that inertially referenced site locations
can be in error by as much as ~6 km if IAU_EARTH is used.
If your site location data are in a frame that is substantially
different from ITRF93, you may need to transform them to the
ITRF93 frame before providing them to PINPOINT.

Run PINPOINT to create an SPK file for the site.

Note that PINPOINT can create one SPK file providing data for
multiple sites.

3) If you need to compute geometry relative to a topocentric
(local level) reference frame centered at the surface site, you'll
also need to create a topocentric frame kernel for that site.
The easiest way to do this is to use PINPOINT's topocentric
frame kernel generation feature. See the PINPOINT User's guide for

To see examples topocentric frame specifications, see
the NAIF topocentric frame kernel for the DSN stations:


See the comments in this frame kernel (it's a text file) for details
concerning its contents.

Having defined a topocentric frame centered at the surface site,
you can use the name of this frame in calls to any SPICE routine
that requires a frame name as input.

4) Obtain one or more binary Earth PCK kernels to provide
Earth orientation data. These kernels can be obtained from
the NAIF ftp site:


See the aareadme.txt file there for a discussion of the types
of binary Earth PCKs that are available.

Once you have the SPK kernel, name/ID code mapping kernel,
and binary Earth PCK file loaded these into your application,
your application can call the SPK API routines (such as SPKEZR
or SPKPOS) to compute position or state vectors using the surface
site as an observer or target.

5) Validate your kernels.

  - Look up the Earth-surface site vector in the ITRF93 frame using
    SPKEZR. Check position and velocity against your input data.

  - Check the topocentric frame kernel, if you've created one. If this
    frame has been specified to be consistent with the frames NAIF
    defines for the DSN, the +X axis should point north, the +Y axis
    west, and the +Z axis "up."

    Note that the axes of the topocentric frame, expressed relative to
    ITRF93, can be picked off from the rows of the ITRF93-to-topocentric
    frame transformation matrix returned by the SPICE routine PXFORM.
    The SPICE routines UCRSS (unit cross product) and VSEP (3-d vector
    angular separation) can be helpful for vector comparisons.

  - You also can obtain the outward normal vector on the Earth reference
    ellipsoid at your site's longitude and geodetic latitude; this vector
    should be parallel to your topocentric frame's +Z axis. To do this,
    convert the site location to geodetic coordinates using RECGEO; then
    use the resulting latitude and longitude and an altitude value of 0
    as inputs to GEOREC to produce a point on the reference ellipsoid at
    the same latitude and longitude of your site. Call the SPICE routine
    SURFNM to obtain the outward normal vector at this point. **Note: unless
    your site has an altitude of 0, don't input its Cartesian coordinates
    directly into SURFNM; the resulting computation will produce a normal
    vector for a different ellipsoid than the one you want to use.**

After following these steps, you can get the state of a target ephemeris object,
as seen from the surface site, using just one SPICE call: SPKEZR returns the
observer-target state vector, expressed in a user-specified reference frame, at a
specified observation time. (If velocity is not needed, SPKPOS can be called

Target azimuth and elevation can be obtained using a second SPICE call:
after a call to SPKEZR or SPKPOS, where the reference frame used is the topocentric
frame associated with the surface site, a subsequent call to RECLAT yields
the elevation and longitude of the target in that frame. Negating longitude
yields azimuth.

One note of caution: a variety of "local level" and "azimuth"
definitions exist. The instructions above are compatible with
definitions used by NAIF. Check these against your requirements;
some adjustments might be needed for your application.


PINPOINT User's Guide
  (Follow links for your platform)

NAIF_IDs tutorial


Text kernel tutorial

PCK tutorials



SPICE Toolkit Required Reading

   (Follow links for your platform)

  Also included in your SPICE Toolkit under /doc

SPICE binary PCK programming Lesson


PCK file aareadme.txt file on NAIF ftp site:


DSN station topocentric frame kernel on NAIF ftp site:


Comments from DSN station SPK file on NAIF ftp site


Dear all,

is it possible with SPICE to calculate on an arbitrary coordinate on the Mars 
surface at an arbitrary epoch to calculate the local sun zenith angle and the 
azimuth of the sun?

I searched around a lot in the SPICE docs, but it seems that one always needs an 
observer frame, but I was hoping that this calculations are possible without 
having to write my own frame kernel.
I am aware that I need to define my local frame at my surface point on Mars, but 
I am not sure how.
Any help or hint for the right spot in the docs would be appreciated.

Best regards,
Spice_discussion mailing list
Spice_discussion at naif.jpl.nasa.gov

More information about the Spice_discussion mailing list