Welcome to SPICE
Welcome to SPICE, an ancillary information system that provides scientists and engineers the capability to include space geometry and event data into mission design, science observation planning, and science data analysis software.
The principle components of the SPICE system are SPICE Toolkit software and SPICE data files—often called "kernels."
SPICE is used throughout NASA and within many other U.S. and international agencies for organizing, distributing, and accessing ancillary data associated with space science missions. The NAIF website contains the few important rules regarding using SPICE. Please take a moment to read these.
Using SPICE Toolkit Software
Your first step is to download a SPICE Toolkit package from the NAIF website if a current version is not already installed on your machine or available through some form of connected server. In addition to the Toolkit download package and installation script you will find several important documents.
The README file provides installation instructions.
The Description document
(dscriptn.txt) provides an
overview of the contents and organization
of the Toolkit.
The What's New
describes new and changed capabilities of this
Toolkit as regards
previous versions, and lists the supported
(environment = language/platform/OS/compiler) for
What Else is Needed
Use of the SPICE system requires (at a minimum) one of the following: a FORTRAN 77 compiler/linker, an ANSI C compiler/linker, an IDL installation, or a MATLAB installation, that is consistent with the components NAIF used in building the Toolkit you have downloaded. You'll also need a text editor—preferably one that is familiar to you and perhaps that is good for writing code. Familiarity with a debugger can also be helpful as you develop your application program. You will need to know how to build and execute a program on your computer.
Getting StartedNAIF provides a variety of aids to help you begin using SPICE. Make good use of these.
TutorialsNAIF offers a large set of tutorials, provided in viewgraph style. Individual tutorials, or the entire package, may be downloaded from the NAIF website. These tutorials are listed pretty much in the order a beginner might wish to follow. However we especially encourage a new SPICE user to look through "conventions" through "intro to toolkit," and also "common_problems" and "summary of key points." The new user should also look at other tutorials as appropriate to the task at hand; probably this would include "time" and "spk" at a minimum.
Programming ExamplesThree kinds of programming examples are available, each a little different. Each type is offered in all the languages supported by SPICE.
In addition to the training code described above, nearly every API (subroutine) contains one or more example code fragments showing samples of how that particular routine might be used in a typical problem. These examples are contained in the header of the module. The html versions of Toolkit documentation contain hyperlinks to these headers, or you may open the source code module in an editor or with a text display utility.
Finding the Appropriate Routine
The real programming power of SPICE derives from the extensive set of built in computations you need not re-invent. However, as the Toolkits contain hundreds of routines, reading all routine headers or API descriptions to determine the appropriate routine for a given task is not practical. In addition to numerous API references in the tutorials mentioned earlier, NAIF provides two products in each Toolkit to help you find an API that may meet your needs.
SPICE stores data in files that are often referred to as "kernels.'' A kernel may store data in either text (ASCII) or binary format. In order to access data within a kernel an application program must "load" the kernel using a SPICE API ("furnsh").
Excepting the important platform-specific differences mentioned below, any particular kernel may be used with any of the Toolkits.
text kernels consists of:
As for any text file, a SPICE text kernel contains operating
specific line terminators. Trying to use a non-native
style text kernel is
one of the most prevalent user errors. To
mitigate this problem somewhat the
CSPICE, Icy, and Mice Toolkits
include code that allows reading of
non-native text kernels.
Unfortunately this accommodation is not possible
FORTRAN Toolkits because the FORTRAN language does not allow
C-style line terminations. FORTRAN Toolkits contain
code that will issue a SPICE
error message whenever a non-native text
kernel load occurs.
The set of binary kernels consists of:
Binary kernels typically contain numeric and textual information. Hardware architecture (the CPU chip) determines the format of numeric binary data; the two formats used by computers supported by NAIF are called "big endian" and "little endian." Because kernels are frequently transferred between computers which may use incompatible binary architecture, SPICE software has been designed to read non-native binary kernels. (But not to write to a non-native binary kernel.)
One "loads" kernels to give the SPICE
system the information
find the data within the kernels.
The tutorial named "intro to kernels" quickly
describes the loading
process. The Kernel Required Reading document (kernel.req) provides a complete description.
Examples of loading kernels may be seen in the cookbook programs and
the "open book"
programming lessons previously mentioned.
unusual circumstances, kernels of all types need "loading"
in your program—do not embed the load statement in a loop.
Creating or Modifying Kernels
The majority of SPICE users will not need to create or modify kernels. But if you do need to do so you must do so carefully to avoid structural problems and to help ensure others will easily use the kernel. Careful testing of a kernel you create, and of the kernel production process for binary kernels, is essential!
Creating or Modifying Text KernelsBecause they are just text files, text kernels are created or modified with any text editor. Although the format of these files appears fairly easy to deduce, we recommend you consult the document kernel.req before you attempt to create or edit any text kernel for the first time. You should also review the tutorial created for the kind of text kernel with which you will be working.
Creating or Modifying Binary Kernels
Some SPICE users will want to create or modify binary kernels. This task requires a good understanding of the particular SPICE kernel type, and of the appropriate binary kernel writer API(s). You should be familiar with the tutorial discussing the kernel type of interest. NAIF recommends you also read the "Making an SPK" or the "Making a CK" tutorial, if relevant. You should also read appropriate portions of the "required reading" reference document pertinent to your task (spk.req, ck.req, pck.req or ek.req).
Annotating a New or Modified KernelWhenever you create or modify a kernel you have the responsibility to properly and thoroughly annotate that kernel so that users of it (including yourself) can understand why, when and how it was made. This annotation process is called adding comments (or adding meta-data). Both text and binary kernels can accommodate such comments. The tutorial named "introduction to kernels" provides some information about this.
Comments (metadata) are added to text kernels using any text editor, just as for making or modifying the data sections of the text kernel.
Comments (metadata) are normally added to, extracted from, or removed from a binary kernel using a Toolkit utility program named "commnt."
Selecting and Obtaining Kernels
Knowing which kernel, or set of kernels, to use in any particular task can be a challenge. Having kernel producers use a consistent and well thought out kernel naming methodology is a must. Having kernel producers provide high quality metadata with each kernel or kernel collection is equally important. Nevertheless, kernel selection is one of the most challenging aspect of using the SPICE system. (Probably the same challenge would exist no matter what kind of ancillary information system would be used.)
Often three classes of kernels are available:
Mission operations kernels are those produced before or while a spacecraft is operating, to support science observation planning, initial science data processing and analysis, and mission engineering functions. There are often many of these kernels. Those types that provide data as a function of time—especially SPK and CK—may have many overlaps in time. Some may be "predict" versions made for observation planning while others may be "reconstruction" versions made for science data processing. Selecting kernels from this class can be quite a challenge, especially if you are not a regular consumer of mission operations kernels.
Certainly for NASA planetary missions, and probably for missions operated by other agencies, mission archived kernels are usually your best bet—if there are already archived kernels covering the period of the mission of interest to you. A mission's archived kernels are usually better organized and documented, and often sets of "small" kernels covering short periods of time have been merged into more easily used "large" kernels covering a longer time span.
For JPL-managed missions the mission archived kernels often have associated "furnsh" kernels (meta-kernels) that logically aggregate the entire collection of kernels appropriate for a given time span or a given mission phase. Make use of these!
Be aware that for all but the shortest missions the archiving of SPICE data is usually done in increments, with a new batch of data added to the collection on a regular basis—typically every three or six months. The usual (preferred) NAIF methodology for archiving SPICE data is to create a single, "accumulating" SPICE dataset. Every few months the next batch of kernels is added to the existing dataset, with updates made to the dataset's metadata indicating the new (longer) time span covered by the whole collection.
Generic kernels are those that are not tied specifically to one mission; they are usually applicable to many missions, or could be useful independent of any mission. Examples of generic kernels are:
A majority of the generic kernels are produced by NAIF and made available from the generic kernels link on the Data webpage. But, as the use of SPICE spreads, other agencies may also offer generic kernels.
Since you probably won't produce your own kernels, you
obtain them from someplace—normally a project database
or project data
management team. Once a mission is complete the
kernels should be
available from a national data archive center. The
NAIF node of the
Planetary Data System is one such example (http://naif.jpl.nasa.gov/naif/data.html).