NAIF May 2003 (EDW)
Welcome to SPICE, a NAIF (The Navigation and Ancillary Information
Facility at JPL) developed software system that provides the
capability to easily combine accurate space geometry and event data
with your mission analysis, observation planning, or science data
processing software.
Since its introduction, SPICE earned wide acceptance for organizing, distributing, and accessing both space geometry and mission event data. As you move on from your current investigations to other planetary science studies, SPICE can likely assist you with these new endeavors.
The SPICE system supports the following platforms/compilers:
This overview guides you through the Toolkit's various components and identifies more extensive documentation.
We at NAIF are committed to providing a robust, flexible, and
understandable product that suits the needs of the space sciences
community. All SPICE Toolkit software undergoes careful review and
testing; the documentation for the SPICE software is extensive and
accurate.
To further enhance the SPICE user experience, NAIF encourages users to comment on the product. Such comments can range from bug reports to requests for new functionality.
In addition to listening to users' comments, NAIF uses the product in support of JPL flight projects. With such practical experience, we understand the perspective and future needs of the novice working to learn SPICE.
The SPICE system is a continual work in progress. However, NAIF is equally committed to providing SPICE users a consistent product. We understand the frustrations of learning a programming system only to have it change in unanticipated ways. Therefore, we never change the intended functionality of, or the interface to, released software and data products. If you build a program using today's SPICE system, it will work the same way when you re-build it with tomorrow's SPICE system. Our motto "Once SPICE, always SPICE."
NAIF developed a pure ANSI C version of the SPICE Toolkit named
``CSPICE'' to present C programmers a natural C-style interface to the
FORTRAN SPICE Toolkit's functionality. (The term SPICE is more general
and refers to either the FORTRAN or C systems.)
First released in May 1999, NAIF subjected CSPICE to an elaborate testing process, but lacks the benefit of extensive, sustained testing by practical use. In contrast, various NASA flight projects have used the FORTRAN Toolkit since 1990.
NAIF delivers the CSPICE Toolkit as a distinct product from the FORTRAN SPICE Toolkit; NAIF does not deliver intermixed versions of these products.
The cspice.req ``Required Reading'' document, included in the CSPICE Toolkit, provides a detailed description of the product.
The advent of the CSPICE extension to the SPICE system presented NAIF
the opportunity to create an interface named ``Icy'' between the IDL
environment and CSPICE. Currently available in Beta-test status and to
be formally released in 2004, Icy provides access to the CSPICE vector
math, SPICE file read/write and data evaluation routines (among
others).
The Icy distribution consists of a superset of the CSPICE distribution containing CSPICE plus the IDL/CSPICE interface code, Icy API html documentation, CSPICE API html documentation, and the Icy programming guide.
SPICE stores data in specialized files named ``kernels''. A kernel may
store data in either ASCII text or binary formats.
Text kernels are interpreted as simply a string of ASCII characters with special markers to indicate data assignments. Caution, a text file contains operating system specific line terminators. Reading a file containing the wrong terminators for your operating system may produce useless results.
Binary kernels on the other hand have more specialized organization. They typically contain numeric and textual information. The numeric information is stored in the binary format used by your computer instead of a form easily read by people.
The binary kernels set consists of:
The set of text kernels consists of:
The C and FORTRAN Toolkits use the same kernel files on the same architecture platform.
Both types of kernels (text and binary) must be read to be useful. The SPICE system provides software for reading (and in some cases writing) these kernels. Still, you can use these kernels without ever concerning yourself with the details of their format.
To make the information in kernels available to your software you will need to load them. This lets the SPICE system know where to find these data. Loading text kernels is discussed in the document kernels.req. Loading SP-kernels, C-kernels, and PC-kernels is discussed in the documents spk.req, ck.req, and pck.req respectively. Moreover examples of loading kernels are provided in the cookbook programs provided with SPICE (see the section on Example Programs below). Kernels of all types need to be loaded only once in your program - no need to embed the load statement in a loop.
As mentioned, several SPICE kernel types store numeric data in binary
format. Unfortunately, hardware architecture (the CPU chip) determines
the format of numeric binary data. The two most common formats are
IEEE standard big endian and non-IEEE standard little endian.
To accommodate those users who require the use of kernels across multiple computing architectures, SPICE software can read non-native binary kernels on most platforms (not including VAX/VMS).
Your first step to join the SPICE user community is to install a
Toolkit delivery onto your computer. An installation nominally
requires nothing more than executing a script or command procedure
(provided with your SPICE package) to unpack the SPICE directory
system. A Toolkit delivery usually includes precompiled executables
and libraries.
Should you want or need to rebuild the executables and libraries, a script exists for that task.
The time required for a rebuild varies with the speed of your computer and its FORTRAN or C compiler. On most systems, a rebuild process lasts less than thirty minutes.
Once you install the SPICE system on your computer, consult the
document dscriptn.txt for a description of the directory structure
created by the installation process and the contents of the various
directories.
A toolkit delivery is a collection of files segregated by category: documentation, source code, make or link procedures, and some sample data.
Documentation is stored in the doc subdirectory of the main toolkit directory. These files include user's guides for the various applications, index information, and discussion of related collections of routines that make up the SPICELIB or CSPICE libraries.
Documentation on the design and function of a particular subroutine is found in the source code for the routine. All subroutines contain an extensive comment block called a ``header'' that appears at the beginning of the source file.
The main component of all Toolkit deliveries, regardless of target language, is the code library, SPICELIB in the FORTRAN delivery and CSPICE in the C. The source files in these libraries compile to object libraries, spicelib.a (FORTRAN) and cspice.a (C) stored in the ``lib'' subdirectory. You link against these libraries when creating your own programs. Other object files are linked with SPICELIB or CSPICE to create the application tools included in the SPICE system.
Sample data files make up the remaining files. Some of these (LSK and PCK) can be used as you receive them. Others must be converted from transfer to binary format before you can use them with Toolkit software; these are the ephemeris (SPK), attitude (CK) and spacecraft events (EK) information files. The conversion programs used for converting these files are called spacit, tobin and toxfr. They are provided with the SPICE system and their executable modules are located under the exe subdirectory. They are discussed briefly in the TOOLS section below and are documented in the spacit.ug and convert.ug User's Guide documents that come with SPICE.
The following discussion of delivery contents refers to either the FORTRAN or C SPICE Toolkits. The installation trees for these Toolkits are always disjoint: the directories discussed will contain FORTRAN or C products but not both.
Practical use of the SPICE system requires (at a minimum):
In future releases of the SPICE system, NAIF intends to provide documentation describing the development of SPICE-based applications in the various computing environments for which we actively support the SPICE system. But for now, if any of these topics (editing, compiling or linking) are not clear to you, try examining the routines used by the installation procedure to build the various SPICE applications. For example, examine the procedure mkprodct (or mkspacit on some computer platforms) located in the source code directory for SPACIT (see dscriptn.txt to locate this directory). If this example fails to answer any questions, NAIF recommends you consult a colleague or your system administrator to find out the details of program development on your computer.
If you ``speak'' FORTRAN, C or IDL, then you're ready to program.
However, you might need to code in another language (for example Java
or Visual Basic) and still use SPICE routines. Caution, cross language
linking is notoriously tricky. Matrices, strings, and other data types
may be organized differently in your language of choice from the way
they are organized in FORTRAN or C.
If you choose this path you will need to find out how your language of choice supports calls to FORTRAN or C object modules. Your best source of information will be a colleague who has already mastered this art. There may be a programmer's reference manual that describes cross-language syntax. In addition, you may be able to receive support from the company that supplies the language you choose for writing your software.
Most SPICE users will not need to create or modify kernels. Moreover,
of the users who need to create or modify kernels, most will only need
to deal with one of the various text kernels. Because these are text
files they can be created and modified with any text editor. Although
the format of these files is fairly easy to deduce, we recommend you
consult the document kernel.req before you attempt to edit a text
kernel for the first time.
Some SPICE users will want to create binary kernels. This task requires a deeper understanding of the SPICE kernel format and kernel readers. If you need to create SPICE binary kernels we recommend you read all of the material in the one of spk.req, ck.req, pck.req or ek.req pertinent to your task. In addition, if you are producing these data products in an official project capacity we encourage you to contact NAIF to discuss any issues that might be relevant to your task of producing binary kernels.
Since you probably won't produce your own kernels, you need to 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.
We often learn new ideas best by seeing examples of their use. For
this reason SPICE comes with a collection of simple example programs
called the SPICE Cookbook, located under the cookbook subdirectory.
These sample programs show in a few pages how to load various kernel
files, how to call the kernel readers and how to perform common
geometric and time computations. Most users find these to be very
valuable in getting started with the SPICE system. We recommend you
look at the Cookbook early to help you get an idea of how easily you
can begin programming using SPICE.
Toolkit distributions include several utility programs to assist you
with using SPICE. These programs are:
The SPICE system is very much concerned with concepts of geometry and
time. The planetary science community uses several different time and
coordinate systems when describing geometry and time. Within the
context of a single planetary mission, one does not often need to be
concerned with the details of these systems. Project management simply
dictates a common system to be used for all software and data
products. However, the scope of the SPICE system spans many planetary
missions and terrestrial based investigations. As a result, you will
need to pay more careful attention to the details of the various
measurement systems.
SPICE includes mechanisms for converting between different time systems such as UTC, JED, TDB and Spacecraft Clock. SPICE also provides conversions between various inertial reference frames such as J2000, B1950, EME50, and non-inertial frames such as body-fixed frames.
Additional detailed information available in:
The SPICE system is much more than kernels and kernel readers. Over
half the Toolkit's routines perform functions designed to ease the
process of building software. Those familiar with the standard C
library will find a find a parallel between some SPICE FORTRAN
routines and standard C functions. A subset of the text and file
manipulation capabilities inherent to the Perl language are also
integrated into the SPICELIB and CSPICE libraries.
Use of the Toolkit for more than simple data acquisition and analysis means you can often produce software more robust, and in less time than similar software developed without using Toolkit routines. There are some obvious reasons for this. You don't have to write the software that duplicates Toolkit functions. Toolkit software has already undergone careful testing. The action of Toolkit software is carefully specified. In addition, you benefit from a centralized error handling facility integrated with Toolkit software.
To find out more about the various features of the Toolkit, consult the following documents found in the doc subdirectory:
The real programming power of SPICE derives from the extensive set of
built in capabilities you need not re-invent. However, since SPICE
contains over 1100 routines, reading all the routine headers is not a
practical way to locate the appropriate routine for a given task. If
you can classify the function you need as belonging to one of the
categories listed in the previous section, then you can consult one of
the listed documents. However, there many routines in SPICE don't fit
into one of the categories. (For example, the Toolkit contains over
forty routines for performing vector-matrix arithmetic.) With this
indexing problem in mind, we have provided additional documents to
help you quickly locate the proper routine for the task.
The documents spicelib.idx and cspice.idx provide a permuted index to all of the routines in SPICELIB or CSPICE respectively. Like the index to a reference work, this helps you find the right routine for a specific task. Moreover, the index is permuted. Thus, the word you think of as an index to a routine has a much greater chance of pointing to a relevant routine. For example you will find:
Cross product of two vectors Product of two vectors, cross Vectors, cross product of twoall listed in the permuted index. Each of these point to the SPICELIB subroutine VCRSS, or the CSPICE function vcrss_c, that computes a cross product.
With any new product people sometime encounter problems. If you run
into a problems here are some steps you can take to try to resolve
them.
All Toolkit distributions include a document named ``problems.txt'' in the doc directory. This document lists the most common problems and aggravations the new SPICE user might experience and the most probable solutions.
If you think the problem is related to a SPICE routine, look at the documents related to the routine (these are listed in the required reading section of the routine's header). These documents may contain useful information for diagnosing and correcting the problem.
If the problem seems related to your programming environment, (for example you can't link a program, can't find a file, don't have sufficient privileges to perform some action, etc.) contact your system manager. (s)he may be able to assist you. NAIF can provide little more than sympathy with regards to such situations.
If you use a SPICE based product developed by someone else, contact the developer for assistance.
If your program executes but your output disagrees with those of a colleague who ran the same program with identical inputs, ensure you both use the same kernel files.
If you don't have the latest version of a kernel associated with a flight project (or want to find out if you do) contact the project data administrator.
If you can't seem to fit the problem into one of the above categories, or just aren't getting anywhere, send us (NAIF) e-mail or call us on the phone. We'll do what we can within our resources to help.
The NAIF Team encourages all SPICE users to comment on the SPICE
system. If you like what you've so far received, let us know. If some
part of the system fails, or performs in an unexpected manner, tell us
that too.
If you have ideas for improvements or enhancements, we'd like to hear about them. With the support and suggestions of users, the SPICE system will continue as a valuable resource for the space science community for decades to come.