SPICE kernels
Hint
If you are having issues with loading spice kernels after following the guide on this page, check the list of common issues and solutions
Introduction
The core logic of PlanetMapper uses the SPICE system, which was developed by NASA’s Navigation and Ancillary Information Facility to provide detailed and accurate information about the positions and properties of Solar System bodies and spacecraft. This SPICE database is stored in a series of files called ‘SPICE kernels’ which must be downloaded for PlanetMapper to function.
Most useful SPICE kernels can be found at https://naif.jpl.nasa.gov/pub/naif/. Each individual SPICE kernel typically contains information about a specific object or set of objects (e.g. one kernel file may contain information about Jupiter and its moons, while another may contain information about a specific spacecraft). Therefore, you only need to download a small subset of the SPICE kernels.
If you already have the appropriate SPICE kernels saved to your computer, you can skip to the section on customising the kernel directory below.
Downloading SPICE kernels
To aid in downloading appropriate SPICE kernels, PlanetMapper contains a series of useful functions such as planetmapper.kernel_downloader.download_urls()
to download kernels from the NAIF database. These functions will automatically download the SPICE kernels to your computer where they can be used by PlanetMapper, so you only need to worry about downloading the kernels once, then PlanetMapper will be able to automatically find and load them in the future.
Note
By default, PlanetMapper will downloaded and search for kernels in a directory named spice_kernels
within your user directory. If you would like to customise this location (e.g. if you already have kernels saved elsewhere), follow the instructions in the section on customising the kernel directory below before downloading any kernels.
Required kernels
To download kernels which are required for virtually every SPICE calculation, run the following commands in Python:
from planetmapper.kernel_downloader import download_urls
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/')
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/')
This will automatically download a series of ‘leap second kernels’ and ‘planetary constant kernels’ to your computer. The function planetmapper.kernel_downloader.download_urls()
effectively replicates the file structure from the NAIF database to your local system. Therefore, the leap second kernels will be automatically downloaded to ~/spice_kernels/naif/generic_kernels/lsk/
and the planetary constant kernels will be downloaded to ~/spice_kernels/naif/generic_kernels/pck/
.
These required kernels are relatively small (~50KB for .../lsk
and ~50MB for .../pck
), so downloading them should be relatively fast. If you don’t want to use planetmapper.kernel_downloader.download_urls()
, you can instead manually browse and download files from https://naif.jpl.nasa.gov/pub/naif/ yourself.
Once you have downloaded these required kernels, you will also need to download some of the ephemeris kernels described below.
Planetary ephemeris kernels
Warning
Some SPICE ephemeris kernels can be very large (>1GB), so make sure you have enough free disk space when downloading.
The positions of solar system bodies (e.g. planets and moons) are contained in ephemeris kernels. The kernels are required for each body which you are observing, e.g. if you are using observations of Jupiter you will need to have a Jupiter kernel downloaded.
If you have enough disk space, you can easily download all the planet and moon kernels using:
# Note, you will also need to download the lsk and pck kernels as described above
from planetmapper.kernel_downloader import download_urls
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/')
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/')
These spk
kernels add up to ~30GB, so if you have limited disk space, you may want to instead download the specific kernels for the bodies you are interested in. Look at the summaries
and readme
text files at the top of the planets and satellites archive pages to see which specific files you want to download.
For example, if you are only interested in Jupiter and its moons, you could use:
# Note, you will also need to download the lsk and pck kernels as described above
# Note, the exact URLs in this example may not work if new kernel versions are published
from planetmapper.kernel_downloader import download_urls
# Locations of planetary system barycentres:
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de430.bsp')
# Locations of Jupiter and its major satellites:
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/jup365.bsp')
# Optionally download locations of smaller satellites of Jupiter:
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/jup344.bsp')
Similarly, if you are interested in Uranus, you could use:
# Note, you will also need to download the lsk and pck kernels as described above
# Note, the exact URLs in this example may not work if new kernel versions are published
from planetmapper.kernel_downloader import download_urls
# Locations of planetary system barycentres:
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de430.bsp')
# Locations of Uranus and its major satellites:
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/ura111.bsp')
# Optionally download locations of smaller satellites of Uranus:
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/ura115.bsp')
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/ura116.bsp')
Hint
The kernels for the locations of planets are actually located in the generic_kernels/spk/satellites directory, so even if you are only interested in the central planet, you will still need to download at least one kernel from the satellites directory. Search the aa_summaries.txt file for the planet(s) you are interested in to find the required kernel(s).
Spacecraft kernels
If you are using observations from a spacecraft, you will also need to download the ephemeris kernels describing the spacecraft’s position over time. For example, if you are using observations from the Hubble Space Telescope, you should run:
# Note, you will also need to download lsk, pck and spk kernels as described above
from planetmapper.kernel_downloader import download_urls
download_urls('https://naif.jpl.nasa.gov/pub/naif/HST/kernels/spk/')
The directory name for different missions can be found by searching the NAIF archive.
Small body kernels
The JPL Horizons system can be used to generate SPICE kernels for small bodies, such as asteroids and comets, which may not be available on the NAIF archive. Simply select Small-Body SPK File as the ephemeris type in the Horizons web application and download the generated SPK file. You should then place this file in your SPICE kernel directory, where it will automatically be loaded by PlanetMapper (see customising the kernel directory below). For more information about the JPL Horizons generated kernels, see the Horizons documentation.
Manually defining kernel variables for small bodies
For some bodies, the JPL Horizons generated kernels do not contain all the information needed to perform the SPICE calculations required by PlanetMapper. In these cases, you will need to manually create a text kernel file containing this required information, in addition to downloading the generated SPK file from JPL Horizons.
The following is an template for a text kernel file for Chiron, which will allow PlanetMapper to use JPL Horizons generated Chiron kernels. The placeholder values should be replaced with appropriate values for your target body, then the file should be saved in your kernel directory with a .tpc
file extension.
\begindata
NAIF_BODY_NAME += 'CHIRON'
NAIF_BODY_CODE += 20002060
FRAME_CHIRON_FIXED = 1234567
FRAME_1234567_NAME = 'CHIRON_FIXED'
FRAME_1234567_CLASS = 2
FRAME_1234567_CLASS_ID = 20002060
FRAME_1234567_CENTER = 20002060
BODY20002060_RADII = (XXX.XX XXX.XX XXX.XX)
BODY20002060_POLE_RA = (XXX.XX XXX.XX XXX.XX)
BODY20002060_POLE_DEC = (XXX.XX XXX.XX XXX.XX)
BODY20002060_PM = (XXX.XX XXX.XX XXX.XX)
\begintext
The
NAIF_BODY_
variables tell SPICE the name(s) that refer to the body with numeric ID 20002060 (more details). This allows you to call PlanetMapper with the name'CHIRON'
instead of the numeric ID. The numeric ID code for the target body will usually be in the filename of the JPL Horizons generated SPK file.The
FRAME_
variables define a new reference frame that is centred on Chiron (more details). This frame will then be used by PlanetMapper to define any Chiron-centred coordinates (e.g. longitude/latitude).The frame ID code,
1234567
, is arbitrary, but should not conflict with any other frame IDs that you are using. Values from 1400000 to 2000000 are recommended for public use.The
'CHIRON_FIXED'
name is also arbitrary, and should be passed to PlanetMapper when creating aplanetmapper.Body
object centred on Chiron:
body = planetmapper.Body('CHIRON', target_frame='CHIRON_FIXED')
The
BODY20002060_
variables are used to define the properties and orientation of Chiron itself. TheXXX.XX
values here are placeholders, and should be replaced with appropriate values to define the size, orientation and rotation of Chiron. See the SPICE documentation for more details on these parameters.
Other kernels
In some cases, you may require other kernels in addition to those listed above. You should be able to identify the kernels required by searching the NAIF archive. For example, you can download some comet ephemerides using
from planetmapper.kernel_downloader import download_urls
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/comets/')
The NAIF useful links page may also be useful for finding other information and sources of kernels.
Customising the kernel directory
By default, PlanetMapper downloads and looks for spice kernels in the ~/spice_kernels
directory. However, if needed (e.g. if you already have kernels saved elsewhere), this directory can be customised using the different methods described below. The environment variable method is usually the simplest and easiest.
Method 1: Environment variable
The easiest way to customise the directory is to set the environment variable PLANETMAPPER_KERNEL_PATH
to point to your desired path. For example, on a Unix-like system, you can add a line to to your .bash_profile
file to automatically set this environment variable:
export PLANETMAPPER_KERNEL_PATH="/path/where/you/save/your/spice/kernels"
Method 2: Using set_kernel_path
The function planetmapper.set_kernel_path()
can be used to set the kernel path for a single script. This function must be called before using any other planetmapper
functionality, so it is easiest to run planetmapper.set_kernel_path()
immediately after importing planetmapper
:
import planetmapper
planetmapper.set_kernel_path('/path/where/you/save/your/spice/kernels')
This path should also be set before downloading any SPICE kernels, otherwise they will be downloaded to the incorrect directory:
import planetmapper
from planetmapper.kernel_downloader import download_urls
planetmapper.set_kernel_path('/path/where/you/save/your/spice/kernels')
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/')
download_urls('https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/')
Automatic kernel loading
PlanetMapper will automatically load SPICE kernels the first time any object inheriting from planetmapper.SpiceBase
(e.g. planetmapper.Body
) is created. All kernels in the directory returned by planetmapper.get_kernel_path()
which match any of the patterns **/*.bsp
, **/*.tpc
or **/*.tls
are loaded by default.
If you would like finer control over kernel loading, you can call planetmapper.base.prevent_kernel_loading()
immediately after importing PlanetMapper to disable automatic kernel loading, then manually load kernels yourself using spiceypy.furnsh
.
See planetmapper.SpiceBase
and planetmapper.SpiceBase.load_spice_kernels()
for more detail about controlling automatic kernel loading.