From 1c6080387e9fda13172ce5b69b01019136fc9968 Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Wed, 22 Aug 2018 17:25:03 -0400 Subject: [PATCH 01/11] Documentation Changes * updated docs and readme to point to conda-forge installation for now on * inserted NAIF Python Lessons into the docs with minimal modification --- README.rst | 22 +- docs/binary_pck.rst | 920 ++++++++++++++ docs/event_finding.rst | 1218 +++++++++++++++++++ docs/insitu_sensing.rst | 1453 +++++++++++++++++++++++ docs/installation.rst | 85 +- docs/lessonindex.rst | 11 +- docs/other_stuff.rst | 2237 +++++++++++++++++++++++++++++++++++ docs/remote_sensing.rst | 2500 +++++++++++++++++++++++++++++++++++++++ 8 files changed, 8436 insertions(+), 10 deletions(-) create mode 100644 docs/binary_pck.rst create mode 100644 docs/event_finding.rst create mode 100644 docs/insitu_sensing.rst create mode 100644 docs/other_stuff.rst create mode 100644 docs/remote_sensing.rst diff --git a/README.rst b/README.rst index d31c5983..e22f01ea 100644 --- a/README.rst +++ b/README.rst @@ -46,11 +46,23 @@ about SpiceyPy, usership, and how it works please cite my 2017 abstract, availab Installation ------------ -First install the dependencies (numpy, six, pytest) for the project. Then -run ``pip install spiceypy`` to install from pypi. - -SpiceyPy is also available through conda by either first installing pip via conda or by running -``conda install -c https://conda.anaconda.org/andrewannex spiceypy``. ++----------------+-------------------+ +| PyPI | Conda Forge | ++================+===================+ +| |PyPI| | |Conda Version| | ++----------------+-------------------+ + +.. |PyPI| image:: https://img.shields.io/pypi/v/spiceypy.svg + :target: https://pypi.org/project/spiceypy/ +.. |Conda Version| image:: https://img.shields.io/conda/vn/conda-forge/spiceypy.svg + :target: https://anaconda.org/conda-forge/spiceypy + +SpiceyPy can be installed using pip by running: +``pip install spiceypy`` + +Anaconda users should use the conda-forge distribution of SpiceyPy by running: +``conda config --add channels conda-forge`` +``conda install spiceypy`` If you wish to install spiceypy from source first download or clone the project. Then run ``python setup.py install``. To uninstall run ``pip uninstall spiceypy``. diff --git a/docs/binary_pck.rst b/docs/binary_pck.rst new file mode 100644 index 00000000..b69cf9af --- /dev/null +++ b/docs/binary_pck.rst @@ -0,0 +1,920 @@ +Binary PCK Hands-On Lesson (Python) +=================================== + +November 20, 2017 + +Overview +-------- + +In this lesson you will develop two programs that demonstrate geometric +computations using \``high-accuracy’’ Earth and Moon binary PCKs. The +programs also demonstrate use of frame kernels and SPK files normally +used together with these high-accuracy PCKs. + +References +---------- + +This section lists SPICE documents referred to in this lesson. + +The following SPICE tutorials serve as references for the discussions in +this lesson: + +:: + + Name Lesson steps/functions it describes + ---------------- ----------------------------------------------- + Frames Moon rotation, Earth rotation + PCK Moon rotation, Earth rotation + ``High Accuracy + Orientation and + Body-Fixed + frames for Moon + and Earth'' + (backup) Moon rotation, Earth rotation + +These tutorials are available from the NAIF ftp server at JPL: + +:: + + http://naif.jpl.nasa.gov/naif/tutorials.html + +Required Readings + +The Required Reading documents are provided with the Toolkit and are +located under the \``cspice/doc’’ directory in the CSPICE Toolkit +installation tree. + +:: + + Name Lesson steps/functions that it describes + --------------- ----------------------------------------- + frames.req Using reference frames + pck.req Obtaining planetary constants data + spk.req Obtaining ephemeris data + time.req Time conversion + +The Permuted Index + +Another useful document distributed with the Toolkit is the permuted +index. This is located under the \``cspice/doc’’ directory in the C +installation tree. + +This text document provides a simple mechanism by which users can +discover which SpiceyPy functions perform functions of interest, as well +as the names of the source files that contain these functions. + +SpiceyPy API Documentation + +A SpiceyPy function’s parameters specification is available using the +built-in Python help system. A more detailed specification of the API +can be found in the CSPICE HTML API documentation page located under +\``cspice/doc/html/cspice’’. + +For example, the Python help function + +:: + + >>> import spiceypy + >>> help(spiceypy.str2et) + +describes of the str2et function’s parameters, while the document + +:: + + cspice/doc/html/cspice/str2et_c.html + +describes extensively the str2et functionality. + +Kernels Used +------------ + +The following kernels are used in examples provided in this lesson: + +:: + + # FILE NAME TYPE DESCRIPTION + -- ------------------------------ ---- ------------------------------ + 1 naif0008.tls LSK Generic LSK + 2 de414_2000_2020.bsp SPK Solar System Ephemeris + 3 moon_060721.tf FK Lunar FK + 4 pck00008.tpc PCK NAIF text PCK + 5 moon_pa_de403_1950-2198.bpc PCK Moon binary PCK + 6 earthstns_itrf93_050714.bsp SPK DSN station Ephemeris + 7 earth_topo_050714.tf FK Earth topocentric FK + 8 earth_000101_070725_070503.bpc PCK Earth binary PCK + +These SPICE kernels are included in the lesson package available from +the NAIF server at JPL: + +:: + + ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/ + +SpiceyPy Modules Used +--------------------- + +This section provides a complete list of the functions and kernels that +are suggested for usage in each of the exercises in this lesson. (You +may wish to not look at this list unless/until you \``get stuck’’ while +working on your own.) + +:: + + CHAPTER EXERCISE FUNCTIONS NON-VOID KERNELS + ------- --------- --------------- --------------- ---------- + 1 mrotat spiceypy.furnsh spiceypy.str2et 1-5 + spiceypy.unload spiceypy.spkpos + spiceypy.reclat + spiceypy.dpr + spiceypy.vsep + spiceypy.subpnt + spiceypy.vdist + + 2 erotat spiceypy.furnsh spiceypy.str2et 1-2,4,6-8 + spiceypy.unload spiceypy.spkpos + spiceypy.reclat + spiceypy.dpr + spiceypy.vsep + spiceypy.spd + spiceypy.timout + spiceypy.pxform + spiceypy.twopi + spiceypy.subslr + spiceypy.vdist + +Use the Python built-in help system on the various functions listed +above for the API parameters’ description, and refer to the headers of +their corresponding CSPICE versions for detailed interface +specifications. + +Moon rotation (mrotat) +====================== + +Task Statement +-------------- + +Write a program that performs the following computations: + +:: + + 1. Convert the time string 2007 JAN 1 00:00:00 UTC to a double + precision number representing seconds past J2000 TDB. + + In the following instructions, we'll call the result of this + computation ET. + + 2. Compute the apparent position of the Earth as seen from the + Moon in the IAU_MOON reference frame at the epoch ET. Use light + time and stellar aberration corrections. Use spiceypy.reclat to + compute the planetocentric longitude and latitude of the Earth + position vector; display these coordinates in degrees. + + 3. Repeat the computation of step 2 using the MOON_ME reference + frame. Display the results as above. + + 4. Compute the angular separation of the position vectors found in + steps 2 and 3. Display the result in degrees. + + 5. Repeat the computation of step 2 using the MOON_PA reference + frame. Display the results as above. + + 6. Compute the angular separation of the position vectors found in + steps 3 and 5 (these vectors are expressed in the MOON_ME and + MOON_PA frames). Display the result in degrees. + + 7. Compute the apparent sub-Earth point on the Moon at ET, + expressed in the MOON_ME reference frame and using light time + and stellar aberration corrections. Convert the sub-Earth point + to latitudinal coordinates using spiceypy.reclat. Display the + longitude and latitude of the sub-Earth point in degrees. + + 8. Repeat step 7, now using the MOON_PA frame. + + 9. Compute the distance between the two sub-Earth points found + above in steps 7 and 8. Display the result in kilometers. + +Learning Goals +-------------- + +Familiarity with SPICE kernels required to obtain high-accuracy +orientation of the Moon. Understanding the differences between results +obtained using low and high-accuracy Moon orientation data. +Understanding the difference between the MOON_ME and MOON_PA frames. + +Approach +-------- + +The following \``tips’’ may simplify the solution process. + +:: + + -- Examine the SPICE kernels provided with this lesson. Use BRIEF + to find coverage periods of SPK kernels and binary PCKs. Use + COMMNT to view the comment areas of binary PCKs. Examine text + kernels, in particular text kernel comments, using a text + editor or browser. + + -- Decide which SPICE kernels are necessary. Prepare a meta-kernel + listing the kernels and load it into the program. + + -- Consult the above list titled ``SpiceyPy Modules Used'' to see + which routines are needed. + + -- The computational steps listed above should be followed in the + order shown. + +You may find it useful to consult the permuted index, the headers of +various source modules, and the tutorials titled ``PCK'' and``\ High +Accuracy Orientation and Body-Fixed frames for Moon and Earth.’’ + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘mrotat.tm’. Its contents follow: + +:: + + KPL/MK + + Meta-kernel for the ``Moon Rotation'' task in the Binary PCK + Hands On Lesson. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File name Contents + --------------------------- ------------------------------------ + naif0008.tls Generic LSK + de414_2000_2020.bsp Solar System Ephemeris + moon_060721.tf Lunar FK + pck00008.tpc NAIF text PCK + moon_pa_de403_1950-2198.bpc Moon binary PCK + + \begindata + + KERNELS_TO_LOAD = ( 'kernels/lsk/naif0008.tls' + 'kernels/spk/de414_2000_2020.bsp' + 'kernels/fk/moon_060721.tf' + 'kernels/pck/pck00008.tpc' + 'kernels/pck/moon_pa_de403_1950-2198.bpc' ) + \begintext + +Solution Source Code + +A sample solution to the problem follows: + +:: + + # + # Solution mrotat + # + from __future__ import print_function + # + # SpiceyPy package: + # + import spiceypy + + def mrotat(): + # + # Local parameters + # + METAKR = 'mrotat.tm' + + # + # Load the kernels that this program requires. + # + spiceypy.furnsh( METAKR ) + + # + # Convert our UTC string to seconds past J2000 TDB. + # + timstr = '2007 JAN 1 00:00:00' + et = spiceypy.str2et( timstr ) + + # + # Look up the apparent position of the Earth relative + # to the Moon's center in the IAU_MOON frame at ET. + # + [imoonv, ltime] = spiceypy.spkpos( + 'earth', et, 'iau_moon', 'lt+s', 'moon' ) + + # + #Express the Earth direction in terms of longitude + #and latitude in the IAU_MOON frame. + # + [r, lon, lat] = spiceypy.reclat( imoonv ) + + print( '\n' + 'Moon-Earth direction using low accuracy\n' + 'PCK and IAU_MOON frame:\n' + 'Earth lon (deg): {0:15.6f}\n' + 'Earth lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + # + # Look up the apparent position of the Earth relative + # to the Moon's center in the MOON_ME frame at ET. + # + [mmoonv, ltime] = spiceypy.spkpos( 'earth', et, 'moon_me', + 'lt+s', 'moon' ) + # + # Express the Earth direction in terms of longitude + # and latitude in the MOON_ME frame. + # + [r, lon, lat] = spiceypy.reclat( mmoonv ) + + print( 'Moon-Earth direction using high accuracy\n' + 'PCK and MOON_ME frame:\n' + 'Earth lon (deg): {0:15.6f}\n' + 'Earth lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + # + # Find the angular separation of the Earth position + # vectors in degrees. + # + sep = spiceypy.dpr() * spiceypy.vsep( imoonv, mmoonv ) + + print( 'For IAU_MOON vs MOON_ME frames:' ) + print( 'Moon-Earth vector separation angle (deg): ' + '{:15.6f}\n'.format( sep ) ) + # + # Look up the apparent position of the Earth relative + # to the Moon's center in the MOON_PA frame at ET. + # + [pmoonv, ltime] = spiceypy.spkpos( 'earth', et, 'moon_pa', + 'lt+s', 'moon' ) + # + # Express the Earth direction in terms of longitude + # and latitude in the MOON_PA frame. + # + [r, lon, lat] = spiceypy.reclat( pmoonv ) + + print( 'Moon-Earth direction using high accuracy\n' + 'PCK and MOON_PA frame:\n' + 'Earth lon (deg): {0:15.6f}\n' + 'Earth lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + # + # Find the angular separation of the Earth position + # vectors in degrees. + # + sep = spiceypy.dpr() * spiceypy.vsep( pmoonv, mmoonv ) + + print( 'For MOON_PA vs MOON_ME frames:' ) + print( 'Moon-Earth vector separation angle (deg): ' + '{:15.6f}\n'.format( sep ) ) + # + # Find the apparent sub-Earth point on the Moon at ET + # using the MOON_ME frame. + # + [msub, trgepc, srfvec ] = spiceypy.subpnt( + 'near point: ellipsoid', 'moon', + et, 'moon_me', 'lt+s', 'earth' ) + # + # Display the sub-point in latitudinal coordinates. + # + [r, lon, lat] = spiceypy.reclat( msub ) + + print( 'Sub-Earth point on Moon using high accuracy\n' + 'PCK and MOON_ME frame:\n' + 'Sub-Earth lon (deg): {0:15.6f}\n' + 'Sub-Earth lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + # + # Find the apparent sub-Earth point on the Moon at + # ET using the MOON_PA frame. + # + [psub, trgepc, srfvec] = spiceypy.subpnt( + 'near point: ellipsoid', 'moon', + et, 'moon_pa', 'lt+s', 'earth' ) + # + # Display the sub-point in latitudinal coordinates. + # + [r, lon, lat] = spiceypy.reclat( psub ) + + print( 'Sub-Earth point on Moon using high accuracy\n' + 'PCK and MOON_PA frame:\n' + 'Sub-Earth lon (deg): {0:15.6f}\n' + 'Sub-Earth lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + # + # Find the distance between the sub-Earth points + # in km. + # + dist = spiceypy.vdist( msub, psub ) + + print( 'Distance between sub-Earth points (km): ' + '{:15.6f}\n'.format( dist ) ) + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + mrotat() + +Solution Sample Output + +Execute the program: + +:: + + Moon-Earth direction using low accuracy + PCK and IAU_MOON frame: + Earth lon (deg): 3.613102 + Earth lat (deg): -6.438342 + + Moon-Earth direction using high accuracy + PCK and MOON_ME frame: + Earth lon (deg): 3.611229 + Earth lat (deg): -6.439501 + + For IAU_MOON vs MOON_ME frames: + Moon-Earth vector separation angle (deg): 0.002194 + + Moon-Earth direction using high accuracy + PCK and MOON_PA frame: + Earth lon (deg): 3.593319 + Earth lat (deg): -6.417582 + + For MOON_PA vs MOON_ME frames: + Moon-Earth vector separation angle (deg): 0.028235 + + Sub-Earth point on Moon using high accuracy + PCK and MOON_ME frame: + Sub-Earth lon (deg): 3.611419 + Sub-Earth lat (deg): -6.439501 + + Sub-Earth point on Moon using high accuracy + PCK and MOON_PA frame: + Sub-Earth lon (deg): 3.593509 + Sub-Earth lat (deg): -6.417582 + + Distance between sub-Earth points (km): 0.856182 + +Earth rotation (erotat) +======================= + +.. _task-statement-1: + +Task Statement +-------------- + +Write a program that performs the following computations: + +:: + + 1. Convert the time string 2007 JAN 1 00:00:00 UTC to a double + precision number representing seconds past J2000 TDB. + + In the following instructions, we'll call the result of this + computation ET. + + 2. Compute the apparent position of the Moon as seen from the + Earth in the IAU_EARTH reference frame at the epoch ET. Use + light time and stellar aberration corrections. Display the + planetocentric longitude and latitude of the Moon position + vector in degrees. + + 3. Repeat the first computation using the ITRF93 reference frame. + Display the results as above. + + 4. Compute the angular separation of the position vectors found + the the previous two steps. Display the result in degrees. + +The following computations (steps 5-10) examine the cause of the angular +offset found above, which is attributable to the rotation between the +ITRF93 and IAU_EARTH frames. Steps 11 and up don’t rely on the results +of steps 5-10, so steps 5-10 may be safely skipped if they’re not of +interest to you. + +For each of the two epochs ET and ET + 100 days, examine the differences +between the axes of the ITRF93 and IAU_EARTH frames using the following +method: + +:: + + 5. Convert the epoch of interest to a string in the format style + ``2007-MAY-16 02:29:00.000 (UTC).'' Display this string. + + 6. Look up the 3x3 position transformation matrix that converts + vectors from the IAU_EARTH to the ITRF93 frame at the epoch of + interest. We'll call the returned matrix RMAT. + + 7. Extract the first row of RMAT into a 3-vector, which we'll call + ITRFX. This is the X-axis of the ITRF93 frame expressed + relative to the IAU_EARTH frame. + + 8. Extract the third row of RMAT into a 3-vector, which we'll call + ITRFZ. This is the Z-axis of the ITRF93 frame expressed + relative to the IAU_EARTH frame. + + 9. Compute the angular separation between the vector ITRFX and the + X-axis (1, 0, 0) of the IAU_EARTH frame. Display the result in + degrees. + + 10. Compute the angular separation between the vector ITRFZ and the + Z-axis (0, 0, 1) of the IAU_EARTH frame. Display the result in + degrees. + +This is the end of the computations to be performed for the epochs ET +and ET + 100 days. The following steps are part of a new computation. + +Find the azimuth and elevation of the apparent position of the Moon as +seen from the DSN station DSS-13 by the following steps: + +:: + + 11. Find the apparent position vector of the Moon relative to the + DSN station DSS-13 in the topocentric reference frame + DSS-13_TOPO at epoch ET. Use light time and stellar aberration + corrections. + + For this step, you'll need to have loaded a station SPK file + providing geocentric station position vectors, as well as a + frame kernel specifying topocentric reference frames centered + at the respective DSN stations. (Other kernels will be needed + as well; you must choose these.) + + 12. Convert the position vector to latitudinal coordinates. Use the + routine spiceypy.reclat for this computation. + + 13. Compute the Moon's azimuth and elevation as follows: azimuth is + the negative of topocentric longitude and lies within the range + 0-360 degrees; elevation is equal to the topocentric latitude. + Display the results in degrees. + +The next computations demonstrate \``high-accuracy’’ geometric +computations using the Earth as the target body. These computations are +*not* realistic; they are simply meant to demonstrate SPICE system +features used for geometry computations involving the Earth as a target +body. For example, the same basic techniques would be used to find the +sub-solar point on the Earth as seen from an Earth-orbiting spacecraft. + +:: + + 14. Compute the apparent sub-solar point on the Earth at ET, + expressed relative to the IAU_EARTH reference frame, using + light time and stellar aberration corrections and using the Sun + as the observer. Convert the sub-solar point to latitudinal + coordinates using spiceypy.reclat. Display the longitude and + latitude of the sub-solar point in degrees. + + 15. Repeat the sub-solar point computation described above, using + the ITRF93 Earth body-fixed reference frame. Display the + results as above. + + 16. Compute the distance between the two sub-solar points found + above. Display the result in kilometers. + +.. _learning-goals-1: + +Learning Goals +-------------- + +Familiarity with SPICE kernels required to obtain high-accuracy +orientation of the Earth. Understanding the differences between results +obtained using low and high-accuracy Earth orientation data. + +Understanding of topocentric frames and computation of target geometry +relative to a surface location on the Earth. Knowledge of SPICE kernels +required to support such computations. + +.. _approach-1: + +Approach +-------- + +The following \``tips’’ may simplify the solution process. + +:: + + -- Examine the SPICE kernels provided with this lesson. Use BRIEF + to find coverage periods of SPK kernels and binary PCKs. Use + COMMNT to view the comment areas of binary PCKs. Examine text + kernels, in particular text kernel comments, using a text + editor or browser. + + -- Decide which SPICE kernels are necessary. Prepare a meta-kernel + listing the kernels and load it into the program. + + -- Consult the above list titled ``SpiceyPy Modules Used'' to see + which routines are needed. Note the functions used to provide + the values ``seconds per day,'' ``degrees per radian,'' and ``2 + times Pi.'' + + -- Examine the header of the function spiceypy.reclat. Note that + this function may be used for coordinate conversions in + situations where the input rectangular coordinates refer to any + reference frame, not only a body-centered, body-fixed frame + whose X-Y plane coincides with the body's equator. + + -- The computational steps listed above should be followed in the + order shown, but steps 5-10 may be omitted. + +You may find it useful to consult the permuted index, the headers of +various source modules, and the tutorials titled ``PCK'' and``\ High +Accuracy Orientation and Body-Fixed frames for Moon and Earth.’’ + +.. _solution-1: + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘erotat.tm’. Its contents follow: + +:: + + KPL/MK + + Meta-kernel for the ``Earth Rotation'' task + in the Binary PCK Hands On Lesson. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File name Contents + ------------------------------ --------------------------------- + naif0008.tls Generic LSK + de414_2000_2020.bsp Solar System Ephemeris + earthstns_itrf93_050714.bsp DSN station Ephemeris + earth_topo_050714.tf Earth topocentric FK + pck00008.tpc NAIF text PCK + earth_000101_070725_070503.bpc Earth binary PCK + + + \begindata + + KERNELS_TO_LOAD = ( 'kernels/lsk/naif0008.tls' + 'kernels/spk/de414_2000_2020.bsp' + 'kernels/spk/earthstns_itrf93_050714.bsp' + 'kernels/fk/earth_topo_050714.tf' + 'kernels/pck/pck00008.tpc' + 'kernels/pck/earth_000101_070725_070503.bpc' ) + + \begintext + +Solution Source Code + +A sample solution to the problem follows: + +:: + + # + # Solution mrotat + # + from __future__ import print_function + # + # SpiceyPy package: + # + import spiceypy + + def erotat(): + # + # Local parameters + # + METAKR = 'erotat.tm' + + x = [ 1.0, 0.0, 0.0 ] + z = [ 0.0, 0.0, 1.0 ] + + # + # Load the kernels that this program requires. + # + spiceypy.furnsh( METAKR ) + + # + # Convert our UTC string to seconds past J2000 TDB. + # + timstr = '2007 JAN 1 00:00:00' + et = spiceypy.str2et( timstr ) + + # + # Look up the apparent position of the Moon relative + # to the Earth's center in the IAU_EARTH frame at ET. + # + [lmoonv, ltime] = spiceypy.spkpos( 'moon', et, 'iau_earth', + 'lt+s', 'earth' ) + # + # Express the Moon direction in terms of longitude + # and latitude in the IAU_EARTH frame. + # + [r, lon, lat] = spiceypy.reclat( lmoonv ) + + print( 'Earth-Moon direction using low accuracy\n' + 'PCK and IAU_EARTH frame:\n' + 'Moon lon (deg): {0:15.6f}\n' + 'Moon lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + # + # Look up the apparent position of the Moon relative + # to the Earth's center in the ITRF93 frame at ET. + # + [hmoonv, ltime] = spiceypy.spkpos( 'moon', et, 'ITRF93', + 'lt+s', 'earth' ) + # + # Express the Moon direction in terms of longitude + # and latitude in the ITRF93 frame. + # + [r, lon, lat] = spiceypy.reclat( hmoonv ) + + print( 'Earth-Moon direction using high accuracy\n' + 'PCK and ITRF93 frame:\n' + 'Moon lon (deg): {0:15.6f}\n' + 'Moon lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + # + # Find the angular separation of the Moon position + # vectors in degrees. + # + sep = spiceypy.dpr() * spiceypy.vsep( lmoonv, hmoonv ) + + print( 'Earth-Moon vector separation angle (deg): ' + '{:15.6f}\n'.format( sep ) ) + + # + # Next, express the +Z and +X axes of the ITRF93 frame in + # the IAU_EARTH frame. We'll do this for two times: et + # and et + 100 days. + # + for i in range(2): + # + # Set the time, expressing the time delta in + # seconds. + # + t = et + i*spiceypy.spd()*100 + + # + # Convert the TDB time T to a string for output. + # + outstr = spiceypy.timout( + t, 'YYYY-MON-DD HR:MN:SC.### (UTC)' ) + + print( 'Epoch: {:s}'.format( outstr ) ) + + # + # Find the rotation matrix for conversion of + # position vectors from the IAU_EARTH to the + # ITRF93 frame. + # + rmat = spiceypy.pxform( 'iau_earth', 'itrf93', t ) + itrfx = rmat[0] + itrfz = rmat[2] + + # + # Display the angular offsets of the ITRF93 + # +X and +Z axes from their IAU_EARTH counterparts. + # + sep = spiceypy.vsep( itrfx, x ) + + print( 'ITRF93 - IAU_EARTH +X axis separation ' + 'angle (deg): {:13.6f}'.format( + sep * spiceypy.dpr() ) ) + + sep = spiceypy.vsep( itrfz, z ) + + print( 'ITRF93 - IAU_EARTH +Z axis separation ' + 'angle (deg): {:13.6f}\n'.format( + sep * spiceypy.dpr() ) ) + + # + # Find the azimuth and elevation of apparent + # position of the Moon in the local topocentric + # reference frame at the DSN station DSS-13. + # First look up the Moon's position relative to the + # station in that frame. + # + [topov, ltime] = spiceypy.spkpos( 'moon', et, 'DSS-13_TOPO', + 'lt+s', 'DSS-13' ) + + # + # Express the station-moon direction in terms of longitude + # and latitude in the DSS-13_TOPO frame. + # + [r, lon, lat] = spiceypy.reclat( topov ) + + # + # Convert to azimuth-elevation. + # + az = -lon + + if az < 0.0: + az += spiceypy.twopi() + + el = lat + + print( 'DSS-13-Moon az/el using high accuracy ' + 'PCK and DSS-13_TOPO frame:\n' + 'Moon Az (deg): {0:15.6f}\n' + 'Moon El (deg): {1:15.6f}\n'.format( + az * spiceypy.dpr(), + el * spiceypy.dpr() ) ) + + # + # Find the sub-solar point on the Earth at ET using the + # Earth body-fixed frame IAU_EARTH. Treat the Sun as + # the observer. + # + [lsub, trgepc, srfvec] = spiceypy.subslr( + 'near point: ellipsoid', 'earth', et, + 'IAU_EARTH', 'lt+s', 'sun' ); + + # + # Display the sub-point in latitudinal coordinates. + # + [r, lon, lat] = spiceypy.reclat( lsub ) + + print( 'Sub-Solar point on Earth using low accuracy\n' + 'PCK and IAU_EARTH frame:\n' + 'Sub-Solar lon (deg): {0:15.6f}\n' + 'Sub-Solar lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + + # + # Find the sub-solar point on the Earth at ET using the + # Earth body-fixed frame ITRF93. Treat the Sun as + # the observer. + # + [hsub, trgepc, srfvec] = spiceypy.subslr( + 'near point: ellipsoid', 'earth', et, + 'ITRF93', 'lt+s', 'sun' ); + + # + # Display the sub-point in latitudinal coordinates. + # + [r, lon, lat] = spiceypy.reclat( hsub ) + + print( 'Sub-Solar point on Earth using ' + 'high accuracy \nPCK and ITRF93 frame:\n' + 'Sub-Solar lon (deg): {0:15.6f}\n' + 'Sub-Solar lat (deg): {1:15.6f}\n'.format( + lon * spiceypy.dpr(), + lat * spiceypy.dpr() ) ) + + # + # Find the distance between the sub-solar point + # vectors in km. + # + dist = spiceypy.vdist( lsub, hsub ) + + print( 'Distance between sub-solar points (km): ' + '{:15.6f}'.format( dist ) ) + + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + erotat() + +Solution Sample Output + +Execute the program: + +:: + + Earth-Moon direction using low accuracy + PCK and IAU_EARTH frame: + Moon lon (deg): -35.496272 + Moon lat (deg): 26.416959 + + Earth-Moon direction using high accuracy + PCK and ITRF93 frame: + Moon lon (deg): -35.554286 + Moon lat (deg): 26.419156 + + Earth-Moon vector separation angle (deg): 0.052002 + + Epoch: 2007-JAN-01 00:00:00.000 (UTC) + ITRF93 - IAU_EARTH +X axis separation angle (deg): 0.057677 + ITRF93 - IAU_EARTH +Z axis separation angle (deg): 0.002326 + + Epoch: 2007-APR-10 23:59:59.998 (UTC) + ITRF93 - IAU_EARTH +X axis separation angle (deg): 0.057787 + ITRF93 - IAU_EARTH +Z axis separation angle (deg): 0.002458 + + DSS-13-Moon az/el using high accuracy PCK and DSS-13_TOPO frame: + Moon Az (deg): 72.169006 + Moon El (deg): 20.689488 + + Sub-Solar point on Earth using low accuracy + PCK and IAU_EARTH frame: + Sub-Solar lon (deg): -177.100531 + Sub-Solar lat (deg): -22.910377 + + Sub-Solar point on Earth using high accuracy + PCK and ITRF93 frame: + Sub-Solar lon (deg): -177.157874 + Sub-Solar lat (deg): -22.912593 + + Distance between sub-solar points (km): 5.881861 diff --git a/docs/event_finding.rst b/docs/event_finding.rst new file mode 100644 index 00000000..4e4dddc2 --- /dev/null +++ b/docs/event_finding.rst @@ -0,0 +1,1218 @@ +Geometric Event Finding Hands-On Lesson, using MEX (Python) +=========================================================== + +November 20, 2017 + +Overview +-------- + +This lesson illustrates how the Geometry Finder (GF) subsystem of the +SpiceyPy Toolkit can be used to find time intervals when specified +geometric conditions are satisfied. + +In this lesson the student is asked to construct a program that finds +the time intervals, within a specified time range, when the Mars Express +Orbiter (MEX) is visible from the DSN station DSS-14. Possible +occultation of the spacecraft by Mars is to be considered. + +References +---------- + +This section lists SPICE documents referred to in this lesson. + +In some cases the lesson explanations also refer to the information +provided in the meta-data area of the kernels used in the lesson +examples. It is especially true in case of the FK and IK files, which +often contain comprehensive descriptions of the frames, instrument FOVs, +etc. Since both FK and IK are text kernels, the information provided in +them can be viewed using any text editor, while the meta information +provided in binary kernels – SPKs and CKs – can be viewed using +``commnt'' or``\ spacit’‘utility programs located in \``cspice/exe’’ of +Toolkit installation tree. + +The following SPICE tutorials serve as references for the discussions in +this lesson: + +:: + + Name Lesson steps/functions it describes + ---------------- ----------------------------------------------- + Time Time Conversion + SCLK and LSK Time Conversion + SPK Obtaining Ephemeris Data + Frames Reference Frames + Using Frames Reference Frames + PCK Planetary Constants Data + Lunar-Earth PCK Lunar and Earth Orientation Data + GF The SPICE Geometry Finder (GF) subsystem + +These tutorials are available from the NAIF ftp server at JPL: + +:: + + http://naif.jpl.nasa.gov/naif/tutorials.html + +Required Readings + +The Required Reading documents are provided with the Toolkit and are +located under the \``cspice/doc’’ directory in the CSPICE Toolkit +installation tree. + +:: + + Name Lesson steps/functions that it describes + --------------- ----------------------------------------- + cells.req Cell/window initialization + frames.req Using reference frames + gf.req The SPICE geometry finder (GF) subsystem + kernel.req Loading SPICE kernels + naif_ids.req Body and reference frame names + pck.req Obtaining planetary constants data + spk.req Computing positions and velocities + time.req UTC to ET time conversion + windows.req The SPICE window data type + +The Permuted Index + +Another useful document distributed with the Toolkit is the permuted +index. This is located under the \``cspice/doc’’ directory in the C +installation tree. + +This text document provides a simple mechanism by which users can +discover which SpiceyPy functions perform functions of interest, as well +as the names of the source files that contain these functions. + +SpiceyPy API Documentation + +A SpiceyPy function’s parameters specification is available using the +built-in Python help system. A more detailed specification of the API +can be found in the CSPICE HTML API documentation page located under +\``cspice/doc/html/cspice’’. + +For example, the Python help function + +:: + + >>> import spiceypy + >>> help(spiceypy.str2et) + +describes of the str2et function’s parameters, while the document + +:: + + cspice/doc/html/cspice/str2et_c.html + +describes extensively the str2et functionality. + +Kernels Used +------------ + +The following kernels are used in examples provided in this lesson: + +:: + + # FILE NAME TYPE DESCRIPTION + -- ------------------------------ ---- ------------------------------ + 1 de405xs.bsp SPK Planetary ephemeris SPK, + subsetted to cover only time + range of interest + 2 earthstns_itrf93_050714.bsp SPK DSN station SPK + 3 earth_topo_050714.tf FK DSN station frame definitions + 4 earth_000101_060525_060303.bpc PCK Binary PCK for Earth + 5 naif0008.tls LSK Generic LSK + 6 ORMM__040501000000_00076XS.BSP SPK MEX Orbiter trajectory SPK, + subsetted to cover only time + range of interest + 7 pck00008.tpc PCK Generic PCK + 8 mars_lowres.bds DSK Low-resolution Mars DSK + +These SPICE kernels are included in the lesson package available from +the NAIF server at JPL: + +:: + + ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/ + +SpiceyPy Modules Used +--------------------- + +This section provides a complete list of the functions and kernels that +are suggested for usage in each of the exercises in this lesson. (You +may wish to not look at this list unless/until you \``get stuck’’ while +working on your own.) + +:: + + CHAPTER EXERCISE FUNCTIONS NON-VOID KERNELS + ------- --------- --------------- --------------- ---------- + 1 viewpr spiceypy.furnsh spiceypy.rpd 1-7 + spiceypy.wninsd spiceypy.str2et + spiceypy.gfposc spiceypy.timout + spiceypy.unload spiceypy.wncard + spiceypy.wnfetd + + 2 visibl spiceypy.furnsh spiceypy.rpd 1-8 + spiceypy.wninsd spiceypy.str2et + spiceypy.gfposc spiceypy.timout + spiceypy.gfoclt spiceypy.wndifd + spiceypy.unload spiceypy.wncard + spiceypy.wnfetd + + extra (*) spiceypy.gfdist spiceypy.repmc 1,5-7 + spiceypy.kclear spiceypy.repmf + + + (*) Additional APIs and kernels used in Extra Credit tasks. + +Use the Python built-in help system on the various functions listed +above for the API parameters’ description, and refer to the headers of +their corresponding CSPICE versions for detailed interface +specifications. + +Find View Periods +================= + +Task Statement +-------------- + +Write a program that finds the set of time intervals, within the time +range + +:: + + 2004 MAY 2 TDB + 2004 MAY 6 TDB + +when the Mars Express Orbiter (MEX) is visible from the DSN station +DSS-14. These time intervals are frequently called \``view periods.’’ + +The spacecraft is considered visible if its apparent position (that is, +its position corrected for light time and stellar aberration) has +elevation of at least 6 degrees in the topocentric reference frame +DSS-14_TOPO. In this exercise, we ignore the possibility of occultation +of the spacecraft by Mars. + +Use a search step size that ensures that no view periods of duration 5 +minutes or longer will be missed by the search. + +Display the start and stop times of these intervals using TDB calendar +dates and millisecond precision. + +Learning Goals +-------------- + +Exposure to SPICE GF event finding routines. Familiarity with SPICE +windows and routines that manipulate them. Exposure to SPICE time +parsing and output formatting routines. + +Approach +-------- + +Solution steps + +A possible solution could consist of the following steps: + +Preparation: + +:: + + 1. Decide what SPICE kernels are necessary. Use the SPICE summary + tool BRIEF to examine the coverage of the binary kernels and + verify the availability of required data. + + 2. Create a meta-kernel listing the SPICE kernels to be loaded. + (Hint: consult a programming example tutorial, or the + Introduction to Kernels tutorial, for a reminder of how to do + this.) + + Name the meta-kernel 'viewpr.tm'. + +Next, write a program that performs the following steps: + +:: + + 1. Use spiceypy.furnsh to load the meta-kernel. + + 2. Create confinement and output SpiceyPy windows using + stypes.SPICEDOUBLE_CELL. + + 3. Insert the given time bounds into the confinement window using + spiceypy.wninsd. + + 4. Select a step size for searching for visibility state + transitions: in this case, each target rise or set event is a + state transition. + + The step size must be large enough so the search proceeds with + reasonable speed, but small enough so that no visibility + transition events---that is, target rise or set events---are + missed. + + 5. Use the GF routine spiceypy.gfposc to find the window of times, + within the confinement window, during which the MEX spacecraft + is above the elevation limit as seen from DSN station DSS-14, + in the reference frame DSS-14_TOPO. + + Use light time and stellar aberration corrections for the + apparent position of the spacecraft as seen from the station. + + 6. Fetch and display the contents of the result window. Use + spiceypy.wnfetd to extract from the result window the start and + stop times of each time interval. Display each of the intervals + in the result window as a pair of start and stop times. Express + each time as a TDB calendar date using the routine + spiceypy.timout. + +You may find it useful to consult the references listed above. In +particular, the header of the SPICE GF function spiceypy.gfposc contains +pertinent documentation. + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘viewpr.tm’. Its contents follow: + +:: + + KPL/MK + + Example meta-kernel for geometric event finding hands-on + coding lesson. + + Version 2.0.0 13-JUL-2017 (JDR) + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File Name Description + ------------------------------ ------------------------------ + de405xs.bsp Planetary ephemeris SPK, + subsetted to cover only + time range of interest. + earthstns_itrf93_050714.bsp DSN station SPK. + earth_topo_050714.tf DSN station frame definitions. + earth_000101_060525_060303.bpc Binary PCK for Earth. + naif0008.tls Generic LSK. + ORMM__040501000000_00076XS.BSP MEX Orbiter trajectory SPK, + subsetted to cover only + time range of interest. + pck00008.tpc Generic PCK. + + + \begindata + + KERNELS_TO_LOAD = ( + + 'kernels/spk/de405xs.bsp' + 'kernels/spk/earthstns_itrf93_050714.bsp' + 'kernels/fk/earth_topo_050714.tf' + 'kernels/pck/earth_000101_060525_060303.bpc' + 'kernels/lsk/naif0008.tls' + 'kernels/spk/ORMM__040501000000_00076XS.BSP' + 'kernels/pck/pck00008.tpc' + ) + + \begintext + +Solution Code + +The example program below shows one possible solution. + +:: + + # + # Solution viewpr + # + from __future__ import print_function + import spiceypy.utils.support_types as stypes + import spiceypy + + def viewpr(): + # + # Local Parameters + # + METAKR = 'viewpr.tm' + TDBFMT = 'YYYY MON DD HR:MN:SC.### (TDB) ::TDB' + MAXIVL = 1000 + MAXWIN = 2 * MAXIVL + + # + # Load the meta-kernel. + # + spiceypy.furnsh( METAKR ) + + # + # Assign the inputs for our search. + # + # Since we're interested in the apparent location of the + # target, we use light time and stellar aberration + # corrections. We use the "converged Newtonian" form + # of the light time correction because this choice may + # increase the accuracy of the occultation times we'll + # compute using gfoclt. + # + srfpt = 'DSS-14' + obsfrm = 'DSS-14_TOPO' + target = 'MEX' + abcorr = 'CN+S' + start = '2004 MAY 2 TDB' + stop = '2004 MAY 6 TDB' + elvlim = 6.0 + + # + # The elevation limit above has units of degrees; we convert + # this value to radians for computation using SPICE routines. + # We'll store the equivalent value in radians in revlim. + # + revlim = spiceypy.rpd() * elvlim + + # + # Since SPICE doesn't directly support the AZ/EL coordinate + # system, we use the equivalent constraint + # + # latitude > revlim + # + # in the latitudinal coordinate system, where the reference + # frame is topocentric and is centered at the viewing location. + # + crdsys = 'LATITUDINAL' + coord = 'LATITUDE' + relate = '>' + + # + # The adjustment value only applies to absolute extrema + # searches; simply give it an initial value of zero + # for this inequality search. + # + adjust = 0.0 + + # + # stepsz is the step size, measured in seconds, used to search + # for times bracketing a state transition. Since we don't expect + # any events of interest to be shorter than five minutes, and + # since the separation between events is well over 5 minutes, + # we'll use this value as our step size. Units are seconds. + # + stepsz = 300.0 + + # + # Display a banner for the output report: + # + print( '\n{:s}\n'.format( + 'Inputs for target visibility search:' ) ) + + print( ' Target = ' + '{:s}'.format( target ) ) + print( ' Observation surface location = ' + '{:s}'.format( srfpt ) ) + print( ' Observer\'s reference frame = ' + '{:s}'.format( obsfrm ) ) + print( ' Elevation limit (degrees) = ' + '{:f}'.format( elvlim ) ) + print( ' Aberration correction = ' + '{:s}'.format( abcorr ) ) + print( ' Step size (seconds) = ' + '{:f}'.format( stepsz ) ) + + # + # Convert the start and stop times to ET. + # + etbeg = spiceypy.str2et( start ) + etend = spiceypy.str2et( stop ) + + # + # Display the search interval start and stop times + # using the format shown below. + # + # 2004 MAY 06 20:15:00.000 (TDB) + # + timstr = spiceypy.timout( etbeg, TDBFMT ) + print( ' Start time = ' + '{:s}'.format(timstr) ) + + timstr = spiceypy.timout( etend, TDBFMT ) + print( ' Stop time = ' + '{:s}'.format(timstr) ) + + print( ' ' ) + + # + # Initialize the "confinement" window with the interval + # over which we'll conduct the search. + # + cnfine = stypes.SPICEDOUBLE_CELL(2) + spiceypy.wninsd( etbeg, etend, cnfine ) + + # + # In the call below, the maximum number of window + # intervals gfposc can store internally is set to MAXIVL. + # We set the cell size to MAXWIN to achieve this. + # + riswin = stypes.SPICEDOUBLE_CELL( MAXWIN ) + + # + # Now search for the time period, within our confinement + # window, during which the apparent target has elevation + # at least equal to the elevation limit. + # + spiceypy.gfposc( target, obsfrm, abcorr, srfpt, + crdsys, coord, relate, revlim, + adjust, stepsz, MAXIVL, cnfine, riswin ) + + # + # The function wncard returns the number of intervals + # in a SPICE window. + # + winsiz = spiceypy.wncard( riswin ) + + if winsiz == 0: + + print( 'No events were found.' ) + + else: + + # + # Display the visibility time periods. + # + print( 'Visibility times of {0:s} ' + 'as seen from {1:s}:\n'.format( + target, srfpt ) ) + + for i in range(winsiz): + # + # Fetch the start and stop times of + # the ith interval from the search result + # window riswin. + # + [intbeg, intend] = spiceypy.wnfetd( riswin, i ) + + # + # Convert the rise time to a TDB calendar string. + # + timstr = spiceypy.timout( intbeg, TDBFMT ) + + # + # Write the string to standard output. + # + if i == 0: + + print( 'Visibility or window start time:' + ' {:s}'.format( timstr ) ) + else: + + print( 'Visibility start time: ' + ' {:s}'.format( timstr ) ) + + # + # Convert the set time to a TDB calendar string. + # + timstr = spiceypy.timout( intend, TDBFMT ) + + # + # Write the string to standard output. + # + if i == (winsiz-1): + + print( 'Visibility or window stop time: ' + ' {:s}'.format( timstr ) ) + else: + + print( 'Visibility stop time: ' + ' {:s}'.format( timstr ) ) + + print( ' ' ) + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + viewpr() + +Solution Sample Output + +Numerical results shown for this example may differ across platforms +since the results depend on the SPICE kernels used as input and on the +host platform’s arithmetic implementation. + +Execute the program. The output is: + +:: + + Inputs for target visibility search: + + Target = MEX + Observation surface location = DSS-14 + Observer's reference frame = DSS-14_TOPO + Elevation limit (degrees) = 6.000000 + Aberration correction = CN+S + Step size (seconds) = 300.000000 + Start time = 2004 MAY 02 00:00:00.000 (TDB) + Stop time = 2004 MAY 06 00:00:00.000 (TDB) + + Visibility times of MEX as seen from DSS-14: + + Visibility or window start time: 2004 MAY 02 00:00:00.000 (TDB) + Visibility stop time: 2004 MAY 02 05:35:03.096 (TDB) + + Visibility start time: 2004 MAY 02 16:09:14.078 (TDB) + Visibility stop time: 2004 MAY 03 05:33:57.257 (TDB) + + Visibility start time: 2004 MAY 03 16:08:02.279 (TDB) + Visibility stop time: 2004 MAY 04 05:32:50.765 (TDB) + + Visibility start time: 2004 MAY 04 16:06:51.259 (TDB) + Visibility stop time: 2004 MAY 05 05:31:43.600 (TDB) + + Visibility start time: 2004 MAY 05 16:05:40.994 (TDB) + Visibility or window stop time: 2004 MAY 06 00:00:00.000 (TDB) + +Find Times when Target is Visible +================================= + +.. _task-statement-1: + +Task Statement +-------------- + +Extend the program of the previous chapter to find times when the MEX +orbiter is: + +:: + + -- Above the elevation limit in the DSS-14_TOPO topocentric + reference frame. + + -- and is not occulted by Mars + +Finding time intervals that satisfy the second condition requires a +search for occultations of the spacecraft by Mars. Perform this search +twice: once using an ellipsoidal shape model for Mars, and once using a +DSK shape model. + +Compute the final results twice as well, using the results of both +occultation searches. + +For each of the two shape model cases, store the set of time intervals +when the spacecraft is visible in a SpiceyPy window. We’ll call this the +\``result window.’’ + +Display each of the intervals in each result window as a pair of start +and stop times. Express each time as a TDB calendar date using the same +format as in the previous program. + +.. _learning-goals-1: + +Learning Goals +-------------- + +Familiarity with the GF occultation finding routine spiceypy.gfoclt. +Experience with Digital Shape Kernel (DSK) shape models. Further +experience with the SpiceyPy window functions. + +.. _approach-1: + +Approach +-------- + +Solution steps + +A possible solution would consist of the following steps: + +:: + + 1. Use the meta-kernel from the previous chapter as the starting + point. Add more kernels to it as needed. + + Name the meta-kernel 'visibl.tm'. + + 2. Include the code from the program of the previous chapter in a + new source file; modify this code to create the new program. + + 3. Your program will need additional windows to capture the + results of occultation searches performed using both + ellipsoidal and DSK shape models. Additional windows will be + needed to compute the set differences of the elevation search + (``view period'') window and each of the occultation search + windows. Further details are provided below. + + Create additional output SpiceyPy windows using + stypes.SPICEDOUBLE_CELL. + + 4. The remaining steps can be performed twice: once using an + ellipsoidal shape model for Mars, and once using a DSK Mars + shape model. Alternatively, two copies of the entire solution + program can be created: one for each shape model. + + 5. Search for occultations of the MEX orbiter as seen from DSS-14 + using spiceypy.gfoclt. Use as the confinement window for this + search the result window from the elevation search performed by + spiceypy.gfposc. + + Since occultations occur when the apparent MEX spacecraft + position is behind the apparent figure of Mars, light time + correction must be performed for the occultation search. To + improve accuracy of the occultation state determination, use + ``converged Newtonian'' light time correction. + + 6. Use the SpiceyPy window subtraction routine spiceypy.wndifd to + subtract the window of times when the spacecraft is occulted + from the window of times when the spacecraft is above the + elevation limit. The difference window is the final result. + + 7. Modify the code to display the contents of the difference + window. + +This completes the assignment. + +.. _solution-1: + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘visibl.tm’. Its contents follow: + +:: + + KPL/MK + + Example meta-kernel for geometric event finding hands-on + coding lesson. + + Version 3.0.0 26-OCT-2017 (BVS) + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File Name Description + ------------------------------ ------------------------------ + de405xs.bsp Planetary ephemeris SPK, + subsetted to cover only + time range of interest. + earthstns_itrf93_050714.bsp DSN station SPK. + earth_topo_050714.tf DSN station frame definitions. + earth_000101_060525_060303.bpc Binary PCK for Earth. + naif0008.tls Generic LSK. + ORMM__040501000000_00076XS.BSP MEX Orbiter trajectory SPK, + subsetted to cover only + time range of interest. + pck00008.tpc Generic PCK. + mars_lowres.bds Low-resolution Mars DSK. + + + \begindata + + KERNELS_TO_LOAD = ( + + 'kernels/spk/de405xs.bsp' + 'kernels/spk/earthstns_itrf93_050714.bsp' + 'kernels/fk/earth_topo_050714.tf' + 'kernels/pck/earth_000101_060525_060303.bpc' + 'kernels/lsk/naif0008.tls' + 'kernels/spk/ORMM__040501000000_00076XS.BSP' + 'kernels/pck/pck00008.tpc' + 'kernels/dsk/mars_lowres.bds' + ) + + \begintext + +Solution Code + +:: + + # + # Solution visibl + # + from __future__ import print_function + + # + # SpiceyPy package: + # + import spiceypy.utils.support_types as stypes + import spiceypy + + def visibl(): + # + # Local Parameters + # + METAKR = 'visibl.tm' + SCLKID = -82 + TDBFMT = 'YYYY MON DD HR:MN:SC.### TDB ::TDB' + MAXIVL = 1000 + MAXWIN = 2 * MAXIVL + + # + # Load the meta-kernel. + # + spiceypy.furnsh( METAKR ) + + # + # Assign the inputs for our search. + # + # Since we're interested in the apparent location of the + # target, we use light time and stellar aberration + # corrections. We use the "converged Newtonian" form + # of the light time correction because this choice may + # increase the accuracy of the occultation times we'll + # compute using gfoclt. + # + srfpt = 'DSS-14' + obsfrm = 'DSS-14_TOPO' + target = 'MEX' + abcorr = 'CN+S' + start = '2004 MAY 2 TDB' + stop = '2004 MAY 6 TDB' + elvlim = 6.0 + + # + # The elevation limit above has units of degrees; we convert + # this value to radians for computation using SPICE routines. + # We'll store the equivalent value in radians in revlim. + # + revlim = spiceypy.rpd() * elvlim + + # + # We model the target shape as a point. We either model the + # blocking body's shape as an ellipsoid, or we represent + # its shape using actual topographic data. No body-fixed + # reference frame is required for the target since its + # orientation is not used. + # + back = target + bshape = 'POINT' + bframe = ' ' + front = 'MARS' + fshape = 'ELLIPSOID' + fframe = 'IAU_MARS' + + # + # The occultation type should be set to 'ANY' for a point + # target. + # + occtyp = 'any' + + # + # Since SPICE doesn't directly support the AZ/EL coordinate + # system, we use the equivalent constraint + # + # latitude > revlim + # + # in the latitudinal coordinate system, where the reference + # frame is topocentric and is centered at the viewing location. + # + crdsys = 'LATITUDINAL' + coord = 'LATITUDE' + relate = '>' + + # + # The adjustment value only applies to absolute extrema + # searches; simply give it an initial value of zero + # for this inequality search. + # + adjust = 0.0 + + # + # stepsz is the step size, measured in seconds, used to search + # for times bracketing a state transition. Since we don't expect + # any events of interest to be shorter than five minutes, and + # since the separation between events is well over 5 minutes, + # we'll use this value as our step size. Units are seconds. + # + stepsz = 300.0 + + # + # Display a banner for the output report: + # + print( '\n{:s}\n'.format( + 'Inputs for target visibility search:' ) ) + + print( ' Target = ' + '{:s}'.format( target ) ) + print( ' Observation surface location = ' + '{:s}'.format( srfpt ) ) + print( ' Observer\'s reference frame = ' + '{:s}'.format( obsfrm ) ) + print( ' Blocking body = ' + '{:s}'.format( front ) ) + print( ' Blocker\'s reference frame = ' + '{:s}'.format( fframe ) ) + print( ' Elevation limit (degrees) = ' + '{:f}'.format( elvlim ) ) + print( ' Aberration correction = ' + '{:s}'.format( abcorr ) ) + print( ' Step size (seconds) = ' + '{:f}'.format( stepsz ) ) + + # + # Convert the start and stop times to ET. + # + etbeg = spiceypy.str2et( start ) + etend = spiceypy.str2et( stop ) + + # + # Display the search interval start and stop times + # using the format shown below. + # + # 2004 MAY 06 20:15:00.000 (TDB) + # + btmstr = spiceypy.timout( etbeg, TDBFMT ) + print( ' Start time = ' + '{:s}'.format(btmstr) ) + + etmstr = spiceypy.timout( etend, TDBFMT ) + print( ' Stop time = ' + '{:s}'.format(etmstr) ) + + print( ' ' ) + + # + # Initialize the "confinement" window with the interval + # over which we'll conduct the search. + # + cnfine = stypes.SPICEDOUBLE_CELL(2) + spiceypy.wninsd( etbeg, etend, cnfine ) + + # + # In the call below, the maximum number of window + # intervals gfposc can store internally is set to MAXIVL. + # We set the cell size to MAXWIN to achieve this. + # + riswin = stypes.SPICEDOUBLE_CELL( MAXWIN ) + + # + # Now search for the time period, within our confinement + # window, during which the apparent target has elevation + # at least equal to the elevation limit. + # + spiceypy.gfposc( target, obsfrm, abcorr, srfpt, + crdsys, coord, relate, revlim, + adjust, stepsz, MAXIVL, cnfine, riswin ) + + # + # Now find the times when the apparent target is above + # the elevation limit and is not occulted by the + # blocking body (Mars). We'll find the window of times when + # the target is above the elevation limit and *is* occulted, + # then subtract that window from the view period window + # riswin found above. + # + # For this occultation search, we can use riswin as + # the confinement window because we're not interested in + # occultations that occur when the target is below the + # elevation limit. + # + # Find occultations within the view period window. + # + print( ' Searching using ellipsoid target shape model...' ) + + eocwin = stypes.SPICEDOUBLE_CELL( MAXWIN ) + + fshape = 'ELLIPSOID' + + spiceypy.gfoclt( occtyp, front, fshape, fframe, + back, bshape, bframe, abcorr, + srfpt, stepsz, riswin, eocwin ) + print( ' Done.' ) + + # + # Subtract the occultation window from the view period + # window: this yields the time periods when the target + # is visible. + # + evswin = spiceypy.wndifd( riswin, eocwin ) + + # + # Repeat the search using low-resolution DSK data + # for the front body. + # + print( ' Searching using DSK target shape model...' ) + + docwin = stypes.SPICEDOUBLE_CELL( MAXWIN ) + + fshape = 'DSK/UNPRIORITIZED' + + spiceypy.gfoclt( occtyp, front, fshape, fframe, + back, bshape, bframe, abcorr, + srfpt, stepsz, riswin, docwin ) + print( ' Done.\n' ) + + dvswin = spiceypy.wndifd( riswin, docwin ) + + # + # The function wncard returns the number of intervals + # in a SPICE window. + # + winsiz = spiceypy.wncard( evswin ) + + if winsiz == 0: + + print( 'No events were found.' ) + + else: + # + # Display the visibility time periods. + # + print( 'Visibility start and stop times of ' + '{0:s} as seen from {1:s}\n' + 'using both ellipsoidal and DSK ' + 'target shape models:\n'.format( + target, srfpt ) ) + + for i in range(winsiz): + # + # Fetch the start and stop times of + # the ith interval from the ellipsoid + # search result window evswin. + # + [intbeg, intend] = spiceypy.wnfetd( evswin, i ) + + # + # Convert the rise time to TDB calendar strings. + # Write the results. + # + btmstr = spiceypy.timout( intbeg, TDBFMT ) + etmstr = spiceypy.timout( intend, TDBFMT ) + + print( ' Ell: {:s} : {:s}'.format( btmstr, etmstr ) ) + + # + # Fetch the start and stop times of + # the ith interval from the DSK + # search result window dvswin. + # + [dintbg, dinten] = spiceypy.wnfetd( dvswin, i ) + + # + # Convert the rise time to TDB calendar strings. + # Write the results. + # + btmstr = spiceypy.timout( dintbg, TDBFMT ) + etmstr = spiceypy.timout( dinten, TDBFMT ) + + print( ' DSK: {:s} : {:s}\n'.format( btmstr, etmstr ) ) + # + # End of result display loop. + # + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + visibl() + +Solution Sample Output + +Numerical results shown for this example may differ across platforms +since the results depend on the SPICE kernels used as input and on the +host platform’s arithmetic implementation. + +Execute the program. The output is: + +:: + + Inputs for target visibility search: + + Target = MEX + Observation surface location = DSS-14 + Observer's reference frame = DSS-14_TOPO + Blocking body = MARS + Blocker's reference frame = IAU_MARS + Elevation limit (degrees) = 6.000000 + Aberration correction = CN+S + Step size (seconds) = 300.000000 + Start time = 2004 MAY 02 00:00:00.000 TDB + Stop time = 2004 MAY 06 00:00:00.000 TDB + + Searching using ellipsoid target shape model... + Done. + Searching using DSK target shape model... + Done. + + Visibility start and stop times of MEX as seen from DSS-14 + using both ellipsoidal and DSK target shape models: + + Ell: 2004 MAY 02 00:00:00.000 TDB : 2004 MAY 02 04:49:30.827 TDB + DSK: 2004 MAY 02 00:00:00.000 TDB : 2004 MAY 02 04:49:32.645 TDB + + Ell: 2004 MAY 02 16:09:14.078 TDB : 2004 MAY 02 20:00:22.514 TDB + DSK: 2004 MAY 02 16:09:14.078 TDB : 2004 MAY 02 20:00:23.980 TDB + + Ell: 2004 MAY 02 21:01:38.222 TDB : 2004 MAY 03 03:35:42.256 TDB + DSK: 2004 MAY 02 21:01:43.195 TDB : 2004 MAY 03 03:35:44.140 TDB + + Ell: 2004 MAY 03 04:36:42.484 TDB : 2004 MAY 03 05:33:57.257 TDB + DSK: 2004 MAY 03 04:36:46.856 TDB : 2004 MAY 03 05:33:57.257 TDB + + Ell: 2004 MAY 03 16:08:02.279 TDB : 2004 MAY 03 18:46:26.013 TDB + DSK: 2004 MAY 03 16:08:02.279 TDB : 2004 MAY 03 18:46:27.306 TDB + + Ell: 2004 MAY 03 19:46:54.618 TDB : 2004 MAY 04 02:21:44.562 TDB + DSK: 2004 MAY 03 19:46:59.723 TDB : 2004 MAY 04 02:21:46.574 TDB + + Ell: 2004 MAY 04 03:21:56.347 TDB : 2004 MAY 04 05:32:50.765 TDB + DSK: 2004 MAY 04 03:22:00.850 TDB : 2004 MAY 04 05:32:50.765 TDB + + Ell: 2004 MAY 04 16:06:51.259 TDB : 2004 MAY 04 17:32:25.809 TDB + DSK: 2004 MAY 04 16:06:51.259 TDB : 2004 MAY 04 17:32:27.118 TDB + + Ell: 2004 MAY 04 18:32:05.975 TDB : 2004 MAY 05 01:07:48.264 TDB + DSK: 2004 MAY 04 18:32:11.046 TDB : 2004 MAY 05 01:07:50.061 TDB + + Ell: 2004 MAY 05 02:07:11.601 TDB : 2004 MAY 05 05:31:43.600 TDB + DSK: 2004 MAY 05 02:07:16.241 TDB : 2004 MAY 05 05:31:43.600 TDB + + Ell: 2004 MAY 05 16:05:40.994 TDB : 2004 MAY 05 16:18:35.560 TDB + DSK: 2004 MAY 05 16:05:40.994 TDB : 2004 MAY 05 16:18:36.994 TDB + + Ell: 2004 MAY 05 17:17:27.717 TDB : 2004 MAY 05 23:54:04.672 TDB + DSK: 2004 MAY 05 17:17:32.375 TDB : 2004 MAY 05 23:54:06.221 TDB + +Extra Credit +============ + +In this \``extra credit’’ section you will be presented with more +complex tasks, aimed at improving your understanding of the geometry +event finding subsystem and particularly the spiceypy.gfposc and +spiceypy.gfdist functions. + +These \``extra credit’’ tasks are provided as task statements, and +unlike the regular tasks, no approach or solution source code is +provided. In the next section, you will find the numeric solutions to +the questions asked in these tasks. + +Task statements +--------------- + +:: + + 1. Write a program that finds the times, within the time range + + 2004 MAY 2 TDB + 2004 MAY 6 TDB + + when the MEX spacecraft crosses Mars' equator. Display the + results using TDB calendar dates and millisecond precision. + + 2. Write a program that finds the times, within the time range + + 2004 MAY 2 TDB + 2004 MAY 6 TDB + + when the MEX spacecraft is at periapsis. Display the results + using TDB calendar dates and millisecond precision. + + 3. Write a program that finds the times, within the time range + + 2004 MAY 2 TDB + 2004 MAY 6 TDB + + when the MEX spacecraft is at apoapsis. Display the results + using TDB calendar dates and millisecond precision. + +Solutions +--------- + +:: + + 1. Solution for the equator crossing search, using spiceypy.gfposc + for the MEX spacecraft latitude in the Mars body-fixed frame + equal to 0 degrees: + + + Inputs for equator crossing search: + + Target = MEX + Observer = MARS + Observer's reference frame = IAU_MARS + Latitude limit (degrees) = 0.000000 + Aberration correction = NONE + Step size (seconds) = 300.000000 + Start time = 2004 MAY 02 00:00:00.000 (TDB) + Stop time = 2004 MAY 06 00:00:00.000 (TDB) + + MEX MARS equator crossing times: + + Equator crossing or start time: 2004 MAY 02 05:00:08.334 (TDB) + Equator crossing time: 2004 MAY 02 06:15:13.074 (TDB) + Equator crossing time: 2004 MAY 02 12:35:14.856 (TDB) + Equator crossing time: 2004 MAY 02 13:50:09.161 (TDB) + Equator crossing time: 2004 MAY 02 20:10:24.439 (TDB) + Equator crossing time: 2004 MAY 02 21:25:10.344 (TDB) + Equator crossing time: 2004 MAY 03 03:45:26.758 (TDB) + Equator crossing time: 2004 MAY 03 05:00:04.086 (TDB) + Equator crossing time: 2004 MAY 03 11:20:32.419 (TDB) + Equator crossing time: 2004 MAY 03 12:34:57.968 (TDB) + Equator crossing time: 2004 MAY 03 18:55:34.883 (TDB) + Equator crossing time: 2004 MAY 03 20:09:53.063 (TDB) + Equator crossing time: 2004 MAY 04 02:30:35.509 (TDB) + Equator crossing time: 2004 MAY 04 03:44:42.753 (TDB) + Equator crossing time: 2004 MAY 04 10:05:41.638 (TDB) + Equator crossing time: 2004 MAY 04 11:19:38.397 (TDB) + Equator crossing time: 2004 MAY 04 17:40:41.405 (TDB) + Equator crossing time: 2004 MAY 04 18:54:31.413 (TDB) + Equator crossing time: 2004 MAY 05 01:15:45.967 (TDB) + Equator crossing time: 2004 MAY 05 02:29:25.294 (TDB) + Equator crossing time: 2004 MAY 05 08:50:53.931 (TDB) + Equator crossing time: 2004 MAY 05 10:04:26.915 (TDB) + Equator crossing time: 2004 MAY 05 16:25:58.350 (TDB) + Equator crossing or stop time: 2004 MAY 05 17:39:23.889 (TDB) + + 2. Solution for the periapsis search, using spiceypy.gfdist for + the MEX spacecraft distance from Mars at a local minimum: + + + Inputs for periapsis search: + + Target = MEX + Observer = MARS + Aberration correction = NONE + Step size (seconds) = 300.000000 + Start time = 2004 MAY 02 00:00:00.000 (TDB) + Stop time = 2004 MAY 06 00:00:00.000 (TDB) + + MEX periapsis times: + + Periapsis or start time: 2004 MAY 02 05:57:51.000 (TDB) + Periapsis time: 2004 MAY 02 13:32:43.325 (TDB) + Periapsis time: 2004 MAY 02 21:07:41.124 (TDB) + Periapsis time: 2004 MAY 03 04:42:30.648 (TDB) + Periapsis time: 2004 MAY 03 12:17:21.143 (TDB) + Periapsis time: 2004 MAY 03 19:52:12.267 (TDB) + Periapsis time: 2004 MAY 04 03:26:57.755 (TDB) + Periapsis time: 2004 MAY 04 11:01:49.826 (TDB) + Periapsis time: 2004 MAY 04 18:36:38.448 (TDB) + Periapsis time: 2004 MAY 05 02:11:28.558 (TDB) + Periapsis time: 2004 MAY 05 09:46:26.309 (TDB) + Periapsis or end time: 2004 MAY 05 17:21:18.875 (TDB) + + 3. Solution for the apoapsis search, using spiceypy.gfdist for the + MEX spacecraft distance from Mars at a local maximum: + + + Inputs for apoapsis search: + + Target = MEX + Observer = MARS + Aberration correction = NONE + Step size (seconds) = 300.000000 + Start time = 2004 MAY 02 00:00:00.000 (TDB) + Stop time = 2004 MAY 06 00:00:00.000 (TDB) + + MEX apoapsis times: + + Apoapsis or start time: 2004 MAY 02 02:10:24.948 (TDB) + Apoapsis time: 2004 MAY 02 09:45:19.189 (TDB) + Apoapsis time: 2004 MAY 02 17:20:14.194 (TDB) + Apoapsis time: 2004 MAY 03 00:55:07.633 (TDB) + Apoapsis time: 2004 MAY 03 08:29:57.890 (TDB) + Apoapsis time: 2004 MAY 03 16:04:48.524 (TDB) + Apoapsis time: 2004 MAY 03 23:39:36.745 (TDB) + Apoapsis time: 2004 MAY 04 07:14:25.662 (TDB) + Apoapsis time: 2004 MAY 04 14:49:15.904 (TDB) + Apoapsis time: 2004 MAY 04 22:24:05.351 (TDB) + Apoapsis time: 2004 MAY 05 05:58:59.270 (TDB) + Apoapsis time: 2004 MAY 05 13:33:54.433 (TDB) + Apoapsis or stop time: 2004 MAY 05 21:08:50.211 (TDB) diff --git a/docs/insitu_sensing.rst b/docs/insitu_sensing.rst new file mode 100644 index 00000000..0f81acb8 --- /dev/null +++ b/docs/insitu_sensing.rst @@ -0,0 +1,1453 @@ +In-situ Sensing Hands-On Lesson, using CASSINI (Python) +======================================================= + +November 20, 2017 + +Overview +-------- + +In this lesson you will develop a simple program illustrating how SPICE +can be used to compute various kinds of geometry information applicable +to the experiments carried out by an in-situ instrument flown on an +interplanetary spacecraft. + +References +---------- + +This section lists SPICE documents referred to in this lesson. + +In some cases the lesson explanations also refer to the information +provided in the meta-data area of the kernels used in the lesson +examples. It is especially true in case of the FK and IK files, which +often contain comprehensive descriptions of the frames, instrument FOVs, +etc. Since both FK and IK are text kernels, the information provided in +them can be viewed using any text editor, while the meta information +provided in binary kernels – SPKs and CKs – can be viewed using +``commnt'' or``\ spacit’‘utility programs located in \``cspice/exe’’ of +Toolkit installation tree. + +The following SPICE tutorials serve as references for the discussions in +this lesson: + +:: + + Name Lesson steps/functions it describes + ---------------- ----------------------------------------------- + Time UTC to ET and SCLK to ET + Loading Kernels Loading SPICE kernels + SCLK SCLK to ET time conversion + SPK Computing positions and velocities + Frames Computing transformations between frames + +These tutorials are available from the NAIF ftp server at JPL: + +:: + + http://naif.jpl.nasa.gov/naif/tutorials.html + +Required Readings + +The Required Reading documents are provided with the Toolkit and are +located under the \``cspice/doc’’ directory in the CSPICE Toolkit +installation tree. + +:: + + Name Lesson steps/functions that it describes + --------------- ----------------------------------------- + kernel.req Loading SPICE kernels + naif_ids.req Body and reference frame names + spk.req Computing positions and velocities + sclk.req SCLK to ET time conversion + time.req UTC to ET time conversion + +The Permuted Index + +Another useful document distributed with the Toolkit is the permuted +index. This is located under the \``cspice/doc’’ directory in the C +installation tree. + +This text document provides a simple mechanism by which users can +discover which SpiceyPy functions perform functions of interest, as well +as the names of the source files that contain these functions. + +SpiceyPy API Documentation + +A SpiceyPy function’s parameters specification is available using the +built-in Python help system. A more detailed specification of the API +can be found in the CSPICE HTML API documentation page located under +\``cspice/doc/html/cspice’’. + +For example, the Python help function + +:: + + >>> import spiceypy + >>> help(spiceypy.str2et) + +describes of the str2et function’s parameters, while the document + +:: + + cspice/doc/html/cspice/str2et_c.html + +describes extensively the str2et functionality. + +Kernels Used +------------ + +The following kernels are used in examples provided in this lesson: + +:: + + # FILE NAME TYPE DESCRIPTION + -- ------------------------- ---- ----------------------------------- + 1 naif0008.tls LSK Generic LSK + 2 cas00084.tsc SCLK Cassini SCLK + 3 020514_SE_SAT105.bsp SPK Saturnian Satellite Ephemeris SPK + 4 030201AP_SK_SM546_T45.bsp SPK Cassini Spacecraft SPK + 5 981005_PLTEPH-DE405S.bsp SPK Planetary Ephemeris SPK + 6 sat128.bsp SPK Saturnian Satellite Ephemeris SPK + 7 04135_04171pc_psiv2.bc CK Cassini Spacecraft CK + 8 cas_v37.tf FK Cassini FK + 9 cpck05Mar2004.tpc PCK Cassini project PCK + +These SPICE kernels are included in the lesson package available from +the NAIF server at JPL: + +:: + + ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/ + +SpiceyPy Modules Used +--------------------- + +This section provides a complete list of the functions and kernels that +are suggested for usage in each of the exercises in this lesson. (You +may wish to not look at this list unless/until you \``get stuck’’ while +working on your own.) + +:: + + CHAPTER EXERCISE FUNCTIONS NON-VOID KERNELS + ------- --------- --------------- --------------- ---------- + 1 convrt spiceypy.furnsh spiceypy.str2et 1 + spiceypy.unload + + 2 sclket spiceypy.furnsh spiceypy.str2et 1,2 + spiceypy.unload spiceypy.scs2e + + 3 getsta spiceypy.furnsh spiceypy.str2et 1-6 + spiceypy.unload spiceypy.scs2e + spiceypy.spkezr + + 4 soldir spiceypy.furnsh spiceypy.str2et 1-8 + spiceypy.unload spiceypy.scs2e + spiceypy.spkezr + spiceypy.spkpos + spiceypy.vhat + + 5 sscpnt spiceypy.furnsh spiceypy.str2et 1-9 + spiceypy.unload spiceypy.scs2e + spiceypy.spkezr + spiceypy.spkpos + spiceypy.vhat + spiceypy.subpnt + spiceypy.reclat + spiceypy.pxform + spiceypy.mxv + spiceypy.dpr + + 6 scvel spiceypy.furnsh spiceypy.str2et 1-9 + spiceypy.unload spiceypy.scs2e + spiceypy.spkezr + spiceypy.spkpos + spiceypy.vhat + spiceypy.subpnt + spiceypy.reclat + spiceypy.pxform + spiceypy.mxv + spiceypy.dpr + +Use the Python built-in help system on the various functions listed +above for the API parameters’ description, and refer to the headers of +their corresponding CSPICE versions for detailed interface +specifications. + +Step-1: \``UTC to ET’’ +====================== + +\``UTC to ET’’ Task Statement +----------------------------- + +Write a program that computes and prints the Ephemeris Time (ET) +corresponding to \``2004-06-11T19:32:00’’ UTC, as the number of +ephemeris seconds past J2000, . + +\``UTC to ET’’ Hints +-------------------- + +Find out what SPICE kernel(s) is(are) needed to support this conversion. +Reference the ``time.req'' and/or``\ Time’’ tutorial. + +Find necessary kernel(s) on the NAIF’s FTP site. + +Find out what routine should be called to load necessary kernel(s). +Reference the ``kernel.req'' and/or``\ Loading Kernels’’ tutorial. + +Find the +``loader'' routine calling sequence specification. Look at the``\ time.req’‘and +that routine’s source code header. This routine may be an entry point, +in which case there will be no source file with the same name. To find +out in which source file this entry point is, search for its name in the +\``Permuted Index’’. + +Find the routine(s) used to convert time between UTC and ET. Look at the +``time.req'' and/or``\ Time’’ tutorial. + +Find the +``converter'' routine(s) calling sequence specification. Look in the``\ time.req’’ +and the routine’s source code header. + +Put all calls together in a program, add variable declarations (the +routine header’s ``Declarations'' and``\ Examples’’ sections are a good +place to look for declaration specification and examples) and output +print statements. + +\``UTC to ET’’ Solution Steps +----------------------------- + +Only one kernel file is needed to support this conversion – an LSK file +\``naif0008.tls’’. + +As any other SPICE kernel this file can be loaded by the spiceypy.furnsh +function. For that, the name of the file can be provided as a sole +argument of this routine: + +:: + + ... + lskfile = 'naif0008.tls' + + spiceypy.furnsh(lskfile) + +or it can be listed in a meta-kernel: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + ) + \begintext + +the name of which, let’s call it \``convrt.tm’’, can be then provided as +a sole argument of the spiceypy.furnsh routine: + +:: + + mkfile = 'convrt.tm' + spiceypy.furnsh(mkfile) + +While the second option seems to involve a bit more work – it requires +making an extra file – it is a much better way to go if you plan to load +more kernels as you extend the program. With the meta-kernel approach +simply adding more kernels to the list in KERNEL_TO_LOAD without +changing the program code will accomplish that. + +The highest level SpiceyPy time routine converting UTC to ET is +spiceypy.str2et (``cspice/src/cspice/str2et_c.c’’). + +It has two arguments – input time string representing UTC in a variety +of formats (see spiceypy.str2et header’s section \``Particulars’’ for +the complete description of input time formats) and output DP number of +ET seconds past J2000. A call to spiceypy.str2et converting a given UTC +to ET could look like this: + +:: + + utc = '2004-06-11T19:32:00' + et = spiceypy.str2et(utc) + +By combining spiceypy.furnsh and spiceypy.str2et calls and required +declarations and by adding a simple print statement, one would get a +complete program that prints ET for the given UTC epoch. + +Use of SpiceyPy calls in a Python script requires the SpiceyPy package +to be installed in your Python distribution, either using pip or conda, +and imported within the script. + +When you execute the script, \``convrt’’, it produces the following +output: + +:: + + > python convrt.py + UTC = 2004-06-11T19:32:00 + ET = 140254384.184625 + +\``UTC to ET’’ Code +------------------- + +Program \``convrt.py’’: + +:: + + from __future__ import print_function + import spiceypy + + def convrt(): + + mkfile = 'convrt.tm' + spiceypy.furnsh(mkfile) + + utc = '2004-06-11T19:32:00' + et = spiceypy.str2et(utc) + + print('UTC = {:s}'.format(utc)) + print('ET = {:20.6f}'.format(et)) + + spiceypy.unload(mkfile) + + + if __name__ == '__main__': + convrt() + +Meta-kernel file \``convrt.tm’’: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + ) + \begintext + +Step-2: \``SCLK to ET’’ +======================= + +\``SCLK to ET’’ Task Statement +------------------------------ + +Extend the program from Step-1 to compute and print ET for the following +CASSINI on-board clock epoch \``1465674964.105’’. + +\``SCLK to ET’’ Hints +--------------------- + +Find out what additional (to those already loaded in Step-1) SPICE +kernel(s) is(are) needed to support SCLK to ET conversion. Look at the +``sclk.req'' and/or``\ SCLK’’ tutorial. + +Find necessary kernel(s) on the NAIF’s FTP site. + +Modify the program or meta-kernel to load this(these) kernels. + +Find the routine(s) needed to convert time between SCLK and ET. Look at +the ``sclk.req'' and/or``\ Time’‘and \``SCLK’’ tutorials. + +Find the +``converter'' routine's calling sequence specification. Look in the``\ sclk.req’’ +and the routine’s source code header. + +Look at \``naif_ids.req’’ and the comments in the additional kernel(s) +that you have loaded for information on proper values of input arguments +of this routine. + +Add calls to the +``converter'' routine(s), necessary variable declarations (the routine header's``\ Declarations’‘and +\``Examples’’ sections are a good place to look for declaration +specification and examples), and output print statements to the program. + +\``SCLK to ET’’ Solution Steps +------------------------------ + +A CASSINI SCLK file is needed additionally to the LSK file loaded in the +Step-1 to support this conversion. + +No code change is needed in the loading portion of the program if a +meta-kernel approach was used in the Step-1. The program will load the +file if it will be added to the list of kernels in the KERNELS_TO_LOAD +variable: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + ) + \begintext + +The highest level SpiceyPy routine converting SCLK to ET is +spiceypy.scs2e (``cspice/src/cspice/scs2e_c.c’’). + +It has three arguments – NAIF ID for CASSINI s/c (-82 as described by +\``naif_ids.req’’ document), input time string representing CASSINI +SCLK, and output DP number of ET seconds past J2000. A call to +spiceypy.str2et converting given SCLK to ET could look like this: + +:: + + scid = -82 + sclk = '1465674964.105' + et = spiceypy.scs2e(scid, sclk) + +By adding the spiceypy.scs2e call, required declarations and a simple +print statement, one would get a complete program that prints ET for the +given SCLK epoch. + +When you execute the script, \``sclket’’, it produces the following +output: + +:: + + > python convrt.py + UTC = 2004-06-11T19:32:00 + ET = 140254384.184625 + SCLK = 1465674964.105 + ET = 140254384.183426 + +\``SCLK to ET’’ Code +-------------------- + +Program \``sclket.py’’: + +:: + + from __future__ import print_function + import spiceypy + + def sclket(): + + mkfile = 'sclket.tm' + spiceypy.furnsh(mkfile) + + utc = '2004-06-11T19:32:00' + et = spiceypy.str2et(utc) + + print('UTC = {:s}'.format(utc)) + print('ET = {:20.6f}'.format(et)) + + scid = -82 + sclk = '1465674964.105' + et = spiceypy.scs2e(scid, sclk) + + print('SCLK = {:s}'.format(sclk)) + print('ET = {:20.6f}'.format(et)) + + spiceypy.unload(mkfile) + + + if __name__ == '__main__': + sclket() + +Meta-kernel file \``sclket.tm’’: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + ) + \begintext + +Step-3: \``Spacecraft State’’ +============================= + +\``Spacecraft State’’ Task Statement +------------------------------------ + +Extend the program from Step-2 to compute geometric state – position and +velocity – of the CASSINI spacecraft with respect to the Sun in the +Ecliptic frame at the epoch specified by SCLK time from Step-2. + +\``Spacecraft State’’ Hints +--------------------------- + +Find out what additional (to those already loaded in Steps-1&2) SPICE +kernel(s) is(are) needed to support state computation. Look at the +``spk.req'' and/or``\ SPK’’ tutorial. + +Find necessary kernel(s) on the NAIF’s FTP site. + +Verify that the kernels contain enough data to compute the state of +interest. Use ``brief'' utility program located under``\ toolkit/exe’’ +directory for that. + +Modify the meta-kernel to load this(these) kernels. + +Determine the routine(s) needed to compute states. Look at the +``spk.req'' and/or``\ SPK’’ tutorial presentation. + +Find the the routine(s) calling sequence specification. Look in the +\``spk.req’’ and the routine’s source code header. + +Reference the ``naif_ids.req'' and``\ frames.req’‘and the routine(s) +header ``Inputs'' and``\ Particulars’’ sections to determine proper +values of the input arguments of this routine. + +Add calls to the routine(s), necessary variable declarations and output +print statements to the program. + +\``Spacecraft State’’ Solution Steps +------------------------------------ + +A CASSINI spacecraft trajectory SPK and generic planetary ephemeris SPK +files are needed to support computation of the state of interest. + +The file names can be added to the meta-kernel to get them loaded into +the program: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris SPK. + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK. + 981005_PLTEPH-DE405S.bsp Planetary Ephemeris SPK. + sat128.bsp Saturnian Satellite Ephemeris SPK. + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + 'kernels/spk/020514_SE_SAT105.bsp' + 'kernels/spk/030201AP_SK_SM546_T45.bsp' + 'kernels/spk/981005_PLTEPH-DE405S.bsp' + 'kernels/spk/sat128.bsp' + ) + \begintext + +The highest level SpiceyPy routine computing states is spiceypy.spkezr +(``cspice/src/cspice/spkezr_c.c’’). + +We are interested in computing CASSINI position and velocity with +respect to the Sun, therefore the target and observer names should be +set to ‘CASSINI’ and ‘Sun’ (both names can be found in +\``naif_ids.req’’). + +The state should be in ecliptic frame, therefore the name of the frame +in which the state should be computed is ‘ECLIPJ2000’ (see +\``frames.req’’ document.) + +Since we need only the geometric position, the \`abcorr’ argument of the +routine should be set to ‘NONE’ (see aberration correction discussion in +the (``cspice/src/cspice/spkezr_c.c’’). + +Putting it all together, we get: + +:: + + target = 'CASSINI' + frame = 'ECLIPJ2000' + corrtn = 'NONE' + observ = 'SUN' + + state, ltime = spiceypy.spkezr(target, et, frame, + corrtn, observ) + +When you execute the script, \``getsta’’, it produces the following +output: + +:: + + > python getsta.py + UTC = 2004-06-11T19:32:00 + ET = 140254384.184625 + SCLK = 1465674964.105 + ET = 140254384.183426 + X = -376599061.916539 + Y = 1294487780.929154 + Z = -7064853.054698 + VX = -5.164226 + VY = 0.801719 + VZ = 0.040603 + +\``Spacecraft State’’ Code +-------------------------- + +Program \``getsta.py’’: + +:: + + from __future__ import print_function + import spiceypy + + def getsta(): + + mkfile = 'getsta.tm' + spiceypy.furnsh(mkfile) + + utc = '2004-06-11T19:32:00' + et = spiceypy.str2et(utc) + + print('UTC = {:s}'.format(utc)) + print('ET = {:20.6f}'.format(et)) + + scid = -82 + sclk = '1465674964.105' + et = spiceypy.scs2e(scid, sclk) + + print('SCLK = {:s}'.format(sclk)) + print('ET = {:20.6f}'.format(et)) + + target = 'CASSINI' + frame = 'ECLIPJ2000' + corrtn = 'NONE' + observ = 'SUN' + + state, ltime = spiceypy.spkezr(target, et, frame, + corrtn, observ) + + print(' X = {:20.6f}'.format(state[0])) + print(' Y = {:20.6f}'.format(state[1])) + print(' Z = {:20.6f}'.format(state[2])) + print('VX = {:20.6f}'.format(state[3])) + print('VY = {:20.6f}'.format(state[4])) + print('VZ = {:20.6f}'.format(state[5])) + + spiceypy.unload(mkfile) + + + if __name__ == '__main__': + getsta() + +Meta-kernel file \``getsta.tm’’: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris SPK. + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK. + 981005_PLTEPH-DE405S.bsp Planetary Ephemeris SPK. + sat128.bsp Saturnian Satellite Ephemeris SPK. + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + 'kernels/spk/020514_SE_SAT105.bsp' + 'kernels/spk/030201AP_SK_SM546_T45.bsp' + 'kernels/spk/981005_PLTEPH-DE405S.bsp' + 'kernels/spk/sat128.bsp' + ) + \begintext + +Step-4: \``Sun Direction’’ +========================== + +\``Sun Direction’’ Task Statement +--------------------------------- + +Extend the program from Step-3 to compute apparent direction of the Sun +in the INMS frame at the epoch specified by SCLK time from Step-2. + +\``Sun Direction’’ Hints +------------------------ + +Determine the additional SPICE kernels needed to support the direction +computation, knowing that they should provide the s/c and instrument +frame orientation. Retrieve these kernels from the NAIF’s FTP site. + +Verify that the orientation data in the kernels have adequate coverage +to support computation of the direction of interest. Use +``ckbrief'' utility program located under``\ toolkit/exe’’ directory +for that. + +Modify the meta-kernel to load this(these) kernels. + +Determine the proper input arguments for the spiceypy.spkpos call to +calculate the direction (which is the position portion of the output +state). Look through the Frames Kernel find the name of the frame to +used. + +Add calls to the routine(s), necessary variable declarations and output +print statements to the program. + +\``Sun Direction’’ Solution Steps +--------------------------------- + +A CASSINI spacecraft orientation CK file, providing s/c orientation with +respect to an inertial frame, and CASSINI FK file, providing orientation +of the INMS frame with respect to the s/c frame, are needed additionally +to already loaded kernels to support computation of this direction. + +The file names can be added to the meta-kernel to get them loaded into +the program: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris SPK. + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK. + 981005_PLTEPH-DE405S.bsp Planetary Ephemeris SPK. + sat128.bsp Saturnian Satellite Ephemeris SPK. + 04135_04171pc_psiv2.bc Cassini Spacecraft CK. + cas_v37.tf Cassini FK. + + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + 'kernels/spk/020514_SE_SAT105.bsp' + 'kernels/spk/030201AP_SK_SM546_T45.bsp' + 'kernels/spk/981005_PLTEPH-DE405S.bsp' + 'kernels/spk/sat128.bsp' + 'kernels/ck/04135_04171pc_psiv2.bc' + 'kernels/fk/cas_v37.tf' + ) + \begintext + +The same highest level SpiceyPy routine computing positions, +spiceypy.spkpos, can be used to compute this direction. + +Since this is the direction of the Sun as seen from the s/c, the target +argument should be set to ‘Sun’ and the observer argument should be set +to ‘CASSINI’. The name of the INMS frame is ‘CASSINI_INMS’, the +definition and description of this frame are provided in the CASSINI FK +file, \``cassini_v02.tf’’. + +Since the apparent, or +:literal:`as seen'', position is sought for, the `abcorr' argument of the routine should be set to 'LT+S' (see aberration correction discussion in the (`\ cspice/src/cspice/spkpos_c.c’’) + +If desired, the position can then be turned into a unit vector using +spiceypy.vhat function +(https://spiceypy.readthedocs.io/en/master/documentation.html# +spiceypy.spiceypy.vhat) Putting it all together, we get: + +:: + + target = 'SUN' + frame = 'CASSINI_INMS' + corrtn = 'LT+S' + observ = 'CASSINI' + + sundir, ltime = spiceypy.spkpos(target, et, frame, + corrtn, observ) + sundir = spiceypy.vhat(sundir) + +When you execute the script, \``soldir’’, it produces the following +output: + +:: + + > python soldir.py + UTC = 2004-06-11T19:32:00 + ET = 140254384.184625 + SCLK = 1465674964.105 + ET = 140254384.183426 + X = -376599061.916539 + Y = 1294487780.929154 + Z = -7064853.054698 + VX = -5.164226 + VY = 0.801719 + VZ = 0.040603 + SUNDIR(X) = -0.290204 + SUNDIR(Y) = 0.881631 + SUNDIR(Z) = 0.372167 + +\``Sun Direction’’ Code +----------------------- + +Program \``soldir.py’’: + +:: + + from __future__ import print_function + import spiceypy + + def soldir(): + + mkfile = 'soldir.tm' + spiceypy.furnsh(mkfile) + + utc = '2004-06-11T19:32:00' + et = spiceypy.str2et(utc) + + print('UTC = {:s}'.format(utc)) + print('ET = {:20.6f}'.format(et)) + + scid = -82 + sclk = '1465674964.105' + et = spiceypy.scs2e(scid, sclk) + + print('SCLK = {:s}'.format(sclk)) + print('ET = {:20.6f}'.format(et)) + + target = 'CASSINI' + frame = 'ECLIPJ2000' + corrtn = 'NONE' + observ = 'SUN' + + state, ltime = spiceypy.spkezr(target, et, frame, + corrtn, observ) + + print(' X = {:20.6f}'.format(state[0])) + print(' Y = {:20.6f}'.format(state[1])) + print(' Z = {:20.6f}'.format(state[2])) + print('VX = {:20.6f}'.format(state[3])) + print('VY = {:20.6f}'.format(state[4])) + print('VZ = {:20.6f}'.format(state[5])) + + target = 'SUN' + frame = 'CASSINI_INMS' + corrtn = 'LT+S' + observ = 'CASSINI' + + sundir, ltime = spiceypy.spkpos(target, et, frame, + corrtn, observ) + sundir = spiceypy.vhat(sundir) + + print('SUNDIR(X) = {:20.6f}'.format(sundir[0])) + print('SUNDIR(Y) = {:20.6f}'.format(sundir[1])) + print('SUNDIR(Z) = {:20.6f}'.format(sundir[2])) + + spiceypy.unload(mkfile) + + + if __name__ == '__main__': + soldir() + +Meta-kernel file \``soldir.tm’’: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris SPK. + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK. + 981005_PLTEPH-DE405S.bsp Planetary Ephemeris SPK. + sat128.bsp Saturnian Satellite Ephemeris SPK. + 04135_04171pc_psiv2.bc Cassini Spacecraft CK. + cas_v37.tf Cassini FK. + + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + 'kernels/spk/020514_SE_SAT105.bsp' + 'kernels/spk/030201AP_SK_SM546_T45.bsp' + 'kernels/spk/981005_PLTEPH-DE405S.bsp' + 'kernels/spk/sat128.bsp' + 'kernels/ck/04135_04171pc_psiv2.bc' + 'kernels/fk/cas_v37.tf' + ) + \begintext + +Step-5: \``Sub-Spacecraft Point’’ +================================= + +\``Sub-Spacecraft Point’’ Task Statement +---------------------------------------- + +Extend the program from Step-4 to compute planetocentric longitude and +and latitude of the sub-spacecraft point on Phoebe, and the direction +from the spacecraft to that point in the INMS frame. + +\``Sub-Spacecraft Point’’ Hints +------------------------------- + +Find the SpiceyPy routine that computes sub-observer point coordinates. +Use ``Most Used SpiceyPy APIs'' or``\ subpt’’ cookbook program for that. + +Refer to the routine’s header to determine the additional kernels needed +for this direction computation. Get these kernels from the NAIF’s FTP +site. Modify the meta-kernel to load this(these) kernels. + +Determine the proper input arguments for the routine. Refer to the +routine’s header for that information. + +Convert the surface point Cartesian vector returned by this routine to +latitudinal coordinates. Use \``Permuted Index’’ to find the routine +that does this conversion. Refer to the routine’s header for +input/output argument specifications. + +Since the Cartesian vector from the spacecraft to the sub-spacecraft +point is computed in the Phoebe body-fixed frame, it should be +transformed into the instrument frame get the direction we are looking +for. Refer to ``frames.req'' and/or``\ Frames’’ tutorial to determine +the name of the routine computing transformations and use it to compute +transformation from Phoebe body-fixed to the INMS frame. + +Using \``Permuted Index’’ find the routine that multiplies 3x3 matrix by +3d vector and use it to rotate the vector to the instrument frame. + +Add calls to the routine(s), necessary variable declarations and output +print statements to the program. + +\``Sub-Spacecraft Point’’ Solution Steps +---------------------------------------- + +The spiceypy.subpnt routine +(\```cspice/src/cspice/subpnt_c.c'') can be used to compute the sub-observer point and the vector from the observer to that point with a single call. To determine this point as the closest point on the Phoebe ellipsoid, the``\ method’ +argument has to be set to ‘NEAR POINT: ELLIPSOID’. For our case the +\`target’ is ‘PHOEBE’, the target body-fixed frame is ‘IAU_PHOEBE’, and +the observer is ‘CASSINI’. + +Since the s/c is close to Phoebe, light time does not need to be taken +into account and, therefore, the \`abcorr’ argument can be set to +‘NONE’. + +In order for spiceypy.subpnt to compute the nearest point location, a +PCK file containing Phoebe radii has to be loaded into the program (see +\``Files’’ section of the routine’s header.) All other files required +for this computation are already being loaded by the program. With PCK +file name added to it, the updated meta-kernel will look like this: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris SPK. + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK. + 981005_PLTEPH-DE405S.bsp Planetary Ephemeris SPK. + sat128.bsp Saturnian Satellite Ephemeris SPK. + 04135_04171pc_psiv2.bc Cassini Spacecraft CK. + cas_v37.tf Cassini FK. + cpck05Mar2004.tpc Cassini project PCK. + + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + 'kernels/spk/020514_SE_SAT105.bsp' + 'kernels/spk/030201AP_SK_SM546_T45.bsp' + 'kernels/spk/981005_PLTEPH-DE405S.bsp' + 'kernels/spk/sat128.bsp' + 'kernels/ck/04135_04171pc_psiv2.bc' + 'kernels/fk/cas_v37.tf' + 'kernels/pck/cpck05Mar2004.tpc' + ) + \begintext + +The sub-spacecraft point Cartesian vector can be converted to +planetocentric radius, longitude and latitude using the spiceypy.reclat +routine (``cspice/src/cspice/reclat_c.c’’). + +The vector from the spacecraft to the sub-spacecraft point returned by +spiceypy.subpnt has to be rotated from the body-fixed frame to the +instrument frame. The name of the routine that computes 3x3 matrices +rotating vectors from one frame to another is spiceypy.pxform +(``cspice/src/cspice/pxform_c.c’’). + +In our case the +``from' argument should be set to 'IAU_PHOEBE' and the``\ to’ argument +should be set to ‘CASSINI_INMS’ + +The vector should be then multiplied by this matrix to rotate it to the +instrument frame. The spiceypy.mxv routine performs that function +(``cspice/src/cspice/mxv_c.c’’) + +After applying the rotation, normalize the resultant vector using the +spiceypy.vhat function. + +For output the longitude and latitude angles returned by spiceypy.reclat +in radians can be converted to degrees by multiplying by spiceypy.dpr +function (``cspice/src/cspice/dpr_c.c’’). + +Putting it all together, we get: + +:: + + method = 'NEAR POINT: ELLIPSOID' + target = 'PHOEBE' + frame = 'IAU_PHOEBE' + corrtn = 'NONE' + observ = 'CASSINI' + + spoint, trgepc, srfvec = spiceypy.subpnt(method, target, et, + frame, corrtn, observ) + + srad, slon, slat = spiceypy.reclat(spoint) + + fromfr = 'IAU_PHOEBE' + tofr = 'CASSINI_INMS' + + m2imat = spiceypy.pxform(fromfr, tofr, et) + + sbpdir = spiceypy.mxv(m2imat, srfvec) + sbpdir = spiceypy.vhat(sbpdir) + + print('LON = {:20.6f}'.format(slon * spiceypy.dpr())) + print('LAT = {:20.6f}'.format(slat * spiceypy.dpr())) + +When you execute the script, \``sscpnt’’, it produces the following +output: + +:: + + > python sscpnt.py + UTC = 2004-06-11T19:32:00 + ET = 140254384.184625 + SCLK = 1465674964.105 + ET = 140254384.183426 + X = -376599061.916539 + Y = 1294487780.929154 + Z = -7064853.054698 + VX = -5.164226 + VY = 0.801719 + VZ = 0.040603 + SUNDIR(X) = -0.290204 + SUNDIR(Y) = 0.881631 + SUNDIR(Z) = 0.372167 + LON = 23.423158 + LAT = 3.709797 + SBPDIR(X) = -0.000776 + SBPDIR(Y) = -0.999873 + SBPDIR(Z) = -0.015905 + +\``Sub-Spacecraft Point’’ Code +------------------------------ + +Program + +:: + + from __future__ import print_function + import spiceypy + + def sscpnt(): + + mkfile = 'sscpnt.tm' + spiceypy.furnsh(mkfile) + + utc = '2004-06-11T19:32:00' + et = spiceypy.str2et(utc) + + print('UTC = {:s}'.format(utc)) + print('ET = {:20.6f}'.format(et)) + + scid = -82 + sclk = '1465674964.105' + et = spiceypy.scs2e(scid, sclk) + + print('SCLK = {:s}'.format(sclk)) + print('ET = {:20.6f}'.format(et)) + + target = 'CASSINI' + frame = 'ECLIPJ2000' + corrtn = 'NONE' + observ = 'SUN' + + state, ltime = spiceypy.spkezr(target, et, frame, + corrtn, observ) + + print(' X = {:20.6f}'.format(state[0])) + print(' Y = {:20.6f}'.format(state[1])) + print(' Z = {:20.6f}'.format(state[2])) + print('VX = {:20.6f}'.format(state[3])) + print('VY = {:20.6f}'.format(state[4])) + print('VZ = {:20.6f}'.format(state[5])) + + target = 'SUN' + frame = 'CASSINI_INMS' + corrtn = 'LT+S' + observ = 'CASSINI' + + sundir, ltime = spiceypy.spkpos(target, et, frame, + corrtn, observ) + sundir = spiceypy.vhat(sundir) + + print('SUNDIR(X) = {:20.6f}'.format(sundir[0])) + print('SUNDIR(Y) = {:20.6f}'.format(sundir[1])) + print('SUNDIR(Z) = {:20.6f}'.format(sundir[2])) + + method = 'NEAR POINT: ELLIPSOID' + target = 'PHOEBE' + frame = 'IAU_PHOEBE' + corrtn = 'NONE' + observ = 'CASSINI' + + spoint, trgepc, srfvec = spiceypy.subpnt(method, target, et, + frame, corrtn, observ) + + srad, slon, slat = spiceypy.reclat(spoint) + + fromfr = 'IAU_PHOEBE' + tofr = 'CASSINI_INMS' + + m2imat = spiceypy.pxform(fromfr, tofr, et) + + sbpdir = spiceypy.mxv(m2imat, srfvec) + sbpdir = spiceypy.vhat(sbpdir) + + print('LON = {:20.6f}'.format(slon * spiceypy.dpr())) + print('LAT = {:20.6f}'.format(slat * spiceypy.dpr())) + print('SBPDIR(X) = {:20.6f}'.format(sbpdir[0])) + print('SBPDIR(Y) = {:20.6f}'.format(sbpdir[1])) + print('SBPDIR(Z) = {:20.6f}'.format(sbpdir[2])) + + spiceypy.unload(mkfile) + + + if __name__ == '__main__': + sscpnt() + +Meta-kernel file \``sscpnt.tm’’: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris SPK. + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK. + 981005_PLTEPH-DE405S.bsp Planetary Ephemeris SPK. + sat128.bsp Saturnian Satellite Ephemeris SPK. + 04135_04171pc_psiv2.bc Cassini Spacecraft CK. + cas_v37.tf Cassini FK. + cpck05Mar2004.tpc Cassini project PCK. + + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + 'kernels/spk/020514_SE_SAT105.bsp' + 'kernels/spk/030201AP_SK_SM546_T45.bsp' + 'kernels/spk/981005_PLTEPH-DE405S.bsp' + 'kernels/spk/sat128.bsp' + 'kernels/ck/04135_04171pc_psiv2.bc' + 'kernels/fk/cas_v37.tf' + 'kernels/pck/cpck05Mar2004.tpc' + ) + \begintext + +Step-6: \``Spacecraft Velocity’’ +================================ + +\``Spacecraft Velocity’’ Task Statement +--------------------------------------- + +Extend the program from Step-5 to compute the spacecraft velocity with +respect to Phoebe in the INMS frame. + +\``Spacecraft Velocity’’ Hints +------------------------------ + +Compute velocity of the spacecraft with respect to Phoebe in some +inertial frame, for example J2000. Recall that velocity is the last +three components of the state vector returned by spiceypy.spkezr. + +Since the velocity vector is computed in the inertial frame, it should +be rotated to the instrument frame. Look at the previous step the +routine that compute necessary rotation and rotate vectors. + +Add calls to the routine(s), necessary variable declarations and output +print statements to the program. + +\``Spacecraft Velocity’’ Solution Steps +--------------------------------------- + +All kernels required for computations in this step are already being +loaded by the program, therefore, the meta-kernel does not need to be +changed. + +The spacecraft velocity vector is the last three components of the state +returned by spiceypy.spkezr. To compute velocity of CASSINI with respect +to Phoebe in the J2000 inertial frame the spiceypy.spkezr arguments +should be set to ‘CASSINI’ (TARG), ‘PHOEBE’ (OBS), ‘J2000’ (REF) and +‘NONE’ (ABCORR). + +The computed velocity vector has to be rotated from the J2000 frame to +the instrument frame. The spiceypy.pxform routine used in the previous +step can be used to compute the rotation matrix needed for that. In this +case the frame name arguments should be set to ‘J2000’ (FROM) and +‘CASSINI_INMS’ (TO). + +As in the previous step the difference vector should be then multiplied +by this rotation matrix using the spiceypy.mxv routine. After applying +the rotation, normalize the resultant vector using the spiceypy.vhat +routine. + +Putting it all together, we get: + +:: + + target = 'CASSINI' + frame = 'J2000' + corrtn = 'NONE' + observ = 'PHOEBE' + + state, ltime = spiceypy.spkezr(target, et, frame, + corrtn, observ) + scvdir = state[3:6] + + fromfr = 'J2000' + tofr = 'CASSINI_INMS' + j2imat = spiceypy.pxform(fromfr, tofr, et) + + scvdir = spiceypy.mxv(j2imat, scvdir) + scvdir = spiceypy.vhat(scvdir) + +When you execute the script, \``scvel’’, it produces the following +output: + +:: + + > python scvel.py + UTC = 2004-06-11T19:32:00 + ET = 140254384.184625 + SCLK = 1465674964.105 + ET = 140254384.183426 + X = -376599061.916539 + Y = 1294487780.929154 + Z = -7064853.054698 + VX = -5.164226 + VY = 0.801719 + VZ = 0.040603 + SUNDIR(X) = -0.290204 + SUNDIR(Y) = 0.881631 + SUNDIR(Z) = 0.372167 + LON = 23.423158 + LAT = 3.709797 + SBPDIR(X) = -0.000776 + SBPDIR(Y) = -0.999873 + SBPDIR(Z) = -0.015905 + SCVDIR(X) = 0.395785 + SCVDIR(Y) = -0.292808 + SCVDIR(Z) = 0.870413 + +Note that computing the spacecraft velocity in the instrument frame by a +single call to spiceypy.spkezr by specifying ‘CASSINI_INMS’ in the +\`ref’ argument returns an incorrect result. Such computation will take +into account the spacecraft angular velocity from the CK files, which +should not be considered in this case. + +``Spacecraft Velocity'' Code Program``\ scvel.py’’: +--------------------------------------------------- + +:: + + from __future__ import print_function + import spiceypy + + def scvel(): + + mkfile = 'scvel.tm' + spiceypy.furnsh(mkfile) + + utc = '2004-06-11T19:32:00' + et = spiceypy.str2et(utc) + + print('UTC = {:s}'.format(utc)) + print('ET = {:20.6f}'.format(et)) + + scid = -82 + sclk = '1465674964.105' + et = spiceypy.scs2e(scid, sclk) + + print('SCLK = {:s}'.format(sclk)) + print('ET = {:20.6f}'.format(et)) + + target = 'CASSINI' + frame = 'ECLIPJ2000' + corrtn = 'NONE' + observ = 'SUN' + + state, ltime = spiceypy.spkezr(target, et, frame, + corrtn, observ) + + print(' X = {:20.6f}'.format(state[0])) + print(' Y = {:20.6f}'.format(state[1])) + print(' Z = {:20.6f}'.format(state[2])) + print('VX = {:20.6f}'.format(state[3])) + print('VY = {:20.6f}'.format(state[4])) + print('VZ = {:20.6f}'.format(state[5])) + + target = 'SUN' + frame = 'CASSINI_INMS' + corrtn = 'LT+S' + observ = 'CASSINI' + + sundir, ltime = spiceypy.spkpos(target, et, frame, + corrtn, observ) + sundir = spiceypy.vhat(sundir) + + print('SUNDIR(X) = {:20.6f}'.format(sundir[0])) + print('SUNDIR(Y) = {:20.6f}'.format(sundir[1])) + print('SUNDIR(Z) = {:20.6f}'.format(sundir[2])) + + method = 'NEAR POINT: ELLIPSOID' + target = 'PHOEBE' + frame = 'IAU_PHOEBE' + corrtn = 'NONE' + observ = 'CASSINI' + + spoint, trgepc, srfvec = spiceypy.subpnt(method, target, et, + frame, corrtn, observ) + + srad, slon, slat = spiceypy.reclat(spoint) + + fromfr = 'IAU_PHOEBE' + tofr = 'CASSINI_INMS' + + m2imat = spiceypy.pxform(fromfr, tofr, et) + + sbpdir = spiceypy.mxv(m2imat, srfvec) + sbpdir = spiceypy.vhat(sbpdir) + + print('LON = {:20.6f}'.format(slon * spiceypy.dpr())) + print('LAT = {:20.6f}'.format(slat * spiceypy.dpr())) + print('SBPDIR(X) = {:20.6f}'.format(sbpdir[0])) + print('SBPDIR(Y) = {:20.6f}'.format(sbpdir[1])) + print('SBPDIR(Z) = {:20.6f}'.format(sbpdir[2])) + + target = 'CASSINI' + frame = 'J2000' + corrtn = 'NONE' + observ = 'PHOEBE' + + state, ltime = spiceypy.spkezr(target, et, frame, + corrtn, observ) + scvdir = state[3:6] + + fromfr = 'J2000' + tofr = 'CASSINI_INMS' + j2imat = spiceypy.pxform(fromfr, tofr, et) + + scvdir = spiceypy.mxv(j2imat, scvdir) + scvdir = spiceypy.vhat(scvdir) + + print('SCVDIR(X) = {:20.6f}'.format(scvdir[0])) + print('SCVDIR(Y) = {:20.6f}'.format(scvdir[1])) + print('SCVDIR(Z) = {:20.6f}'.format(scvdir[2])) + + spiceypy.unload(mkfile) + + + if __name__ == '__main__': + scvel() + +Meta-kernel file \``scvel.tm’’: + +:: + + KPL/MK + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + + File Name Description + -------------------------- ---------------------------------- + naif0008.tls Generic LSK. + cas00084.tsc Cassini SCLK. + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris SPK. + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK. + 981005_PLTEPH-DE405S.bsp Planetary Ephemeris SPK. + sat128.bsp Saturnian Satellite Ephemeris SPK. + 04135_04171pc_psiv2.bc Cassini Spacecraft CK. + cas_v37.tf Cassini FK. + cpck05Mar2004.tpc Cassini project PCK. + + + \begindata + KERNELS_TO_LOAD = ( + 'kernels/lsk/naif0008.tls' + 'kernels/sclk/cas00084.tsc' + 'kernels/spk/020514_SE_SAT105.bsp' + 'kernels/spk/030201AP_SK_SM546_T45.bsp' + 'kernels/spk/981005_PLTEPH-DE405S.bsp' + 'kernels/spk/sat128.bsp' + 'kernels/ck/04135_04171pc_psiv2.bc' + 'kernels/fk/cas_v37.tf' + 'kernels/pck/cpck05Mar2004.tpc' + ) + \begintext diff --git a/docs/installation.rst b/docs/installation.rst index 333fb15f..7f588986 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,12 +2,12 @@ Installation ============ -SpiceyPy is currently supported on Mac, Linux, and Windows systems. +SpiceyPy is currently supported on Mac, Linux, FreeBSD, and Windows systems. .. _installation: If you are new to python, it is a good idea to read a bit about it first ``_. -For new installations of python, it is encouraged to install and or update: pip, setuptools, wheel, numpy, six, certifi:: +For new installations of python, it is encouraged to install and or update: pip, setuptools, wheel, numpy, six, and certifi first before installing SpiceyPy :: pip install -U pip setuptools wheel pip install -U numpy six certifi @@ -18,7 +18,8 @@ Then to install SpiceyPy, simply run:: If you use anaconda/miniconda/conda run:: - conda install -c https://conda.anaconda.org/andrewannex spiceypy + conda config --add channels conda-forge + conda install spiceypy If no error was returned you have successfully installed SpiceyPy. To verify this you can list the installed packages via this pip command:: @@ -38,6 +39,84 @@ Or you can start a python interpreter and try importing SpiceyPy like so: This should print out the toolkit version without any errors. You have now verified that SpiceyPy is installed. +A simple example program +------------------------ + +This script calls the spiceypy function ‘tkvrsn’ and outputs the return +value. + +:: + + File tkvrsn.py + + from __future__ import print_function + import spiceypy + + def print_ver(): + """Prints the TOOLKIT version + """ + print(spiceypy.tkvrsn('TOOLKIT')) + + if __name__ == '__main__': + print_ver() + +From the command line, execute the function: + +:: + + $ python tkvrsn.py + CSPICE_N0066 + +From Python, execute the function: + +:: + + $ python + >>> import tkvrsn + >>> tkvrsn.print_ver() + CSPICE_N0066 + +SpiceyPy Documentation +---------------------- + +The current version of SpiceyPy does not provide extensive +documentation, but there are several ways to navigate your way through +the Python version of the toolkit. One simple way is to use the standard +Python mechanisms. All interfaces implemented in SpiceyPy can be listed +using the standard built-in function dir(), which returns an +alphabetized list of names comprising (among) other things, the API +names. If you need to get additional information about an API +parameters, the standard built-in function help() could be used: + +:: + + >>> import spiceypy + >>> help(spiceypy.tkvrsn) + +which produces + +:: + + Help on function tkvrsn in module spiceypy.spiceypy: + + tkvrsn(item) + Given an item such as the Toolkit or an entry point name, return + the latest version string. + + http://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/tkvrsn_c. + html + + :param item: Item for which a version string is desired. + :type item: str + :return: the latest version string. + :rtype: str + +As indicated in the help on the function, the complete documentation is +available on the CSPICE toolkit version. Therefore it is recommended to +have the CSPICE toolkit version installed locally in order to access its +documentation offline. + + ============= Common Issues ============= diff --git a/docs/lessonindex.rst b/docs/lessonindex.rst index 525cdbca..7ed2de11 100644 --- a/docs/lessonindex.rst +++ b/docs/lessonindex.rst @@ -2,8 +2,10 @@ Lessons ======= Here listed are the various SPICE lessons provided by the NAIF translated to -use python code examples. Please refer to the NAIF lessons for the kernel -files needed. +use python code examples. Please refer to the NAIF lesson files for the kernel +files needed to complete the exercises and to obtain the full content naiflessons_. + +.. _naiflessons: https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/ Contents: @@ -11,5 +13,10 @@ Contents: :maxdepth: 1 basics + remote_sensing + event_finging + insitu_sensing + binary_pck + other_stuff diff --git a/docs/other_stuff.rst b/docs/other_stuff.rst new file mode 100644 index 00000000..da158bec --- /dev/null +++ b/docs/other_stuff.rst @@ -0,0 +1,2237 @@ +Other Stuff (Python) +==================== + +November 20, 2017 + +The extensive scope of the SpiceyPy system’s functionality includes +features the average user may not expect or appreciate, features NAIF +refers to as “Other Stuff.” This workbook includes a set of lessons to +introduce the beginning to moderate user to such features. + +The lessons provide a brief description to several related sets of +routines, associated reference documents, a programming task designed to +teach the use of the routines, and an example solution to the +programming problem. + +Overview +-------- + +This workbook contains lessons to demonstrate use of the less celebrated +SpiceyPy routines. + +:: + + 1. Kernel Management with the Kernel Subsystem + + 2. The Kernel Pool + + 3. Coordinate Conversions + + 4. Advanced Time Manipulation Routines + + 5. Error Handling + + 6. Windows and Cells + + 7. Utility and Constants Routines + +References +---------- + +This section lists SPICE documents referred to in this lesson. + +The following SPICE tutorials serve as references for the discussions in +this lesson: + +:: + + Name Lesson steps/functions it describes + ---------------- ----------------------------------------------- + concepts Concepts of space geometry and time + intro_to_kernels Using kernels, meta-kernels + time Time systems, conversions and formats + lsk_and_sclk LSK and SCLK + derived_quant "high-level" observation geometry computations + other_functions Intro to some SPICE "low level" computations + exceptions built-in mechanism for trapping/handling errors + +These tutorials are available from the NAIF ftp server at JPL: + +:: + + http://naif.jpl.nasa.gov/naif/tutorials.html + +Required Readings + +The Required Reading documents are provided with the Toolkit and are +located under the \``cspice/doc’’ directory in the CSPICE Toolkit +installation tree. + +:: + + Name Lesson steps/functions that it describes + --------------- ----------------------------------------- + cells.req The SPICE cell data type + error.req The SPICE error handling system + kernel.req Loading SPICE kernels + time.req Time conversion + windows.req The SPICE window data type + +The Permuted Index + +Another useful document distributed with the Toolkit is the permuted +index. This is located under the \``cspice/doc’’ directory in the C +installation tree. + +This text document provides a simple mechanism by which users can +discover which SpiceyPy functions perform functions of interest, as well +as the names of the source files that contain these functions. + +SpiceyPy API Documentation + +A SpiceyPy function’s parameters specification is available using the +built-in Python help system. A more detailed specification of the API +can be found in the CSPICE HTML API documentation page located under +\``cspice/doc/html/cspice’’. + +For example, the Python help function + +:: + + >>> import spiceypy + >>> help(spiceypy.str2et) + +describes of the str2et function’s parameters, while the document + +:: + + cspice/doc/html/cspice/str2et_c.html + +describes extensively the str2et functionality. + +Kernels Used +------------ + +The following kernels are used in examples provided in this lesson: + +:: + + # FILE NAME TYPE DESCRIPTION + -- ------------ ---- ------------------------------------------------ + 1 naif0008.tls LSK Generic LSK + 2 de405s.bsp SPK Planet Ephemeris SPK + 3 pck00008.tpc PCK Generic PCK + +These SPICE kernels are included in the lesson package available from +the NAIF server at JPL: + +:: + + ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/ + +SpiceyPy Modules Used +--------------------- + +This section provides a complete list of the functions and kernels that +are suggested for usage in each of the exercises in this lesson. (You +may wish to not look at this list unless/until you \``get stuck’’ while +working on your own.) + +:: + + CHAPTER EXERCISE FUNCTIONS NON-VOID KERNELS + ------- --------- --------------- --------------- ---------- + 1 kpool spiceypy.furnsh spiceypy.ktotal 1-3 + spiceypy.unload spiceypy.kdata + spiceypy.kclear + + 2 kervar spiceypy.furnsh spiceypy.gnpool 1-3 + spiceypy.kclear spiceypy.dtpool + spiceypy.gdpool + spiceypy.gcpool + + 3 coord spiceypy.furnsh spiceypy.dpr 1-3 + spiceypy.kclear spiceypy.str2et + spiceypy.bodvrd + spiceypy.spkpos + spiceypy.recrad + spiceypy.reclat + spiceypy.recsph + spiceypy.recgeo + + 4 xtic spiceypy.furnsh spiceypy.str2et 1 + spiceypy.tsetyr spiceypy.timout + spiceypy.kclear spiceypy.tpictr + spiceypy.jyear + + 5 aderr spiceypy.furnsh spiceypy.spkezr 1-3 + spiceypy.kclear + + 6 win spiceypy.furnsh spiceypy.str2et 1-3 + spiceypy.wninsd spiceypy.wnvald + spiceypy.kclear spiceypy.wnintd + spiceypy.card + spiceypy.wnfetd + spiceypy.et2utc + spiceypy.wnsumd + + 7 units spiceypy.tkvrsn + spiceypy.convrt + + xconst spiceypy.spd + spiceypy.dpr + spiceypy.rpd + spiceypy.clight + spiceypy.j2100 + spiceypy.j2000 + spiceypy.tyear + spiceypy.halfpi + +Use the Python built-in help system on the various functions listed +above for the API parameters’ description, and refer to the headers of +their corresponding CSPICE versions for detailed interface +specifications. + +NAIF Documentation +================== + +The technical complexity of the various SPICE subsystems mandates an +extensive, user-friendly documentation set. The set differs somewhat +depending on your choice of development language but provides the same +information with regards to SPICE operation. The sources for a user +needing information concerning SPICE are: + +:: + + -- Required Readings and Users Guides + + -- Library Source Code Documentation + + -- API Documentation + + -- Tutorials + +Required Reading and Users Guides + +NAIF Required Reading (*.req) documents introduce the functionality of +particular SpiceyPy subsystems: + +:: + + abcorr.req + cells.req + ck.req + daf.req + das.req + dla.req + dsk.req + ek.req + ellipses.req + error.req + frames.req + gf.req + kernel.req + naif_ids.req + pck.req + planes.req + problems.req + rotation.req + scanning.req + sclk.req + sets.req + spc.req + spk.req + symbols.req + time.req + windows.req + +NAIF Users Guides (*.ug) describe the proper use of particular SpiceyPy +tools: + +:: + + brief.ug + chronos.ug + ckbrief.ug + commnt.ug + convert.ug + dskbrief.ug + dskexp.ug + frmdiff.ug + inspekt.ug + mkdsk.ug + mkspk.ug + msopck.ug + simple.ug + spacit.ug + spkdiff.ug + spkmerge.ug + states.ug + subpt.ug + tictoc.ug + tobin.ug + toxfr.ug + version.ug + +These text documents exist in the ‘doc’ directory of the main CSPICE +Toolkit directory: + +:: + + ../cspice/doc/ + +HTML format documentation + +The SpiceyPy distributions include HTML versions of Required Readings +and Users Guides, accessible from the HTML documentation directory: + +:: + + ../cspice/doc/html/index.html + +Library Source Code Documentation + +All SPICELIB and CSPICE source files include usage and design +information incorporated in a comment block known as the “header.” +(Every toolkit includes either the SPICELIB or CSPICE library.) + +A header consists of several marked sections: + +:: + + -- Procedure: Routine name and one line expansion of the routine's + name. + + -- Abstract: A tersely worded explanation describing the routine. + + -- Copyright: An identification of the copyright holder for the + routine. + + -- Required_Reading: A list of SpiceyPy required reading documents + relating to the routine. + + -- Brief_I/O: A table of arguments, identifying each as either + input, output, or both, with a very brief description of the + variable. + + -- Detailed_Input & Detailed_Output: An elaboration of the + Brief_I/O section providing comprehensive information on + argument use. + + -- Parameters: Description and declaration of any parameters + (constants) specific to the routine. + + -- Exceptions: A list of error conditions the routine detects and + signals plus a discussion of any other exceptional conditions + the routine may encounter. + + -- Files: A list of other files needed for the routine to operate. + + -- Particulars: A discussion of the routine's function (if + needed). This section may also include information relating to + "how" and "why" the routine performs an operation and to + explain functionality of routines that operate by side effects. + + -- Examples: Descriptions and code snippets concerning usage of + the routine. + + -- Restrictions: Restrictions or warnings concerning use. + + -- Literature_References: A list of sources required to understand + the algorithms or data used in the routine. + + -- Author_and_Institution: The names and affiliations for authors + of the routine. + + -- Version: A list of edits and the authors of those edits made to + the routine since initial delivery to the SpiceyPy system. + +The source code for SpiceyPy products is stored in ‘src’ sub-directory +of the main SpiceyPy directory: + +API Documentation + +The SpiceyPy package is documented in \``readthedocs’’ website: + +:: + + https://spiceypy.readthedocs.io/en/master/index.html + +Each API documentation page is in large part copied from the +``Abstract'' and``\ Brief_I/O’’ sections of the corresponding CSPICE +function documentation. Each API page includes a link to the API +documentation for the CSPICE routine called by the SpiceyPy interface. + +This SpiceyPy API documentation (the same information as in the website +but without hyperlinks) is also available from the Python built-in help +system: + +:: + + >>> help ( spiceypy.str2et ) + Help on function str2et in module spiceypy.spiceypy: + + str2et(*args, **kwargs) + Convert a string representing an epoch to a double precision + value representing the number of TDB seconds past the J2000 + epoch corresponding to the input epoch. + + ... + + :param time: A string representing an epoch. + :type time: str + :return: The equivalent value in seconds past J2000, TDB. + :rtype: float + +In order to have offline access to the documentation it is recommended +to have the CSPICE Toolkit installed locally. The CSPICE package +includes the CSPICE Reference Guide, an index of all CSPICE wrapper APIs +with hyperlinks to API specific documentation. Each API documentation +page includes cross-links to any other wrapper API mentioned in the +document and links to the wrapper source code. + +:: + + ...cspice/doc/html/cspice/index.html + +Text kernels +------------ + +Several workbooks use SPICE text kernels. SPICE identifies a text kernel +as an ASCII text file containing the mark-up tags the kernel subsystem +requires to identify data assignments in that file, and “name=value” +data assignments. + +The subsystem uses two tags: + +:: + + \begintext + +and + +:: + + \begindata + +to mark information blocks within the text kernel. The +:raw-latex:`\begintext `tag specifies all text following the tag as +comment information to be ignored by the subsystem. + +Things to know: + +:: + + 1. The \begindata tag marks the start of a data definition block. + The subsystem processes all text following this marker as SPICE + kernel data assignments until finding a \begintext marker. + + 2. The kernel subsystem defaults to the \begintext mode until the + parser encounters a \begindata tag. Once in \begindata mode the + subsystem processes all text as variable assignments until the + next \begintext tag. + + 3. Enter the tags as the only text on a line, i.e.: + + + \begintext + + ... commentary information on the data assignments ... + + \begindata + + ... data assignments ... + + + 4. CSPICE delivery N0059 added to the CSPICE and Icy text kernel + parsers the functionality to read non native text kernels, i.e. + a Unix compiled library can read a MS Windows native text + kernel, a MS Windows compiled library can read a Unix native + text kernel. Mice acquires this capability from CSPICE. + + 5. With regards to the FORTRAN distribution, as of delivery N0057 + the spiceypy.furnsh call includes a line terminator check, + signaling an error on any attempt to read non-native text + kernels. + +Text kernel format + +Scalar assignments. + +:: + + VAR_NAME_DP = 1.234 + VAR_NAME_INT = 1234 + VAR_NAME_STR = 'FORBIN' + +Please note the use of a single quote in string assignments. + +Vector assignments. Vectors must contain the same type data. + +:: + + VEC_NAME_DP = ( 1.234 , 45.678 , 901234.5 ) + VEC_NAME_INT = ( 1234 , 456 , 789 ) + VEC_NAME_STR = ( 'FORBIN', 'FALKEN', 'ROBUR' ) + + also + + VEC_NAME_DP = ( 1.234, + 45.678, + 901234.5 ) + + VEC_NAME_STR = ( 'FORBIN', + 'FALKEN', + 'ROBUR' ) + +Time assignments. + +:: + + TIME_VAL = @31-JAN-2003-12:34:56.798 + TIME_VEC = ( @01-DEC-2004, @15-MAR-2004 ) + +The at-sign character ‘@’ indicates a time string. The pool subsystem +converts the strings to double precision TDB (a numeric value). Please +note, the time strings must not contain embedded blanks. WARNING - a TDB +string is not the same as a UTC string. + +The above examples depict direct assignments via the ‘=’ operator. The +kernel pool also permits incremental assignments via the ‘+=’ operator. + +Please refer to the kernels required reading, kernel.req, for additional +information. + +Lesson 1: Kernel Management with the Kernel Subsystem +===================================================== + +Task Statement +-------------- + +Write a program to load a meta kernel, interrogate the SpiceyPy system +for the names and types of all loaded kernels, then demonstrate the +unload functionality and the resulting effects. + +Learning Goals +-------------- + +This lesson demonstrates use of the kernel subsystem to load, unload, +and list loaded kernels. + +This lesson requires creation of a SPICE meta kernel. + +Code Solution +------------- + +First, create a meta text kernel: + +You can use two versions of a meta kernel with code examples (kpool.tm) +in this lesson. Either a kernel with explicit path information: + +:: + + KPL/MK + + \begindata + + KERNELS_TO_LOAD = ( 'kernels/spk/de405s.bsp', + 'kernels/pck/pck00008.tpc', + 'kernels/lsk/naif0008.tls' ) + + \begintext + +… or a more generic meta kernel using the PATH_VALUES/PATH_SYMBOLS +functionality to declare path names as variables: + +:: + + KPL/MK + + Define the paths to the kernel directory. Use the PATH_SYMBOLS + as aliases to the paths. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File Name Description + --------------- ------------------------------ + naif0008.tls Generic LSK. + de405s.bsp Planet Ephemeris SPK. + pck00008.tpc Generic PCK. + + + \begindata + + PATH_VALUES = ( 'kernels/lsk', + 'kernels/spk', + 'kernels/pck' ) + + PATH_SYMBOLS = ( 'LSK', 'SPK', 'PCK' ) + + KERNELS_TO_LOAD = ( '$LSK/naif0008.tls', + '$SPK/de405s.bsp', + '$PCK/pck00008.tpc' ) + + \begintext + +Now the solution source code: + +:: + + from __future__ import print_function + + # + # Import the CSPICE-Python interface. + # + import spiceypy + + def kpool(): + + # + # Assign the path name of the meta kernel to META. + # + META = 'kpool.tm' + + + # + # Load the meta kernel then use KTOTAL to interrogate the SPICE + # kernel subsystem. + # + spiceypy.furnsh( META ) + + + count = spiceypy.ktotal( 'ALL' ); + print( 'Kernel count after load: {0}\n'.format(count)) + + + # + # Loop over the number of files; interrogate the SPICE system + # with spiceypy.kdata for the kernel names and the type. + # 'found' returns a boolean indicating whether any kernel files + # of the specified type were loaded by the kernel subsystem. + # This example ignores checking 'found' as kernels are known + # to be loaded. + # + for i in range(0, count): + [ file, type, source, handle] = spiceypy.kdata(i, 'ALL'); + print( 'File {0}'.format(file) ) + print( 'Type {0}'.format(type) ) + print( 'Source {0}\n'.format(source) ) + + + # + # Unload one kernel then check the count. + # + spiceypy.unload( 'kernels/spk/de405s.bsp') + count = spiceypy.ktotal( 'ALL' ); + + # + # The subsystem should report one less kernel. + # + print( 'Kernel count after one unload: {0}'.format(count)) + + # + # Now unload the meta kernel. This action unloads all + # files listed in the meta kernel. + # + spiceypy.unload( META ) + + + # + # Check the count; spiceypy should return a count of zero. + # + count = spiceypy.ktotal( 'ALL'); + print( 'Kernel count after meta unload: {0}'.format(count)) + + + # + # Done. Unload the kernels. + # + spiceypy.kclear + + if __name__ == '__main__': + kpool() + +Run the code example + +First we see the number of all loaded kernels returned from the +spiceypy.ktotal call. + +Then the spiceypy.kdata loop returns the name of each loaded kernel, the +type of kernel (SPK, CK, TEXT, etc.) and the source of the kernel - the +mechanism that loaded the kernel. The source either identifies a meta +kernel, or contains an empty string. An empty source string indicates a +direct load of the kernel with a spiceypy.furnsh call. + +:: + + Kernel count after load: 4 + + File kpool.tm + Type META + Source + + File kernels/lsk/naif0008.tls + Type TEXT + Source kpool.tm + + File kernels/spk/de405s.bsp + Type SPK + Source kpool.tm + + File kernels/pck/pck00008.tpc + Type TEXT + Source kpool.tm + + Kernel count after one unload: 3 + Kernel count after meta unload: 0 + +Lesson 2: The Kernel Pool +========================= + +.. _task-statement-1: + +Task Statement +-------------- + +Write a program to retrieve particular string and numeric text kernel +variables, both scalars and arrays. Interrogate the kernel pool for +assigned variable names. + +.. _learning-goals-1: + +Learning Goals +-------------- + +The lesson demonstrates the SpiceyPy system’s facility to retrieve +different types of data (string, numeric, scalar, array) from the kernel +pool. + +For the code examples, use this generic text kernel (kervar.tm) +containing PCK-type data, kernels to load, and example time strings: + +:: + + KPL/MK + + Name the kernels to load. Use path symbols. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File Name Description + --------------- ------------------------------ + naif0008.tls Generic LSK. + de405s.bsp Planet Ephemeris SPK. + pck00008.tpc Generic PCK. + + + \begindata + + PATH_VALUES = ('kernels/spk', + 'kernels/pck', + 'kernels/lsk') + + PATH_SYMBOLS = ('SPK' , 'PCK' , 'LSK' ) + + KERNELS_TO_LOAD = ( '$SPK/de405s.bsp', + '$PCK/pck00008.tpc', + '$LSK/naif0008.tls') + + \begintext + + Ring model data. + + \begindata + + BODY699_RING1_NAME = 'A Ring' + BODY699_RING1 = (122170.0 136780.0 0.1 0.1 0.5) + + BODY699_RING1_1_NAME = 'Encke Gap' + BODY699_RING1_1 = (133405.0 133730.0 0.0 0.0 0.0) + + BODY699_RING2_NAME = 'Cassini Division' + BODY699_RING2 = (117580.0 122170.0 0.0 0.0 0.0) + + \begintext + + The kernel pool recognizes values preceded by '@' as time + values. When read, the kernel subsystem converts these + representations into double precision ephemeris time. + + Caution: The kernel subsystem interprets the time strings + identified by '@' as TDB. The same string passed as input + to @STR2ET is processed as UTC. + + The three expressions stored in the EXAMPLE_TIMES array represent + the same epoch. + + \begindata + + EXAMPLE_TIMES = ( @APRIL-1-2004-12:34:56.789, + @4/1/2004-12:34:56.789, + @JD2453097.0242684 + ) + + \begintext + +The main references for pool routines are found in the help command, the +CSPICE source files or the API documentation for the particular +routines. + +.. _code-solution-1: + +Code Solution +------------- + +:: + + from __future__ import print_function + + # + # Import the CSPICE-Python interface. + # + import spiceypy + from spiceypy.utils.support_types import SpiceyError + + def kervar(): + + # + # Define the max number of kernel variables + # of concern for this examples. + # + N_ITEMS = 20 + + # + # Load the example kernel containing the kernel variables. + # The kernels defined in KERNELS_TO_LOAD load into the + # kernel pool with this call. + # + spiceypy.furnsh( 'kervar.tm' ) + + # + # Initialize the start value. This value indicates + # index of the first element to return if a kernel + # variable is an array. START = 0 indicates return everything. + # START = 1 indicates return everything but the first element. + # + START = 0 + + # + # Set the template for the variable names to find. Let's + # look for all variables containing the string RING. + # Define this with the wildcard template '*RING*'. Note: + # the template '*RING' would match any variable name + # ending with the RING string. + # + tmplate = '*RING*' + + # + # We're ready to interrogate the kernel pool for the + # variables matching the template. spiceypy.gnpool tells us: + # + # 1. Does the kernel pool contain any variables that + # match the template (value of found). + # 2. If so, how many variables? + # 3. The variable names. (cvals, an array of strings) + # + + try: + cvals = spiceypy.gnpool( tmplate, START, N_ITEMS ) + print( 'Number variables matching template: {0}'.\ + format( len(cvals)) ) + except SpiceyError: + print( 'No kernel variables matched template.' ) + return + + + # + # Okay, now we know something about the kernel pool + # variables of interest to us. Let's find out more... + # + for cval in cvals: + + # + # Use spiceypy.dtpool to return the dimension and type, + # C (character) or N (numeric), of each pool + # variable name in the cvals array. We know the + # kernel data exists. + # + [dim, type] = spiceypy.dtpool( cval ) + + print( '\n' + cval ) + print( ' Number items: {0} Of type: {1}\n'.\ + format(dim, type) ) + + # + # Test character equality, 'N' or 'C'. + # + if type == 'N': + + # + # If 'type' equals 'N', we found a numeric array. + # In this case any numeric array will be an array + # of double precision numbers ('doubles'). + # spiceypy.gdpool retrieves doubles from the + # kernel pool. + # + dvars = spiceypy.gdpool( cval, START, N_ITEMS ) + for dvar in dvars: + print(' Numeric value: {0:20.6f}'.format(dvar)) + + elif type == 'C': + + # + # If 'type' equals 'C', we found a string array. + # spiceypy.gcpool retrieves string values from the + # kernel pool. + # + cvars = spiceypy.gcpool( cval, START, N_ITEMS ) + + for cvar in cvars: + print(' String value: {0}\n'.format(cvar)) + + else: + + # + # This block should never execute. + # + print('Unknown type. Code error.') + + + # + # Now look at the time variable EXAMPLE_TIMES. Extract this + # value as an array of doubles. + # + dvars = spiceypy.gdpool( 'EXAMPLE_TIMES', START, N_ITEMS ) + + print( 'EXAMPLE_TIMES' ) + + for dvar in dvars: + print(' Time value: {0:20.6f}'.format(dvar)) + + # + # Done. Unload the kernels. + # + spiceypy.kclear + + if __name__ == '__main__': + kervar() + +Run the code example + +The program runs and first reports the number of kernel pool variables +matching the template, 6. + +The program then loops over the spiceypy.dtpool 6 times, reporting the +name of each pool variable, the number of data items assigned to that +variable, and the variable type. Within the spiceypy.dtpool loop, a +second loop outputs the contents of the data variable using +spiceypy.gcpool or spiceypy.gdpool. + +:: + + Number variables matching template: 6 + + BODY699_RING1_1 + Number items: 5 Of type: N + + Numeric value: 133405.000000 + Numeric value: 133730.000000 + Numeric value: 0.000000 + Numeric value: 0.000000 + Numeric value: 0.000000 + + BODY699_RING1 + Number items: 5 Of type: N + + Numeric value: 122170.000000 + Numeric value: 136780.000000 + Numeric value: 0.100000 + Numeric value: 0.100000 + Numeric value: 0.500000 + + BODY699_RING2 + Number items: 5 Of type: N + + Numeric value: 117580.000000 + Numeric value: 122170.000000 + Numeric value: 0.000000 + Numeric value: 0.000000 + Numeric value: 0.000000 + + BODY699_RING1_1_NAME + Number items: 1 Of type: C + + String value: Encke Gap + + + BODY699_RING2_NAME + Number items: 1 Of type: C + + String value: Cassini Division + + + BODY699_RING1_NAME + Number items: 1 Of type: C + + String value: A Ring + + EXAMPLE_TIMES + Time value: 134094896.789000 + Time value: 134094896.789000 + Time value: 134094896.789753 + +Note the final time value differs from the previous values in the final +three decimal places despite the intention that all three strings +represent the same time. This results from round-off when converting a +decimal Julian day representation to the seconds past J2000 ET +representation. + +Related Routines +---------------- + +:: + + -- spiceypy.gipool retrieves integer values from the kernel + subsystem. + +Lesson 3: Coordinate Conversions +================================ + +.. _task-statement-2: + +Task Statement +-------------- + +Write a program to convert a Cartesian 3-vector representing some +location to the other coordinate representations. Use the position of +the Moon with respect to Earth in an inertial and non-inertial reference +frame as the example vector. + +.. _learning-goals-2: + +Learning Goals +-------------- + +The SpiceyPy system provides functions to convert coordinate tuples +between Cartesian and various non Cartesian coordinate systems including +conversion between geodetic and rectangular coordinates. + +This lesson presents these coordinate transform routines for +rectangular, cylindrical, and spherical systems. + +.. _code-solution-2: + +Code Solution +------------- + +:: + + from __future__ import print_function + from builtins import input + import sys + + # + # Import the CSPICE-Python interface. + # + import spiceypy + + def coord(): + + # + # Define the inertial and non inertial frame names. + # + # Initialize variables or set type. All variables + # used in a PROMPT construct must be initialized + # as strings. + # + INRFRM = 'J2000' + NONFRM = 'IAU_EARTH' + r2d = spiceypy.dpr() + + # + # Load the needed kernels using a spiceypy.furnsh call on the + # meta kernel. + # + spiceypy.furnsh( 'coord.tm' ) + + # + # Prompt the user for a time string. Convert the + # time string to ephemeris time J2000 (ET). + # + timstr = input( 'Time of interest: ') + et = spiceypy.str2et( timstr ) + + # + # Access the kernel pool data for the triaxial radii of the + # Earth, rad[1][0] holds the equatorial radius, rad[1][2] + # the polar radius. + # + rad = spiceypy.bodvrd( 'EARTH', 'RADII', 3 ) + + # + # Calculate the flattening factor for the Earth. + # + # equatorial_radius - polar_radius + # flat = ________________________________ + # + # equatorial_radius + # + flat = (rad[1][0] - rad[1][2])/rad[1][0] + + # + # Make the spiceypy.spkpos call to determine the apparent + # position of the Moon w.r.t. to the Earth at 'et' in the + # inertial frame. + # + [pos, ltime] = spiceypy.spkpos('MOON', et, INRFRM, + 'LT+S','EARTH' ) + + # + # Show the current frame and time. + # + print( ' Time : {0}'.format(timstr) ) + print( ' Inertial Frame: {0}\n'.format(INRFRM) ) + + # + # First convert the position vector + # X = pos(1), Y = pos(2), Z = pos(3), to RA/DEC. + # + [ range, ra, dec ] = spiceypy.recrad( pos ) + + print(' Range/Ra/Dec' ) + print(' Range: {0:20.6f}'.format(range) ) + print(' RA : {0:20.6f}'.format(ra * r2d) ) + print(' DEC : {0:20.6f}'.format(dec* r2d) ) + + # + # ...latitudinal coordinates... + # + [ range, lon, lat ] = spiceypy.reclat( pos ) + print(' Latitudinal ' ) + print(' Rad : {0:20.6f}'.format(range) ) + print(' Lon : {0:20.6f}'.format(lon * r2d) ) + print(' Lat : {0:20.6f}'.format(lat * r2d) ) + + # + # ...spherical coordinates use the colatitude, + # the angle from the Z axis. + # + [ range, colat, lon ] = spiceypy.recsph( pos ) + print( ' Spherical' ) + print(' Rad : {0:20.6f}'.format(range) ) + print(' Lon : {0:20.6f}'.format(lon * r2d) ) + print(' Colat: {0:20.6f}'.format(colat * r2d) ) + + # + # Make the spiceypy.spkpos call to determine the apparent + # position of the Moon w.r.t. to the Earth at 'et' in the + # non-inertial, body fixed, frame. + # + [pos, ltime] = spiceypy.spkpos('MOON', et, NONFRM, + 'LT+S','EARTH') + + print() + print( ' Non-inertial Frame: {0}'.format(NONFRM) ) + + # + # ...latitudinal coordinates... + # + [ range, lon, lat ] = spiceypy.reclat( pos ) + print(' Latitudinal ' ) + print(' Rad : {0:20.6f}'.format(range) ) + print(' Lon : {0:20.6f}'.format(lon * r2d) ) + print(' Lat : {0:20.6f}'.format(lat * r2d) ) + + # + # ...spherical coordinates use the colatitude, + # the angle from the Z axis. + # + [ range, colat, lon ] = spiceypy.recsph( pos ) + print( ' Spherical' ) + print(' Rad : {0:20.6f}'.format(range) ) + print(' Lon : {0:20.6f}'.format(lon * r2d) ) + print(' Colat: {0:20.6f}'.format(colat * r2d) ) + + # + # ...finally, convert the position to geodetic coordinates. + # + [ lon, lat, range ] = spiceypy.recgeo( pos, rad[1][0], flat ) + print( ' Geodetic' ) + print(' Rad : {0:20.6f}'.format(range) ) + print(' Lon : {0:20.6f}'.format(lon * r2d) ) + print(' Lat : {0:20.6f}'.format(lat * r2d) ) + print() + + # + # Done. Unload the kernels. + # + spiceypy.kclear + + + if __name__ == '__main__': + coord() + +Run the code example + +Input “Feb 3 2002 TDB” to calculate the Moon’s position. (the ‘TDB’ tag +indicates a Barycentric Dynamical Time value). + +:: + + Time of interest: Feb 3 2002 TDB + +Examine the Moon position in the J2000 inertial frame, display the time +and frame: + +:: + + Time : Feb 3 2002 TDB + Inertial Frame: J2000 + +Convert the Moon Cartesian coordinates to right ascension declination. + +:: + + Range/Ra/Dec + Range: 369340.815193 + RA : 203.643686 + DEC : -4.979010 + +Latitudinal. Note the difference in the expressions for longitude and +right ascension though they represent a measure of the same quantity. +The RA/DEC system measures RA in the interval [0,2Pi). Latitudinal +coordinates measures longitude in the interval (-Pi,Pi]. + +:: + + Latitudinal + Rad : 369340.815193 + Lon : -156.356314 + Lat : -4.979010 + +Spherical. Note the difference between the expression of latitude in the +Latitudinal system and the corresponding Spherical colatitude. The +spherical coordinate system uses the colatitude, the angle measure away +from the positive Z axis. Latitude is the angle between the position +vector and the x-y (equatorial) plane with positive angle defined as +toward the positive Z direction + +:: + + Spherical + Rad : 369340.815193 + Lon : -156.356314 + Colat: 94.979010 + +The same position look-up in a body fixed (non-inertial) frame, +IAU_EARTH. + +:: + + Non-inertial Frame: IAU_EARTH + +Latitudinal coordinates return the geocentric latitude. + +:: + + Latitudinal + Rad : 369340.815193 + Lon : 70.986950 + Lat : -4.989675 + +Spherical. + +:: + + Spherical + Rad : 369340.815193 + Lon : 70.986950 + Colat: 94.989675 + +Geodetic. The cartographic lat/lon. + +:: + + Geodetic + Rad : 362962.836755 + Lon : 70.986950 + Lat : -4.990249 + +.. _related-routines-1: + +Related Routines +---------------- + +:: + + -- spiceypy.latrec, latitudinal to rectangular + + -- spiceypy.latcyl, latitudinal to cylindrical + + -- spiceypy.latsph, latitudinal to spherical + + -- spiceypy.reccyl, rectangular to cylindrical + + -- spiceypy.sphrec, spherical to rectangular + + -- spiceypy.sphcyl, spherical to cylindrical + + -- spiceypy.sphlat, spherical to latitudinal + + -- spiceypy.cyllat, cylindrical to latitudinal + + -- spiceypy.cylsph, cylindrical to spherical + + -- spiceypy.cylrec, cylindrical to rectangular + + -- spiceypy.georec, geodetic to rectangular + +Lesson 4: Advanced Time Manipulation Routines +============================================= + +.. _task-statement-3: + +Task Statement +-------------- + +Demonstrate the advanced functions of the time utilities with regard to +formatting of time strings for output. Formatting options include +altering calendar representations of the time strings. Convert time-date +strings between different SpiceyPy-supported formats. + +.. _learning-goals-3: + +Learning Goals +-------------- + +Introduce the routines used for advanced manipulation of time strings. +Understand the concept of ephemeris time (ET) as used in SpiceyPy. + +.. _code-solution-3: + +Code Solution +------------- + +Caution: Be sure to assign sufficient string lengths for time +formats/pictures. + +:: + + from __future__ import print_function + + # + # Import the CSPICE-Python interface. + # + import spiceypy + + def xtic(): + + # + # Assign the META variable to the name of the meta-kernel + # that contains the LSK kernel and create an arbitrary + # time string. + # + CALSTR = 'Mar 15, 2003 12:34:56.789 AM PST' + META = 'xtic.tm' + AMBIGSTR = 'Mar 15, 79 12:34:56' + T_FORMAT1 = 'Wkd Mon DD HR:MN:SC PDT YYYY ::UTC-7' + T_FORMAT2 = 'Wkd Mon DD HR:MN ::UTC-7 YR (JULIAND.##### JDUTC)' + + # + # Load the meta-kernel. + # + spiceypy.furnsh( META ) + print( 'Original time string : {0}'.format(CALSTR) ) + + # + # Convert the time string to the number of ephemeris + # seconds past the J2000 epoch. This is the most common + # internal time representation used by the CSPICE + # system; CSPICE refers to this as ephemeris time (ET). + # + et = spiceypy.str2et( CALSTR ) + print( 'Corresponding ET : {0:20.6f}\n'.format(et) ) + + # + # Make a picture of an output format. Describe a Unix-like + # time string then send the picture and the 'et' value through + # spiceypy.timout to format and convert the ET representation + # of the time string into the form described in + # spiceypy.timout. The '::UTC-7' token indicates the time + # zone for the `timstr' output - PDT. 'PDT' is part of the + # output, but not a time system token. + # + timstr = spiceypy.timout( et, T_FORMAT1) + print( 'Time in string format 1 : {0}'.format(timstr) ) + + timstr = spiceypy.timout( et, T_FORMAT2) + print( 'Time in string format 2 : {0}'.format(timstr) ) + + # + # Why create a picture by hand when spiceypy can do it for + # you? Input a string to spiceypy.tpictr with the format of + # interest. `ok' returns a boolean indicating whether an + # error occurred while parsing the picture string, if so, + # an error diagnostic message returns in 'xerror'. In this + # example the picture string is known as correct. + # + pic = '12:34:56.789 P.M. PDT January 1, 2006' + [ pictr, ok, xerror] = spiceypy.tpictr(pic) + + if not bool(ok): + print( xerror ) + exit + + + timstr = spiceypy.timout( et, pictr) + print( 'Time in string format 3 : {0}'.format( timstr ) ) + + # + # Two digit year representations often cause problems due to + # the ambiguity of the century. The routine spiceypy.tsetyr + # gives the user the ability to set a default range for 2 + # digit year representation. SPICE uses 1969AD as the default + # start year so the numbers inclusive of 69 to 99 represent + # years 1969AD to 1999AD, the numbers inclusive of 00 to 68 + # represent years 2000AD to 2068AD. + # + # The defined time string 'AMBIGSTR' contains a two-digit + # year. Since the SPICE base year is 1969, the time subsystem + # interprets the string as 1979. + # + et1 = spiceypy.str2et( AMBIGSTR ) + + # + # Set 1980 as the base year causes SPICE to interpret the + # time string's "79" as 2079. + # + spiceypy.tsetyr( 1980 ) + et2 = spiceypy.str2et( AMBIGSTR ) + + # + # Calculate the number of years between the two ET + # representations, ~100. + # + print( 'Years between evaluations: {0:20.6f}'.\ + format( (et2 - et1)/spiceypy.jyear())) + + # + # Reset the default year to 1969. + # + spiceypy.tsetyr( 1969 ) + + # + # Done. Unload the kernels. + # + spiceypy.kclear + + + if __name__ == '__main__': + xtic() + +Run the code example + +:: + + Original time string : Mar 15, 2003 12:34:56.789 AM PST + Corresponding ET : 100989360.974561 + + Time in string format 1 : Sat Mar 15 01:34:56 PDT 2003 + Time in string format 2 : Sat Mar 15 01:34 03 (2452713.85760 JDUTC) + Time in string format 3 : 01:34:56.789 A.M. PDT March 15, 2003 + Years between evaluations: 100.000000 + +Lesson 5: Error Handling +======================== + +.. _task-statement-4: + +Task Statement +-------------- + +Write an interactive program to return a state vector based on a user’s +input. Code the program with the capability to recover from user input +mistakes, inform the user of the mistake, then continue to run. + +.. _learning-goals-4: + +Learning Goals +-------------- + +Learn how to write a program that has the capability to recover from +expected SPICE errors. + +The SpiceyPy error subsystem differs from CSPICE and SPICELIB packages +in that the user cannot alter the state of the error subsystem, rather +the user can respond to an error signal using try-except blocks. This +block natively receives and processes any SpiceyError exception signaled +from SpiceyPy. The user can therefore “catch” an error signal so as to +respond in an appropriate manner. + +.. _code-solution-4: + +Code Solution +------------- + +:: + + from __future__ import print_function + from builtins import input + + # + # Import the CSPICE-Python interface. + # + import spiceypy + from spiceypy.utils.support_types import SpiceyError + + def aderr(): + + # + # Set initial parameters. + # + SPICETRUE = True + SPICEFALSE= False + doloop = SPICETRUE + + # + # Load the data we need for state evaluation. + # + spiceypy.furnsh( 'aderr.tm' ) + + # + # Start our input query loop to the user. + # + while (doloop): + + # + # For simplicity, we request only one input. + # The program calculates the state vector from + # Earth to the user specified target 'targ' in the + # J2000 frame, at ephemeris time zero, using + # aberration correction LT+S (light time plus + # stellar aberration). + # + targ = input( 'Target: ' ) + + + if targ == 'NONE': + # + # An exit condition. If the user inputs NONE + # for a target name, set the loop to stop... + # + doloop = SPICEFALSE + + else: + + # + # ...otherwise evaluate the state between the Earth + # and the target. Initialize an error handler. + # + try: + + # + # Perform the state lookup. + # + [state, ltime] = spiceypy.spkezr(targ, 0., 'J2000', + 'LT+S', 'EARTH') + + # + # No error, output the state. + # + print( 'R : {0:20.6f} {1:20.6f} ' + '{2:20.5f}'.format(*state[0:3])) + print( 'V : {0:20.6f} {1:20.6f} ' + '{2:20.6f}'.format(*state[3:6]) ) + print( 'LT: {0:20.6f}\n'.format(float(ltime))) + + except SpiceyError as err: + + # + # What if spiceypy.spkezr signaled an error? + # Then spiceypy signals an error to python. + # + # Examine the value of 'e' to retrieve the + # error message. + # + print( err ) + print( ) + + + # + # Done. Unload the kernels. + # + spiceypy.kclear + + + if __name__ == '__main__': + aderr() + +Run the code example + +Now run the code with various inputs to observe behavior. Begin the run +using known astronomical bodies, e.g. “Moon”, “Mars”, “Pluto barycenter” +and “Puck”. Recall the SpiceyPy default units are kilometers, kilometers +per second, kilograms, and seconds. The ‘R’ marker identifies the +(X,Y,Z) position of the body in kilometers, the ‘V’ marker identifies +the velocity of the body in kilometers per second, and the ‘LT’ marker +identifies the one-way light time between the bodies at the requested +evaluation time. + +:: + + Target: Moon + R : -291584.616595 -266693.402359 -76095.64756 + V : 0.643439 -0.666066 -0.301310 + LT: 1.342311 + + Target: Mars + R : 234536077.419136 -132584383.595569 -63102685.70619 + V : 30.961373 28.932996 13.113031 + LT: 923.001080 + + Target: Pluto barycenter + R : -1451304742.838526 -4318174144.406321 -918251433.58736 + V : 35.079843 3.053138 -0.036762 + LT: 15501.258293 + + Target: Puck + + ===================================================================== + =========== + + Toolkit version: N0066 + + SPICE(SPKINSUFFDATA) -- + + Insufficient ephemeris data has been loaded to compute the state of 7 + 15 (PUCK) relative to 0 (SOLAR SYSTEM BARYCENTER) at the ephemeris ep + och 2000 JAN 01 12:00:00.000. + + spkezr_c --> SPKEZR --> SPKEZ --> SPKACS --> SPKAPS --> SPKLTC --> SP + KGEO + + ===================================================================== + =========== + + Target: + +Perplexing. What happened? + +The kernel files named in meta.tm did not include ephemeris data for +Puck. When the SPK subsystem tried to evaluate Puck’s position, the +evaluation failed due to lack of data, so an error signaled. + +The above error signifies an absence of state information at ephemeris +time 2000 JAN 01 12:00:00.000 (the requested time, ephemeris time zero). + +Try another look-up, this time for “Casper” + +:: + + Target: Casper + + ===================================================================== + =========== + + Toolkit version: N0066 + + SPICE(IDCODENOTFOUND) -- + + The target, 'Casper', is not a recognized name for an ephemeris objec + t. The cause of this problem may be that you need an updated version + of the SPICE Toolkit. Alternatively you may call SPKEZ directly if yo + u know the SPICE ID codes for both 'Casper' and 'EARTH' + + spkezr_c --> SPKEZR + + ===================================================================== + =========== + + Target: + +An easy to understand error. The SPICE system does not contain +information on a body named ‘Casper.’ + +Another look-up, this time, “Venus”. + +:: + + Target: Venus + R : -80970027.540532 -139655772.573898 -53860125.95820 + V : 31.166910 -27.001056 -12.316514 + LT: 567.655074 + + Target: + +The look-up succeeded despite two errors in our run. The SpiceyPy system +can respond to error conditions (not system errors) in much the same +fashion as languages with catch/throw instructions. + +Lesson 6: Windows, and Cells +============================ + +Programming task +---------------- + +Given the times of line-of-sight for a vehicle from a ground station and +the times for an acceptable Sun-station-vehicle phase angle, write a +program to determine the time intervals common to both configurations. + +.. _learning-goals-5: + +Learning Goals +-------------- + +SpiceyPy implementation of SPICE cells consists of a class that provides +an interface to the underlying CSPICE cell structure. + +A user should create cells by use of the appropriate SpiceyPy calls. +NAIF recommends against manual creation of cells. + +A ‘window’ is a type of cell containing ordered, double precision values +describing a collection of zero or more intervals. + +We define an interval, ‘i’, as all double precision values bounded by +and including an ordered pair of numbers, + +:: + + [ a , b ] + i i + +where + +:: + + a < b + i - i + +The intervals within a window are both ordered and disjoint. That is, +the beginning of each interval is greater than the end of the previous +interval: + +:: + + b < a + i i+1 + +A common use of the windows facility is to calculate the intersection +set of a number of time intervals. + +.. _code-solution-5: + +Code Solution +------------- + +:: + + from __future__ import print_function + + # + # Import the CSPICE-Python interface. + # + import spiceypy + + def win(): + + MAXSIZ = 8 + + # + # Define a set of time intervals. For the purposes of this + # tutorial program, define time intervals representing + # an unobscured line of sight between a ground station + # and some body. + # + los = [ 'Jan 1, 2003 22:15:02', 'Jan 2, 2003 4:43:29', + 'Jan 4, 2003 9:55:30', 'Jan 4, 2003 11:26:52', + 'Jan 5, 2003 11:09:17', 'Jan 5, 2003 13:00:41', + 'Jan 6, 2003 00:08:13', 'Jan 6, 2003 2:18:01' ] + + # + # A second set of intervals representing the times for which + # an acceptable phase angle exists between the ground station, + # the body and the Sun. + # + phase = [ 'Jan 2, 2003 00:03:30', 'Jan 2, 2003 19:00:00', + 'Jan 3, 2003 8:00:00', 'Jan 3, 2003 9:50:00', + 'Jan 5, 2003 12:00:00', 'Jan 5, 2003 12:45:00', + 'Jan 6, 2003 00:30:00', 'Jan 6, 2003 23:00:00' ] + + # + # Load our meta kernel for the leapseconds data. + # + spiceypy.furnsh( 'win.tm' ) + + # + # SPICE windows consist of double precision values; convert + # the string time tags defined in the 'los'and 'phase' + # arrays to double precision ET. Store the double values + # in the 'loswin' and 'phswin' windows. + # + los_et = spiceypy.str2et( los ) + phs_et = spiceypy.str2et( phase ) + + loswin = spiceypy.stypes.SPICEDOUBLE_CELL( MAXSIZ ) + phswin = spiceypy.stypes.SPICEDOUBLE_CELL( MAXSIZ ) + + for i in range(0, int( MAXSIZ/2 ) ): + spiceypy.wninsd( los_et[2*i], los_et[2*i+1], loswin ) + spiceypy.wninsd( phs_et[2*i], phs_et[2*i+1], phswin ) + + spiceypy.wnvald( MAXSIZ, MAXSIZ, loswin ) + spiceypy.wnvald( MAXSIZ, MAXSIZ, phswin ) + + # + # The issue for consideration, at what times do line of + # sight events coincide with acceptable phase angles? + # Perform the set operation AND on loswin, phswin, + # (the intersection of the time intervals) + # place the results in the window 'sched'. + # + sched = spiceypy.wnintd( loswin, phswin ) + + print( 'Number data values in sched : ' + '{0:2d}'.format(spiceypy.card(sched)) ) + + # + # Output the results. The number of intervals in 'sched' + # is half the number of data points (the cardinality). + # + print( ' ' ) + print( 'Time intervals meeting defined criterion.' ) + + for i in range( spiceypy.card(sched)//2): + + # + # Extract from the derived 'sched' the values defining the + # time intervals. + # + [left, right ] = spiceypy.wnfetd( sched, i ) + + # + # Convert the ET values to UTC for human comprehension. + # + utcstr_l = spiceypy.et2utc( left , 'C', 3 ) + utcstr_r = spiceypy.et2utc( right, 'C', 3 ) + + # + # Output the UTC string and the corresponding index + # for the interval. + # + print( '{0:2d} {1} {2}'.format(i, utcstr_l, utcstr_r)) + + + # + # Summarize the 'sched' window. + # + [meas, avg, stddev, small, large] = spiceypy.wnsumd( sched ) + + print( '\nSummary of sched window\n' ) + + print( 'o Total measure of sched : {0:16.6f}'.format(meas)) + print( 'o Average measure of sched : {0:16.6f}'.format(avg)) + print( 'o Standard deviation of ' ) + print( ' the measures in sched : ' + '{0:16.6f}'.format(stddev)) + + # + # The values for small and large refer to the indexes of the + # values in the window ('sched'). The shortest interval is + # + # [ sched.base[ sched.data + small] + # sched.base[ sched.data + small +1] ]; + # + # the longest is + # + # [ sched.base[ sched.data + large] + # sched.base[ sched.data + large +1] ]; + # + # Output the interval indexes for the shortest and longest + # intervals. As Python bases an array index on 0, the interval + # index is half the array index. + # + print( 'o Index of shortest interval: ' + '{0:2d}'.format(int(small/2)) ) + print( 'o Index of longest interval : ' + '{0:2d}'.format(int(large/2)) ) + + # + # Done. Unload the kernels. + # + spiceypy.kclear + + if __name__ == '__main__': + win() + +Run the code example + +The output window has the name \`sched’ (schedule). + +Output the amount of data held in \`sched’ compared to the maximum +possible amount. + +:: + + Number data values in sched : 6 + +List the time intervals for which a line of sight exists during the time +of a proper phase angle. + +:: + + Time intervals meeting defined criterion. + 0 2003 JAN 02 00:03:30.000 2003 JAN 02 04:43:29.000 + 1 2003 JAN 05 12:00:00.000 2003 JAN 05 12:45:00.000 + 2 2003 JAN 06 00:30:00.000 2003 JAN 06 02:18:01.000 + +Finally, an analysis of the \`sched’ data. The measure of an interval +[a,b] (a <= b) equals b-a. Real values output in units of seconds. + +:: + + Summary of sched window + + o Total measure of sched : 25980.000009 + o Average measure of sched : 8660.000003 + o Standard deviation of + the measures in sched : 5958.550217 + o Index of shortest interval: 1 + o Index of longest interval : 0 + +.. _related-routines-2: + +Related Routines +---------------- + +:: + + -- spiceypy.wncomd determines the compliment of a window with + respect to a defined interval. + + -- spiceypy.wncond contracts a window's intervals. + + -- spiceypy.wndifd : Calculate the difference between two windows; + i.e. every point existing in the first but not the second. + + -- spiceypy.wnelmd returns TRUE or FALSE if a value exists in a + window. + + -- spiceypy.wnexpd expands the size of the intervals in a window. + + -- spiceypy.wnextd extracts a window's endpoints . + + -- spiceypy.wnfild fills gaps between intervals in a window. + + -- spiceypy.wnfltd filter/removes small intervals from a window. + + -- spiceypy.wnincd determines if an interval exists within a + window. + + -- spiceypy.wninsd inserts an interval into a window. + + -- spiceypy.wnreld compares two windows. Comparison operations + available, equality '=', inequality '<>', subset '<=' and '>=', + proper subset '<' and '>'. + + -- spiceypy.wnunid calculates the union of two windows. + +Lesson 7: Utility and Constants Routines +======================================== + +.. _task-statement-5: + +Task Statement +-------------- + +Write an interactive program to convert values between various units. +Demonstrate the flexibility of the unit conversion routine, the string +equality function, and show the version ID function. + +.. _learning-goals-6: + +Learning Goals +-------------- + +SpiceyPy provides several routines to perform commonly needed tasks. +Among these: + +SpiceyPy also includes a set of functions that return constant values +often used in astrodynamics, time calculations, and geometry. + +.. _code-solution-6: + +Code Solution +------------- + +:: + + from __future__ import print_function + from builtins import input + + # + # Import the CSPICE-Python interface. + # + import spiceypy + + + def tostan(alias): + + value = alias + + # + # As a convenience, let's alias a few common terms + # to their appropriate counterpart. + # + if alias == 'meter': + + # + # First, a 'meter' by any other name is a + # 'METER' and smells as sweet ... + # + value = 'METERS' + + elif (alias == 'klicks') \ + or (alias == 'kilometers') \ + or (alias =='kilometer'): + + # + # ... 'klicks' and 'KILOMETERS' and 'KILOMETER' + # identifies 'KM'.... + # + value = 'KM' + + elif alias == 'secs': + + # + # ... 'secs' to 'SECONDS'. + # + value = 'SECONDS' + + elif alias == 'miles': + + # + # ... and finally 'miles' to 'STATUTE_MILES'. + # Normal people think in statute miles. + # Only sailors think in nautical miles - one + # minute of arc at the equator. + # + value = 'STATUTE_MILES' + + else: + pass + + + # + # Much better. Now return. If the input matched + # none of the aliases, this function did nothing. + # + return value + + def units(): + + # + # Display the Toolkit version string with a spiceypy.tkvrsn + # call. + # + vers = spiceypy.tkvrsn( 'TOOLKIT' ) + print('\nConvert demo program compiled against CSPICE ' + 'Toolkit ' + vers) + + # + # The user first inputs the name of a unit of measure. + # Send the name through tostan for de-aliasing. + # + funits = input( 'From Units : ' ) + funits = tostan( funits ) + + # + # Input a double precision value to express in a new + # unit format. + # + fvalue = float(input( 'From Value : ' )) + + # + # Now the user inputs the name of the output units. + # Again we send the units name through tostan for + # de-aliasing. + # + tunits = input( 'To Units : ' ) + tunits = tostan( tunits ) + + tvalue = spiceypy.convrt( fvalue, funits, tunits) + print( '{0:12.5f} {1}'.format(tvalue, tunits) ) + + if __name__ == '__main__': + units() + +Run the code example + +Run a few conversions through the application to ensure it works. The +intro banner gives us the Toolkit version against which the application +was linked: + +:: + + Convert demo program compiled against CSPICE Toolkit CSPICE_N0066 + From Units : klicks + From Value : 3 + To Units : miles + 1.86411 STATUTE_MILES + +Now we know. Three kilometers equals 1.864 miles. + +Legend states Pheidippides ran from the Marathon Plain to Athens. The +modern marathon race (inspired by this event) spans 26.2 miles. How far +in kilometers? + +:: + + Convert demo program compiled against CSPICE Toolkit CSPICE_N0066 + From Units : miles + From Value : 26.2 + To Units : km + 42.16481 km + +.. _task-statement-6: + +Task Statement +-------------- + +Write a program to output SpiceyPy constants and use those constants to +calculate some rudimentary values. + +.. _code-solution-7: + +Code Solution +------------- + +:: + + from __future__ import print_function + + # + # Import the CSPICE-Python interface. + # + import spiceypy + + def xconst(): + + # + # All the function have the same calling sequence: + # + # VALUE = function_name() + # + # some_procedure( function_name() ) + # + # First a simple example using the seconds per day + # constant... + # + print( 'Number of (S)econds (P)er (D)ay : ' + '{0:19.12f}'.format(spiceypy.spd() )) + + # + # ...then show the value of degrees per radian, 180/Pi... + # + print( 'Number of (D)egrees (P)er (R)adian : ' + '{0:19.16f}'.format(spiceypy.dpr() )) + + # + # ...and the inverse, radians per degree, Pi/180. + # It is obvious spiceypy.dpr() equals 1.d/spiceypy.rpd(), or + # more simply spiceypy.dpr() * spiceypy.rpd() equals 1 + # + print( 'Number of (R)adians (P)er (D)egree : ' + '{0:19.16f}'.format(spiceypy.rpd() )) + + # + # What's the value for the astrophysicist's favorite + # physical constant (in a vacuum)? + # + print( 'Speed of light in KM per second : ' + '{0:19.12f}'.format(spiceypy.clight() )) + + # + # How long (in Julian days) from the J2000 epoch to the + # J2100 epoch? + # + print( 'Number of days between epochs J2000') + print( ' and J2100 : ' + '{0:19.12f}'.format( spiceypy.j2100() + - spiceypy.j2000() )) + + # + # Redo the calculation returning seconds... + # + print( 'Number of seconds between epochs' ) + print( ' J2000 and J2100 : ' + '{0:19.5f}'.format(spiceypy.spd() * \ + (spiceypy.j2100() - spiceypy.j2000() ) )) + + + # + # ...then tropical years. + # + val =(spiceypy.spd()/spiceypy.tyear() ) * \ + (spiceypy.j2100()- spiceypy.j2000() ) + print( 'Number of tropical years between' ) + print( ' epochs J2000 and J2100 : ' + '{0:19.12f}'.format(val)) + + + # + # Finally, how can I convert a radian value to degrees. + # + print( 'Number of degrees in Pi/2 radians of arc: ' + '{0:19.16f}'.format( spiceypy.halfpi() + * spiceypy.dpr() )) + + # + # and degrees to radians. + # + print( 'Number of radians in 250 degrees of arc : ' + '{0:19.16f}'.format(250. * spiceypy.rpd() )) + + if __name__ == '__main__': + xconst() + +Run the code example + +:: + + Number of (S)econds (P)er (D)ay : 86400.000000000000 + Number of (D)egrees (P)er (R)adian : 57.2957795130823229 + Number of (R)adians (P)er (D)egree : 0.0174532925199433 + Speed of light in KM per second : 299792.457999999984 + Number of days between epochs J2000 + and J2100 : 36525.000000000000 + Number of seconds between epochs + J2000 and J2100 : 3155760000.00000 + Number of tropical years between + epochs J2000 and J2100 : 100.002135902909 + Number of degrees in Pi/2 radians of arc: 90.0000000000000000 + Number of radians in 250 degrees of arc : 4.3633231299858242 + +.. _related-routines-3: + +Related Routines +---------------- + +:: + + -- spiceypy.b1900 : Julian Date of the epoch Besselian Date 1900.0 + + -- spiceypy.b1950 : Julian date of the epoch Besselian Date 1950.0 + + -- spiceypy.j1900 : Julian date of 1900 JAN 0.5 this corresponds + to calendar date 1899 DEC 31 12:00:00 + + -- spiceypy.j1950 : Julian date of 1950 JAN 1.0 this corresponds + to calendar date 1950 JAN 01 00:00:00 + + -- spiceypy.twopi : double precision value of 2 * Pi + + -- spiceypy.pi : double precision value of Pi + + -- spiceypy.jyear : seconds per Julian year (365.25 Julian days) diff --git a/docs/remote_sensing.rst b/docs/remote_sensing.rst new file mode 100644 index 00000000..c72639d4 --- /dev/null +++ b/docs/remote_sensing.rst @@ -0,0 +1,2500 @@ +Remote Sensing Hands-On Lesson, using CASSINI (Python) +====================================================== + +November 20, 2017 + +Overview +-------- + +In this lesson you will develop a series of simple programs that +demonstrate the usage of SpiceyPy to compute a variety of different +geometric quantities applicable to experiments carried out by a remote +sensing instrument flown on an interplanetary spacecraft. This +particular lesson focuses on a framing camera flying on the Cassini +spacecraft, but many of the concepts are easily extended and generalized +to other scenarios. + +References +---------- + +This section lists SPICE documents referred to in this lesson. + +In some cases the lesson explanations also refer to the information +provided in the meta-data area of the kernels used in the lesson +examples. It is especially true in case of the FK and IK files, which +often contain comprehensive descriptions of the frames, instrument FOVs, +etc. Since both the FK and IK are text kernels, the information provided +in them can be viewed using any text editor, while the meta information +provided in binary kernels—SPKs and CKs—can be viewed using +``commnt'' or``\ spacit’‘utility programs located in \``cspice/exe’’ of +Toolkit installation tree. + +Tutorials + +The following SPICE tutorials serve as references for the discussions in +this lesson: + +:: + + Name Lesson steps/functions it describes + ---------------- ----------------------------------------------- + Time Time Conversion + SCLK and LSK Time Conversion + SPK Obtaining Ephemeris Data + Frames Reference Frames + Using Frames Reference Frames + PCK Planetary Constants Data + CK Spacecraft Orientation Data + DSK Detailed Target Shape (Topography) Data + +These tutorials are available from the NAIF ftp server at JPL: + +:: + + http://naif.jpl.nasa.gov/naif/tutorials.html + +Required Readings + +The Required Reading documents are provided with the Toolkit and are +located under the \``cspice/doc’’ directory in the CSPICE Toolkit +installation tree. + +:: + + Name Lesson steps/functions that it describes + --------------- ----------------------------------------- + ck.req Obtaining spacecraft orientation data + dsk.req Obtaining detailed body shape data + frames.req Using reference frames + naif_ids.req Determining body ID codes + pck.req Obtaining planetary constants data + sclk.req SCLK time conversion + spk.req Obtaining ephemeris Data + time.req Time conversion + +The Permuted Index + +Another useful document distributed with the Toolkit is the permuted +index. This is located under the \``cspice/doc’’ directory in the C +installation tree. + +This text document provides a simple mechanism by which users can +discover which SpiceyPy functions perform functions of interest, as well +as the names of the source files that contain these functions. + +SpiceyPy API Documentation + +A SpiceyPy function’s parameters specification is available using the +built-in Python help system. A more detailed specification of the API +can be found in the CSPICE HTML API documentation page located under +\``cspice/doc/html/cspice’’. + +For example, the Python help function + +:: + + >>> import spiceypy + >>> help(spiceypy.str2et) + +describes of the str2et function’s parameters, while the document + +:: + + cspice/doc/html/cspice/str2et_c.html + +describes extensively the str2et functionality. + +Kernels Used +------------ + +The following kernels are used in examples provided in this lesson: + +:: + + # FILE NAME TYPE DESCRIPTION + -- ------------------------- ---- ----------------------------------- + 1 naif0008.tls LSK Generic LSK + 2 cas00084.tsc SCLK Cassini SCLK + 3 981005_PLTEPH-DE405S.bsp SPK Solar System Ephemeris + 4 020514_SE_SAT105.bsp SPK Saturnian Satellite Ephemeris + 5 030201AP_SK_SM546_T45.bsp SPK Cassini Spacecraft SPK + 6 cas_v37.tf FK Cassini FK + 7 04135_04171pc_psiv2.bc CK Cassini Spacecraft CK + 8 cpck05Mar2004.tpc PCK Cassini Project PCK + 9 phoebe_64q.bds DSK Phoebe DSK + 10 cas_iss_v09.ti IK ISS Instrument Kernel + +These SPICE kernels are included in the lesson package available from +the NAIF server at JPL: + +:: + + ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/ + +In addition to these kernels, the extra credit exercises require the +following kernels: + +:: + + # FILE NAME TYPE DESCRIPTION + -- --------------- ---- --------------------------------------------- + 11 jup310_2004.bsp SPK Generic Jovian Satellite Ephemeris + +These SPICE kernels are available from the NAIF server at JPL: + +:: + + https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/ + +SpiceyPy Modules Used +--------------------- + +This section provides a complete list of the functions and kernels that +are suggested for usage in each of the exercises in this lesson. (You +may wish to not look at this list unless/until you \``get stuck’’ while +working on your own.) + +:: + + CHAPTER EXERCISE FUNCTIONS NON-VOID KERNELS + ------- --------- --------------- --------------- ---------- + 1 convtm spiceypy.furnsh spiceypy.str2et 1,2 + spiceypy.unload spiceypy.etcal + spiceypy.timout + spiceypy.sce2s + + extra (*) spiceypy.unitim 1,2 + spiceypy.sct2e + spiceypy.et2utc + spiceypy.scs2e + + 2 getsta spiceypy.furnsh spiceypy.str2et 1,3-5 + spiceypy.unload spiceypy.spkezr + spiceypy.spkpos + spiceypy.vnorm + spiceypy.convrt + + extra (*) spiceypy.kclear 1,3-5,11 + + 3 xform spiceypy.furnsh spiceypy.str2et 1-8 + spiceypy.unload spiceypy.spkezr + spiceypy.sxform + spiceypy.mxvg + spiceypy.spkpos + spiceypy.pxform + spiceypy.mxv + spiceypy.convrt + spiceypy.vsep + + extra (*) spiceypy.kclear 1-8 + + 4 subpts spiceypy.furnsh spiceypy.str2et 1,3-5,8,9 + spiceypy.unload spiceypy.subpnt + spiceypy.vnorm + spiceypy.subslr + + extra (*) spiceypy.kclear spiceypy.reclat 1,3-5,8 + spiceypy.dpr + spiceypy.bodvrd + spiceypy.recpgr + + 5 fovint spiceypy.furnsh spiceypy.str2et 1-10 + spiceypy.unload spiceypy.bodn2c + spiceypy.getfov + spiceypy.sincpt + spiceypy.reclat + spiceypy.dpr + spiceypy.illumf + spiceypy.et2lst + + + (*) Additional APIs and kernels used in Extra Credit tasks. + +Use the Python built-in help system on the various functions listed +above for the API parameters’ description, and refer to the headers of +their corresponding CSPICE versions for detailed interface +specifications. + +Time Conversion (convtm) +======================== + +Task Statement +-------------- + +Write a program that prompts the user for an input UTC time string, +converts it to the following time systems and output formats: + +:: + + 1. Ephemeris Time (ET) in seconds past J2000 + + 2. Calendar Ephemeris Time + + 3. Spacecraft Clock Time + +and displays the results. Use the program to convert “2004 jun 11 +19:32:00” UTC into these alternate systems. + +Learning Goals +-------------- + +Familiarity with the various time conversion and parsing functions +available in the Toolkit. Exposure to source code headers and their +usage in learning to call functions. + +Approach +-------- + +The solution to the problem can be broken down into a series of simple +steps: + +:: + + -- Decide which SPICE kernels are necessary. Prepare a meta-kernel + listing the kernels and load it into the program. + + -- Prompt the user for an input UTC time string. + + -- Convert the input time string into ephemeris time expressed as + seconds past J2000 TDB. Display the result. + + -- Convert ephemeris time into a calendar format. Display the + result. + + -- Convert ephemeris time into a spacecraft clock string. Display + the result. + +You may find it useful to consult the permuted index, the headers of +various source modules, and the +``Time Required Reading'' (time.req) and``\ SCLK Required Reading’’ +(sclk.req) documents. + +When completing the \``calendar format’’ step above, consider using one +of two possible methods: spiceypy.etcal or spiceypy.timout. + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘convtm.tm’. Its contents follow: + +:: + + KPL/MK + + This is the meta-kernel used in the solution of the ``Time + Conversion'' task in the Remote Sensing Hands On Lesson. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File name Contents + -------------------------- ----------------------------- + naif0008.tls Generic LSK + cas00084.tsc Cassini SCLK + + + \begindata + KERNELS_TO_LOAD = ( 'kernels/lsk/naif0008.tls', + 'kernels/sclk/cas00084.tsc' ) + \begintext + +Solution Source Code + +A sample solution to the problem follows: + +:: + + # + # Solution convtm + # + from __future__ import print_function + from builtins import input + + import spiceypy + + def convtm(): + # + # Local Parameters + # + METAKR = 'convtm.tm' + SCLKID = -82 + + spiceypy.furnsh( METAKR ) + + # + # Prompt the user for the input time string. + # + utctim = input( 'Input UTC Time: ' ) + + print( 'Converting UTC Time: {:s}'.format( utctim ) ) + + # + # Convert utctim to ET. + # + et = spiceypy.str2et( utctim ) + + print( ' ET Seconds Past J2000: {:16.3f}'.format( et ) ) + + # + # Now convert ET to a calendar time string. + # This can be accomplished in two ways. + # + calet = spiceypy.etcal( et ) + + print( ' Calendar ET (etcal): {:s}'.format( calet ) ) + + # + # Or use timout for finer control over the + # output format. The picture below was built + # by examining the header of timout. + # + calet = spiceypy.timout( et, 'YYYY-MON-DDTHR:MN:SC ::TDB' ) + + print( ' Calendar ET (timout): {:s}'.format( calet ) ) + + # + # Convert ET to spacecraft clock time. + # + sclkst = spiceypy.sce2s( SCLKID, et ) + + print( ' Spacecraft Clock Time: {:s}'.format( sclkst ) ) + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + convtm() + +Solution Sample Output + +Execute the program: + +:: + + Input UTC Time: 2004 jun 11 19:32:00 + Converting UTC Time: 2004 jun 11 19:32:00 + ET Seconds Past J2000: 140254384.185 + Calendar ET (etcal): 2004 JUN 11 19:33:04.184 + Calendar ET (timout): 2004-JUN-11T19:33:04 + Spacecraft Clock Time: 1/1465674964.105 + +Extra Credit +------------ + +In this \``extra credit’’ section you will be presented with more +complex tasks, aimed at improving your understanding of time +conversions, the Toolkit routines that deal with them, and some common +errors that may happen during the execution of these conversions. + +These \``extra credit’’ tasks are provided as task statements, and +unlike the regular tasks, no approach or solution source code is +provided. In the next section, you will find the numeric solutions (when +applicable) and answers to the questions asked in these tasks. + +Task statements and questions + +:: + + 1. Extend your program to convert the input UTC time string to TDB + Julian Date. Convert "2004 jun 11 19:32:00" UTC. + + 2. Remove the LSK from the original meta-kernel and run your + program again, using the same inputs as before. Has anything + changed? Why? + + 3. Remove the SCLK from the original meta-kernel and run your + program again, using the same inputs as before. Has anything + changed? Why? + + 4. Modify your program to perform conversion of UTC or ephemeris + time, to a spacecraft clock string using the NAIF ID for the + CASSINI ISS NAC camera. Convert "2004 jun 11 19:32:00" UTC. + + 5. Find the earliest UTC time that can be converted to CASSINI + spacecraft clock. + + 6. Extend your program to convert the spacecraft clock time + obtained in the regular task back to UTC Time and present it in + ISO calendar date format, with a resolution of milliseconds. + + 7. Examine the contents of the generic LSK and the CASSINI SCLK + kernels. Can you understand and explain what you see? + +Solutions and answers + +:: + + 1. Two methods exist in order to convert ephemeris time to Julian + Date: spiceypy.unitim and spiceypy.timout. The difference + between them is the type of output produced by each method. + spiceypy.unitim returns the double precision value of an input + epoch, while spiceypy.timout returns the string representation + of the ephemeris time in Julian Date format (when picture input + is set to 'JULIAND.######### ::TDB'). Refer to the function + header for further details. The solution for the requested + input UTC string is: + + Julian Date TDB: 2453168.3146318 + + 2. When running the original program without the LSK kernel, an + error is produced: + + Traceback (most recent call last): + File "convtm.py", line 67, in + convtm() + File "convtm.py", line 30, in convtm + et = spiceypy.str2et( utctim ) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 76, in with_errcheck + checkForSpiceError(f) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 59, in checkForSpiceError + raise stypes.SpiceyError(msg) + spiceypy.utils.support_types.SpiceyError: + ===================================================================== + =========== + + Toolkit version: N0066 + + SPICE(NOLEAPSECONDS) -- + + The variable that points to the leapseconds (DELTET/DELTA_AT) could n + ot be located in the kernel pool. It is likely that the leapseconds + kernel has not been loaded via the routine FURNSH. + + str2et_c --> STR2ET --> TTRANS + + ===================================================================== + =========== + + This error is triggered by spiceypy.str2et because the variable + that points to the leapseconds is not present in the kernel + pool and therefore the program lacks data required to perform + the requested UTC to ephemeris time conversion. + + By default, SPICE will report, as a minimum, a short + descriptive message and a expanded form of this short message + where more details about the error are provided. If this error + message is not sufficient for you to understand what has + happened, you could go to the ``Exceptions'' section in the + SPICELIB or CSPICE headers of the function that has triggered + the error and find out more information about the possible + causes. + + 3. When running the original program without the SCLK kernel, an + error is produced: + + Traceback (most recent call last): + File "convtm.py", line 67, in + convtm() + File "convtm.py", line 58, in convtm + sclkst = spiceypy.sce2s( SCLKID, et ) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 76, in with_errcheck + checkForSpiceError(f) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 59, in checkForSpiceError + raise stypes.SpiceyError(msg) + spiceypy.utils.support_types.SpiceyError: + ===================================================================== + =========== + + Toolkit version: N0066 + + SPICE(KERNELVARNOTFOUND) -- + The Variable Was not Found in the Kernel Pool. + SCLK_DATA_TYPE_82 not found. Did you load the SCLK kernel? + + sce2s_c --> SCE2S --> SCE2T --> SCTYPE --> SCLI01 + + ===================================================================== + =========== + + This error is triggered by spiceypy.sce2s. In this case the + error message may not give you enough information to understand + what has actually happened. Nevertheless, the expanded form of + this short message clearly indicates that the SCLK kernel for + the spacecraft ID -82 has not been loaded. + + The UTC string to ephemeris time conversion and the conversion + of ephemeris time into a calendar format worked normally as + these conversions only require the LSK kernel to be loaded. + + 4. The first thing you need to do is to find out what the NAIF ID + is for the CASSINI ISS NAC camera. In order to do so, examine + the ISS instrument kernel listed above and look for the ``NAIF + ID Code to Name Mapping'' and there, for the NAIF ID given to + CASSINI_ISS_NAC (which is -82360). Then replace in your code + the SCLK ID -82 with -82360. After executing the program using + the original meta-kernel, you will be getting the same error as + in the previous task. Despite the error being exactly the same, + this case is different. Generally, spacecraft clocks are + associated with the spacecraft ID and not with its payload, + sensors or structures IDs. Therefore, in order to do + conversions from/to spacecraft clock for payload, sensors or + spacecraft structures, the spacecraft ID must be used. + + Note that this does not need to be true for all missions or + payloads, as SPICE does not restrict the SCLKs to spacecraft + IDs only. Please refer to your mission's SCLK kernels for + particulars. + + 5. Use spiceypy.sct2e with the encoding of the Cassini spacecraft + clock time set to 0.0 ticks and convert the resulting ephemeris + time to UTC using either spiceypy.timout or spiceypy.et2utc. + The solution for the requested SCLK string is: + + Earliest UTC convertible to SCLK: 1980-01-01T00:00:00.000 + + 6. Use spiceypy.scs2e with the SCLK string obtained in the + computations performed in the regular tasks and convert the + resulting ephemeris time to UTC using either spiceypy.et2utc, + with 'ISOC' format and 3 digits precision, or using + spiceypy.timout using the time picture 'YYYY-MM-DDTHR:MN:SC.### + ::RND'. The solution of the requested conversion is: + + Spacecraft Clock Time: 1/1465674964.105 + UTC time from spacecraft clock: 2004-06-11T19:31:59.999 + +Obtaining Target States and Positions (getsta) +============================================== + +.. _task-statement-1: + +Task Statement +-------------- + +Write a program that prompts the user for an input UTC time string, +computes the following quantities at that epoch: + +:: + + 1. The apparent state of Phoebe as seen from CASSINI in the J2000 + frame, in kilometers and kilometers/second. This vector itself + is not of any particular interest, but it is a useful + intermediate quantity in some geometry calculations. + + 2. The apparent position of the Earth as seen from CASSINI in the + J2000 frame, in kilometers. + + 3. The one-way light time between CASSINI and the apparent + position of Earth, in seconds. + + 4. The apparent position of the Sun as seen from Phoebe in the + J2000 frame (J2000), in kilometers. + + 5. The actual (geometric) distance between the Sun and Phoebe, in + astronomical units. + +and displays the results. Use the program to compute these quantities at +“2004 jun 11 19:32:00” UTC. + +.. _learning-goals-1: + +Learning Goals +-------------- + +Understand the anatomy of an spiceypy.spkezr call. Discover the +difference between spiceypy.spkezr and spiceypy.spkpos. Familiarity with +the Toolkit utility \``brief’’. Exposure to unit conversion with +SpiceyPy. + +.. _approach-1: + +Approach +-------- + +The solution to the problem can be broken down into a series of simple +steps: + +:: + + -- Decide which SPICE kernels are necessary. Prepare a meta-kernel + listing the kernels and load it into the program. + + -- Prompt the user for an input time string. + + -- Convert the input time string into ephemeris time expressed as + seconds past J2000 TDB. + + -- Compute the state of Phoebe relative to CASSINI in the J2000 + reference frame, corrected for aberrations. + + -- Compute the position of Earth relative to CASSINI in the J2000 + reference frame, corrected for aberrations. (The function in + the library that computes this also returns the one-way light + time between CASSINI and Earth.) + + -- Compute the position of the Sun relative to Phoebe in the J2000 + reference frame, corrected for aberrations. + + -- Compute the position of the Sun relative to Phoebe without + correcting for aberration. + + Compute the length of this vector. This provides the desired + distance in kilometers. + + -- Convert the distance in kilometers into AU. + +You may find it useful to consult the permuted index, the headers of +various source modules, and the \``SPK Required Reading’’ (spk.req) +document. + +When deciding which SPK files to load, the Toolkit utility \``brief’’ +may be of some use. + +``brief'' is located in the``\ cspice/exe’‘directory for C toolkits. +Consult its user’s guide available in \``cspice/doc/brief.ug’’ for +details. + +.. _solution-1: + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘getsta.tm’. Its contents follow: + +:: + + KPL/MK + + This is the meta-kernel used in the solution of the + ``Obtaining Target States and Positions'' task in the + Remote Sensing Hands On Lesson. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File name Contents + -------------------------- ----------------------------- + naif0008.tls Generic LSK + 981005_PLTEPH-DE405S.bsp Solar System Ephemeris + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK + + + \begindata + KERNELS_TO_LOAD = ( 'kernels/lsk/naif0008.tls', + 'kernels/spk/981005_PLTEPH-DE405S.bsp', + 'kernels/spk/020514_SE_SAT105.bsp', + 'kernels/spk/030201AP_SK_SM546_T45.bsp' ) + \begintext + +Solution Source Code + +A sample solution to the problem follows: + +:: + + # + # Solution getsta.py + # + from __future__ import print_function + from builtins import input + + import spiceypy + + def getsta(): + # + # Local parameters + # + METAKR = 'getsta.tm' + + # + # Load the kernels that this program requires. We + # will need a leapseconds kernel to convert input + # UTC time strings into ET. We also will need the + # necessary SPK files with coverage for the bodies + # in which we are interested. + # + spiceypy.furnsh( METAKR ) + + # + #Prompt the user for the input time string. + # + utctim = input( 'Input UTC Time: ' ) + + print( 'Converting UTC Time: {:s}'.format(utctim) ) + + # + #Convert utctim to ET. + # + et = spiceypy.str2et( utctim ) + + print( ' ET seconds past J2000: {:16.3f}'.format(et) ) + + # + # Compute the apparent state of Phoebe as seen from + # CASSINI in the J2000 frame. All of the ephemeris + # readers return states in units of kilometers and + # kilometers per second. + # + [state, ltime] = spiceypy.spkezr( 'PHOEBE', et, 'J2000', + 'LT+S', 'CASSINI' ) + + print( ' Apparent state of Phoebe as seen ' + 'from CASSINI in the J2000\n' + ' frame (km, km/s):' ) + + print( ' X = {:16.3f}'.format(state[0]) ) + print( ' Y = {:16.3f}'.format(state[1]) ) + print( ' Z = {:16.3f}'.format(state[2]) ) + print( ' VX = {:16.3f}'.format(state[3]) ) + print( ' VY = {:16.3f}'.format(state[4]) ) + print( ' VZ = {:16.3f}'.format(state[5]) ) + + # + # Compute the apparent position of Earth as seen from + # CASSINI in the J2000 frame. Note: We could have + # continued using spkezr and simply ignored the + # velocity components. + # + [pos, ltime] = spiceypy.spkpos( 'EARTH', et, 'J2000', + 'LT+S', 'CASSINI', ) + + print( ' Apparent position of Earth as ' + 'seen from CASSINI in the J2000\n' + ' frame (km):' ) + print( ' X = {:16.3f}'.format(pos[0]) ) + print( ' Y = {:16.3f}'.format(pos[1]) ) + print( ' Z = {:16.3f}'.format(pos[2]) ) + + # + # We need only display LTIME, as it is precisely the + # light time in which we are interested. + # + print( ' One way light time between CASSINI and ' + 'the apparent position\n' + ' of Earth (seconds):' + ' {:16.3f}'.format(ltime) ) + + # + # Compute the apparent position of the Sun as seen from + # PHOEBE in the J2000 frame. + # + [pos, ltime] = spiceypy.spkpos( 'SUN', et, 'J2000', + 'LT+S', 'PHOEBE', ) + + print( ' Apparent position of Sun as ' + 'seen from Phoebe in the\n' + ' J2000 frame (km):' ) + print( ' X = {:16.3f}'.format(pos[0]) ) + print( ' Y = {:16.3f}'.format(pos[1]) ) + print( ' Z = {:16.3f}'.format(pos[2]) ) + + # + # Now we need to compute the actual distance between + # the Sun and Phoebe. The above spkpos call gives us + # the apparent distance, so we need to adjust our + # aberration correction appropriately. + # + [pos, ltime] = spiceypy.spkpos( 'SUN', et, 'J2000', + 'NONE', 'PHOEBE' ) + + # + # Compute the distance between the body centers in + # kilometers. + # + dist = spiceypy.vnorm( pos ) + + # + # Convert this value to AU using convrt. + # + dist = spiceypy.convrt( dist, 'KM', 'AU' ) + + print( ' Actual distance between Sun and ' + 'Phoebe body centers:\n' + ' (AU): {:16.3f}'.format(dist) ) + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + getsta() + +Solution Sample Output + +Execute the program: + +:: + + Input UTC Time: 2004 jun 11 19:32:00 + Converting UTC Time: 2004 jun 11 19:32:00 + ET seconds past J2000: 140254384.185 + Apparent state of Phoebe as seen from CASSINI in the J2000 + frame (km, km/s): + X = -119.921 + Y = 2194.139 + Z = -57.639 + VX = -5.980 + VY = -2.119 + VZ = -0.295 + Apparent position of Earth as seen from CASSINI in the J2000 + frame (km): + X = 353019393.123 + Y = -1328180352.140 + Z = -568134171.697 + One way light time between CASSINI and the apparent position + of Earth (seconds): 4960.427 + Apparent position of Sun as seen from Phoebe in the + J2000 frame (km): + X = 376551465.272 + Y = -1190495630.303 + Z = -508438699.110 + Actual distance between Sun and Phoebe body centers: + (AU): 9.012 + +.. _extra-credit-1: + +Extra Credit +------------ + +In this \``extra credit’’ section you will be presented with more +complex tasks, aimed at improving your understanding of state +computations, particularly the application of the different light time +and stellar aberration corrections available in the spiceypy.spkezr +function, and some common errors that may happen when computing these +states. + +These \``extra credit’’ tasks are provided as task statements, and +unlike the regular tasks, no approach or solution source code is +provided. In the next section, you will find the numeric solutions (when +applicable) and answers to the questions asked in these tasks. + +Task statements and questions + +:: + + 1. Remove the Solar System ephemerides SPK from the original + meta-kernel and run your program again, using the same inputs + as before. Has anything changed? Why? + + 2. Extend your program to compute the geometric position of + Jupiter as seen from Saturn in the J2000 frame (J2000), in + kilometers. + + 3. Extend, or modify, your program to compute the position of the + Sun as seen from Saturn in the J2000 frame (J2000), in + kilometers, using the following light time and aberration + corrections: NONE, LT and LT+S. Explain the differences. + + 4. Examine the CASSINI frames definition kernel and the ISS + instrument kernel to find the SPICE ID/name definitions. + +Solutions and answers + +:: + + 1. When running the original program without the Solar System + ephemerides SPK, an error is produced by spiceypy.spkezr: + + Traceback (most recent call last): + File "getsta.py", line 128, in + getsta() + File "getsta.py", line 47, in getsta + 'LT+S', 'CASSINI' ) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 76, in with_errcheck + checkForSpiceError(f) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 59, in checkForSpiceError + raise stypes.SpiceyError(msg) + spiceypy.utils.support_types.SpiceyError: + ===================================================================== + =========== + + Toolkit version: N0066 + + SPICE(SPKINSUFFDATA) -- + + Insufficient ephemeris data has been loaded to compute the state of - + 82 (CASSINI) relative to 0 (SOLAR SYSTEM BARYCENTER) at the ephemeris + epoch 2004 JUN 11 19:33:04.184. + + spkezr_c --> SPKEZR --> SPKEZ --> SPKACS --> SPKGEO + + ===================================================================== + =========== + + This error is generated when trying to compute the apparent + state of Phoebe as seen from CASSINI in the J2000 frame because + despite both Phoebe and CASSINI ephemeris data being relative + to the Saturn Barycenter, the state of the spacecraft with + respect to the solar system barycenter is required to compute + the light time and stellar aberrations. The loaded SPK data are + enough to compute geometric states of CASSINI with respect to + the Saturn Barycenter, and geometric states of Phoebe with + respect to the Saturn Barycenter, but insufficient to compute + the state of the spacecraft relative to the Solar System + Barycenter because the SPK data needed to compute geometric + states of Saturn Barycenter relative to the Solar System + barycenter are no longer loaded. Run ``brief'' on the SPKs used + in the original task to find out which ephemeris objects are + available from those kernels. If you want to find out what is + the 'center of motion' for the ephemeris object(s) included in + an SPK, use the -c option when running ``brief'': + + + BRIEF -- Version 4.0.0, September 8, 2010 -- Toolkit Version N0066 + + + Summary for: kernels/spk/981005_PLTEPH-DE405S.bsp + + Bodies: MERCURY BARYCENTER (1) w.r.t. SOLAR SYSTEM BARYCENTER (0) + VENUS BARYCENTER (2) w.r.t. SOLAR SYSTEM BARYCENTER (0) + EARTH BARYCENTER (3) w.r.t. SOLAR SYSTEM BARYCENTER (0) + MARS BARYCENTER (4) w.r.t. SOLAR SYSTEM BARYCENTER (0) + JUPITER BARYCENTER (5) w.r.t. SOLAR SYSTEM BARYCENTER (0) + SATURN BARYCENTER (6) w.r.t. SOLAR SYSTEM BARYCENTER (0) + URANUS BARYCENTER (7) w.r.t. SOLAR SYSTEM BARYCENTER (0) + NEPTUNE BARYCENTER (8) w.r.t. SOLAR SYSTEM BARYCENTER (0) + PLUTO BARYCENTER (9) w.r.t. SOLAR SYSTEM BARYCENTER (0) + SUN (10) w.r.t. SOLAR SYSTEM BARYCENTER (0) + MERCURY (199) w.r.t. MERCURY BARYCENTER (1) + VENUS (299) w.r.t. VENUS BARYCENTER (2) + MOON (301) w.r.t. EARTH BARYCENTER (3) + EARTH (399) w.r.t. EARTH BARYCENTER (3) + MARS (499) w.r.t. MARS BARYCENTER (4) + Start of Interval (UTC) End of Interval (UTC) + ----------------------------- ------------------------- + ---- + 2004-JUN-11 05:00:00.000 2004-JUN-12 12:00:00.000 + + + Summary for: kernels/spk/020514_SE_SAT105.bsp + + Bodies: MIMAS (601) w.r.t. SATURN BARYCENTER (6) + ENCELADUS (602) w.r.t. SATURN BARYCENTER (6) + TETHYS (603) w.r.t. SATURN BARYCENTER (6) + DIONE (604) w.r.t. SATURN BARYCENTER (6) + RHEA (605) w.r.t. SATURN BARYCENTER (6) + TITAN (606) w.r.t. SATURN BARYCENTER (6) + HYPERION (607) w.r.t. SATURN BARYCENTER (6) + IAPETUS (608) w.r.t. SATURN BARYCENTER (6) + PHOEBE (609) w.r.t. SATURN BARYCENTER (6) + SATURN (699) w.r.t. SATURN BARYCENTER (6) + Start of Interval (UTC) End of Interval (UTC) + ----------------------------- ------------------------- + ---- + 2004-JUN-11 05:00:00.000 2004-JUN-12 12:00:00.000 + + + Summary for: kernels/spk/030201AP_SK_SM546_T45.bsp + + Body: CASSINI (-82) w.r.t. SATURN BARYCENTER (6) + Start of Interval (UTC) End of Interval (UTC) + ----------------------------- --------------------------- + -- + 2004-JUN-11 05:00:00.000 2004-JUN-12 12:00:00.000 + + + + 2. If you run your extended program with the original meta-kernel, + the SPICE(SPKINSUFFDATA) error should be produced by the + spiceypy.spkpos function because you have not loaded enough + ephemeris data to compute the position of Jupiter with respect + to Saturn. The loaded SPKs contain data for Saturn relative to + the Solar System Barycenter, and for the Jupiter System + Barycenter relative to the Solar System Barycenter, but the + data for Jupiter relative to the Jupiter System Barycenter are + missing: + + + Additional kernels required for this task: + + File name Contents + ----------------------- ---------------------------------- + jup310_2004.bsp Generic Jovian Satellite Ephemeris + + + available in the NAIF server at: + + https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/ + + + Download the relevant SPK, add it to the meta-kernel and run + again your extended program. The solution for the input UTC + time "2004 jun 11 19:32:00" when using the downloaded Jovian + Satellite Ephemeris SPK: + + Actual position of Jupiter as seen from Saturn in the + J2000 frame (km): + X = -436016583.291 + Y = -1094176737.323 + Z = -446585337.431 + + 3. When using 'NONE' aberration corrections, spiceypy.spkpos + returns the geometric position of the target body relative to + the observer. If 'LT' is used, the returned vector corresponds + to the position of the target at the moment it emitted photons + arriving at the observer at `et'. If 'LT+S' is used instead, + the returned vector takes into account the observer's velocity + relative to the solar system barycenter. The solution for the + input UTC time "2004 jun 11 19:32:00" is: + + + Actual (geometric) position of Sun as seen from Saturn in the + J2000 frame (km): + X = 367770592.367 + Y = -1197330367.359 + Z = -510369088.677 + Light-time corrected position of Sun as seen from Saturn in the + J2000 frame (km): + X = 367770572.921 + Y = -1197330417.733 + Z = -510369109.509 + Apparent position of Sun as seen from Saturn in the + J2000 frame (km): + X = 367726456.168 + Y = -1197342627.879 + Z = -510372252.747 + +Spacecraft Orientation and Reference Frames (xform) +=================================================== + +.. _task-statement-2: + +Task Statement +-------------- + +Write a program that prompts the user for an input time string, computes +and displays the following at the epoch of interest: + +:: + + 1. The apparent state of Phoebe as seen from CASSINI in the + IAU_PHOEBE body-fixed frame. This vector itself is not of any + particular interest, but it is a useful intermediate quantity + in some geometry calculations. + + 2. The angular separation between the apparent position of Earth + as seen from CASSINI and the nominal boresight of the CASSINI + high gain antenna (HGA). + + The HGA boresight direction is provided by the kernel variable + TKFRAME_-82101_BORESIGHT, which is defined in the Cassini frame + kernel cited above in the section ``Kernels Used.'' In this + kernel, the HGA boresight vector is expressed relative to the + CASSINI_HGA reference frame. + +Use the program to compute these quantities at the epoch “2004 jun 11 +19:32:00” UTC. + +.. _learning-goals-2: + +Learning Goals +-------------- + +Familiarity with the different types of kernels involved in chaining +reference frames together, both inertial and non-inertial. Discover some +of the matrix and vector math functions. Understand the difference +between spiceypy.pxform and spiceypy.sxform. + +.. _approach-2: + +Approach +-------- + +The solution to the problem can be broken down into a series of simple +steps: + +:: + + -- Decide which SPICE kernels are necessary. Prepare a meta-kernel + listing the kernels and load it into the program. + + -- Prompt the user for an input time string. + + -- Convert the input time string into ephemeris time expressed as + seconds past J2000 TDB. + + -- Compute the state of Phoebe relative to CASSINI in the J2000 + reference frame, corrected for aberrations. + + -- Compute the state transformation matrix from J2000 to + IAU_PHOEBE at the epoch, adjusted for light time. + + -- Multiply the state of Phoebe relative to CASSINI in the J2000 + reference frame by the state transformation matrix computed in + the previous step. + + -- Compute the position of Earth relative to CASSINI in the J2000 + reference frame, corrected for aberrations. + + -- Determine what the nominal boresight of the CASSINI high gain + antenna is by examining the frame kernel's content. + + -- Compute the rotation matrix from the CASSINI high gain antenna + frame to J2000. + + -- Multiply the nominal boresight expressed in the CASSINI high + gain antenna frame by the rotation matrix from the previous + step. + + -- Compute the separation between the result of the previous step + and the apparent position of the Earth relative to CASSINI in + the J2000 frame. + +HINT: Several of the steps above may be compressed into a single step +using SpiceyPy functions with which you are already familiar. The +\``long way’’ presented above is intended to facilitate the introduction +of the functions spiceypy.pxform and spiceypy.sxform. + +You may find it useful to consult the permuted index, the headers of +various source modules, and the following toolkit documentation: + +:: + + 1. Frames Required Reading (frames.req) + + 2. PCK Required Reading (pck.req) + + 3. SPK Required Reading (spk.req) + + 4. CK Required Reading (ck.req) + +This particular example makes use of many of the different types of +SPICE kernels. You should spend a few moments thinking about which +kernels you will need and what data they provide. + +.. _solution-2: + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘xform.tm’. Its contents follow: + +:: + + KPL/MK + + This is the meta-kernel used in the solution of the ``Spacecraft + Orientation and Reference Frames'' task in the Remote Sensing + Hands On Lesson. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File name Contents + -------------------------- ----------------------------- + naif0008.tls Generic LSK + cas00084.tsc Cassini SCLK + 981005_PLTEPH-DE405S.bsp Solar System Ephemeris + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK + cas_v37.tf Cassini FK + 04135_04171pc_psiv2.bc Cassini Spacecraft CK + cpck05Mar2004.tpc Cassini Project PCK + + + \begindata + KERNELS_TO_LOAD = ( 'kernels/lsk/naif0008.tls', + 'kernels/sclk/cas00084.tsc', + 'kernels/spk/981005_PLTEPH-DE405S.bsp', + 'kernels/spk/020514_SE_SAT105.bsp', + 'kernels/spk/030201AP_SK_SM546_T45.bsp', + 'kernels/fk/cas_v37.tf', + 'kernels/ck/04135_04171pc_psiv2.bc', + 'kernels/pck/cpck05Mar2004.tpc' ) + \begintext + +Solution Source Code + +A sample solution to the problem follows: + +:: + + # + # Solution xform.py + # + from __future__ import print_function + from builtins import input + + import spiceypy + + def xform(): + # + # Local parameters + # + METAKR = 'xform.tm' + + # + # Load the kernels that this program requires. We + # will need: + # + # A leapseconds kernel + # A spacecraft clock kernel for CASSINI + # The necessary ephemerides + # A planetary constants file (PCK) + # A spacecraft orientation kernel for CASSINI (CK) + # A frame kernel (TF) + # + spiceypy.furnsh( METAKR ) + + # + # Prompt the user for the input time string. + # + utctim = input( 'Input UTC Time: ' ) + + print( 'Converting UTC Time: {:s}'.format(utctim) ) + + # + #Convert utctim to ET. + # + et = spiceypy.str2et( utctim ) + + print( ' ET seconds past J2000: {:16.3f}'.format(et) ) + + # + # Compute the apparent state of Phoebe as seen from + # CASSINI in the J2000 frame. + # + [state, ltime] = spiceypy.spkezr( 'PHOEBE', et, 'J2000', + 'LT+S', 'CASSINI' ) + # + # Now obtain the transformation from the inertial + # J2000 frame to the non-inertial body-fixed IAU_PHOEBE + # frame. Since we want the apparent position, we + # need to subtract ltime from et. + # + sform = spiceypy.sxform( 'J2000', 'IAU_PHOEBE', et-ltime ) + + # + # Now rotate the apparent J2000 state into IAU_PHOEBE + # with the following matrix multiplication: + # + bfixst = spiceypy.mxvg ( sform, state, 6, 6 ) + + # + # Display the results. + # + print( ' Apparent state of Phoebe as seen ' + 'from CASSINI in the IAU_PHOEBE\n' + ' body-fixed frame (km, km/s):' ) + print( ' X = {:19.6f}'.format(bfixst[0]) ) + print( ' Y = {:19.6f}'.format(bfixst[1]) ) + print( ' Z = {:19.6f}'.format(bfixst[2]) ) + print( ' VX = {:19.6f}'.format(bfixst[3]) ) + print( ' VY = {:19.6f}'.format(bfixst[4]) ) + print( ' VZ = {:19.6f}'.format(bfixst[5]) ) + + # + # It is worth pointing out, all of the above could + # have been done with a single use of spkezr: + # + [state, ltime] = spiceypy.spkezr( + 'PHOEBE', et, 'IAU_PHOEBE', + 'LT+S', 'CASSINI' ) + # + # Display the results. + # + print( ' Apparent state of Phoebe as seen ' + 'from CASSINI in the IAU_PHOEBE\n' + ' body-fixed frame (km, km/s) ' + 'obtained using spkezr directly:' ) + print( ' X = {:19.6f}'.format(state[0]) ) + print( ' Y = {:19.6f}'.format(state[1]) ) + print( ' Z = {:19.6f}'.format(state[2]) ) + print( ' VX = {:19.6f}'.format(state[3]) ) + print( ' VY = {:19.6f}'.format(state[4]) ) + print( ' VZ = {:19.6f}'.format(state[5]) ) + + # + # Note that the velocity found by using spkezr + # to compute the state in the IAU_PHOEBE frame differs + # at the few mm/second level from that found previously + # by calling spkezr and then sxform. Computing + # velocity via a single call to spkezr as we've + # done immediately above is slightly more accurate because + # it accounts for the effect of the rate of change of + # light time on the apparent angular velocity of the + # target's body-fixed reference frame. + # + # Now we are to compute the angular separation between + # the apparent position of the Earth as seen from the + # orbiter and the nominal boresight of the high gain + # antenna. First, compute the apparent position of + # the Earth as seen from CASSINI in the J2000 frame. + # + [pos, ltime] = spiceypy.spkpos( 'EARTH', et, 'J2000', + 'LT+S', 'CASSINI' ) + + # + # Now compute the location of the antenna boresight + # at this same epoch. From reading the frame kernel + # we know that the antenna boresight is nominally the + # +Z axis of the CASSINI_HGA frame defined there. + # + bsight = [ 0.0, 0.0, 1.0] + + # + # Now compute the rotation matrix from CASSINI_HGA into + # J2000. + # + pform = spiceypy.pxform( 'CASSINI_HGA', 'J2000', et ) + + # + # And multiply the result to obtain the nominal + # antenna boresight in the J2000 reference frame. + # + bsight = spiceypy.mxv( pform, bsight ) + + # + # Lastly compute the angular separation. + # + sep = spiceypy.convrt( spiceypy.vsep(bsight, pos), + 'RADIANS', 'DEGREES' ) + + print( ' Angular separation between the ' + 'apparent position of\n' + ' Earth and the CASSINI high ' + 'gain antenna boresight (degrees):\n' + ' {:16.3f}'.format(sep) ) + + # + # Or alternatively we can work in the antenna + # frame directly. + # + [pos, ltime] = spiceypy.spkpos( + 'EARTH', et, 'CASSINI_HGA', + 'LT+S', 'CASSINI' ) + + # + # The antenna boresight is the Z-axis in the + # CASSINI_HGA frame. + # + bsight = [ 0.0, 0.0, 1.0 ] + + # + # Lastly compute the angular separation. + # + sep = spiceypy.convrt( spiceypy.vsep(bsight, pos), + 'RADIANS', 'DEGREES' ) + + print( ' Angular separation between the ' + 'apparent position of\n' + ' Earth and the CASSINI high ' + 'gain antenna boresight computed\n' + ' using vectors in the CASSINI_HGA ' + 'frame (degrees):\n' + ' {:16.3f}'.format(sep) ) + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + xform() + +Solution Sample Output + +Execute the program: + +:: + + Input UTC Time: 2004 jun 11 19:32:00 + Converting UTC Time: 2004 jun 11 19:32:00 + ET seconds past J2000: 140254384.185 + Apparent state of Phoebe as seen from CASSINI in the IAU_PHOEBE + body-fixed frame (km, km/s): + X = -1982.639762 + Y = -934.530471 + Z = -166.562595 + VX = 3.970833 + VY = -3.812498 + VZ = -2.371663 + Apparent state of Phoebe as seen from CASSINI in the IAU_PHOEBE + body-fixed frame (km, km/s) obtained using spkezr directly: + X = -1982.639762 + Y = -934.530471 + Z = -166.562595 + VX = 3.970832 + VY = -3.812496 + VZ = -2.371663 + Angular separation between the apparent position of + Earth and the CASSINI high gain antenna boresight (degrees): + 71.924 + Angular separation between the apparent position of + Earth and the CASSINI high gain antenna boresight computed + using vectors in the CASSINI_HGA frame (degrees): + 71.924 + +.. _extra-credit-2: + +Extra Credit +------------ + +In this \``extra credit’’ section you will be presented with more +complex tasks, aimed at improving your understanding of frame +transformations, and some common errors that may happen when computing +them. + +These \``extra credit’’ tasks are provided as task statements, and +unlike the regular tasks, no approach or solution source code is +provided. In the next section, you will find the numeric solutions (when +applicable) and answers to the questions asked in these tasks. + +Task statements and questions + +:: + + 1. Run the original program using the input UTC time ``2004 jun 11 + 18:25:00''. Explain what happens. + + 2. Compute the angular separation between the apparent position of + the Sun as seen from CASSINI and the nominal boresight of the + CASSINI high gain antenna (HGA). Is the HGA illuminated? + +Solutions and answers + +:: + + 1. When running the original software using as input the UTC time + string "2004 jun 11 18:25:00": + + Traceback (most recent call last): + File "xform.py", line 183, in + xform() + File "xform.py", line 130, in xform + pform = spiceypy.pxform( 'CASSINI_HGA', 'J2000', et ) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 76, in with_errcheck + checkForSpiceError(f) + File "/home/bsemenov/local/lib/python3.5/site-packages/spiceypy/spi + ceypy.py", line 59, in checkForSpiceError + raise stypes.SpiceyError(msg) + spiceypy.utils.support_types.SpiceyError: + ===================================================================== + =========== + + Toolkit version: N0066 + + SPICE(NOFRAMECONNECT) -- + + At epoch 1.4025036418463E+08 TDB (2004 JUN 11 18:26:04.184 TDB), ther + e is insufficient information available to transform from reference f + rame -82101 (CASSINI_HGA) to reference frame 1 (J2000). Frame CASSINI + _HGA could be transformed to frame -82000 (CASSINI_SC_COORD). The lat + ter is a CK frame; a CK file containing data + + pxform_c --> PXFORM --> REFCHG + + ===================================================================== + =========== + + spiceypy.pxform returns the SPICE(NOFRAMECONNECT) error, which + indicates that there are not sufficient data to perform the + transformation from the CASSINI_HGA frame to J2000 at the + requested epoch. If you summarize the CASSINI spacecraft CK + using the ``ckbrief'' utility program with the -dump option + (display interpolation intervals boundaries) you will find that + the CK contains gaps within its segment: + + + CKBRIEF -- Version 6.1.0, June 27, 2014 -- Toolkit Version N0066 + + + Summary for: kernels/ck/04135_04171pc_psiv2.bc + + Segment No.: 1 + + Object: -82000 + Interval Begin UTC Interval End UTC AV + ------------------------ ------------------------ --- + 2004-JUN-11 05:00:00.000 2004-JUN-11 09:25:02.019 Y + 2004-JUN-11 09:26:14.019 2004-JUN-11 18:24:37.152 Y + 2004-JUN-11 18:26:13.152 2004-JUN-12 05:53:26.012 Y + 2004-JUN-12 05:54:56.012 2004-JUN-12 10:32:08.016 Y + 2004-JUN-12 10:33:26.016 2004-JUN-12 11:59:59.998 Y + + + + whereas if you had used ckbrief without -dump you would have + gotten the following information (only CK segment begin/end + times): + + + CKBRIEF -- Version 6.1.0, June 27, 2014 -- Toolkit Version N0066 + + + Summary for: kernels/ck/04135_04171pc_psiv2.bc + + Object: -82000 + Interval Begin UTC Interval End UTC AV + ------------------------ ------------------------ --- + 2004-JUN-11 05:00:00.000 2004-JUN-12 11:59:59.998 Y + + + + which has insufficient detail to reveal the problem. + + 2. By computing the apparent position of the Sun as seen from + CASSINI in the CASSINI_HGA frame, and the angular separation + between this vector and the nominal boresight of the CASSINI + high gain antenna (+Z-axis of the CASSINI_HGA frame), you will + find whether the HGA is illuminated. The solution for the input + UTC time "2004 jun 11 19:32:00" is: + + Angular separation between the apparent position of the Sun and the + nominal boresight of the CASSINI high gain antenna (degrees): + 73.130 + + HGA illumination: + CASSINI high gain antenna IS illuminated. + + since the angular separation is smaller than 90 degrees. + +Computing Sub-s/c and Sub-solar Points on an Ellipsoid and a DSK (subpts) +========================================================================= + +.. _task-statement-3: + +Task Statement +-------------- + +Write a program that prompts the user for an input UTC time string and +computes the following quantities at that epoch: + +:: + + 1. The apparent sub-observer point of CASSINI on Phoebe, in the + body fixed frame IAU_PHOEBE, in kilometers. + + 2. The apparent sub-solar point on Phoebe, as seen from CASSINI in + the body fixed frame IAU_PHOEBE, in kilometers. + +The program computes each point twice: once using an ellipsoidal shape +model and the + +:: + + near point/ellipsoid + +definition, and once using a DSK shape model and the + +:: + + nadir/dsk/unprioritized + +definition. + +The program displays the results. Use the program to compute these +quantities at “2004 jun 11 19:32:00” UTC. + +.. _learning-goals-3: + +Learning Goals +-------------- + +Discover higher level geometry calculation functions in SpiceyPy and +their usage as it relates to CASSINI. + +.. _approach-3: + +Approach +-------- + +This particular problem is more of an exercise in searching the permuted +index to find the appropriate functions and then reading their headers +to understand how to call them. + +One point worth considering: how would the results change if the +sub-solar and sub-observer points were computed using the + +:: + + intercept/ellipsoid + +and + +:: + + intercept/dsk/unprioritized + +definitions? Which definition is appropriate? + +.. _solution-3: + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘subpts.tm’. Its contents follow: + +:: + + KPL/MK + + This is the meta-kernel used in the solution of the + ``Computing Sub-spacecraft and Sub-solar Points'' task + in the Remote Sensing Hands On Lesson. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File name Contents + -------------------------- ----------------------------- + naif0008.tls Generic LSK + 981005_PLTEPH-DE405S.bsp Solar System Ephemeris + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK + cpck05Mar2004.tpc Cassini Project PCK + phoebe_64q.bds Phoebe DSK + + + \begindata + KERNELS_TO_LOAD = ( 'kernels/lsk/naif0008.tls', + 'kernels/spk/981005_PLTEPH-DE405S.bsp', + 'kernels/spk/020514_SE_SAT105.bsp', + 'kernels/spk/030201AP_SK_SM546_T45.bsp', + 'kernels/pck/cpck05Mar2004.tpc' + 'kernels/dsk/phoebe_64q.bds' ) + + \begintext + +Solution Source Code + +A sample solution to the problem follows: + +:: + + # + # Solution subpts.py + # + from __future__ import print_function + from builtins import input + + # + # SpiceyPy package: + # + import spiceypy + + def subpts(): + # + # Local parameters + # + METAKR = 'subpts.tm' + + # + # Load the kernels that this program requires. We + # will need: + # + # A leapseconds kernel + # The necessary ephemerides + # A planetary constants file (PCK) + # A DSK file containing Phoebe shape data + # + spiceypy.furnsh( METAKR ) + + # + #Prompt the user for the input time string. + # + utctim = input( 'Input UTC Time: ' ) + + print( ' Converting UTC Time: {:s}'.format(utctim) ) + + # + #Convert utctim to ET. + # + et = spiceypy.str2et( utctim ) + + print( ' ET seconds past J2000: {:16.3f}'.format(et) ) + + for i in range(2): + + if i == 0: + # + # Use the "near point" sub-point definition + # and an ellipsoidal model. + # + method = 'NEAR POINT/Ellipsoid' + + else: + # + # Use the "nadir" sub-point definition + # and a DSK model. + # + method = 'NADIR/DSK/Unprioritized' + + print( '\n Sub-point/target shape model: {:s}\n'.format( + method ) ) + + # + # Compute the apparent sub-observer point of CASSINI + # on Phoebe. + # + [spoint, trgepc, srfvec] = spiceypy.subpnt( + method, 'PHOEBE', et, + 'IAU_PHOEBE', 'LT+S', 'CASSINI' ) + + print( ' Apparent sub-observer point of CASSINI ' + 'on Phoebe in the\n' + ' IAU_PHOEBE frame (km):' ) + print( ' X = {:16.3f}'.format(spoint[0]) ) + print( ' Y = {:16.3f}'.format(spoint[1]) ) + print( ' Z = {:16.3f}'.format(spoint[2]) ) + print( ' ALT = {:16.3f}'.format(spiceypy.vnorm(srfvec)) ) + + # + # Compute the apparent sub-solar point on Phoebe + # as seen from CASSINI. + # + [spoint, trgepc, srfvec] = spiceypy.subslr( + method, 'PHOEBE', et, + 'IAU_PHOEBE', 'LT+S', 'CASSINI' ) + + print( ' Apparent sub-solar point on Phoebe ' + 'as seen from CASSINI in\n' + ' the IAU_PHOEBE frame (km):' ) + print( ' X = {:16.3f}'.format(spoint[0]) ) + print( ' Y = {:16.3f}'.format(spoint[1]) ) + print( ' Z = {:16.3f}'.format(spoint[2]) ) + + # + # End of computation block for "method" + # + print( '' ) + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + subpts() + +Solution Sample Output + +Execute the program: + +:: + + Input UTC Time: 2004 jun 11 19:32:00 + Converting UTC Time: 2004 jun 11 19:32:00 + ET seconds past J2000: 140254384.185 + + Sub-point/target shape model: NEAR POINT/Ellipsoid + + Apparent sub-observer point of CASSINI on Phoebe in the + IAU_PHOEBE frame (km): + X = 104.498 + Y = 45.269 + Z = 7.383 + ALT = 2084.116 + Apparent sub-solar point on Phoebe as seen from CASSINI in + the IAU_PHOEBE frame (km): + X = 78.681 + Y = 76.879 + Z = -21.885 + + Sub-point/target shape model: NADIR/DSK/Unprioritized + + Apparent sub-observer point of CASSINI on Phoebe in the + IAU_PHOEBE frame (km): + X = 95.373 + Y = 40.948 + Z = 6.610 + ALT = 2094.242 + Apparent sub-solar point on Phoebe as seen from CASSINI in + the IAU_PHOEBE frame (km): + X = 79.111 + Y = 77.338 + Z = -22.028 + +.. _extra-credit-3: + +Extra Credit +------------ + +In this \``extra credit’’ section you will be presented with more +complex tasks, aimed at improving your understanding of spiceypy.subpnt +and spiceypy.subslr functions. + +These \``extra credit’’ tasks are provided as task statements, and +unlike the regular tasks, no approach or solution source code is +provided. In the next section, you will find the numeric solutions (when +applicable) and answers to the questions asked in these tasks. + +Task statements and questions + +:: + + 1. Recompute the apparent sub-solar point on Phoebe as seen from + CASSINI in the body fixed frame IAU_PHOEBE in kilometers using + the 'Intercept/ellipsoid' method at ``2004 jun 11 19:32:00''. + Explain the differences. + + 2. Compute the geometric sub-spacecraft point of CASSINI on Phoebe + in the body fixed frame IAU_PHOEBE in kilometers using the + 'Near point/ellipsoid' method at ``2004 jun 11 19:32:00''. + + 3. Transform the sub-spacecraft Cartesian coordinates obtained in + the previous task to planetocentric and planetographic + coordinates. When computing planetographic coordinates, + retrieve Phoebe's radii by calling spiceypy.bodvrd and use the + first element of the returned radii values as Phoebe's + equatorial radius. Explain why planetocentric and + planetographic latitudes and longitudes are different. Explain + why the planetographic altitude for a point on the surface of + Phoebe is not zero and whether this is correct or not. + +Solutions and answers + +:: + + 1. The differences observed are due to the computation method. The + ``Intercept/ellipsoid'' method defines the sub-solar point as + the target surface intercept of the line containing the Sun and + the target's center, while the ``Near point/ellipsoid'' method + defines the sub-solar point as the the nearest point on the + target relative to the Sun. Since Phoebe is not spherical, + these two points are not the same: + + Apparent sub-solar point on Phoebe as seen from CASSINI in + the IAU_PHOEBE frame using the 'Near Point: ellipsoid' method + (km): + X = 78.681 + Y = 76.879 + Z = -21.885 + + Apparent sub-solar point on Phoebe as seen from CASSINI in + the IAU_PHOEBE frame using the 'Intercept: ellipsoid' method + (km): + X = 74.542 + Y = 79.607 + Z = -24.871 + + 2. The geometric sub-spacecraft point of CASSINI on Phoebe in the + body fixed frame IAU_PHOEBE in kilometers at ``2004 jun 11 + 19:32:00'' UTC epoch is: + + Geometric sub-spacecraft point of CASSINI on Phoebe in + the IAU_PHOEBE frame using the 'Near Point: ellipsoid' method + (km): + X = 104.497 + Y = 45.270 + Z = 7.384 + + 3. The sub-spacecraft point of CASSINI on Phoebe in planetocentric + and planetographic coordinates at ``2004 jun 11 19:32:00'' UTC + epoch is: + + Planetocentric coordinates of the CASSINI + sub-spacecraft point on Phoebe (degrees, km): + LAT = 3.710 + LON = 23.423 + R = 114.121 + + Planetographic coordinates of the CASSINI + sub-spacecraft point on Phoebe (degrees, km): + LAT = 4.454 + LON = 336.577 + ALT = -0.831 + + The planetocentric and planetographic longitudes are different + (``graphic'' = 360 - ``centric'') because planetographic + longitudes on Phoebe are measured positive west as defined by + Phoebe's rotation direction. + + The planetocentric and planetographic latitudes are different + because the planetocentric latitude was computed as the angle + between the direction from the center of the body to the point + and the equatorial plane, while the planetographic latitude was + computed as the angle between the surface normal at the point + and the equatorial plane. + + The planetographic altitude is non zero because it was computed + using a different and incorrect Phoebe surface model: a + spheroid with equal equatorial radii. The surface point + returned by spiceypy.subpnt was computed by treating Phoebe as + a triaxial ellipsoid with different equatorial radii. The + planetographic latitude is also incorrect because it is based + on the normal to the surface of the spheroid rather than the + ellipsoid, In general planetographic coordinates cannot be used + for bodies with shapes modeled as triaxial ellipsoids. + +Intersecting Vectors with an Ellipsoid and a DSK (fovint) +========================================================= + +.. _task-statement-4: + +Task Statement +-------------- + +Write a program that prompts the user for an input UTC time string and, +for that time, computes the intersection of the CASSINI ISS NAC camera +boresight and field of view (FOV) boundary vectors with the surface of +Phoebe. Compute each intercept twice: once with Phoebe’s shape modeled +as an ellipsoid, and once with Phoebe’s shape modeled by DSK data. The +program presents each point of intersection as + +:: + + 1. A Cartesian vector in the IAU_PHOEBE frame + + 2. Planetocentric (latitudinal) coordinates in the IAU_PHOEBE + frame. + +For each of the camera FOV boundary and boresight vectors, if an +intersection is found, the program displays the results of the above +computations, otherwise it indicates no intersection exists. + +At each point of intersection compute the following: + +:: + + 3. Phase angle + + 4. Solar incidence angle + + 5. Emission angle + +These angles should be computed using both ellipsoidal and DSK shape +models. + +Additionally compute the local solar time at the intercept of the camera +boresight with the surface of Phoebe, using both ellipsoidal and DSK +shape models. + +Use this program to compute values at the epoch: + +:: + + "2004 jun 11 19:32:00" UTC + +.. _learning-goals-4: + +Learning Goals +-------------- + +Understand how field of view parameters are retrieved from instrument +kernels. Learn how various standard planetary constants are retrieved +from text PCKs. Discover how to compute the intersection of field of +view vectors with target bodies whose shapes are modeled as ellipsoids +or provided by DSKs. Discover another high level geometry function and +another time conversion function in SpiceyPy. + +.. _approach-4: + +Approach +-------- + +This problem can be broken down into several simple, small steps: + +:: + + -- Decide which SPICE kernels are necessary. Prepare a meta-kernel + listing the kernels and load it into the program. Remember, you + will need to find a kernel with information about the CASSINI + NAC camera. + + -- Prompt the user for an input time string. + + -- Convert the input time string into ephemeris time expressed as + seconds past J2000 TDB. + + -- Retrieve the FOV (field of view) configuration for the CASSINI + NAC camera. + +For each vector in the set of boundary corner vectors, and for the +boresight vector, perform the following operations: + +:: + + -- Compute the intercept of the vector with Phoebe modeled as an + ellipsoid or using DSK data + + -- If this intercept is found, convert the position vector of the + intercept into planetocentric coordinates. + + Then compute the phase, solar incidence, and emission angles at + the intercept. Otherwise indicate to the user no intercept was + found for this vector. + + -- Compute the planetocentric longitude of the boresight + intercept. + +Finally + +:: + + -- Compute the local solar time at the boresight intercept + longitude on a 24-hour clock. The input time for this + computation should be the TDB observation epoch minus one-way + light time from the boresight intercept to the spacecraft. + +It may be useful to consult the CASSINI ISS instrument kernel to +determine the name of the NAC camera as well as its configuration. This +exercise may make use of some of the concepts and (loosely) code from +the \``Spacecraft Orientation and Reference Frames’’ task. + +.. _solution-4: + +Solution +-------- + +Solution Meta-Kernel + +The meta-kernel we created for the solution to this exercise is named +‘fovint.tm’. Its contents follow: + +:: + + KPL/MK + + This is the meta-kernel used in the solution of the + ``Intersecting Vectors with a Triaxial Ellipsoid'' task + in the Remote Sensing Hands On Lesson. + + The names and contents of the kernels referenced by this + meta-kernel are as follows: + + File name Contents + -------------------------- ----------------------------- + naif0008.tls Generic LSK + cas00084.tsc Cassini SCLK + 981005_PLTEPH-DE405S.bsp Solar System Ephemeris + 020514_SE_SAT105.bsp Saturnian Satellite Ephemeris + 030201AP_SK_SM546_T45.bsp Cassini Spacecraft SPK + cas_v37.tf Cassini FK + 04135_04171pc_psiv2.bc Cassini Spacecraft CK + cpck05Mar2004.tpc Cassini Project PCK + cas_iss_v09.ti ISS Instrument Kernel + phoebe_64q.bds Phoebe DSK + + + \begindata + KERNELS_TO_LOAD = ( 'kernels/lsk/naif0008.tls', + 'kernels/sclk/cas00084.tsc', + 'kernels/spk/981005_PLTEPH-DE405S.bsp', + 'kernels/spk/020514_SE_SAT105.bsp', + 'kernels/spk/030201AP_SK_SM546_T45.bsp', + 'kernels/fk/cas_v37.tf', + 'kernels/ck/04135_04171pc_psiv2.bc', + 'kernels/pck/cpck05Mar2004.tpc', + 'kernels/ik/cas_iss_v09.ti' + 'kernels/dsk/phoebe_64q.bds' ) + \begintext + +Solution Source Code + +A sample solution to the problem follows: + +:: + + # + # Solution fovint.py + # + from __future__ import print_function + from builtins import input + + # + # SpiceyPy package: + # + import spiceypy + from spiceypy.utils.support_types import SpiceyError + + def fovint(): + # + # Local parameters + # + METAKR = 'fovint.tm' + ROOM = 4 + + # + # Load the kernels that this program requires. We + # will need: + # + # A leapseconds kernel. + # A SCLK kernel for CASSINI. + # Any necessary ephemerides. + # The CASSINI frame kernel. + # A CASSINI C-kernel. + # A PCK file with Phoebe constants. + # The CASSINI ISS I-kernel. + # A DSK file containing Phoebe shape data. + # + spiceypy.furnsh( METAKR ) + + # + #Prompt the user for the input time string. + # + utctim = input( 'Input UTC Time: ' ) + + print( 'Converting UTC Time: {:s}'.format(utctim) ) + + # + #Convert utctim to ET. + # + et = spiceypy.str2et( utctim ) + + print( ' ET seconds past J2000: {:16.3f}\n'.format(et) ) + + # + # Now we need to obtain the FOV configuration of + # the ISS NAC camera. To do this we will need the + # ID code for CASSINI_ISS_NAC. + # + try: + nacid = spiceypy.bodn2c( 'CASSINI_ISS_NAC' ) + + except SpiceyError: + # + # Stop the program if the code was not found. + # + print( 'Unable to locate the ID code for ' + 'CASSINI_ISS_NAC' ) + raise + + # + # Now retrieve the field of view parameters. + # + [ shape, insfrm, + bsight, n, bounds ] = spiceypy.getfov( nacid, ROOM ) + + # + # `bounds' is a numpy array. We'll convert it to a list. + # + # Rather than treat BSIGHT as a separate vector, + # copy it into the last slot of BOUNDS. + # + bounds = bounds.tolist() + bounds.append( bsight ) + + # + # Set vector names to be used for output. + # + vecnam = [ 'Boundary Corner 1', + 'Boundary Corner 2', + 'Boundary Corner 3', + 'Boundary Corner 4', + 'Cassini NAC Boresight' ] + + # + # Set values of "method" string that specify use of + # ellipsoidal and DSK (topographic) shape models. + # + # In this case, we can use the same methods for calls to both + # spiceypy.sincpt and spiceypy.ilumin. Note that some SPICE + # routines require different "method" inputs from those + # shown here. See the API documentation of each routine + # for details. + # + method = [ 'Ellipsoid', 'DSK/Unprioritized'] + + # + # Get ID code of Phoebe. We'll use this ID code later, when we + # compute local solar time. + # + try: + phoeid = spiceypy.bodn2c( 'PHOEBE' ) + except: + # + # The ID code for PHOEBE is built-in to the library. + # However, it is good programming practice to get + # in the habit of handling exceptions that may + # be thrown when a quantity is not found. + # + print( 'Unable to locate the body ID code ' + 'for Phoebe.' ) + raise + + # + # Now perform the same set of calculations for each + # vector listed in the BOUNDS array. Use both + # ellipsoidal and detailed (DSK) shape models. + # + for i in range(5): + # + # Call sincpt to determine coordinates of the + # intersection of this vector with the surface + # of Phoebe. + # + print( 'Vector: {:s}\n'.format( vecnam[i] ) ) + + for j in range(2): + + print ( ' Target shape model: {:s}\n'.format( + method[j] ) ) + try: + + [point, trgepc, srfvec ] = spiceypy.sincpt( + method[j], 'PHOEBE', et, + 'IAU_PHOEBE', 'LT+S', 'CASSINI', + insfrm, bounds[i] ) + + # + # Now, we have discovered a point of intersection. + # Start by displaying the position vector in the + # IAU_PHOEBE frame of the intersection. + # + print( ' Position vector of surface intercept ' + 'in the IAU_PHOEBE frame (km):' ) + print( ' X = {:16.3f}'.format( point[0] ) ) + print( ' Y = {:16.3f}'.format( point[1] ) ) + print( ' Z = {:16.3f}'.format( point[2] ) ) + + # + # Display the planetocentric latitude and longitude + # of the intercept. + # + [radius, lon, lat] = spiceypy.reclat( point ) + + print( ' Planetocentric coordinates of ' + 'the intercept (degrees):' ) + print( ' LAT = {:16.3f}'.format( + lat * spiceypy.dpr() ) ) + print( ' LON = {:16.3f}'.format( + lon * spiceypy.dpr() ) ) + # + # Compute the illumination angles at this + # point. + # + [ trgepc, srfvec, phase, solar, \ + emissn, visibl, lit ] = \ + spiceypy.illumf( + method[j], 'PHOEBE', 'SUN', et, + 'IAU_PHOEBE', 'LT+S', 'CASSINI', point ) + + print( ' Phase angle (degrees): ' + '{:16.3f}'.format( phase*spiceypy.dpr() ) ) + print( ' Solar incidence angle (degrees): ' + '{:16.3f}'.format( solar*spiceypy.dpr() ) ) + print( ' Emission angle (degrees): ' + '{:16.3f}'.format( emissn*spiceypy.dpr()) ) + print( ' Observer visible: {:s}'.format( + str(visibl) ) ) + print( ' Sun visible: {:s}'.format( + str(lit) ) ) + + if i == 4: + # + # Compute local solar time corresponding + # to the light time corrected TDB epoch + # at the boresight intercept. + # + [hr, mn, sc, time, ampm] = spiceypy.et2lst( + trgepc, + phoeid, + lon, + 'PLANETOCENTRIC' ) + + print( '\n Local Solar Time at boresight ' + 'intercept (24 Hour Clock):\n' + ' {:s}'.format( time ) ) + # + # End of LST computation block. + # + + except SpiceyError as exc: + # + # Display a message if an exception was thrown. + # For simplicity, we treat this as an indication + # that the point of intersection was not found, + # although it could be due to other errors. + # Otherwise, continue with the calculations. + # + print( 'Exception message is: {:s}'.format( + exc.value )) + # + # End of SpiceyError try-catch block. + # + print( '' ) + # + # End of target shape model loop. + # + # + # End of vector loop. + # + + spiceypy.unload( METAKR ) + + if __name__ == '__main__': + fovint() + +Solution Sample Output + +Execute the program: + +:: + + Input UTC Time: 2004 jun 11 19:32:00 + Converting UTC Time: 2004 jun 11 19:32:00 + ET seconds past J2000: 140254384.185 + + Vector: Boundary Corner 1 + + Target shape model: Ellipsoid + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 91.026 + Y = 67.190 + Z = 2.030 + Planetocentric coordinates of the intercept (degrees): + LAT = 1.028 + LON = 36.432 + Phase angle (degrees): 28.110 + Solar incidence angle (degrees): 16.121 + Emission angle (degrees): 14.627 + Observer visible: true + Sun visible: true + + Target shape model: DSK/Unprioritized + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 78.770 + Y = 61.570 + Z = 0.964 + Planetocentric coordinates of the intercept (degrees): + LAT = 0.552 + LON = 38.013 + Phase angle (degrees): 28.110 + Solar incidence angle (degrees): 31.132 + Emission angle (degrees): 16.539 + Observer visible: true + Sun visible: true + + Vector: Boundary Corner 2 + + Target shape model: Ellipsoid + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 89.991 + Y = 66.726 + Z = 14.733 + Planetocentric coordinates of the intercept (degrees): + LAT = 7.492 + LON = 36.556 + Phase angle (degrees): 27.894 + Solar incidence angle (degrees): 22.894 + Emission angle (degrees): 14.988 + Observer visible: true + Sun visible: true + + Target shape model: DSK/Unprioritized + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 76.586 + Y = 60.579 + Z = 13.657 + Planetocentric coordinates of the intercept (degrees): + LAT = 7.962 + LON = 38.344 + Phase angle (degrees): 27.894 + Solar incidence angle (degrees): 32.013 + Emission angle (degrees): 11.845 + Observer visible: true + Sun visible: true + + Vector: Boundary Corner 3 + + Target shape model: Ellipsoid + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 80.963 + Y = 76.643 + Z = 14.427 + Planetocentric coordinates of the intercept (degrees): + LAT = 7.373 + LON = 43.430 + Phase angle (degrees): 28.171 + Solar incidence angle (degrees): 21.315 + Emission angle (degrees): 21.977 + Observer visible: true + Sun visible: true + + Target shape model: DSK/Unprioritized + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 68.677 + Y = 71.100 + Z = 13.444 + Planetocentric coordinates of the intercept (degrees): + LAT = 7.745 + LON = 45.993 + Phase angle (degrees): 28.171 + Solar incidence angle (degrees): 36.039 + Emission angle (degrees): 14.474 + Observer visible: true + Sun visible: true + + Vector: Boundary Corner 4 + + Target shape model: Ellipsoid + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 81.997 + Y = 77.106 + Z = 1.698 + Planetocentric coordinates of the intercept (degrees): + LAT = 0.865 + LON = 43.239 + Phase angle (degrees): 28.385 + Solar incidence angle (degrees): 13.882 + Emission angle (degrees): 21.763 + Observer visible: true + Sun visible: true + + Target shape model: DSK/Unprioritized + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 73.186 + Y = 73.131 + Z = 0.934 + Planetocentric coordinates of the intercept (degrees): + LAT = 0.517 + LON = 44.978 + Phase angle (degrees): 28.385 + Solar incidence angle (degrees): 41.268 + Emission angle (degrees): 17.493 + Observer visible: true + Sun visible: true + + Vector: Cassini NAC Boresight + + Target shape model: Ellipsoid + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 86.390 + Y = 72.089 + Z = 8.255 + Planetocentric coordinates of the intercept (degrees): + LAT = 4.196 + LON = 39.844 + Phase angle (degrees): 28.139 + Solar incidence angle (degrees): 18.247 + Emission angle (degrees): 17.858 + Observer visible: true + Sun visible: true + + Local Solar Time at boresight intercept (24 Hour Clock): + 11:31:50 + + Target shape model: DSK/Unprioritized + + Position vector of surface intercept in the IAU_PHOEBE frame (km): + X = 74.326 + Y = 66.602 + Z = 7.247 + Planetocentric coordinates of the intercept (degrees): + LAT = 4.153 + LON = 41.863 + Phase angle (degrees): 28.139 + Solar incidence angle (degrees): 33.200 + Emission angle (degrees): 9.230 + Observer visible: true + Sun visible: true + + Local Solar Time at boresight intercept (24 Hour Clock): + 11:39:55 + +.. _extra-credit-4: + +Extra Credit +------------ + +There are no \``extra credit’’ tasks for this step of the lesson. From 767a4f2b2877a904bde42f83d3a680c8b7e7e169 Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Thu, 23 Aug 2018 09:33:48 -0400 Subject: [PATCH 02/11] doc format fixes --- docs/binary_pck.rst | 60 +++++----- docs/event_finding.rst | 42 ++++--- docs/insitu_sensing.rst | 260 ++++++++++++++++++++-------------------- docs/installation.rst | 4 +- docs/other_stuff.rst | 64 +++++----- docs/remote_sensing.rst | 122 ++++++++++--------- 6 files changed, 271 insertions(+), 281 deletions(-) diff --git a/docs/binary_pck.rst b/docs/binary_pck.rst index b69cf9af..e77c9b3f 100644 --- a/docs/binary_pck.rst +++ b/docs/binary_pck.rst @@ -7,7 +7,7 @@ Overview -------- In this lesson you will develop two programs that demonstrate geometric -computations using \``high-accuracy’’ Earth and Moon binary PCKs. The +computations using "high-accuracy" Earth and Moon binary PCKs. The programs also demonstrate use of frame kernels and SPK files normally used together with these high-accuracy PCKs. @@ -25,11 +25,11 @@ this lesson: ---------------- ----------------------------------------------- Frames Moon rotation, Earth rotation PCK Moon rotation, Earth rotation - ``High Accuracy + "High Accuracy Orientation and Body-Fixed frames for Moon - and Earth'' + and Earth" (backup) Moon rotation, Earth rotation These tutorials are available from the NAIF ftp server at JPL: @@ -41,7 +41,7 @@ These tutorials are available from the NAIF ftp server at JPL: Required Readings The Required Reading documents are provided with the Toolkit and are -located under the \``cspice/doc’’ directory in the CSPICE Toolkit +located under the "cspice/doc" directory in the CSPICE Toolkit installation tree. :: @@ -56,7 +56,7 @@ installation tree. The Permuted Index Another useful document distributed with the Toolkit is the permuted -index. This is located under the \``cspice/doc’’ directory in the C +index. This is located under the "cspice/doc" directory in the C installation tree. This text document provides a simple mechanism by which users can @@ -65,10 +65,8 @@ as the names of the source files that contain these functions. SpiceyPy API Documentation -A SpiceyPy function’s parameters specification is available using the -built-in Python help system. A more detailed specification of the API -can be found in the CSPICE HTML API documentation page located under -\``cspice/doc/html/cspice’’. +A SpiceyPy function's parameters specification is available using the +built-in Python help system. For example, the Python help function @@ -77,11 +75,11 @@ For example, the Python help function >>> import spiceypy >>> help(spiceypy.str2et) -describes of the str2et function’s parameters, while the document +describes of the str2et function's parameters, while the document :: - cspice/doc/html/cspice/str2et_c.html + https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html describes extensively the str2et functionality. @@ -115,7 +113,7 @@ SpiceyPy Modules Used This section provides a complete list of the functions and kernels that are suggested for usage in each of the exercises in this lesson. (You -may wish to not look at this list unless/until you \``get stuck’’ while +may wish to not look at this list unless/until you "get stuck" while working on your own.) :: @@ -143,7 +141,7 @@ working on your own.) spiceypy.vdist Use the Python built-in help system on the various functions listed -above for the API parameters’ description, and refer to the headers of +above for the API parameters' description, and refer to the headers of their corresponding CSPICE versions for detailed interface specifications. @@ -204,7 +202,7 @@ Understanding the difference between the MOON_ME and MOON_PA frames. Approach -------- -The following \``tips’’ may simplify the solution process. +The following "tips" may simplify the solution process. :: @@ -217,15 +215,15 @@ The following \``tips’’ may simplify the solution process. -- Decide which SPICE kernels are necessary. Prepare a meta-kernel listing the kernels and load it into the program. - -- Consult the above list titled ``SpiceyPy Modules Used'' to see + -- Consult the above list titled "SpiceyPy Modules Used" to see which routines are needed. -- The computational steps listed above should be followed in the order shown. You may find it useful to consult the permuted index, the headers of -various source modules, and the tutorials titled ``PCK'' and``\ High -Accuracy Orientation and Body-Fixed frames for Moon and Earth.’’ +various source modules, and the tutorials titled "PCK" and" High +Accuracy Orientation and Body-Fixed frames for Moon and Earth." Solution -------- @@ -233,13 +231,13 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘mrotat.tm’. Its contents follow: +'mrotat.tm'. Its contents follow: :: KPL/MK - Meta-kernel for the ``Moon Rotation'' task in the Binary PCK + Meta-kernel for the "Moon Rotation" task in the Binary PCK Hands On Lesson. The names and contents of the kernels referenced by this @@ -489,8 +487,8 @@ Write a program that performs the following computations: The following computations (steps 5-10) examine the cause of the angular offset found above, which is attributable to the rotation between the -ITRF93 and IAU_EARTH frames. Steps 11 and up don’t rely on the results -of steps 5-10, so steps 5-10 may be safely skipped if they’re not of +ITRF93 and IAU_EARTH frames. Steps 11 and up don't rely on the results +of steps 5-10, so steps 5-10 may be safely skipped if they're not of interest to you. For each of the two epochs ET and ET + 100 days, examine the differences @@ -500,7 +498,7 @@ method: :: 5. Convert the epoch of interest to a string in the format style - ``2007-MAY-16 02:29:00.000 (UTC).'' Display this string. + "2007-MAY-16 02:29:00.000 (UTC)." Display this string. 6. Look up the 3x3 position transformation matrix that converts vectors from the IAU_EARTH to the ITRF93 frame at the epoch of @@ -549,7 +547,7 @@ seen from the DSN station DSS-13 by the following steps: 0-360 degrees; elevation is equal to the topocentric latitude. Display the results in degrees. -The next computations demonstrate \``high-accuracy’’ geometric +The next computations demonstrate "high-accuracy" geometric computations using the Earth as the target body. These computations are *not* realistic; they are simply meant to demonstrate SPICE system features used for geometry computations involving the Earth as a target @@ -590,7 +588,7 @@ required to support such computations. Approach -------- -The following \``tips’’ may simplify the solution process. +The following "tips" may simplify the solution process. :: @@ -603,10 +601,10 @@ The following \``tips’’ may simplify the solution process. -- Decide which SPICE kernels are necessary. Prepare a meta-kernel listing the kernels and load it into the program. - -- Consult the above list titled ``SpiceyPy Modules Used'' to see + -- Consult the above list titled "SpiceyPy Modules Used" to see which routines are needed. Note the functions used to provide - the values ``seconds per day,'' ``degrees per radian,'' and ``2 - times Pi.'' + the values "seconds per day," "degrees per radian," and "2 + times Pi." -- Examine the header of the function spiceypy.reclat. Note that this function may be used for coordinate conversions in @@ -618,8 +616,8 @@ The following \``tips’’ may simplify the solution process. order shown, but steps 5-10 may be omitted. You may find it useful to consult the permuted index, the headers of -various source modules, and the tutorials titled ``PCK'' and``\ High -Accuracy Orientation and Body-Fixed frames for Moon and Earth.’’ +various source modules, and the tutorials titled "PCK" and" High +Accuracy Orientation and Body-Fixed frames for Moon and Earth." .. _solution-1: @@ -629,13 +627,13 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘erotat.tm’. Its contents follow: +'erotat.tm'. Its contents follow: :: KPL/MK - Meta-kernel for the ``Earth Rotation'' task + Meta-kernel for the "Earth Rotation" task in the Binary PCK Hands On Lesson. The names and contents of the kernels referenced by this diff --git a/docs/event_finding.rst b/docs/event_finding.rst index 4e4dddc2..29c8d17c 100644 --- a/docs/event_finding.rst +++ b/docs/event_finding.rst @@ -27,7 +27,7 @@ often contain comprehensive descriptions of the frames, instrument FOVs, etc. Since both FK and IK are text kernels, the information provided in them can be viewed using any text editor, while the meta information provided in binary kernels – SPKs and CKs – can be viewed using -``commnt'' or``\ spacit’‘utility programs located in \``cspice/exe’’ of +"commnt" or" spacit"utility programs located in "cspice/exe" of Toolkit installation tree. The following SPICE tutorials serve as references for the discussions in @@ -55,7 +55,7 @@ These tutorials are available from the NAIF ftp server at JPL: Required Readings The Required Reading documents are provided with the Toolkit and are -located under the \``cspice/doc’’ directory in the CSPICE Toolkit +located under the "cspice/doc" directory in the CSPICE Toolkit installation tree. :: @@ -75,7 +75,7 @@ installation tree. The Permuted Index Another useful document distributed with the Toolkit is the permuted -index. This is located under the \``cspice/doc’’ directory in the C +index. This is located under the "cspice/doc" directory in the C installation tree. This text document provides a simple mechanism by which users can @@ -84,10 +84,8 @@ as the names of the source files that contain these functions. SpiceyPy API Documentation -A SpiceyPy function’s parameters specification is available using the -built-in Python help system. A more detailed specification of the API -can be found in the CSPICE HTML API documentation page located under -\``cspice/doc/html/cspice’’. +A SpiceyPy function's parameters specification is available using the +built-in Python help system. For example, the Python help function @@ -96,11 +94,11 @@ For example, the Python help function >>> import spiceypy >>> help(spiceypy.str2et) -describes of the str2et function’s parameters, while the document +describes of the str2et function's parameters, while the document :: - cspice/doc/html/cspice/str2et_c.html + https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html describes extensively the str2et functionality. @@ -138,7 +136,7 @@ SpiceyPy Modules Used This section provides a complete list of the functions and kernels that are suggested for usage in each of the exercises in this lesson. (You -may wish to not look at this list unless/until you \``get stuck’’ while +may wish to not look at this list unless/until you "get stuck" while working on your own.) :: @@ -165,7 +163,7 @@ working on your own.) (*) Additional APIs and kernels used in Extra Credit tasks. Use the Python built-in help system on the various functions listed -above for the API parameters’ description, and refer to the headers of +above for the API parameters' description, and refer to the headers of their corresponding CSPICE versions for detailed interface specifications. @@ -184,7 +182,7 @@ range 2004 MAY 6 TDB when the Mars Express Orbiter (MEX) is visible from the DSN station -DSS-14. These time intervals are frequently called \``view periods.’’ +DSS-14. These time intervals are frequently called "view periods." The spacecraft is considered visible if its apparent position (that is, its position corrected for light time and stellar aberration) has @@ -273,7 +271,7 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘viewpr.tm’. Its contents follow: +'viewpr.tm'. Its contents follow: :: @@ -534,7 +532,7 @@ Solution Sample Output Numerical results shown for this example may differ across platforms since the results depend on the SPICE kernels used as input and on the -host platform’s arithmetic implementation. +host platform's arithmetic implementation. Execute the program. The output is: @@ -595,8 +593,8 @@ Compute the final results twice as well, using the results of both occultation searches. For each of the two shape model cases, store the set of time intervals -when the spacecraft is visible in a SpiceyPy window. We’ll call this the -\``result window.’’ +when the spacecraft is visible in a SpiceyPy window. We'll call this the +"result window." Display each of the intervals in each result window as a pair of start and stop times. Express each time as a TDB calendar date using the same @@ -634,7 +632,7 @@ A possible solution would consist of the following steps: results of occultation searches performed using both ellipsoidal and DSK shape models. Additional windows will be needed to compute the set differences of the elevation search - (``view period'') window and each of the occultation search + ("view period") window and each of the occultation search windows. Further details are provided below. Create additional output SpiceyPy windows using @@ -654,7 +652,7 @@ A possible solution would consist of the following steps: position is behind the apparent figure of Mars, light time correction must be performed for the occultation search. To improve accuracy of the occultation state determination, use - ``converged Newtonian'' light time correction. + "converged Newtonian" light time correction. 6. Use the SpiceyPy window subtraction routine spiceypy.wndifd to subtract the window of times when the spacecraft is occulted @@ -674,7 +672,7 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘visibl.tm’. Its contents follow: +'visibl.tm'. Its contents follow: :: @@ -1007,7 +1005,7 @@ Solution Sample Output Numerical results shown for this example may differ across platforms since the results depend on the SPICE kernels used as input and on the -host platform’s arithmetic implementation. +host platform's arithmetic implementation. Execute the program. The output is: @@ -1073,12 +1071,12 @@ Execute the program. The output is: Extra Credit ============ -In this \``extra credit’’ section you will be presented with more +In this "extra credit" section you will be presented with more complex tasks, aimed at improving your understanding of the geometry event finding subsystem and particularly the spiceypy.gfposc and spiceypy.gfdist functions. -These \``extra credit’’ tasks are provided as task statements, and +These "extra credit" tasks are provided as task statements, and unlike the regular tasks, no approach or solution source code is provided. In the next section, you will find the numeric solutions to the questions asked in these tasks. diff --git a/docs/insitu_sensing.rst b/docs/insitu_sensing.rst index 0f81acb8..1e07542b 100644 --- a/docs/insitu_sensing.rst +++ b/docs/insitu_sensing.rst @@ -23,7 +23,7 @@ often contain comprehensive descriptions of the frames, instrument FOVs, etc. Since both FK and IK are text kernels, the information provided in them can be viewed using any text editor, while the meta information provided in binary kernels – SPKs and CKs – can be viewed using -``commnt'' or``\ spacit’‘utility programs located in \``cspice/exe’’ of +"commnt" or "spacit" utility programs located in "cspice/exe" of Toolkit installation tree. The following SPICE tutorials serve as references for the discussions in @@ -48,7 +48,7 @@ These tutorials are available from the NAIF ftp server at JPL: Required Readings The Required Reading documents are provided with the Toolkit and are -located under the \``cspice/doc’’ directory in the CSPICE Toolkit +located under the "cspice/doc" directory in the CSPICE Toolkit installation tree. :: @@ -64,7 +64,7 @@ installation tree. The Permuted Index Another useful document distributed with the Toolkit is the permuted -index. This is located under the \``cspice/doc’’ directory in the C +index. This is located under the "cspice/doc" directory in the C installation tree. This text document provides a simple mechanism by which users can @@ -73,10 +73,8 @@ as the names of the source files that contain these functions. SpiceyPy API Documentation -A SpiceyPy function’s parameters specification is available using the -built-in Python help system. A more detailed specification of the API -can be found in the CSPICE HTML API documentation page located under -\``cspice/doc/html/cspice’’. +A SpiceyPy function's parameters specification is available using the +built-in Python help system. For example, the Python help function @@ -85,11 +83,11 @@ For example, the Python help function >>> import spiceypy >>> help(spiceypy.str2et) -describes of the str2et function’s parameters, while the document +describes of the str2et function's parameters, while the document :: - cspice/doc/html/cspice/str2et_c.html + https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html describes extensively the str2et functionality. @@ -124,7 +122,7 @@ SpiceyPy Modules Used This section provides a complete list of the functions and kernels that are suggested for usage in each of the exercises in this lesson. (You -may wish to not look at this list unless/until you \``get stuck’’ while +may wish to not look at this list unless/until you "get stuck" while working on your own.) :: @@ -170,55 +168,55 @@ working on your own.) spiceypy.dpr Use the Python built-in help system on the various functions listed -above for the API parameters’ description, and refer to the headers of +above for the API parameters' description, and refer to the headers of their corresponding CSPICE versions for detailed interface specifications. -Step-1: \``UTC to ET’’ +Step-1: "UTC to ET" ====================== -\``UTC to ET’’ Task Statement +"UTC to ET" Task Statement ----------------------------- Write a program that computes and prints the Ephemeris Time (ET) -corresponding to \``2004-06-11T19:32:00’’ UTC, as the number of +corresponding to "2004-06-11T19:32:00" UTC, as the number of ephemeris seconds past J2000, . -\``UTC to ET’’ Hints +"UTC to ET" Hints -------------------- Find out what SPICE kernel(s) is(are) needed to support this conversion. -Reference the ``time.req'' and/or``\ Time’’ tutorial. +Reference the "time.req" and/or" Time" tutorial. -Find necessary kernel(s) on the NAIF’s FTP site. +Find necessary kernel(s) on the NAIF's FTP site. Find out what routine should be called to load necessary kernel(s). -Reference the ``kernel.req'' and/or``\ Loading Kernels’’ tutorial. +Reference the "kernel.req" and/or" Loading Kernels" tutorial. Find the -``loader'' routine calling sequence specification. Look at the``\ time.req’‘and -that routine’s source code header. This routine may be an entry point, +"loader" routine calling sequence specification. Look at the" time.req"and +that routine's source code header. This routine may be an entry point, in which case there will be no source file with the same name. To find out in which source file this entry point is, search for its name in the -\``Permuted Index’’. +"Permuted Index". Find the routine(s) used to convert time between UTC and ET. Look at the -``time.req'' and/or``\ Time’’ tutorial. +"time.req" and/or" Time" tutorial. Find the -``converter'' routine(s) calling sequence specification. Look in the``\ time.req’’ -and the routine’s source code header. +"converter" routine(s) calling sequence specification. Look in the" time.req" +and the routine's source code header. Put all calls together in a program, add variable declarations (the -routine header’s ``Declarations'' and``\ Examples’’ sections are a good +routine header's "Declarations" and" Examples" sections are a good place to look for declaration specification and examples) and output print statements. -\``UTC to ET’’ Solution Steps +"UTC to ET" Solution Steps ----------------------------- Only one kernel file is needed to support this conversion – an LSK file -\``naif0008.tls’’. +"naif0008.tls". As any other SPICE kernel this file can be loaded by the spiceypy.furnsh function. For that, the name of the file can be provided as a sole @@ -251,7 +249,7 @@ or it can be listed in a meta-kernel: ) \begintext -the name of which, let’s call it \``convrt.tm’’, can be then provided as +the name of which, let's call it "convrt.tm", can be then provided as a sole argument of the spiceypy.furnsh routine: :: @@ -266,10 +264,10 @@ simply adding more kernels to the list in KERNEL_TO_LOAD without changing the program code will accomplish that. The highest level SpiceyPy time routine converting UTC to ET is -spiceypy.str2et (``cspice/src/cspice/str2et_c.c’’). +spiceypy.str2et ("cspice/src/cspice/str2et_c.c"). It has two arguments – input time string representing UTC in a variety -of formats (see spiceypy.str2et header’s section \``Particulars’’ for +of formats (see spiceypy.str2et header's section "Particulars" for the complete description of input time formats) and output DP number of ET seconds past J2000. A call to spiceypy.str2et converting a given UTC to ET could look like this: @@ -287,7 +285,7 @@ Use of SpiceyPy calls in a Python script requires the SpiceyPy package to be installed in your Python distribution, either using pip or conda, and imported within the script. -When you execute the script, \``convrt’’, it produces the following +When you execute the script, "convrt", it produces the following output: :: @@ -296,10 +294,10 @@ output: UTC = 2004-06-11T19:32:00 ET = 140254384.184625 -\``UTC to ET’’ Code +"UTC to ET" Code ------------------- -Program \``convrt.py’’: +Program "convrt.py": :: @@ -323,7 +321,7 @@ Program \``convrt.py’’: if __name__ == '__main__': convrt() -Meta-kernel file \``convrt.tm’’: +Meta-kernel file "convrt.tm": :: @@ -343,43 +341,43 @@ Meta-kernel file \``convrt.tm’’: ) \begintext -Step-2: \``SCLK to ET’’ +Step-2: "SCLK to ET" ======================= -\``SCLK to ET’’ Task Statement +"SCLK to ET" Task Statement ------------------------------ Extend the program from Step-1 to compute and print ET for the following -CASSINI on-board clock epoch \``1465674964.105’’. +CASSINI on-board clock epoch "1465674964.105". -\``SCLK to ET’’ Hints +"SCLK to ET" Hints --------------------- Find out what additional (to those already loaded in Step-1) SPICE kernel(s) is(are) needed to support SCLK to ET conversion. Look at the -``sclk.req'' and/or``\ SCLK’’ tutorial. +"sclk.req" and/or" SCLK" tutorial. -Find necessary kernel(s) on the NAIF’s FTP site. +Find necessary kernel(s) on the NAIF's FTP site. Modify the program or meta-kernel to load this(these) kernels. Find the routine(s) needed to convert time between SCLK and ET. Look at -the ``sclk.req'' and/or``\ Time’‘and \``SCLK’’ tutorials. +the "sclk.req" and/or" Time"and "SCLK" tutorials. Find the -``converter'' routine's calling sequence specification. Look in the``\ sclk.req’’ -and the routine’s source code header. +"converter" routine's calling sequence specification. Look in the" sclk.req" +and the routine's source code header. -Look at \``naif_ids.req’’ and the comments in the additional kernel(s) +Look at "naif_ids.req" and the comments in the additional kernel(s) that you have loaded for information on proper values of input arguments of this routine. Add calls to the -``converter'' routine(s), necessary variable declarations (the routine header's``\ Declarations’‘and -\``Examples’’ sections are a good place to look for declaration +"converter" routine(s), necessary variable declarations (the routine header's" Declarations"and +"Examples" sections are a good place to look for declaration specification and examples), and output print statements to the program. -\``SCLK to ET’’ Solution Steps +"SCLK to ET" Solution Steps ------------------------------ A CASSINI SCLK file is needed additionally to the LSK file loaded in the @@ -411,10 +409,10 @@ variable: \begintext The highest level SpiceyPy routine converting SCLK to ET is -spiceypy.scs2e (``cspice/src/cspice/scs2e_c.c’’). +spiceypy.scs2e ("cspice/src/cspice/scs2e_c.c"). It has three arguments – NAIF ID for CASSINI s/c (-82 as described by -\``naif_ids.req’’ document), input time string representing CASSINI +"naif_ids.req" document), input time string representing CASSINI SCLK, and output DP number of ET seconds past J2000. A call to spiceypy.str2et converting given SCLK to ET could look like this: @@ -428,7 +426,7 @@ By adding the spiceypy.scs2e call, required declarations and a simple print statement, one would get a complete program that prints ET for the given SCLK epoch. -When you execute the script, \``sclket’’, it produces the following +When you execute the script, "sclket", it produces the following output: :: @@ -439,10 +437,10 @@ output: SCLK = 1465674964.105 ET = 140254384.183426 -\``SCLK to ET’’ Code +"SCLK to ET" Code -------------------- -Program \``sclket.py’’: +Program "sclket.py": :: @@ -473,7 +471,7 @@ Program \``sclket.py’’: if __name__ == '__main__': sclket() -Meta-kernel file \``sclket.tm’’: +Meta-kernel file "sclket.tm": :: @@ -495,45 +493,45 @@ Meta-kernel file \``sclket.tm’’: ) \begintext -Step-3: \``Spacecraft State’’ +Step-3: "Spacecraft State" ============================= -\``Spacecraft State’’ Task Statement +"Spacecraft State" Task Statement ------------------------------------ Extend the program from Step-2 to compute geometric state – position and velocity – of the CASSINI spacecraft with respect to the Sun in the Ecliptic frame at the epoch specified by SCLK time from Step-2. -\``Spacecraft State’’ Hints +"Spacecraft State" Hints --------------------------- Find out what additional (to those already loaded in Steps-1&2) SPICE kernel(s) is(are) needed to support state computation. Look at the -``spk.req'' and/or``\ SPK’’ tutorial. +"spk.req" and/or" SPK" tutorial. -Find necessary kernel(s) on the NAIF’s FTP site. +Find necessary kernel(s) on the NAIF's FTP site. Verify that the kernels contain enough data to compute the state of -interest. Use ``brief'' utility program located under``\ toolkit/exe’’ +interest. Use "brief" utility program located under" toolkit/exe" directory for that. Modify the meta-kernel to load this(these) kernels. Determine the routine(s) needed to compute states. Look at the -``spk.req'' and/or``\ SPK’’ tutorial presentation. +"spk.req" and/or" SPK" tutorial presentation. Find the the routine(s) calling sequence specification. Look in the -\``spk.req’’ and the routine’s source code header. +"spk.req" and the routine's source code header. -Reference the ``naif_ids.req'' and``\ frames.req’‘and the routine(s) -header ``Inputs'' and``\ Particulars’’ sections to determine proper +Reference the "naif_ids.req" and" frames.req"and the routine(s) +header "Inputs" and" Particulars" sections to determine proper values of the input arguments of this routine. Add calls to the routine(s), necessary variable declarations and output print statements to the program. -\``Spacecraft State’’ Solution Steps +"Spacecraft State" Solution Steps ------------------------------------ A CASSINI spacecraft trajectory SPK and generic planetary ephemeris SPK @@ -571,20 +569,20 @@ the program: \begintext The highest level SpiceyPy routine computing states is spiceypy.spkezr -(``cspice/src/cspice/spkezr_c.c’’). +("cspice/src/cspice/spkezr_c.c"). We are interested in computing CASSINI position and velocity with respect to the Sun, therefore the target and observer names should be -set to ‘CASSINI’ and ‘Sun’ (both names can be found in -\``naif_ids.req’’). +set to 'CASSINI' and 'Sun' (both names can be found in +"naif_ids.req"). The state should be in ecliptic frame, therefore the name of the frame -in which the state should be computed is ‘ECLIPJ2000’ (see -\``frames.req’’ document.) +in which the state should be computed is 'ECLIPJ2000' (see +"frames.req" document.) -Since we need only the geometric position, the \`abcorr’ argument of the -routine should be set to ‘NONE’ (see aberration correction discussion in -the (``cspice/src/cspice/spkezr_c.c’’). +Since we need only the geometric position, the \`abcorr' argument of the +routine should be set to 'NONE' (see aberration correction discussion in +the ("cspice/src/cspice/spkezr_c.c"). Putting it all together, we get: @@ -598,7 +596,7 @@ Putting it all together, we get: state, ltime = spiceypy.spkezr(target, et, frame, corrtn, observ) -When you execute the script, \``getsta’’, it produces the following +When you execute the script, "getsta", it produces the following output: :: @@ -615,10 +613,10 @@ output: VY = 0.801719 VZ = 0.040603 -\``Spacecraft State’’ Code +"Spacecraft State" Code -------------------------- -Program \``getsta.py’’: +Program "getsta.py": :: @@ -664,7 +662,7 @@ Program \``getsta.py’’: if __name__ == '__main__': getsta() -Meta-kernel file \``getsta.tm’’: +Meta-kernel file "getsta.tm": :: @@ -694,25 +692,25 @@ Meta-kernel file \``getsta.tm’’: ) \begintext -Step-4: \``Sun Direction’’ +Step-4: "Sun Direction" ========================== -\``Sun Direction’’ Task Statement +"Sun Direction" Task Statement --------------------------------- Extend the program from Step-3 to compute apparent direction of the Sun in the INMS frame at the epoch specified by SCLK time from Step-2. -\``Sun Direction’’ Hints +"Sun Direction" Hints ------------------------ Determine the additional SPICE kernels needed to support the direction computation, knowing that they should provide the s/c and instrument -frame orientation. Retrieve these kernels from the NAIF’s FTP site. +frame orientation. Retrieve these kernels from the NAIF's FTP site. Verify that the orientation data in the kernels have adequate coverage to support computation of the direction of interest. Use -``ckbrief'' utility program located under``\ toolkit/exe’’ directory +"ckbrief" utility program located under" toolkit/exe" directory for that. Modify the meta-kernel to load this(these) kernels. @@ -725,7 +723,7 @@ used. Add calls to the routine(s), necessary variable declarations and output print statements to the program. -\``Sun Direction’’ Solution Steps +"Sun Direction" Solution Steps --------------------------------- A CASSINI spacecraft orientation CK file, providing s/c orientation with @@ -773,13 +771,13 @@ The same highest level SpiceyPy routine computing positions, spiceypy.spkpos, can be used to compute this direction. Since this is the direction of the Sun as seen from the s/c, the target -argument should be set to ‘Sun’ and the observer argument should be set -to ‘CASSINI’. The name of the INMS frame is ‘CASSINI_INMS’, the +argument should be set to 'Sun' and the observer argument should be set +to 'CASSINI'. The name of the INMS frame is 'CASSINI_INMS', the definition and description of this frame are provided in the CASSINI FK -file, \``cassini_v02.tf’’. +file, "cassini_v02.tf". Since the apparent, or -:literal:`as seen'', position is sought for, the `abcorr' argument of the routine should be set to 'LT+S' (see aberration correction discussion in the (`\ cspice/src/cspice/spkpos_c.c’’) +:literal:`as seen", position is sought for, the `abcorr' argument of the routine should be set to 'LT+S' (see aberration correction discussion in the (`\ cspice/src/cspice/spkpos_c.c") If desired, the position can then be turned into a unit vector using spiceypy.vhat function @@ -797,7 +795,7 @@ spiceypy.spiceypy.vhat) Putting it all together, we get: corrtn, observ) sundir = spiceypy.vhat(sundir) -When you execute the script, \``soldir’’, it produces the following +When you execute the script, "soldir", it produces the following output: :: @@ -817,10 +815,10 @@ output: SUNDIR(Y) = 0.881631 SUNDIR(Z) = 0.372167 -\``Sun Direction’’ Code +"Sun Direction" Code ----------------------- -Program \``soldir.py’’: +Program "soldir.py": :: @@ -879,7 +877,7 @@ Program \``soldir.py’’: if __name__ == '__main__': soldir() -Meta-kernel file \``soldir.tm’’: +Meta-kernel file "soldir.tm": :: @@ -914,63 +912,63 @@ Meta-kernel file \``soldir.tm’’: ) \begintext -Step-5: \``Sub-Spacecraft Point’’ +Step-5: "Sub-Spacecraft Point" ================================= -\``Sub-Spacecraft Point’’ Task Statement +"Sub-Spacecraft Point" Task Statement ---------------------------------------- Extend the program from Step-4 to compute planetocentric longitude and and latitude of the sub-spacecraft point on Phoebe, and the direction from the spacecraft to that point in the INMS frame. -\``Sub-Spacecraft Point’’ Hints +"Sub-Spacecraft Point" Hints ------------------------------- Find the SpiceyPy routine that computes sub-observer point coordinates. -Use ``Most Used SpiceyPy APIs'' or``\ subpt’’ cookbook program for that. +Use "Most Used SpiceyPy APIs" or" subpt" cookbook program for that. -Refer to the routine’s header to determine the additional kernels needed -for this direction computation. Get these kernels from the NAIF’s FTP +Refer to the routine's header to determine the additional kernels needed +for this direction computation. Get these kernels from the NAIF's FTP site. Modify the meta-kernel to load this(these) kernels. Determine the proper input arguments for the routine. Refer to the -routine’s header for that information. +routine's header for that information. Convert the surface point Cartesian vector returned by this routine to -latitudinal coordinates. Use \``Permuted Index’’ to find the routine -that does this conversion. Refer to the routine’s header for +latitudinal coordinates. Use "Permuted Index" to find the routine +that does this conversion. Refer to the routine's header for input/output argument specifications. Since the Cartesian vector from the spacecraft to the sub-spacecraft point is computed in the Phoebe body-fixed frame, it should be transformed into the instrument frame get the direction we are looking -for. Refer to ``frames.req'' and/or``\ Frames’’ tutorial to determine +for. Refer to "frames.req" and/or" Frames" tutorial to determine the name of the routine computing transformations and use it to compute transformation from Phoebe body-fixed to the INMS frame. -Using \``Permuted Index’’ find the routine that multiplies 3x3 matrix by +Using "Permuted Index" find the routine that multiplies 3x3 matrix by 3d vector and use it to rotate the vector to the instrument frame. Add calls to the routine(s), necessary variable declarations and output print statements to the program. -\``Sub-Spacecraft Point’’ Solution Steps +"Sub-Spacecraft Point" Solution Steps ---------------------------------------- The spiceypy.subpnt routine -(\```cspice/src/cspice/subpnt_c.c'') can be used to compute the sub-observer point and the vector from the observer to that point with a single call. To determine this point as the closest point on the Phoebe ellipsoid, the``\ method’ -argument has to be set to ‘NEAR POINT: ELLIPSOID’. For our case the -\`target’ is ‘PHOEBE’, the target body-fixed frame is ‘IAU_PHOEBE’, and -the observer is ‘CASSINI’. +("`cspice/src/cspice/subpnt_c.c") can be used to compute the sub-observer point and the vector from the observer to that point with a single call. To determine this point as the closest point on the Phoebe ellipsoid, the" method' +argument has to be set to 'NEAR POINT: ELLIPSOID'. For our case the +\`target' is 'PHOEBE', the target body-fixed frame is 'IAU_PHOEBE', and +the observer is 'CASSINI'. Since the s/c is close to Phoebe, light time does not need to be taken -into account and, therefore, the \`abcorr’ argument can be set to -‘NONE’. +into account and, therefore, the \`abcorr' argument can be set to +'NONE'. In order for spiceypy.subpnt to compute the nearest point location, a PCK file containing Phoebe radii has to be loaded into the program (see -\``Files’’ section of the routine’s header.) All other files required +"Files" section of the routine's header.) All other files required for this computation are already being loaded by the program. With PCK file name added to it, the updated meta-kernel will look like this: @@ -1011,28 +1009,28 @@ file name added to it, the updated meta-kernel will look like this: The sub-spacecraft point Cartesian vector can be converted to planetocentric radius, longitude and latitude using the spiceypy.reclat -routine (``cspice/src/cspice/reclat_c.c’’). +routine ("cspice/src/cspice/reclat_c.c"). The vector from the spacecraft to the sub-spacecraft point returned by spiceypy.subpnt has to be rotated from the body-fixed frame to the instrument frame. The name of the routine that computes 3x3 matrices rotating vectors from one frame to another is spiceypy.pxform -(``cspice/src/cspice/pxform_c.c’’). +("cspice/src/cspice/pxform_c.c"). In our case the -``from' argument should be set to 'IAU_PHOEBE' and the``\ to’ argument -should be set to ‘CASSINI_INMS’ +"from' argument should be set to 'IAU_PHOEBE' and the" to' argument +should be set to 'CASSINI_INMS' The vector should be then multiplied by this matrix to rotate it to the instrument frame. The spiceypy.mxv routine performs that function -(``cspice/src/cspice/mxv_c.c’’) +("cspice/src/cspice/mxv_c.c") After applying the rotation, normalize the resultant vector using the spiceypy.vhat function. For output the longitude and latitude angles returned by spiceypy.reclat in radians can be converted to degrees by multiplying by spiceypy.dpr -function (``cspice/src/cspice/dpr_c.c’’). +function ("cspice/src/cspice/dpr_c.c"). Putting it all together, we get: @@ -1060,7 +1058,7 @@ Putting it all together, we get: print('LON = {:20.6f}'.format(slon * spiceypy.dpr())) print('LAT = {:20.6f}'.format(slat * spiceypy.dpr())) -When you execute the script, \``sscpnt’’, it produces the following +When you execute the script, "sscpnt", it produces the following output: :: @@ -1085,7 +1083,7 @@ output: SBPDIR(Y) = -0.999873 SBPDIR(Z) = -0.015905 -\``Sub-Spacecraft Point’’ Code +"Sub-Spacecraft Point" Code ------------------------------ Program @@ -1172,7 +1170,7 @@ Program if __name__ == '__main__': sscpnt() -Meta-kernel file \``sscpnt.tm’’: +Meta-kernel file "sscpnt.tm": :: @@ -1209,16 +1207,16 @@ Meta-kernel file \``sscpnt.tm’’: ) \begintext -Step-6: \``Spacecraft Velocity’’ +Step-6: "Spacecraft Velocity" ================================ -\``Spacecraft Velocity’’ Task Statement +"Spacecraft Velocity" Task Statement --------------------------------------- Extend the program from Step-5 to compute the spacecraft velocity with respect to Phoebe in the INMS frame. -\``Spacecraft Velocity’’ Hints +"Spacecraft Velocity" Hints ------------------------------ Compute velocity of the spacecraft with respect to Phoebe in some @@ -1232,7 +1230,7 @@ routine that compute necessary rotation and rotate vectors. Add calls to the routine(s), necessary variable declarations and output print statements to the program. -\``Spacecraft Velocity’’ Solution Steps +"Spacecraft Velocity" Solution Steps --------------------------------------- All kernels required for computations in this step are already being @@ -1242,14 +1240,14 @@ changed. The spacecraft velocity vector is the last three components of the state returned by spiceypy.spkezr. To compute velocity of CASSINI with respect to Phoebe in the J2000 inertial frame the spiceypy.spkezr arguments -should be set to ‘CASSINI’ (TARG), ‘PHOEBE’ (OBS), ‘J2000’ (REF) and -‘NONE’ (ABCORR). +should be set to 'CASSINI' (TARG), 'PHOEBE' (OBS), 'J2000' (REF) and +'NONE' (ABCORR). The computed velocity vector has to be rotated from the J2000 frame to the instrument frame. The spiceypy.pxform routine used in the previous step can be used to compute the rotation matrix needed for that. In this -case the frame name arguments should be set to ‘J2000’ (FROM) and -‘CASSINI_INMS’ (TO). +case the frame name arguments should be set to 'J2000' (FROM) and +'CASSINI_INMS' (TO). As in the previous step the difference vector should be then multiplied by this rotation matrix using the spiceypy.mxv routine. After applying @@ -1276,7 +1274,7 @@ Putting it all together, we get: scvdir = spiceypy.mxv(j2imat, scvdir) scvdir = spiceypy.vhat(scvdir) -When you execute the script, \``scvel’’, it produces the following +When you execute the script, "scvel", it produces the following output: :: @@ -1305,12 +1303,12 @@ output: SCVDIR(Z) = 0.870413 Note that computing the spacecraft velocity in the instrument frame by a -single call to spiceypy.spkezr by specifying ‘CASSINI_INMS’ in the -\`ref’ argument returns an incorrect result. Such computation will take +single call to spiceypy.spkezr by specifying 'CASSINI_INMS' in the +\`ref' argument returns an incorrect result. Such computation will take into account the spacecraft angular velocity from the CK files, which should not be considered in this case. -``Spacecraft Velocity'' Code Program``\ scvel.py’’: +"Spacecraft Velocity" Code Program" scvel.py": --------------------------------------------------- :: @@ -1415,7 +1413,7 @@ should not be considered in this case. if __name__ == '__main__': scvel() -Meta-kernel file \``scvel.tm’’: +Meta-kernel file "scvel.tm": :: diff --git a/docs/installation.rst b/docs/installation.rst index 7f588986..23696e85 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -42,7 +42,7 @@ verified that SpiceyPy is installed. A simple example program ------------------------ -This script calls the spiceypy function ‘tkvrsn’ and outputs the return +This script calls the spiceypy function 'tkvrsn' and outputs the return value. :: @@ -134,7 +134,7 @@ of OpenSSL, the easiest way to do this is to install python using homebrew, once can be installed to this new installation of python (IMHO this is the best option). If your python 3.6 distribution was installed from the packages available at python.org an included command -``Install Certificates.command`` should be run before attempting to install SpiceyPy again. +"Install Certificates.command" should be run before attempting to install SpiceyPy again. That command installs the certifi package that can also be install using pip. Alternatively, installing an anaconda or miniconda diff --git a/docs/other_stuff.rst b/docs/other_stuff.rst index da158bec..c726999b 100644 --- a/docs/other_stuff.rst +++ b/docs/other_stuff.rst @@ -3,7 +3,7 @@ Other Stuff (Python) November 20, 2017 -The extensive scope of the SpiceyPy system’s functionality includes +The extensive scope of the SpiceyPy system's functionality includes features the average user may not expect or appreciate, features NAIF refers to as “Other Stuff.” This workbook includes a set of lessons to introduce the beginning to moderate user to such features. @@ -64,7 +64,7 @@ These tutorials are available from the NAIF ftp server at JPL: Required Readings The Required Reading documents are provided with the Toolkit and are -located under the \``cspice/doc’’ directory in the CSPICE Toolkit +located under the "cspice/doc" directory in the CSPICE Toolkit installation tree. :: @@ -80,7 +80,7 @@ installation tree. The Permuted Index Another useful document distributed with the Toolkit is the permuted -index. This is located under the \``cspice/doc’’ directory in the C +index. This is located under the "cspice/doc" directory in the C installation tree. This text document provides a simple mechanism by which users can @@ -89,10 +89,8 @@ as the names of the source files that contain these functions. SpiceyPy API Documentation -A SpiceyPy function’s parameters specification is available using the -built-in Python help system. A more detailed specification of the API -can be found in the CSPICE HTML API documentation page located under -\``cspice/doc/html/cspice’’. +A SpiceyPy function's parameters specification is available using the +built-in Python help system. For example, the Python help function @@ -101,11 +99,11 @@ For example, the Python help function >>> import spiceypy >>> help(spiceypy.str2et) -describes of the str2et function’s parameters, while the document +describes of the str2et function's parameters, while the document :: - cspice/doc/html/cspice/str2et_c.html + https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html describes extensively the str2et functionality. @@ -134,7 +132,7 @@ SpiceyPy Modules Used This section provides a complete list of the functions and kernels that are suggested for usage in each of the exercises in this lesson. (You -may wish to not look at this list unless/until you \``get stuck’’ while +may wish to not look at this list unless/until you "get stuck" while working on your own.) :: @@ -188,7 +186,7 @@ working on your own.) spiceypy.halfpi Use the Python built-in help system on the various functions listed -above for the API parameters’ description, and refer to the headers of +above for the API parameters' description, and refer to the headers of their corresponding CSPICE versions for detailed interface specifications. @@ -213,7 +211,7 @@ needing information concerning SPICE are: Required Reading and Users Guides -NAIF Required Reading (*.req) documents introduce the functionality of +NAIF Required Reading (\*.req) documents introduce the functionality of particular SpiceyPy subsystems: :: @@ -245,7 +243,7 @@ particular SpiceyPy subsystems: time.req windows.req -NAIF Users Guides (*.ug) describe the proper use of particular SpiceyPy +NAIF Users Guides (\*.ug) describe the proper use of particular SpiceyPy tools: :: @@ -273,7 +271,7 @@ tools: toxfr.ug version.ug -These text documents exist in the ‘doc’ directory of the main CSPICE +These text documents exist in the 'doc' directory of the main CSPICE Toolkit directory: :: @@ -346,19 +344,19 @@ A header consists of several marked sections: -- Version: A list of edits and the authors of those edits made to the routine since initial delivery to the SpiceyPy system. -The source code for SpiceyPy products is stored in ‘src’ sub-directory +The source code for SpiceyPy products is stored in 'src' sub-directory of the main SpiceyPy directory: API Documentation -The SpiceyPy package is documented in \``readthedocs’’ website: +The SpiceyPy package is documented in "readthedocs" website: :: https://spiceypy.readthedocs.io/en/master/index.html Each API documentation page is in large part copied from the -``Abstract'' and``\ Brief_I/O’’ sections of the corresponding CSPICE +"Abstract" and" Brief_I/O" sections of the corresponding CSPICE function documentation. Each API page includes a link to the API documentation for the CSPICE routine called by the SpiceyPy interface. @@ -491,13 +489,13 @@ Time assignments. TIME_VAL = @31-JAN-2003-12:34:56.798 TIME_VEC = ( @01-DEC-2004, @15-MAR-2004 ) -The at-sign character ‘@’ indicates a time string. The pool subsystem +The at-sign character '@' indicates a time string. The pool subsystem converts the strings to double precision TDB (a numeric value). Please note, the time strings must not contain embedded blanks. WARNING - a TDB string is not the same as a UTC string. -The above examples depict direct assignments via the ‘=’ operator. The -kernel pool also permits incremental assignments via the ‘+=’ operator. +The above examples depict direct assignments via the '=' operator. The +kernel pool also permits incremental assignments via the '+=' operator. Please refer to the kernels required reading, kernel.req, for additional information. @@ -703,7 +701,7 @@ assigned variable names. Learning Goals -------------- -The lesson demonstrates the SpiceyPy system’s facility to retrieve +The lesson demonstrates the SpiceyPy system's facility to retrieve different types of data (string, numeric, scalar, array) from the kernel pool. @@ -1175,7 +1173,7 @@ Code Solution Run the code example -Input “Feb 3 2002 TDB” to calculate the Moon’s position. (the ‘TDB’ tag +Input “Feb 3 2002 TDB” to calculate the Moon's position. (the 'TDB' tag indicates a Barycentric Dynamical Time value). :: @@ -1451,7 +1449,7 @@ Lesson 5: Error Handling Task Statement -------------- -Write an interactive program to return a state vector based on a user’s +Write an interactive program to return a state vector based on a user's input. Code the program with the capability to recover from user input mistakes, inform the user of the mistake, then continue to run. @@ -1573,9 +1571,9 @@ Run the code example Now run the code with various inputs to observe behavior. Begin the run using known astronomical bodies, e.g. “Moon”, “Mars”, “Pluto barycenter” and “Puck”. Recall the SpiceyPy default units are kilometers, kilometers -per second, kilograms, and seconds. The ‘R’ marker identifies the -(X,Y,Z) position of the body in kilometers, the ‘V’ marker identifies -the velocity of the body in kilometers per second, and the ‘LT’ marker +per second, kilograms, and seconds. The 'R' marker identifies the +(X,Y,Z) position of the body in kilometers, the 'V' marker identifies +the velocity of the body in kilometers per second, and the 'LT' marker identifies the one-way light time between the bodies at the requested evaluation time. @@ -1620,7 +1618,7 @@ evaluation time. Perplexing. What happened? The kernel files named in meta.tm did not include ephemeris data for -Puck. When the SPK subsystem tried to evaluate Puck’s position, the +Puck. When the SPK subsystem tried to evaluate Puck's position, the evaluation failed due to lack of data, so an error signaled. The above error signifies an absence of state information at ephemeris @@ -1652,7 +1650,7 @@ Try another look-up, this time for “Casper” Target: An easy to understand error. The SPICE system does not contain -information on a body named ‘Casper.’ +information on a body named 'Casper.' Another look-up, this time, “Venus”. @@ -1690,10 +1688,10 @@ an interface to the underlying CSPICE cell structure. A user should create cells by use of the appropriate SpiceyPy calls. NAIF recommends against manual creation of cells. -A ‘window’ is a type of cell containing ordered, double precision values +A 'window' is a type of cell containing ordered, double precision values describing a collection of zero or more intervals. -We define an interval, ‘i’, as all double precision values bounded by +We define an interval, 'i', as all double precision values bounded by and including an ordered pair of numbers, :: @@ -1867,9 +1865,9 @@ Code Solution Run the code example -The output window has the name \`sched’ (schedule). +The output window has the name \`sched' (schedule). -Output the amount of data held in \`sched’ compared to the maximum +Output the amount of data held in \`sched' compared to the maximum possible amount. :: @@ -1886,7 +1884,7 @@ of a proper phase angle. 1 2003 JAN 05 12:00:00.000 2003 JAN 05 12:45:00.000 2 2003 JAN 06 00:30:00.000 2003 JAN 06 02:18:01.000 -Finally, an analysis of the \`sched’ data. The measure of an interval +Finally, an analysis of the \`sched' data. The measure of an interval [a,b] (a <= b) equals b-a. Real values output in units of seconds. :: diff --git a/docs/remote_sensing.rst b/docs/remote_sensing.rst index c72639d4..9c3c4b27 100644 --- a/docs/remote_sensing.rst +++ b/docs/remote_sensing.rst @@ -26,7 +26,7 @@ often contain comprehensive descriptions of the frames, instrument FOVs, etc. Since both the FK and IK are text kernels, the information provided in them can be viewed using any text editor, while the meta information provided in binary kernels—SPKs and CKs—can be viewed using -``commnt'' or``\ spacit’‘utility programs located in \``cspice/exe’’ of +"commnt" or" spacit"utility programs located in "cspice/exe" of Toolkit installation tree. Tutorials @@ -56,7 +56,7 @@ These tutorials are available from the NAIF ftp server at JPL: Required Readings The Required Reading documents are provided with the Toolkit and are -located under the \``cspice/doc’’ directory in the CSPICE Toolkit +located under the "cspice/doc" directory in the CSPICE Toolkit installation tree. :: @@ -75,7 +75,7 @@ installation tree. The Permuted Index Another useful document distributed with the Toolkit is the permuted -index. This is located under the \``cspice/doc’’ directory in the C +index. This is located under the "cspice/doc" directory in the C installation tree. This text document provides a simple mechanism by which users can @@ -84,10 +84,8 @@ as the names of the source files that contain these functions. SpiceyPy API Documentation -A SpiceyPy function’s parameters specification is available using the -built-in Python help system. A more detailed specification of the API -can be found in the CSPICE HTML API documentation page located under -\``cspice/doc/html/cspice’’. +A SpiceyPy function's parameters specification is available using the +built-in Python help system. For example, the Python help function @@ -96,11 +94,11 @@ For example, the Python help function >>> import spiceypy >>> help(spiceypy.str2et) -describes of the str2et function’s parameters, while the document +describes of the str2et function's parameters, while the document :: - cspice/doc/html/cspice/str2et_c.html + https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html describes extensively the str2et functionality. @@ -151,7 +149,7 @@ SpiceyPy Modules Used This section provides a complete list of the functions and kernels that are suggested for usage in each of the exercises in this lesson. (You -may wish to not look at this list unless/until you \``get stuck’’ while +may wish to not look at this list unless/until you "get stuck" while working on your own.) :: @@ -211,7 +209,7 @@ working on your own.) (*) Additional APIs and kernels used in Extra Credit tasks. Use the Python built-in help system on the various functions listed -above for the API parameters’ description, and refer to the headers of +above for the API parameters' description, and refer to the headers of their corresponding CSPICE versions for detailed interface specifications. @@ -266,10 +264,10 @@ steps: You may find it useful to consult the permuted index, the headers of various source modules, and the -``Time Required Reading'' (time.req) and``\ SCLK Required Reading’’ +"Time Required Reading" (time.req) and" SCLK Required Reading" (sclk.req) documents. -When completing the \``calendar format’’ step above, consider using one +When completing the "calendar format" step above, consider using one of two possible methods: spiceypy.etcal or spiceypy.timout. Solution @@ -278,14 +276,14 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘convtm.tm’. Its contents follow: +'convtm.tm'. Its contents follow: :: KPL/MK - This is the meta-kernel used in the solution of the ``Time - Conversion'' task in the Remote Sensing Hands On Lesson. + This is the meta-kernel used in the solution of the "Time + Conversion" task in the Remote Sensing Hands On Lesson. The names and contents of the kernels referenced by this meta-kernel are as follows: @@ -383,12 +381,12 @@ Execute the program: Extra Credit ------------ -In this \``extra credit’’ section you will be presented with more +In this "extra credit" section you will be presented with more complex tasks, aimed at improving your understanding of time conversions, the Toolkit routines that deal with them, and some common errors that may happen during the execution of these conversions. -These \``extra credit’’ tasks are provided as task statements, and +These "extra credit" tasks are provided as task statements, and unlike the regular tasks, no approach or solution source code is provided. In the next section, you will find the numeric solutions (when applicable) and answers to the questions asked in these tasks. @@ -478,7 +476,7 @@ Solutions and answers descriptive message and a expanded form of this short message where more details about the error are provided. If this error message is not sufficient for you to understand what has - happened, you could go to the ``Exceptions'' section in the + happened, you could go to the "Exceptions" section in the SPICELIB or CSPICE headers of the function that has triggered the error and find out more information about the possible causes. @@ -524,8 +522,8 @@ Solutions and answers 4. The first thing you need to do is to find out what the NAIF ID is for the CASSINI ISS NAC camera. In order to do so, examine - the ISS instrument kernel listed above and look for the ``NAIF - ID Code to Name Mapping'' and there, for the NAIF ID given to + the ISS instrument kernel listed above and look for the "NAIF + ID Code to Name Mapping" and there, for the NAIF ID given to CASSINI_ISS_NAC (which is -82360). Then replace in your code the SCLK ID -82 with -82360. After executing the program using the original meta-kernel, you will be getting the same error as @@ -598,7 +596,7 @@ Learning Goals Understand the anatomy of an spiceypy.spkezr call. Discover the difference between spiceypy.spkezr and spiceypy.spkpos. Familiarity with -the Toolkit utility \``brief’’. Exposure to unit conversion with +the Toolkit utility "brief". Exposure to unit conversion with SpiceyPy. .. _approach-1: @@ -639,14 +637,14 @@ steps: -- Convert the distance in kilometers into AU. You may find it useful to consult the permuted index, the headers of -various source modules, and the \``SPK Required Reading’’ (spk.req) +various source modules, and the "SPK Required Reading" (spk.req) document. -When deciding which SPK files to load, the Toolkit utility \``brief’’ +When deciding which SPK files to load, the Toolkit utility "brief" may be of some use. -``brief'' is located in the``\ cspice/exe’‘directory for C toolkits. -Consult its user’s guide available in \``cspice/doc/brief.ug’’ for +"brief" is located in the" cspice/exe"directory for C toolkits. +Consult its user's guide available in "cspice/doc/brief.ug" for details. .. _solution-1: @@ -657,14 +655,14 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘getsta.tm’. Its contents follow: +'getsta.tm'. Its contents follow: :: KPL/MK This is the meta-kernel used in the solution of the - ``Obtaining Target States and Positions'' task in the + "Obtaining Target States and Positions" task in the Remote Sensing Hands On Lesson. The names and contents of the kernels referenced by this @@ -853,14 +851,14 @@ Execute the program: Extra Credit ------------ -In this \``extra credit’’ section you will be presented with more +In this "extra credit" section you will be presented with more complex tasks, aimed at improving your understanding of state computations, particularly the application of the different light time and stellar aberration corrections available in the spiceypy.spkezr function, and some common errors that may happen when computing these states. -These \``extra credit’’ tasks are provided as task statements, and +These "extra credit" tasks are provided as task statements, and unlike the regular tasks, no approach or solution source code is provided. In the next section, you will find the numeric solutions (when applicable) and answers to the questions asked in these tasks. @@ -932,11 +930,11 @@ Solutions and answers the state of the spacecraft relative to the Solar System Barycenter because the SPK data needed to compute geometric states of Saturn Barycenter relative to the Solar System - barycenter are no longer loaded. Run ``brief'' on the SPKs used + barycenter are no longer loaded. Run "brief" on the SPKs used in the original task to find out which ephemeris objects are available from those kernels. If you want to find out what is the 'center of motion' for the ephemeris object(s) included in - an SPK, use the -c option when running ``brief'': + an SPK, use the -c option when running "brief": BRIEF -- Version 4.0.0, September 8, 2010 -- Toolkit Version N0066 @@ -1077,7 +1075,7 @@ and displays the following at the epoch of interest: The HGA boresight direction is provided by the kernel variable TKFRAME_-82101_BORESIGHT, which is defined in the Cassini frame - kernel cited above in the section ``Kernels Used.'' In this + kernel cited above in the section "Kernels Used." In this kernel, the HGA boresight vector is expressed relative to the CASSINI_HGA reference frame. @@ -1141,7 +1139,7 @@ steps: HINT: Several of the steps above may be compressed into a single step using SpiceyPy functions with which you are already familiar. The -\``long way’’ presented above is intended to facilitate the introduction +"long way" presented above is intended to facilitate the introduction of the functions spiceypy.pxform and spiceypy.sxform. You may find it useful to consult the permuted index, the headers of @@ -1169,14 +1167,14 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘xform.tm’. Its contents follow: +'xform.tm'. Its contents follow: :: KPL/MK - This is the meta-kernel used in the solution of the ``Spacecraft - Orientation and Reference Frames'' task in the Remote Sensing + This is the meta-kernel used in the solution of the "Spacecraft + Orientation and Reference Frames" task in the Remote Sensing Hands On Lesson. The names and contents of the kernels referenced by this @@ -1429,12 +1427,12 @@ Execute the program: Extra Credit ------------ -In this \``extra credit’’ section you will be presented with more +In this "extra credit" section you will be presented with more complex tasks, aimed at improving your understanding of frame transformations, and some common errors that may happen when computing them. -These \``extra credit’’ tasks are provided as task statements, and +These "extra credit" tasks are provided as task statements, and unlike the regular tasks, no approach or solution source code is provided. In the next section, you will find the numeric solutions (when applicable) and answers to the questions asked in these tasks. @@ -1443,8 +1441,8 @@ Task statements and questions :: - 1. Run the original program using the input UTC time ``2004 jun 11 - 18:25:00''. Explain what happens. + 1. Run the original program using the input UTC time "2004 jun 11 + 18:25:00". Explain what happens. 2. Compute the angular separation between the apparent position of the Sun as seen from CASSINI and the nominal boresight of the @@ -1491,7 +1489,7 @@ Solutions and answers indicates that there are not sufficient data to perform the transformation from the CASSINI_HGA frame to J2000 at the requested epoch. If you summarize the CASSINI spacecraft CK - using the ``ckbrief'' utility program with the -dump option + using the "ckbrief" utility program with the -dump option (display interpolation intervals boundaries) you will find that the CK contains gaps within its segment: @@ -1626,14 +1624,14 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘subpts.tm’. Its contents follow: +'subpts.tm'. Its contents follow: :: KPL/MK This is the meta-kernel used in the solution of the - ``Computing Sub-spacecraft and Sub-solar Points'' task + "Computing Sub-spacecraft and Sub-solar Points" task in the Remote Sensing Hands On Lesson. The names and contents of the kernels referenced by this @@ -1760,7 +1758,7 @@ A sample solution to the problem follows: # # End of computation block for "method" # - print( '' ) + print( " ) spiceypy.unload( METAKR ) @@ -1810,11 +1808,11 @@ Execute the program: Extra Credit ------------ -In this \``extra credit’’ section you will be presented with more +In this "extra credit" section you will be presented with more complex tasks, aimed at improving your understanding of spiceypy.subpnt and spiceypy.subslr functions. -These \``extra credit’’ tasks are provided as task statements, and +These "extra credit" tasks are provided as task statements, and unlike the regular tasks, no approach or solution source code is provided. In the next section, you will find the numeric solutions (when applicable) and answers to the questions asked in these tasks. @@ -1825,12 +1823,12 @@ Task statements and questions 1. Recompute the apparent sub-solar point on Phoebe as seen from CASSINI in the body fixed frame IAU_PHOEBE in kilometers using - the 'Intercept/ellipsoid' method at ``2004 jun 11 19:32:00''. + the 'Intercept/ellipsoid' method at "2004 jun 11 19:32:00". Explain the differences. 2. Compute the geometric sub-spacecraft point of CASSINI on Phoebe in the body fixed frame IAU_PHOEBE in kilometers using the - 'Near point/ellipsoid' method at ``2004 jun 11 19:32:00''. + 'Near point/ellipsoid' method at "2004 jun 11 19:32:00". 3. Transform the sub-spacecraft Cartesian coordinates obtained in the previous task to planetocentric and planetographic @@ -1847,9 +1845,9 @@ Solutions and answers :: 1. The differences observed are due to the computation method. The - ``Intercept/ellipsoid'' method defines the sub-solar point as + "Intercept/ellipsoid" method defines the sub-solar point as the target surface intercept of the line containing the Sun and - the target's center, while the ``Near point/ellipsoid'' method + the target's center, while the "Near point/ellipsoid" method defines the sub-solar point as the the nearest point on the target relative to the Sun. Since Phoebe is not spherical, these two points are not the same: @@ -1869,8 +1867,8 @@ Solutions and answers Z = -24.871 2. The geometric sub-spacecraft point of CASSINI on Phoebe in the - body fixed frame IAU_PHOEBE in kilometers at ``2004 jun 11 - 19:32:00'' UTC epoch is: + body fixed frame IAU_PHOEBE in kilometers at "2004 jun 11 + 19:32:00" UTC epoch is: Geometric sub-spacecraft point of CASSINI on Phoebe in the IAU_PHOEBE frame using the 'Near Point: ellipsoid' method @@ -1880,7 +1878,7 @@ Solutions and answers Z = 7.384 3. The sub-spacecraft point of CASSINI on Phoebe in planetocentric - and planetographic coordinates at ``2004 jun 11 19:32:00'' UTC + and planetographic coordinates at "2004 jun 11 19:32:00" UTC epoch is: Planetocentric coordinates of the CASSINI @@ -1896,7 +1894,7 @@ Solutions and answers ALT = -0.831 The planetocentric and planetographic longitudes are different - (``graphic'' = 360 - ``centric'') because planetographic + ("graphic" = 360 - "centric") because planetographic longitudes on Phoebe are measured positive west as defined by Phoebe's rotation direction. @@ -1928,8 +1926,8 @@ Task Statement Write a program that prompts the user for an input UTC time string and, for that time, computes the intersection of the CASSINI ISS NAC camera boresight and field of view (FOV) boundary vectors with the surface of -Phoebe. Compute each intercept twice: once with Phoebe’s shape modeled -as an ellipsoid, and once with Phoebe’s shape modeled by DSK data. The +Phoebe. Compute each intercept twice: once with Phoebe's shape modeled +as an ellipsoid, and once with Phoebe's shape modeled by DSK data. The program presents each point of intersection as :: @@ -2030,7 +2028,7 @@ Finally It may be useful to consult the CASSINI ISS instrument kernel to determine the name of the NAC camera as well as its configuration. This exercise may make use of some of the concepts and (loosely) code from -the \``Spacecraft Orientation and Reference Frames’’ task. +the "Spacecraft Orientation and Reference Frames" task. .. _solution-4: @@ -2040,14 +2038,14 @@ Solution Solution Meta-Kernel The meta-kernel we created for the solution to this exercise is named -‘fovint.tm’. Its contents follow: +'fovint.tm'. Its contents follow: :: KPL/MK This is the meta-kernel used in the solution of the - ``Intersecting Vectors with a Triaxial Ellipsoid'' task + "Intersecting Vectors with a Triaxial Ellipsoid" task in the Remote Sensing Hands On Lesson. The names and contents of the kernels referenced by this @@ -2303,7 +2301,7 @@ A sample solution to the problem follows: # # End of SpiceyError try-catch block. # - print( '' ) + print( " ) # # End of target shape model loop. # @@ -2497,4 +2495,4 @@ Execute the program: Extra Credit ------------ -There are no \``extra credit’’ tasks for this step of the lesson. +There are no "extra credit" tasks for this step of the lesson. From 42a78cb49f4e9a2e5b0e03a672aba2f594a58a46 Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Thu, 23 Aug 2018 09:56:38 -0400 Subject: [PATCH 03/11] more doc fixes --- docs/lessonindex.rst | 2 +- spiceypy/spiceypy.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/lessonindex.rst b/docs/lessonindex.rst index 7ed2de11..18b78a79 100644 --- a/docs/lessonindex.rst +++ b/docs/lessonindex.rst @@ -14,7 +14,7 @@ Contents: basics remote_sensing - event_finging + event_finding insitu_sensing binary_pck other_stuff diff --git a/spiceypy/spiceypy.py b/spiceypy/spiceypy.py index d0986cbd..36066bda 100644 --- a/spiceypy/spiceypy.py +++ b/spiceypy/spiceypy.py @@ -2274,8 +2274,8 @@ def dasrfr(handle, lenout=_default_len_out): :type handle: int :param lenout: length of output strs :type lenout: str - :return: ID word, DAS internal file name, Number of reserved records in file, - Number of characters in use in reserved rec. area, Number of comment records in file, + :return: ID word, DAS internal file name, Number of reserved records in file, \ + Number of characters in use in reserved rec. area, Number of comment records in file, \ Number of characters in use in comment area. :rtype: tuple """ @@ -6477,9 +6477,9 @@ def gfudb(udfuns, udfunb, step, cnfine, result): https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/gfudb_c.html - :param udfuns: Name of the routine that computes a scalar quantity of interest corresponding to an `et'. + :param udfuns: Name of the routine that computes a scalar quantity of interest corresponding to an 'et'. :type udfuns: ctypes.CFunctionType - :param udfunb: Name of the routine returning the boolean value corresponding to an `et'. + :param udfunb: Name of the routine returning the boolean value corresponding to an 'et'. :type udfunb: ctypes.CFunctionType :param step: Step size used for locating extrema and roots. :type step: float From 3294d0017820bf3c99b1867d5aa6ce7f71481b82 Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Fri, 24 Aug 2018 13:34:23 -0400 Subject: [PATCH 04/11] replacing some function links to sphinx compatable links --- docs/insitu_sensing.rst | 17 ++++++++--------- docs/lessonindex.rst | 2 +- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/insitu_sensing.rst b/docs/insitu_sensing.rst index 1e07542b..9dd831dd 100644 --- a/docs/insitu_sensing.rst +++ b/docs/insitu_sensing.rst @@ -264,7 +264,7 @@ simply adding more kernels to the list in KERNEL_TO_LOAD without changing the program code will accomplish that. The highest level SpiceyPy time routine converting UTC to ET is -spiceypy.str2et ("cspice/src/cspice/str2et_c.c"). +spiceypy.str2et :py:meth:`spiceypy.spiceypy.str2et` . It has two arguments – input time string representing UTC in a variety of formats (see spiceypy.str2et header's section "Particulars" for @@ -409,7 +409,7 @@ variable: \begintext The highest level SpiceyPy routine converting SCLK to ET is -spiceypy.scs2e ("cspice/src/cspice/scs2e_c.c"). +spiceypy.scs2e :py:meth:`spiceypy.spiceypy.scs2e` . It has three arguments – NAIF ID for CASSINI s/c (-82 as described by "naif_ids.req" document), input time string representing CASSINI @@ -569,7 +569,7 @@ the program: \begintext The highest level SpiceyPy routine computing states is spiceypy.spkezr -("cspice/src/cspice/spkezr_c.c"). +:py:meth:`spiceypy.spiceypy.spkezr` . We are interested in computing CASSINI position and velocity with respect to the Sun, therefore the target and observer names should be @@ -582,7 +582,7 @@ in which the state should be computed is 'ECLIPJ2000' (see Since we need only the geometric position, the \`abcorr' argument of the routine should be set to 'NONE' (see aberration correction discussion in -the ("cspice/src/cspice/spkezr_c.c"). +the :py:meth:`spiceypy.spiceypy.spkezr` . Putting it all together, we get: @@ -1009,28 +1009,27 @@ file name added to it, the updated meta-kernel will look like this: The sub-spacecraft point Cartesian vector can be converted to planetocentric radius, longitude and latitude using the spiceypy.reclat -routine ("cspice/src/cspice/reclat_c.c"). +routine :py:meth:`spiceypy.spiceypy.reclat` . The vector from the spacecraft to the sub-spacecraft point returned by spiceypy.subpnt has to be rotated from the body-fixed frame to the instrument frame. The name of the routine that computes 3x3 matrices rotating vectors from one frame to another is spiceypy.pxform -("cspice/src/cspice/pxform_c.c"). +:py:meth:`spiceypy.spiceypy.pxform` . In our case the "from' argument should be set to 'IAU_PHOEBE' and the" to' argument should be set to 'CASSINI_INMS' The vector should be then multiplied by this matrix to rotate it to the -instrument frame. The spiceypy.mxv routine performs that function -("cspice/src/cspice/mxv_c.c") +instrument frame. The spiceypy.mxv routine performs that function :py:meth:`spiceypy.spiceypy.mxv` . After applying the rotation, normalize the resultant vector using the spiceypy.vhat function. For output the longitude and latitude angles returned by spiceypy.reclat in radians can be converted to degrees by multiplying by spiceypy.dpr -function ("cspice/src/cspice/dpr_c.c"). +function :py:meth:`spiceypy.spiceypy.dpr` . Putting it all together, we get: diff --git a/docs/lessonindex.rst b/docs/lessonindex.rst index 18b78a79..8ae626a0 100644 --- a/docs/lessonindex.rst +++ b/docs/lessonindex.rst @@ -10,7 +10,7 @@ files needed to complete the exercises and to obtain the full content naiflesson Contents: .. toctree:: - :maxdepth: 1 + :maxdepth: 0 basics remote_sensing From 1a1b6688e9a724abce600ed0c5d1966afb4280d7 Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Fri, 24 Aug 2018 13:59:33 -0400 Subject: [PATCH 05/11] fixing headers in naif docs, trying to remove redundant spiceypy dot in module --- docs/basics.rst | 8 ++++---- docs/binary_pck.rst | 4 ++-- docs/documentation.rst | 4 ++-- docs/event_finding.rst | 6 +++--- docs/insitu_sensing.rst | 32 ++++++++++++++++---------------- docs/other_stuff.rst | 16 ++++++++-------- docs/remote_sensing.rst | 10 +++++----- 7 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index 170060d3..877b53c2 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -37,7 +37,7 @@ explanitory error message. A simple example program ------------------------ -The following calls the SPICE function :py:meth:`spiceypy.spiceypy.tkvrsn` which outputs the version +The following calls the SPICE function :py:meth:`spiceypy.tkvrsn` which outputs the version of cspice that SpiceyPy is wrapping. .. code:: python @@ -64,7 +64,7 @@ and traceback (of spice calls). `Read the NAIF tutorial on exceptions here. Date: Sat, 25 Aug 2018 09:51:39 -0400 Subject: [PATCH 06/11] revert a thing --- docs/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/documentation.rst b/docs/documentation.rst index 0b121c04..d92390c9 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -4,7 +4,7 @@ SpiceyPy package spiceypy module ------------------------ -.. automodule:: spiceypy +.. automodule:: spiceypy.spiceypy :members: :undoc-members: :show-inheritance: From e563efe2c26a680ce803afdae87759f37cf89bfc Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Sat, 25 Aug 2018 13:25:04 -0400 Subject: [PATCH 07/11] fixing code blocks --- docs/basics.rst | 8 ++--- docs/binary_pck.rst | 34 ++++++++++----------- docs/insitu_sensing.rst | 66 ++++++++++++++++++++--------------------- docs/installation.rst | 4 +-- 4 files changed, 56 insertions(+), 56 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index 877b53c2..0b230e4f 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -37,7 +37,7 @@ explanitory error message. A simple example program ------------------------ -The following calls the SPICE function :py:meth:`spiceypy.tkvrsn` which outputs the version +The following calls the SPICE function :py:meth:`spiceypy.spiceypy.spiceypytkvrsn` which outputs the version of cspice that SpiceyPy is wrapping. .. code:: python @@ -64,7 +64,7 @@ and traceback (of spice calls). `Read the NAIF tutorial on exceptions here. python convrt.py UTC = 2004-06-11T19:32:00 @@ -299,7 +299,7 @@ output: Program "convrt.py": -:: +.. code-block:: python from __future__ import print_function import spiceypy @@ -323,7 +323,7 @@ Program "convrt.py": Meta-kernel file "convrt.tm": -:: +.. code-block:: text KPL/MK @@ -388,7 +388,7 @@ meta-kernel approach was used in the Step-1. The program will load the file if it will be added to the list of kernels in the KERNELS_TO_LOAD variable: -:: +.. code-block:: text KPL/MK @@ -409,14 +409,14 @@ variable: \begintext The highest level SpiceyPy routine converting SCLK to ET is -spiceypy.scs2e :py:meth:`spiceypy.scs2e` . +spiceypy.scs2e :py:meth:`spiceypy.spiceypy.scs2e` . It has three arguments – NAIF ID for CASSINI s/c (-82 as described by "naif_ids.req" document), input time string representing CASSINI SCLK, and output DP number of ET seconds past J2000. A call to spiceypy.str2et converting given SCLK to ET could look like this: -:: +.. code-block:: python scid = -82 sclk = '1465674964.105' @@ -442,7 +442,7 @@ output: Program "sclket.py": -:: +.. code-block:: python from __future__ import print_function import spiceypy @@ -473,7 +473,7 @@ Program "sclket.py": Meta-kernel file "sclket.tm": -:: +.. code-block:: text KPL/MK @@ -540,7 +540,7 @@ files are needed to support computation of the state of interest. The file names can be added to the meta-kernel to get them loaded into the program: -:: +.. code-block:: text KPL/MK @@ -569,7 +569,7 @@ the program: \begintext The highest level SpiceyPy routine computing states is spiceypy.spkezr -:py:meth:`spiceypy.spkezr` . +:py:meth:`spiceypy.spiceypy.spkezr` . We are interested in computing CASSINI position and velocity with respect to the Sun, therefore the target and observer names should be @@ -582,11 +582,11 @@ in which the state should be computed is 'ECLIPJ2000' (see Since we need only the geometric position, the \`abcorr' argument of the routine should be set to 'NONE' (see aberration correction discussion in -the :py:meth:`spiceypy.spkezr` . +the :py:meth:`spiceypy.spiceypy.spkezr` . Putting it all together, we get: -:: +.. code-block:: python target = 'CASSINI' frame = 'ECLIPJ2000' @@ -618,7 +618,7 @@ output: Program "getsta.py": -:: +.. code-block:: python from __future__ import print_function import spiceypy @@ -664,7 +664,7 @@ Program "getsta.py": Meta-kernel file "getsta.tm": -:: +.. code-block:: text KPL/MK @@ -734,7 +734,7 @@ to already loaded kernels to support computation of this direction. The file names can be added to the meta-kernel to get them loaded into the program: -:: +.. code-block:: text KPL/MK @@ -784,7 +784,7 @@ spiceypy.vhat function (https://spiceypy.readthedocs.io/en/master/documentation.html# spiceypy.vhat) Putting it all together, we get: -:: +.. code-block:: python target = 'SUN' frame = 'CASSINI_INMS' @@ -820,7 +820,7 @@ output: Program "soldir.py": -:: +.. code-block:: python from __future__ import print_function import spiceypy @@ -879,7 +879,7 @@ Program "soldir.py": Meta-kernel file "soldir.tm": -:: +.. code-block:: text KPL/MK @@ -972,7 +972,7 @@ PCK file containing Phoebe radii has to be loaded into the program (see for this computation are already being loaded by the program. With PCK file name added to it, the updated meta-kernel will look like this: -:: +.. code-block:: text KPL/MK @@ -1009,27 +1009,27 @@ file name added to it, the updated meta-kernel will look like this: The sub-spacecraft point Cartesian vector can be converted to planetocentric radius, longitude and latitude using the spiceypy.reclat -routine :py:meth:`spiceypy.reclat` . +routine :py:meth:`spiceypy.spiceypy.reclat` . The vector from the spacecraft to the sub-spacecraft point returned by spiceypy.subpnt has to be rotated from the body-fixed frame to the instrument frame. The name of the routine that computes 3x3 matrices rotating vectors from one frame to another is spiceypy.pxform -:py:meth:`spiceypy.pxform` . +:py:meth:`spiceypy.spiceypy.pxform` . In our case the "from' argument should be set to 'IAU_PHOEBE' and the" to' argument should be set to 'CASSINI_INMS' The vector should be then multiplied by this matrix to rotate it to the -instrument frame. The spiceypy.mxv routine performs that function :py:meth:`spiceypy.mxv` . +instrument frame. The spiceypy.mxv routine performs that function :py:meth:`spiceypy.spiceypy.mxv` . After applying the rotation, normalize the resultant vector using the spiceypy.vhat function. For output the longitude and latitude angles returned by spiceypy.reclat in radians can be converted to degrees by multiplying by spiceypy.dpr -function :py:meth:`spiceypy.dpr` . +function :py:meth:`spiceypy.spiceypy.dpr` . Putting it all together, we get: diff --git a/docs/installation.rst b/docs/installation.rst index 23696e85..13f0f795 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -45,7 +45,7 @@ A simple example program This script calls the spiceypy function 'tkvrsn' and outputs the return value. -:: +.. code-block:: python File tkvrsn.py @@ -95,7 +95,7 @@ parameters, the standard built-in function help() could be used: which produces -:: +.. code-block:: text Help on function tkvrsn in module spiceypy.spiceypy: From 42117913363201c8868df0f24753dfcdf0dd7b0d Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Sun, 26 Aug 2018 11:12:33 -0400 Subject: [PATCH 08/11] updated copyright, made change to import paths that shouldn't break anything... --- LICENSE | 2 +- docs/conf.py | 2 +- docs/event_finding.rst | 2 +- docs/other_stuff.rst | 34 +++++++++++++-------------- docs/remote_sensing.rst | 16 ++++++------- getspice.py | 2 +- setup.py | 2 +- spiceypy/__init__.py | 6 ++--- spiceypy/config.py | 2 +- spiceypy/spiceypy.py | 10 ++++---- spiceypy/tests/__init__.py | 2 +- spiceypy/tests/gettestkernels.py | 2 +- spiceypy/tests/test_gettestkernels.py | 2 +- spiceypy/tests/test_spiceerrors.py | 2 +- spiceypy/tests/test_support_types.py | 2 +- spiceypy/tests/test_wrapper.py | 2 +- spiceypy/utils/__init__.py | 2 +- spiceypy/utils/callbacks.py | 4 ++-- spiceypy/utils/libspicehelper.py | 6 ++--- spiceypy/utils/support_types.py | 4 ++-- 20 files changed, 53 insertions(+), 53 deletions(-) diff --git a/LICENSE b/LICENSE index 96deb274..fd520e6e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docs/conf.py b/docs/conf.py index 1fec9fe6..4f6e0778 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -285,7 +285,7 @@ def __getattr__(cls, name): epub_title = 'SpiceyPy' epub_author = 'Andrew Annex' epub_publisher = 'Andrew Annex' -epub_copyright = '2014-2017, Andrew Annex' +epub_copyright = '2014-2018, Andrew Annex' # The basename for the epub file. It defaults to the project name. #epub_basename = 'SpiceyPy' diff --git a/docs/event_finding.rst b/docs/event_finding.rst index 1383d92f..9f8aacda 100644 --- a/docs/event_finding.rst +++ b/docs/event_finding.rst @@ -567,7 +567,7 @@ Execute the program. The output is: Visibility or window stop time: 2004 MAY 06 00:00:00.000 (TDB) Find Times when Target is Visible ------------------------------- +---------------------------------- .. _task-statement-1: diff --git a/docs/other_stuff.rst b/docs/other_stuff.rst index 586f6640..3e21fe5e 100644 --- a/docs/other_stuff.rst +++ b/docs/other_stuff.rst @@ -413,7 +413,7 @@ and \begindata to mark information blocks within the text kernel. The -:raw-latex:`\begintext `tag specifies all text following the tag as +`\\begintext` tag specifies all text following the tag as comment information to be ignored by the subsystem. Things to know: @@ -501,7 +501,7 @@ Please refer to the kernels required reading, kernel.req, for additional information. Lesson 1: Kernel Management with the Kernel Subsystem ------------------------------- +----------------------------------------------------- Task Statement -------------- @@ -687,7 +687,7 @@ direct load of the kernel with a spiceypy.furnsh call. Lesson 2: The Kernel Pool ------------------------------ -.. _task-statement-1: +.. _task-statement-os-1: Task Statement -------------- @@ -696,7 +696,7 @@ Write a program to retrieve particular string and numeric text kernel variables, both scalars and arrays. Interrogate the kernel pool for assigned variable names. -.. _learning-goals-1: +.. _learning-goals-os-1: Learning Goals -------------- @@ -995,9 +995,9 @@ Related Routines subsystem. Lesson 3: Coordinate Conversions ------------------------------- +--------------------------------- -.. _task-statement-2: +.. _task-statement-os-2: Task Statement -------------- @@ -1007,7 +1007,7 @@ location to the other coordinate representations. Use the position of the Moon with respect to Earth in an inertial and non-inertial reference frame as the example vector. -.. _learning-goals-2: +.. _learning-goals-os-2: Learning Goals -------------- @@ -1287,9 +1287,9 @@ Related Routines -- spiceypy.georec, geodetic to rectangular Lesson 4: Advanced Time Manipulation Routines ------------------------------- +---------------------------------------------- -.. _task-statement-3: +.. _task-statement-os-3: Task Statement -------------- @@ -1299,7 +1299,7 @@ formatting of time strings for output. Formatting options include altering calendar representations of the time strings. Convert time-date strings between different SpiceyPy-supported formats. -.. _learning-goals-3: +.. _learning-goals-os-3: Learning Goals -------------- @@ -1444,7 +1444,7 @@ Run the code example Lesson 5: Error Handling ------------------------------ -.. _task-statement-4: +.. _task-statement-os-4: Task Statement -------------- @@ -1453,7 +1453,7 @@ Write an interactive program to return a state vector based on a user's input. Code the program with the capability to recover from user input mistakes, inform the user of the mistake, then continue to run. -.. _learning-goals-4: +.. _learning-goals-os-4: Learning Goals -------------- @@ -1677,7 +1677,7 @@ Given the times of line-of-sight for a vehicle from a ground station and the times for an acceptable Sun-station-vehicle phase angle, write a program to determine the time intervals common to both configurations. -.. _learning-goals-5: +.. _learning-goals-os-5: Learning Goals -------------- @@ -1936,9 +1936,9 @@ Related Routines -- spiceypy.wnunid calculates the union of two windows. Lesson 7: Utility and Constants Routines ------------------------------- +---------------------------------------- -.. _task-statement-5: +.. _task-statement-os-5: Task Statement -------------- @@ -1947,7 +1947,7 @@ Write an interactive program to convert values between various units. Demonstrate the flexibility of the unit conversion routine, the string equality function, and show the version ID function. -.. _learning-goals-6: +.. _learning-goals-os-6: Learning Goals -------------- @@ -2092,7 +2092,7 @@ in kilometers? To Units : km 42.16481 km -.. _task-statement-6: +.. _task-statement-os-6: Task Statement -------------- diff --git a/docs/remote_sensing.rst b/docs/remote_sensing.rst index be652f7b..5bb50dec 100644 --- a/docs/remote_sensing.rst +++ b/docs/remote_sensing.rst @@ -557,9 +557,9 @@ Solutions and answers UTC time from spacecraft clock: 2004-06-11T19:31:59.999 Obtaining Target States and Positions (getsta) ------------------------------- +---------------------------------------------- -.. _task-statement-1: +.. _task-statement-rs-1: Task Statement -------------- @@ -1052,9 +1052,9 @@ Solutions and answers Z = -510372252.747 Spacecraft Orientation and Reference Frames (xform) ------------------------------- +--------------------------------------------------- -.. _task-statement-2: +.. _task-statement-rs-2: Task Statement -------------- @@ -1548,9 +1548,9 @@ Solutions and answers since the angular separation is smaller than 90 degrees. Computing Sub-s/c and Sub-solar Points on an Ellipsoid and a DSK (subpts) ------------------------------- +------------------------------------------------------------------------- -.. _task-statement-3: +.. _task-statement-rs-3: Task Statement -------------- @@ -1916,9 +1916,9 @@ Solutions and answers for bodies with shapes modeled as triaxial ellipsoids. Intersecting Vectors with an Ellipsoid and a DSK (fovint) ------------------------------- +--------------------------------------------------------- -.. _task-statement-4: +.. _task-statement-rs-4: Task Statement -------------- diff --git a/getspice.py b/getspice.py index 481577cc..f1b98335 100644 --- a/getspice.py +++ b/getspice.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/setup.py b/setup.py index bffca161..23912705 100644 --- a/setup.py +++ b/setup.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/__init__.py b/spiceypy/__init__.py index 9e4fca7d..0142d038 100644 --- a/spiceypy/__init__.py +++ b/spiceypy/__init__.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -22,8 +22,8 @@ SOFTWARE. """ -from .spiceypy import * -from .utils import support_types +from spiceypy.spiceypy import * +from spiceypy.utils import support_types __author__ = 'AndrewAnnex' diff --git a/spiceypy/config.py b/spiceypy/config.py index 3cd02f66..0ee9d762 100644 --- a/spiceypy/config.py +++ b/spiceypy/config.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/spiceypy.py b/spiceypy/spiceypy.py index 36066bda..33457697 100644 --- a/spiceypy/spiceypy.py +++ b/spiceypy/spiceypy.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -23,10 +23,10 @@ """ import ctypes -from .utils import support_types as stypes -from .utils.libspicehelper import libspice -from . import config -from .utils.callbacks import SpiceUDFUNS, SpiceUDFUNB +from spiceypy.utils import support_types as stypes +from spiceypy.utils.libspicehelper import libspice +from spiceypy import config +from spiceypy.utils.callbacks import SpiceUDFUNS, SpiceUDFUNB import functools import numpy from contextlib import contextmanager diff --git a/spiceypy/tests/__init__.py b/spiceypy/tests/__init__.py index 7e82ebe8..baf956bd 100644 --- a/spiceypy/tests/__init__.py +++ b/spiceypy/tests/__init__.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/tests/gettestkernels.py b/spiceypy/tests/gettestkernels.py index e39777b9..bd4672c5 100644 --- a/spiceypy/tests/gettestkernels.py +++ b/spiceypy/tests/gettestkernels.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/tests/test_gettestkernels.py b/spiceypy/tests/test_gettestkernels.py index b38b31a1..a25638f1 100644 --- a/spiceypy/tests/test_gettestkernels.py +++ b/spiceypy/tests/test_gettestkernels.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/tests/test_spiceerrors.py b/spiceypy/tests/test_spiceerrors.py index f4e6795c..8a9d7cb2 100644 --- a/spiceypy/tests/test_spiceerrors.py +++ b/spiceypy/tests/test_spiceerrors.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/tests/test_support_types.py b/spiceypy/tests/test_support_types.py index 36838f3c..e229908d 100644 --- a/spiceypy/tests/test_support_types.py +++ b/spiceypy/tests/test_support_types.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/tests/test_wrapper.py b/spiceypy/tests/test_wrapper.py index baf4f54f..16dd61ca 100644 --- a/spiceypy/tests/test_wrapper.py +++ b/spiceypy/tests/test_wrapper.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/utils/__init__.py b/spiceypy/utils/__init__.py index 7e82ebe8..baf956bd 100644 --- a/spiceypy/utils/__init__.py +++ b/spiceypy/utils/__init__.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/spiceypy/utils/callbacks.py b/spiceypy/utils/callbacks.py index 8fde1b92..8b6ffdb7 100644 --- a/spiceypy/utils/callbacks.py +++ b/spiceypy/utils/callbacks.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -24,7 +24,7 @@ import functools from ctypes import c_int, c_double, c_char_p, POINTER, CFUNCTYPE, byref -from .support_types import SpiceCell +from spiceypy.utils.support_types import SpiceCell UDFUNS = CFUNCTYPE(None, c_double, POINTER(c_double)) UDFUNB = CFUNCTYPE(None, UDFUNS, c_double, POINTER(c_int)) diff --git a/spiceypy/utils/libspicehelper.py b/spiceypy/utils/libspicehelper.py index eeb3a898..ebcb8b4d 100644 --- a/spiceypy/utils/libspicehelper.py +++ b/spiceypy/utils/libspicehelper.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -25,8 +25,8 @@ from ctypes import CDLL, POINTER, c_int, c_double, c_char, c_char_p, c_void_p import os import platform -from . import support_types as stypes -from . import callbacks +from spiceypy.utils import support_types as stypes +from spiceypy.utils import callbacks host_OS = platform.system() sharedLib = "cspice.dll" if host_OS == "Windows" else "spice.so" diff --git a/spiceypy/utils/support_types.py b/spiceypy/utils/support_types.py index 1415a173..de056fb0 100644 --- a/spiceypy/utils/support_types.py +++ b/spiceypy/utils/support_types.py @@ -1,7 +1,7 @@ """ The MIT License (MIT) -Copyright (c) [2015-2017] [Andrew Annex] +Copyright (c) [2015-2018] [Andrew Annex] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -42,6 +42,7 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ +import six from ctypes import c_char_p, c_int, c_double,\ c_char, c_void_p, sizeof, \ @@ -49,7 +50,6 @@ string_at import numpy -import six from numpy import ctypeslib as numpc # Collection of supporting functions for wrapper functions __author__ = 'AndrewAnnex' From 69c05eb383b1759de38872cee230862775f40e82 Mon Sep 17 00:00:00 2001 From: AndrewAnnex Date: Sun, 26 Aug 2018 11:32:04 -0400 Subject: [PATCH 09/11] py27 didn't like my import changes reverting for now --- spiceypy/__init__.py | 4 ++-- spiceypy/spiceypy.py | 8 ++++---- spiceypy/utils/callbacks.py | 2 +- spiceypy/utils/libspicehelper.py | 4 ++-- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/spiceypy/__init__.py b/spiceypy/__init__.py index 0142d038..ec141be8 100644 --- a/spiceypy/__init__.py +++ b/spiceypy/__init__.py @@ -22,8 +22,8 @@ SOFTWARE. """ -from spiceypy.spiceypy import * -from spiceypy.utils import support_types +from .spiceypy import * +from .utils import support_types __author__ = 'AndrewAnnex' diff --git a/spiceypy/spiceypy.py b/spiceypy/spiceypy.py index 33457697..ea1eb0c4 100644 --- a/spiceypy/spiceypy.py +++ b/spiceypy/spiceypy.py @@ -23,10 +23,10 @@ """ import ctypes -from spiceypy.utils import support_types as stypes -from spiceypy.utils.libspicehelper import libspice -from spiceypy import config -from spiceypy.utils.callbacks import SpiceUDFUNS, SpiceUDFUNB +from .utils import support_types as stypes +from .utils.libspicehelper import libspice +from . import config +from .utils.callbacks import SpiceUDFUNS, SpiceUDFUNB import functools import numpy from contextlib import contextmanager diff --git a/spiceypy/utils/callbacks.py b/spiceypy/utils/callbacks.py index 8b6ffdb7..db360672 100644 --- a/spiceypy/utils/callbacks.py +++ b/spiceypy/utils/callbacks.py @@ -24,7 +24,7 @@ import functools from ctypes import c_int, c_double, c_char_p, POINTER, CFUNCTYPE, byref -from spiceypy.utils.support_types import SpiceCell +from .support_types import SpiceCell UDFUNS = CFUNCTYPE(None, c_double, POINTER(c_double)) UDFUNB = CFUNCTYPE(None, UDFUNS, c_double, POINTER(c_int)) diff --git a/spiceypy/utils/libspicehelper.py b/spiceypy/utils/libspicehelper.py index ebcb8b4d..a69326b0 100644 --- a/spiceypy/utils/libspicehelper.py +++ b/spiceypy/utils/libspicehelper.py @@ -25,8 +25,8 @@ from ctypes import CDLL, POINTER, c_int, c_double, c_char, c_char_p, c_void_p import os import platform -from spiceypy.utils import support_types as stypes -from spiceypy.utils import callbacks +from . import support_types as stypes +from . import callbacks host_OS = platform.system() sharedLib = "cspice.dll" if host_OS == "Windows" else "spice.so" From 4c87ffd33f326b2ffb6415f0b7f49eca5f770b36 Mon Sep 17 00:00:00 2001 From: Andrew Annex Date: Sun, 26 Aug 2018 18:31:45 -0400 Subject: [PATCH 10/11] Update basics.rst --- docs/basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/basics.rst b/docs/basics.rst index 0b230e4f..e73c14e7 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -37,7 +37,7 @@ explanitory error message. A simple example program ------------------------ -The following calls the SPICE function :py:meth:`spiceypy.spiceypy.spiceypytkvrsn` which outputs the version +The following calls the SPICE function :py:meth:`spiceypy.spiceypy.tkvrsn` which outputs the version of cspice that SpiceyPy is wrapping. .. code:: python From 9f557788134441edd1ee6a0a7be8acb7456d5c47 Mon Sep 17 00:00:00 2001 From: Andrew Annex Date: Sun, 26 Aug 2018 18:32:03 -0400 Subject: [PATCH 11/11] Update basics.rst --- docs/basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/basics.rst b/docs/basics.rst index e73c14e7..170060d3 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -64,7 +64,7 @@ and traceback (of spice calls). `Read the NAIF tutorial on exceptions here.