or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ck-orientation.mdcoordinate-systems.mddata-structures.mddsk-shape-models.mde-kernels.mdephemeris-trajectories.mderror-handling.mdevent-finding.mdgeometry-surface.mdindex.mdkernel-management.mdlow-level-file-access.mdphysical-constants.mdreference-frames.mdspacecraft-clock.mdtime-systems.mdvector-matrix.md
tile.json

tessl/pypi-spiceypy

A Python wrapper for the NAIF CSPICE Toolkit providing essential tools for spacecraft navigation and planetary science calculations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/spiceypy@6.0.x

To install, run

npx @tessl/cli install tessl/pypi-spiceypy@6.0.0

index.mddocs/

SpiceyPy

A Python wrapper for NASA's NAIF CSPICE Toolkit (N66) providing essential tools for spacecraft navigation and planetary science calculations. SpiceyPy enables Python developers to access comprehensive SPICE functionality for Solar System geometry, spacecraft mission analysis, and astronomical computations through a Pythonic interface.

Package Information

  • Package Name: spiceypy
  • Language: Python
  • Installation: pip install spiceypy or conda install -c conda-forge spiceypy
  • Requirements: Python 3.8+, NumPy ≥1.23.5
  • Architecture: 64-bit (Linux, macOS, Windows, FreeBSD)

Core Imports

import spiceypy as spice

Alternative import for convenience:

from spiceypy import *

Import specific functions:

from spiceypy import furnsh, str2et, spkpos, kclear

Basic Usage

import spiceypy as spice
import numpy as np

# Load SPICE kernels (data files)
spice.furnsh("path/to/metakernel.mk")

# Convert time strings to ephemeris time
et = spice.str2et("2023-01-01T12:00:00")

# Get position of Mars relative to Earth at a specific time
position, light_time = spice.spkpos(
    "MARS",           # Target body
    et,               # Ephemeris time
    "J2000",          # Reference frame
    "LT+S",           # Aberration correction
    "EARTH"           # Observer
)

print(f"Mars position: {position} km")
print(f"Light time: {light_time} seconds")

# Clean up - unload all kernels
spice.kclear()

Architecture

SpiceyPy provides a comprehensive Python interface to NASA's SPICE system:

  • SPICE Kernels: Data files containing ephemeris, attitude, instrument, and reference frame information
  • Kernel Pool: In-memory storage for loaded kernel data, managed automatically by SpiceyPy
  • Vectorization: Most functions accept both scalar and array inputs for efficient batch processing
  • Error Handling: Automatic error checking with detailed exception hierarchy
  • Type Safety: Full type annotations throughout the API for modern Python development

The library encompasses 656+ functions organized into logical functional areas, making it the definitive Python interface for space geometry calculations and spacecraft mission analysis. Coverage includes fundamental operations (time, coordinates, ephemeris), advanced capabilities (databases, shape models, orientation data), and specialized tools (event finding, low-level file access).

Capabilities

Kernel Management

Essential functions for loading and managing SPICE data files (kernels) that contain ephemeris, attitude, instrument, and reference frame information.

def furnsh(kernel: str) -> None
def kclear() -> None
def unload(kernel: str) -> None
def ktotal(kind: str) -> int

Kernel Management

Time Systems

Comprehensive time conversion and manipulation functions supporting various time systems including UTC, ET (Ephemeris Time), TDB, and custom calendar formats.

def str2et(time: Union[str, Iterable[str]]) -> Union[float, ndarray]
def et2utc(et: Union[float, ndarray], format: str, prec: int) -> Union[str, List[str]]
def utc2et(utcstr: str) -> float
def et2lst(et: Union[float, ndarray], body: Union[int, str], lon: float, type: str) -> Union[Tuple[int, int, int, str, str], List[Tuple[int, int, int, str, str]]]

Time Systems

Ephemeris and Trajectories

Functions for computing positions and velocities of celestial bodies, spacecraft, and other objects in the Solar System with high precision.

