SpiceyPy Documentation

SpiceyPy is an open-source, MIT-licensed Python package that provides a Pythonic interface to nearly all of the C SPICE toolkit (N66). It is designed for scientists and engineers working with robotic planetary spacecraft missions to quantify the positions, velocities, geometries, and other properties of spacecraft and planetary bodies through time.

Key characteristics:

• Pythonic Interface: Uses the ctypes module to wrap the underlying C SPICE shared library, providing simplified interactions compared to the original C API.
• Scientific Stack Integration: Relies on NumPy for numeric arrays and is tightly integrated with the SciPy stack.
• Documentation: Every function wrapper includes docstrings with descriptions from the original SPICE documentation and links to the corresponding CSPICE documentation hosted by NAIF.

SpiceyPy is a Python wrapper for the NASA NAIF SPICE Toolkit. It provides Pythonic access to planetary and spacecraft ephemeris and ancillary engineering information.

Note: SpiceyPy is a wrapper; for deep technical details on the underlying SPICE algorithms and logic, users should refer to the official NAIF SPICE documentation.

In SpiceyPy, a plane is a data representation describing a plane in three-dimensional space. It is used to simplify geometry routines and centralize error checking.

A SPICE plane is defined by a unit normal vector N and a scalar constant C. The relationship is defined as:

< X, N > = C

where < X, N > is the inner product of vectors X and N.

Key properties:

• C is the distance of the plane from the origin.
• The vector C * N is the closest point in the plane to the origin.
• For planes not containing the origin, N points from the origin toward the plane.

While SpiceyPy uses the spiceypy.utils.support_types.Plane class to represent this structure, users should avoid interacting with this object directly and instead use the provided construction and decomposition routines.

The SPK system is the component of SPICE concerned with ephemeris data. SPK files (S-kernel and the ephemeris portion of the P-kernel) allow ephemerides for any collection of solar system bodies (spacecraft, planets, satellites, comets, asteroids, etc.) to be combined under a common file format and accessed via a common set of functions.

Key capabilities include:

• Inserting ephemeris data into an SPK file.
• Making ephemeris data from one or more SPK files available to a program.
• Returning the apparent, true, or geometric state (position and velocity) of one ephemeris object as seen from another in a specified reference frame.

The units of encoded SCLK are ticks since spacecraft clock start. A tick is the shortest time increment expressible by a particular spacecraft's clock. The duration of a tick varies by spacecraft (e.g., ~4ms for Mars Global Surveyor, ~8.3ms for Galileo).

• Integral Ticks: Standard SCLK conversions produce integral tick values.
• Continuous Ticks: To minimize discretization error when converting ephemeris times (ET) to ticks, use sce2c. This supports non-integral (continuous) tick values.

Key Functions:

• sce2c(et): Converts ET to continuous (non-integral) ticks.
• sce2t(et): Converts ET to encoded SCLK ticks (integral).

To avoid long, repetitive paths in meta-kernels, you can define path symbols using PATH_VALUES and PATH_SYMBOLS. Symbols are referenced in the KERNELS_TO_LOAD list using a $ prefix.

Example Meta-kernel with symbols:

\begindata
PATH_VALUES  = ( '/flight_projects/mgs/SPICE_kernels', '/generic/SPICE_kernels' )
PATH_SYMBOLS = ( 'MGS', 'GEN' )

KERNELS_TO_LOAD = ( '$GEN/leapseconds.tls', '$MGS/mgs.tsc', '$GEN/generic.bsp' )
\textendata

Note: These symbols are internal to SPICE and are not related to operating system shell symbols.

In the context of spacecraft orientation and reference frame transformations, it is important to distinguish between two primary transformation functions:

• spiceypy.pxform: Used for computing transformation matrices between reference frames. It is often used when you need to transform a vector or a state from one frame to another by explicitly calculating the rotation/transformation matrix.
• spiceypy.sxform: Used for transforming a state (position and velocity) from one reference frame to another.

Understanding when to use each is critical for correctly chaining inertial and non-inertial frames (e.g., transforming from a spacecraft body-fixed frame like CASSINI_HGA to an inertial frame like J2000).

Type 3 segments provide Chebyshev polynomial coefficients for Euler angles (RA, DEC, W) and body-fixed angular rates (X, Y, Z axis rates). Unlike Type 2, the time intervals for each record do not need to be the same length.

Record Structure: Each record contains:

1. MID: Midpoint of the interval (TDB seconds/ET).
2. RADIUS: Radius of the interval (TDB seconds/ET).
3. RA Coefficients: $(\text{polynomial degree} + 1)$ coefficients.
4. DEC Coefficients: $(\text{polynomial degree} + 1)$ coefficients.
5. W Coefficients: $(\text{polynomial degree} + 1)$ coefficients.
6. X-axis rate Coefficients: $(\text{polynomial degree} + 1)$ coefficients.
7. Y-axis rate Coefficients: $(\text{polynomial degree} + 1)$ coefficients.
8. Z-axis rate Coefficients: $(\text{polynomial degree} + 1)$ coefficients.

Note: Type 3 data is described as being seldom used.