[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
http://naif.jpl.nasa.gov/naif/utilities.html
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
point.
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
ellipsoid.
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,
-Nat
Using an Earth surface site as an ephemeris object
==================================================
Note: a list of references is included at the bottom of this
discussion.
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:
http://naif.jpl.nasa.gov/naif/data.html
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
form
NAIF_BODY_NAME += 'MY_OBJECT_NAME'
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
http://naif.jpl.nasa.gov/naif/utilities.html
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
details.
To see examples topocentric frame specifications, see
the NAIF topocentric frame kernel for the DSN stations:
ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/
fk/stations/earth_topo_050714.tf
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:
ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck
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
instead.)
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.
References
==========
PINPOINT User's Guide
http://naif.jpl.nasa.gov/naif/utilities.html
(Follow links for your platform)
NAIF_IDs tutorial
ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/
pdf/individual_docs/06_naif_ids.pdf
Text kernel tutorial
ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/
pdf/individual_docs/08_intro_to_kernels.pdf
PCK tutorials
ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/
pdf/individual_docs/20_pck.pdf
ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/
pdf/individual_docs/25_lunar-earth_pck-fk.pdf
SPICE Toolkit Required Reading
http://naif.jpl.nasa.gov/naif/documentation.html
(Follow links for your platform)
Also included in your SPICE Toolkit under /doc
SPICE binary PCK programming Lesson
ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/
PCK file aareadme.txt file on NAIF ftp site:
ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/aareadme.txt
DSN station topocentric frame kernel on NAIF ftp site:
ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/fk/stations/
earth_topo_050714.tf
Comments from DSN station SPK file on NAIF ftp site
ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/stations/
earthstns_itrf93_050714.cmt
>
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,
Michael
_______________________________________________
Spice_discussion mailing list
Spice_discussion at naif.jpl.nasa.gov
http://naif.jpl.nasa.gov/mailman/listinfo/spice_discussion
More information about the Spice_discussion
mailing list