def spkpos(targ: Union[int, str], et: Union[float, ndarray], ref: str, abcorr: str, obs: Union[int, str]) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]
def spkezr(targ: Union[int, str], et: Union[float, ndarray], ref: str, abcorr: str, obs: Union[int, str]) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]
def spkgeo(targ: int, et: Union[float, ndarray], ref: str, obs: int) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]

Ephemeris and Trajectories

Coordinate Systems

Comprehensive coordinate system transformations including rectangular, spherical, cylindrical, latitudinal, and various planetary coordinate systems.

def sphrec(r: float, colat: float, lon: float) -> ndarray
def recsph(rectan: ndarray) -> Tuple[float, float, float]
def georec(lon: float, lat: float, alt: float, re: float, f: float) -> ndarray
def recgeo(rectan: ndarray, re: float, f: float) -> Tuple[float, float, float]

Coordinate Systems

Reference Frames

Functions for working with reference frames including transformations between frames, frame definitions, and orientation computations.

def pxform(from_frame: str, to_frame: str, et: Union[float, ndarray]) -> Union[ndarray, ndarray]
def sxform(from_frame: str, to_frame: str, et: Union[float, ndarray]) -> Union[ndarray, ndarray]
def frmnam(frcode: int) -> str
def namfrm(frname: str) -> int

Reference Frames

Geometry and Surface Analysis

Advanced geometric computations including surface intersections, illumination analysis, limb finding, and visibility calculations.

def sincpt(method: str, target: str, et: float, fixref: str, abcorr: str, obsrvr: str, dref: str, dvec: ndarray) -> Tuple[ndarray, float, ndarray, bool]
def subpnt(method: str, target: str, et: float, fixref: str, abcorr: str, obsrvr: str) -> Tuple[ndarray, float, ndarray]
def illum(target: str, et: float, abcorr: str, obsrvr: str, spoint: ndarray) -> Tuple[float, float, float]

Geometry and Surface Analysis

Vector and Matrix Mathematics

Linear algebra functions for vector operations, matrix manipulations, and mathematical computations commonly used in space geometry.

def vadd(v1: ndarray, v2: ndarray) -> ndarray
def vsub(v1: ndarray, v2: ndarray) -> ndarray
def vdot(v1: ndarray, v2: ndarray) -> float
def vcrss(v1: ndarray, v2: ndarray) -> ndarray
def mxm(m1: ndarray, m2: ndarray) -> ndarray

Vector and Matrix Mathematics

Physical Constants and Bodies

Functions for retrieving physical constants, body properties, and solar system object information.

def bodvrd(bodynm: str, item: str, maxn: int) -> Tuple[int, ndarray]
def bodn2c(name: str) -> int
def bodc2n(code: int) -> str
def spd() -> float
def rpd() -> float

Physical Constants and Bodies

Event Finding and Search

Advanced search capabilities for finding geometric events such as occultations, oppositions, and user-defined conditions.

def gfdist(target: str, abcorr: str, obsrvr: str, relate: str, refval: float, adjust: float, step: float, cnfine: SpiceCell, result: SpiceCell) -> None
def gfoclt(occtyp: str, front: str, fshape: str, fframe: str, back: str, bshape: str, bframe: str, abcorr: str, obsrvr: str, step: float, cnfine: SpiceCell, result: SpiceCell) -> None

Event Finding and Search

Data Structures and Cells

SPICE-specific data structures including cells, windows, and containers for managing sets of data.

def cell_double(cell_size: int) -> SpiceCell
def cell_int(cell_size: int) -> SpiceCell
def card(cell: SpiceCell) -> int
def size(cell: SpiceCell) -> int

Data Structures and Cells

Error Handling and Utilities

Error management, debugging utilities, and general-purpose functions for SPICE operations.

def failed() -> bool
def reset() -> None
def getmsg(option: str, lenout: int) -> str
def exists(file: str) -> bool

Error Handling and Utilities

E-Kernels (Database Operations)

