Using SPICE with Celestia

SPICE is a software suite developed at NASA for making the geometric calculations needed to plan an interplanetary mission. SPICE is used by mission teams at NASA, ESA, JAXA, and other space agencies. Most versions of Celestia are built with the SPICE libraries, enabling Celestia to use navigational data direct from space missions.

Audience

This tutorial is targeted at two groups of people:

Mission operators and scientists who want to use Celestia for visualization
Experienced Celestia users interested in very accurate reconstructions of space missions

Those already familiar with SPICE can skip the "Introduction to SPICE" section.

Spice Introduction

An in-depth discussion of SPICE is beyond the scope of this tutorial, but knowing few concepts should be enough to make most of this tutorial understandable. SPICE kernel files contain different types of data relevant to space missions. SPK files (typically with the extension bsp) are used to calculate the position of a spacecraft, planet or other body. A single SPK file may have data for multiple bodies. Finding the position of a body relative so some other object may require multiple kernels. For example, one SPK file might have the position of Cassini relative to Saturn. A second SPK kernel might give the positions of the planets relative to the Sun. In order to compute the heliocentric position of Cassini, we need both kernels. Kernel files have orbit or trajectory files covering a finite time span. For spacecraft, the mission is usually split into several kernels, each covering a different mission phase. The site from which you download the SPK files should have some sort of README files describing the source and time coverage for each file.

There is extensive documentation on SPICE available here at the main NAIF site:

http://naif.jpl.nasa.gov/naif/

The NAIF site is a good place to look for SPICE kernels for many space missions, including both currently operational and historical ones:

http://naif.jpl.nasa.gov/naif/data.html

Celestia Introduction

Celestia loads information about solar system bodies (including planets, natural satellites, asteroids, and spacecraft) from .ssc (Solar System Catalog) files. Each ssc file is a list of one or more body definitions. A solar system body has a trajectory, a rotation model, and a collection of attributes related to its appearance (since Celestia is after all a visual simulation.) The trajectory and rotation model specify the position and orientation of the body over a range of time. The possible sources of trajectory information include Keplerian elements, hardcoded calculations (e.g. VSOP87), and of course, SPICE kernels. The lists of rotation model types is similar.

Simple Example

Here's a sample solar system body definition:

Body "Earth" "Sun"
{
    Texture "earth.*"
    Radius 6378.140  # equatorial
    Oblateness 0.0034
 
    CustomOrbit "vsop87-earth"
    CustomRotation "earth-p03lp"
}

This example defines a body called Earth which orbits the Sun. Built-in calculations are used for both the trajectory and rotation of Earth. These particular built-in calculations assume that the coordinate system is the heliocentric J2000 ecliptic system. Indeed, this is the default system for heliocentric objects in Celestia. But, we can make it explicit by adding OrbitFrame and BodyFrame definitions:

Body "Earth" "Sun"
{
    Texture "earth.*"
    Radius 6378.140  # equatorial
    Oblateness 0.0034

    OrbitFrame { J2000Ecliptic {} }  
    CustomOrbit "vsop87-earth"
    BodyFrame { J2000Ecliptic {} }
    CustomRotation "earth-p03lp"
}

Here, the frame for the trajectory and orientation are set to the same thing. But, we can make the BodyFrame different than the orbit frame if we want. This is useful for spacecraft, where it may make more sense to specify local vertical / local horizontal system.

Spacecraft Example

This tutorial will go step by step through the process of introducing a new spacecraft object into Celestia that has a position and attitude calculated by SPICE. We'll use the Deep Impact mission as an example. All of the SPICE kernels required for the mission may be downloaded from the NAIF site:

ftp://naif.jpl.nasa.gov/pub/naif/DEEPIMPACT/kernels/

The first thing to do is to create a new folder for the Deep Impact add-on. Make a folder called deepimpact inside Celestia's extras folder. Then, make subfolders inside deepimpact called data and models. The folder structure should look like this:

extras/
   deepimpact/
       data/
       models/

The ssc file for the Deep Impact mission will go in the deepimpact folder. The models folder will contain a 3D studio mesh file representing the spacecraft. Finally, all the necessary SPICE kernel files will go in data.

