SpiceyPy Documentation Release 3.1.1 Andrew Annex Jul 17, 2020 CONTENTS 1 Installation 3 1.1 If you use anaconda/miniconda/conda run:...............................3 1.2 Offline installation............................................4 1.3 A simple example program.......................................4 1.4 SpiceyPy Documentation........................................5 2 Common Issues 7 2.1 SSL Alert Handshake Issue.......................................7 3 How to install from source (for bleeding edge updates)9 4 Cassini Position Example 11 5 Cells Explained 15 6 Exceptions in SpiceyPy 17 6.1 Exception Hierarchy Basics....................................... 17 6.2 Exception Contents............................................ 18 6.3 Not Found Errors............................................. 18 7 Lessons 21 7.1 Basics of SpiceyPy............................................ 21 7.1.1 Environment Set-up....................................... 21 7.1.2 Confirm SpiceyPy installation................................. 21 7.1.3 A simple example program................................... 21 7.2 Remote Sensing Hands-On Lesson, using CASSINI.......................... 22 7.2.1 Overview............................................ 22 7.2.2 References........................................... 22 7.2.3 Kernels Used.......................................... 24 7.2.4 SpiceyPy Modules Used.................................... 24 7.2.5 Time Conversion (convtm)................................... 25 7.2.6 Obtaining Target States and Positions (getsta)......................... 31 7.2.7 Spacecraft Orientation and Reference Frames (xform)..................... 39 7.2.8 Computing Sub-s/c and Sub-solar Points on an Ellipsoid and a DSK (subpts)........ 47 7.2.9 Intersecting Vectors with an Ellipsoid and a DSK (fovint)................... 53 7.3 Geometric Event Finding Hands-On Lesson, using MEX........................ 63 7.3.1 Overview............................................ 63 7.3.2 References........................................... 63 7.3.3 Kernels Used.......................................... 65 7.3.4 SpiceyPy Modules Used.................................... 65 7.3.5 Find View Periods....................................... 66 i 7.3.6 Find Times when Target is Visible............................... 72 7.3.7 Extra Credit........................................... 81 7.4 In-situ Sensing Hands-On Lesson, using CASSINI........................... 83 7.4.1 Overview............................................ 83 7.4.2 References........................................... 83 7.4.3 Kernels Used.......................................... 85 7.4.4 SpiceyPy Modules Used.................................... 85 7.4.5 Step-1: “UTC to ET”...................................... 86 7.4.6 Step-2: “SCLK to ET”..................................... 89 7.4.7 Step-3: “Spacecraft State”................................... 91 7.4.8 Step-4: “Sun Direction”.................................... 94 7.4.9 Step-5: “Sub-Spacecraft Point”................................. 97 7.4.10 Step-6: “Spacecraft Velocity”.................................. 102 7.5 Binary PCK Hands-On Lesson...................................... 106 7.5.1 Overview............................................ 106 7.5.2 References........................................... 106 7.5.3 Kernels Used.......................................... 108 7.5.4 SpiceyPy Modules Used.................................... 108 7.5.5 Moon rotation (mrotat)..................................... 109 7.5.6 Earth rotation (erotat)...................................... 114 7.6 Other Stuff (Python)........................................... 122 7.6.1 Overview............................................ 122 7.6.2 References........................................... 122 7.6.3 Kernels Used.......................................... 124 7.6.4 SpiceyPy Modules Used.................................... 124 7.6.5 NAIF Documentation...................................... 125 7.6.6 Text kernels........................................... 128 7.6.7 Lesson 1: Kernel Management with the Kernel Subsystem.................. 130 7.6.8 Lesson 2: The Kernel Pool................................... 133 7.6.9 Lesson 3: Coordinate Conversions............................... 138 7.6.10 Lesson 4: Advanced Time Manipulation Routines....................... 142 7.6.11 Lesson 5: Error Handling.................................... 145 7.6.12 Lesson 6: Windows, and Cells................................. 149 7.6.13 Lesson 7: Utility and Constants Routines........................... 153 8 SpiceyPy package 159 8.1 spiceypy module............................................. 159 8.2 spiceypy.utils.support_types module................................... 309 8.3 spiceypy.utils.callbacks module..................................... 315 8.4 spiceypy.utils.exceptions module.................................... 317 8.5 spiceypy.utils.libspice module...................................... 392 9 Indices and tables 393 Python Module Index 395 Index 397 ii SpiceyPy Documentation, Release 3.1.1 This is the documentation for SpiceyPy. The documentation for each function in the wrapper is in large part copied from the “Abstract” and “Brief_I/O” sections of the corresponding CSPICE function documentation. Each wrapper function has a link back to the corresponding original CSPICE function documentation hosted at the NAIF website. For more in-depth information about SPICE, please visit the NAIF website or click here to view the entire CSPICE documentation. The intent of the function doc-strings is to serve only as a quick reference to what the parameter’s expected types are for the purpose of getting started with the wrapper. As each function has a link to the CSPICE documentation for that function, more detailed explanations are deferred to the NAIF via those links. Contents: CONTENTS 1 SpiceyPy Documentation, Release 3.1.1 2 CONTENTS CHAPTER ONE INSTALLATION SpiceyPy is currently supported on Mac, Linux, FreeBSD, and Windows systems. If you are new to python, it is a good idea to read a bit about it first https://docs.python-guide.org. For new installations of python, it is encouraged to install and or update: pip, setuptools, wheel, and numpy first before installing SpiceyPy pip install-U pip setuptools wheel pip install-U numpy Then to install SpiceyPy, simply run: pip install spiceypy 1.1 If you use anaconda/miniconda/conda run: 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: pip list You should see spicepy in the output of this command. Or you can start a python interpreter and try importing SpiceyPy like so: import spiceypy # print out the toolkit version installed print(spiceypy.tkvrsn('TOOLKIT')) This should print out the toolkit version without any errors. You have now verified that SpiceyPy is installed. 3 SpiceyPy Documentation, Release 3.1.1 1.2 Offline installation If you need to install SpiceyPy without a network or if you have a prebuilt shared library at hand, you can override the default behaviour of SpiceyPy by using the CSPICE_SRC_DIR and CSPICE_SHARED_LIB environment variables respectively. For example, if you have downloaded SpiceyPy and the CSPICE toolkit, and extracted CSPICE to /tmp/cspice you can run: export CSPICE_SRC_DIR="/tmp/cspice" python setup.py install Or if you have a shared library of CSPICE located at /tmp/cspice.so, you can run: export CSPICE_SHARED_LIB="/tmp/cspice.so" python setup.py install Both examples above assume you have cloned the SpiceyPy repository and are running those commands within the project directory. 1.3 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 4 Chapter 1. Installation SpiceyPy Documentation, Release 3.1.1 1.4 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. https://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. 1.4. SpiceyPy Documentation 5 SpiceyPy Documentation, Release 3.1.1 6 Chapter