Database-like functionality for storing, querying, and manipulating structured data in SPICE with full SQL-like query support.

def ekopn(fname: str, ifname: str) -> int
def ekfind(query: str, lenout: int) -> Tuple[int, bool, str]
def ekgc(selidx: int, row: int, lenout: int) -> Tuple[str, bool]
def ekgd(selidx: int, row: int) -> Tuple[float, bool]
def ekinsr(handle: int, segno: int, recno: int) -> None

E-Kernels (Database Operations)

DSK (Digital Shape Kernels)

Advanced 3D shape model operations for celestial bodies using Digital Shape Kernels with high-fidelity surface representations.

def dskopn(fname: str, ifname: str, ncomch: int) -> int
def dskw02(handle: int, center: int, surfid: int, dclass: int, frame: str, corsys: int, corpar: ndarray, mncor1: float, mxcor1: float, mncor2: float, mxcor2: float, mncor3: float, mxcor3: float, first: float, last: float, nv: int, vrtces: ndarray, np: int, plates: ndarray, spaixd: ndarray, spaixi: ndarray) -> None
def dskxv(pri: bool, target: str, nsurf: int, srflst: List[int], et: float, fixref: str, vtx: ndarray, raydir: ndarray) -> Tuple[ndarray, bool]
def dskobj(dsk: str) -> List[int]

DSK (Digital Shape Kernels)

CK (C-Kernels/Orientation Data)

Spacecraft and instrument attitude/pointing data management using C-kernels for precise orientation calculations.

def ckopn(fname: str, ifname: str, ncomch: int) -> int
def ckgp(inst: int, sclkdp: float, tol: float, ref: str) -> Tuple[ndarray, float, bool]
def ckgpav(inst: int, sclkdp: float, tol: float, ref: str) -> Tuple[ndarray, ndarray, float, bool]
def ckw01(handle: int, begtim: float, endtim: float, inst: int, ref: str, avflag: bool, segid: str, nrec: int, sclkdp: ndarray, quats: ndarray, avvs: ndarray) -> None
def ckcov(ck: str, idcode: int, needav: bool, level: str, tol: float, timsys: str, cover: SpiceCell) -> None

CK (C-Kernels/Orientation Data)

Spacecraft Clock Functions

Time correlation functions for converting between spacecraft clock time and other time systems.

def scs2e(sc: int, sclkch: str) -> float
def sce2s(sc: int, et: float) -> str
def sct2e(sc: int, sclkdp: float) -> float
def sce2t(sc: int, et: float) -> float
def scfmt(sc: int, ticks: float) -> str

Spacecraft Clock Functions

Low-Level File Access (DAF/DAS)

Advanced low-level functions for direct access to SPICE data files using DAF and DAS architectures.

def dafopr(fname: str) -> int
def dafbfs(handle: int) -> None
def daffna() -> bool
def dafgda(handle: int, begin: int, end: int) -> ndarray
def dasopn(fname: str, ftype: str, ncomch: int) -> int
def dasadd(handle: int, data: ndarray) -> None

Low-Level File Access (DAF/DAS)

Types

from typing import Union, List, Tuple, Iterable
import numpy as np
from numpy import ndarray

# Core SPICE data structures
class SpiceCell:
    """Base class for SPICE cell data structures"""
    pass

class Cell_Double(SpiceCell):
    """Double precision floating point cell"""
    pass

class Cell_Int(SpiceCell):
    """Integer cell"""
    pass

class Cell_Char(SpiceCell):
    """Character string cell"""
    pass

# Exception hierarchy
class SpiceyError(Exception):
    """Base SPICE exception"""
    pass

class NotFoundError(SpiceyError):
    """Exception raised when requested data is not found"""
    pass

# Common type aliases
Vector3 = ndarray  # 3-element numpy array
Vector6 = ndarray  # 6-element numpy array  
Matrix3x3 = ndarray  # 3x3 numpy array
Matrix6x6 = ndarray  # 6x6 numpy array