Getting the SPICE Kernel Files

The first files that we need for the mission are the SPK files. These may be found in the SPK directory:

ftp://naif.jpl.nasa.gov/pub/naif/DEEPIMPACT/kernels/spk/aareadme.txt

There are a lot of kernels in this directory, but fortunately, most are unnecessary. The file aareadme.txt helpfully clarifies which kernel files are necessary.

  NOTE 4: The following four of these SPKs should be loaded in
  this order to make sure that the best trajectory solutions are
  available to the calling application at any given time:

     dii_preenc174_nav_v1.bsp
     dif_preenc174_nav_v1.bsp
     di_tempel1_ssd_v1.bsp
     di_finalenc_nav_v3_to2006048.bsp

The note also specifies a loading order for the files. We will need to pay attention to that later. For now, just copy the four .bsp files into the data subfolder of the Deep Impact mission add-on.

Comet Trajectory

We will be begin by creating a new Celestia object representing Comet 9P/Tempel. Although we could define the comet in a separate ssc file, we'll keep things and define all of the objects relevant to the Deep Impact mission in a single file called deepimpact.ssc. Here's the definition for Comet 9P/Tempel using just Keplerian elements for the orbit:

Body "9P Tempel" "Sol"
{
    Class "comet"
    SemiAxes [ 3.1 2.1 2.1 ]
    Texture "asteroid.jpg"

    EllipticalOrbit {
        Epoch                "2005 7 4 00:00:00"
        Period               5.51521370
        SemiMajorAxis        3.121543768
        Eccentricity         0.517493300
        Inclination         10.530163779
        AscendingNode       68.938123883
        ArgOfPericenter    178.837987181
        MeanAnomaly        359.765094570
    } 
}

The orbital elements were derived from HORIZONS. If you have a SPICE kernel for an object, it's not necessary to begin with orbital elements. It's done here only to illustrate how an object definition is changed to add a SPICE trajectory.

Converting to SPICE

The README file in the SPK directory lists four SPK files that are required for the Deep Impact mission. The same file also recommends an order in which the files should be loaded. The order is important because when there's more than one trajectory segment valid for an object at a particular time, the most recently loaded one has priority. Celestia always loads SPICE files in the order that they're listed in an SSC file. The README doesn't mention two extra kernel files that are needed for the mission: di_tempel1_v01.tpc and di_v17.tf. Together, these define a SPICE frame for the comet Tempel 1. This frame is used for Deep Impact's trajectory right around the time of impact. Careful reading of the documentation accompanying a set of SPICE kernels is often necessary in order to understand which kernel files should be used.

Here is Tempel 1 with the Keplerian orbit replaced by a SPICE orbit:

Body "9P Tempel" "Sol"
{
    Class "comet"
    SemiAxes [ 3.1 2.1 2.1 ]
    Texture "asteroid.jpg"

    SpiceOrbit {
        Kernel [
            "dii_preenc174_nav_v1.bsp"
            "dif_preenc174_nav_v1.bsp"
            "di_tempel1_ssd_v1.bsp"
            "di_finalenc_nav_v3_to06048.bsp"
            "di_tempel1_v01.tpc"
            "di_v17.tf"
        ]

        Origin "SUN"
        Target "TEMPEL 1"
        BoundingRadius 10
    }
}

We are using four parameters for SpiceOrbit. The list of kernel files appears first. Celestia will load these kernel files from the add-on's data directory. It will ignore already loaded kernels, thus it's harmless to repeat the kernel list in the definition of every object that requires it. However, it does mean that multiple objects will have to be updated if a kernel file name changes. Origin and target are both NAIF names or IDs. Instead of "TEMPEL 1", we could have used the NAIF ID code 1000093. The name is much clearer, and so it is favored when available. The SPICE origin must match the Celestia origin. In Celestia an origin is given by the orbit frame center; if an orbit frame isn't explicitly specified (as in our example), the default frame is centered on the parent object. In our example, the Sun is the parent object.

