[Spice_discussion] Solar zenith angle and azimuth

[K. -Michael Aye]

Yes, a very nice complete (it seems, didn't try everything yet) description, many thanks, Nat!

However, we found an alternative way, and are wondering if it's really equivalent or if we will have errors doing it this way, that we don't see yet.
Here is what we found:

First assumption: Local time of a surface point is analog to the sun's azimuth. 
(We need this to calculate the solar irradiation times on elevated topographical features)

Then, cspice_et2lst provides the local time for any surface point of a body.

Furthermore, cspice_ilumin provides the illumination angles for a surface point on a body and we just pick any observer and from the output we only use the incidence angle for the sun's elevation.
The inputs we are using for ilumin is IAU_MARS for fixref, and srfrec to convert the given surface point into rectangular coordinates as required for the 'spoint' input.

Does that sound ok or are we doing some big mistakes here?

Best regards,
Michael


On 1-Jul-2010, at 13:19 , Joe Knapp wrote:

> Excellent description--thanks. I was working on the same problem.
> 
> Question: to get the apparent elevation (zenith angle), is a parallax
> correction to the elevation needed? Refraction?
> 
> Joe
> 
> On Wed, Jun 30, 2010 at 6:46 PM, Nat Bachman
> <nathaniel.bachman at jpl.nasa.gov> wrote:
>> 
>> 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
>> _______________________________________________
>> Spice_discussion mailing list
>> Spice_discussion at naif.jpl.nasa.gov
>> http://naif.jpl.nasa.gov/mailman/listinfo/spice_discussion
>>