The BoundingRadius field gives the radius of a sphere centered at origin that is large enough to completely contain the orbit. This information is used by Celestia to optimize rendering; with it, Celestia can do very quick checks to see whether an object might possibly be visible. Setting too small a value for BoundingRadius may make an object disappear when it should be visible. Making it too large will have no visible side effects, but can force Celestia to make extra calculations. There's no need to get too precise—bounding radii that are too large by a factor of two shouldn't cause any performance problems. On the other hand, setting all bounding radii to extremely large values like 1000 AU is to be avoided. Like other distances in Celestia, the units of BoundingRadius are AU for heliocentric objects and kilometers for everything else.

Spacecraft Trajectory

Now that we've tracked down the kernels file needed for the trajectories of the objects involved in the mission, it's quite straightforward to add the flyby spacecraft:

Body "Deep Impact" "Sol"
{
    Class "spacecraft"
    Radius 0.003
    Mesh "DeepImpact2.3ds"

    SpiceOrbit {
        Origin "SUN"
        Target "DEEP IMPACT FLYBY SPACECRAFT"
        BoundingRadius 10
    }
}

The kernel files are omitted, since they're already loaded in the Tempel 1 definition. The only other thing different from the comet's SpiceOrbit is that we've changed the name of the target object.

Spacecraft Attitude

Showing accurate attitude for a spacecraft is slightly more difficult than getting a correct trajectory. The main chore may be finding all the kernel files necessary. For spacecraft, four types of kernel files are usually necessary:

One or more C-kernels giving the orientation of the spacecraft at different times
A text frame kernel that defines a SPICE frame for the spacecraft
A spacecraft clock (SCLK) kernel for translating UTC to spacecraft clock time
A leap second kernel for converting ephemeris time to UTC

Once the needed kernel files have been installed in the add-on's data directory, we just need to replace the spacecraft's existing rotation model (if any) with a SpiceRotation. The syntax is very similar to that for SpiceOrbit.

SpiceRotation {
    Kernel [
        "dif_sc_050112_050809.bc"
        "di_v17.tf"
        "DIF_SCLKSCET.00036.tsc"       
        "naif0009.tls"
    ]
    Frame "DIF_SPACECRAFT"
    BaseFrame "eclipj2000"
}

Note that there are four kernel files lists: a C-kernel, a text frame kernel, a spacecraft clock kernel, and a leap second kernel. The frame kernel isn't actually necessary because it was already loaded in a SpiceOrbit. However, it's listed here anyway, because this is a tutorial, and in the more typical case, the .tf file will appear in the kernel list for the trajectory. Frame gives the name of a C-kernel frame defined for the spacecraft. BaseFrame should be set to the SPICE equivalent of whatever the object's BodyFrame is in Celestia. The default BodyFrame of a Sun-orbiting object in Celestia is the J2000 ecliptic. This matches the default BaseFrame for a SpiceRotation: eclipj2000. Still, it's a good idea to explicitly specify both frames. This is one situation where Celestia's defaults can be confusing: for objects that orbit something other than a star, the default BodyFrame is the equatorial frame of the parent object. This is rarely what you want when using SPICE!

Debugging SpiceRotation

There are a lot of things that may go wrong when orienting a spacecraft with SPICE. If you restart Celestia and find that you spacecraft is pointing in the wrong direction, here are some things to check:

Press the tilde key (~) to bring up Celestia's console log. See if there are any SPICE errors scrolling by, perhaps indicating that some required kernel files are missing. If not, press the up error to scroll backward in the log. See if any errors occurred when loading the add-on.
Make sure that you haven't forgotten the leap second kernel or frame kernel
Verify that the SPICE frame matches the Celestia frame for the object (i.e. BaseFrame is appropriate for the object's BodyFrame.)
Check to make sure that the spacecraft's 3D mesh is oriented correctly in the body frame. The 'Reference Vectors/Body Axes' option in the spacecraft's right click popup menu is very helpful here.

Adding the Impactor

SPICE Planets

We'll now convert the Earth example to use a SPICE kernel for the orbit of Earth. The SPICE kernel de421.bsp may be downloaded from the NAIF FTP site:

ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/