0
# SpiceyPy
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: spiceypy
7
- **Language**: Python
8
- **Installation**: `pip install spiceypy` or `conda install -c conda-forge spiceypy`
9
- **Requirements**: Python 3.8+, NumPy ≥1.23.5
10
- **Architecture**: 64-bit (Linux, macOS, Windows, FreeBSD)
11

12
## Core Imports
13

14
```python
15
import spiceypy as spice
16
```
17

18
Alternative import for convenience:
19

20
```python
21
from spiceypy import *
22
```
23

24
Import specific functions:
25

26
```python
27
from spiceypy import furnsh, str2et, spkpos, kclear
28
```
29

30
## Basic Usage
31

32
```python
33
import spiceypy as spice
34
import numpy as np
35

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

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

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

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

54
# Clean up - unload all kernels
55
spice.kclear()
56
```
57

58
## Architecture
59

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

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

68
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).
69

70
## Capabilities
71

72
### Kernel Management
73

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

76
```python { .api }
77
def furnsh(kernel: str) -> None
78
def kclear() -> None
79
def unload(kernel: str) -> None
80
def ktotal(kind: str) -> int
81
```
82

83
[Kernel Management](./kernel-management.md)
84

85
### Time Systems
86

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

89
```python { .api }
90
def str2et(time: Union[str, Iterable[str]]) -> Union[float, ndarray]
91
def et2utc(et: Union[float, ndarray], format: str, prec: int) -> Union[str, List[str]]
92
def utc2et(utcstr: str) -> float
93
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]]]
94
```
95

96
[Time Systems](./time-systems.md)
97

98
### Ephemeris and Trajectories
99

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

102
```python { .api }
103
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]]
104
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]]
105
def spkgeo(targ: int, et: Union[float, ndarray], ref: str, obs: int) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]
106
```
107

108
[Ephemeris and Trajectories](./ephemeris-trajectories.md)
109

110
### Coordinate Systems
111

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

114
```python { .api }
115
def sphrec(r: float, colat: float, lon: float) -> ndarray
116
def recsph(rectan: ndarray) -> Tuple[float, float, float]
117
def georec(lon: float, lat: float, alt: float, re: float, f: float) -> ndarray
118
def recgeo(rectan: ndarray, re: float, f: float) -> Tuple[float, float, float]
119
```
120

121
[Coordinate Systems](./coordinate-systems.md)
122

123
### Reference Frames
124

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

127
```python { .api }
128
def pxform(from_frame: str, to_frame: str, et: Union[float, ndarray]) -> Union[ndarray, ndarray]
129
def sxform(from_frame: str, to_frame: str, et: Union[float, ndarray]) -> Union[ndarray, ndarray]
130
def frmnam(frcode: int) -> str
131
def namfrm(frname: str) -> int
132
```
133

134
[Reference Frames](./reference-frames.md)
135

136
### Geometry and Surface Analysis
137

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

140
```python { .api }
141
def sincpt(method: str, target: str, et: float, fixref: str, abcorr: str, obsrvr: str, dref: str, dvec: ndarray) -> Tuple[ndarray, float, ndarray, bool]
142
def subpnt(method: str, target: str, et: float, fixref: str, abcorr: str, obsrvr: str) -> Tuple[ndarray, float, ndarray]
143
def illum(target: str, et: float, abcorr: str, obsrvr: str, spoint: ndarray) -> Tuple[float, float, float]
144
```
145

146
[Geometry and Surface Analysis](./geometry-surface.md)
147

148
### Vector and Matrix Mathematics
149

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

152
```python { .api }
153
def vadd(v1: ndarray, v2: ndarray) -> ndarray
154
def vsub(v1: ndarray, v2: ndarray) -> ndarray
155
def vdot(v1: ndarray, v2: ndarray) -> float
156
def vcrss(v1: ndarray, v2: ndarray) -> ndarray
157
def mxm(m1: ndarray, m2: ndarray) -> ndarray
158
```
159

160
[Vector and Matrix Mathematics](./vector-matrix.md)
161

162
### Physical Constants and Bodies
163

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

166
```python { .api }
167
def bodvrd(bodynm: str, item: str, maxn: int) -> Tuple[int, ndarray]
168
def bodn2c(name: str) -> int
169
def bodc2n(code: int) -> str
170
def spd() -> float
171
def rpd() -> float
172
```
173

174
[Physical Constants and Bodies](./physical-constants.md)
175

176
### Event Finding and Search
177

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

180
```python { .api }
181
def gfdist(target: str, abcorr: str, obsrvr: str, relate: str, refval: float, adjust: float, step: float, cnfine: SpiceCell, result: SpiceCell) -> None
182
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
183
```
184

185
[Event Finding and Search](./event-finding.md)
186

187
### Data Structures and Cells
188

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

191
```python { .api }
192
def cell_double(cell_size: int) -> SpiceCell
193
def cell_int(cell_size: int) -> SpiceCell
194
def card(cell: SpiceCell) -> int
195
def size(cell: SpiceCell) -> int
196
```
197

198
[Data Structures and Cells](./data-structures.md)
199

200
### Error Handling and Utilities
201

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

204
```python { .api }
205
def failed() -> bool
206
def reset() -> None
207
def getmsg(option: str, lenout: int) -> str
208
def exists(file: str) -> bool
209
```
210

211
[Error Handling and Utilities](./error-handling.md)
212

213
### E-Kernels (Database Operations)
214

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

217
```python { .api }
218
def ekopn(fname: str, ifname: str) -> int
219
def ekfind(query: str, lenout: int) -> Tuple[int, bool, str]
220
def ekgc(selidx: int, row: int, lenout: int) -> Tuple[str, bool]
221
def ekgd(selidx: int, row: int) -> Tuple[float, bool]
222
def ekinsr(handle: int, segno: int, recno: int) -> None
223
```
224

225
[E-Kernels (Database Operations)](./e-kernels.md)
226

227
### DSK (Digital Shape Kernels)
228

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

231
```python { .api }
232
def dskopn(fname: str, ifname: str, ncomch: int) -> int
233
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
234
def dskxv(pri: bool, target: str, nsurf: int, srflst: List[int], et: float, fixref: str, vtx: ndarray, raydir: ndarray) -> Tuple[ndarray, bool]
235
def dskobj(dsk: str) -> List[int]
236
```
237

238
[DSK (Digital Shape Kernels)](./dsk-shape-models.md)
239

240
### CK (C-Kernels/Orientation Data)
241

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

244
```python { .api }
245
def ckopn(fname: str, ifname: str, ncomch: int) -> int
246
def ckgp(inst: int, sclkdp: float, tol: float, ref: str) -> Tuple[ndarray, float, bool]
247
def ckgpav(inst: int, sclkdp: float, tol: float, ref: str) -> Tuple[ndarray, ndarray, float, bool]
248
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
249
def ckcov(ck: str, idcode: int, needav: bool, level: str, tol: float, timsys: str, cover: SpiceCell) -> None
250
```
251

252
[CK (C-Kernels/Orientation Data)](./ck-orientation.md)
253

254
### Spacecraft Clock Functions
255

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

258
```python { .api }
259
def scs2e(sc: int, sclkch: str) -> float
260
def sce2s(sc: int, et: float) -> str
261
def sct2e(sc: int, sclkdp: float) -> float
262
def sce2t(sc: int, et: float) -> float
263
def scfmt(sc: int, ticks: float) -> str
264
```
265

266
[Spacecraft Clock Functions](./spacecraft-clock.md)
267

268
### Low-Level File Access (DAF/DAS)
269

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

272
```python { .api }
273
def dafopr(fname: str) -> int
274
def dafbfs(handle: int) -> None
275
def daffna() -> bool
276
def dafgda(handle: int, begin: int, end: int) -> ndarray
277
def dasopn(fname: str, ftype: str, ncomch: int) -> int
278
def dasadd(handle: int, data: ndarray) -> None
279
```
280

281
[Low-Level File Access (DAF/DAS)](./low-level-file-access.md)
282

283
## Types
284

285
```python { .api }
286
from typing import Union, List, Tuple, Iterable
287
import numpy as np
288
from numpy import ndarray
289

290
# Core SPICE data structures
291
class SpiceCell:
292
    """Base class for SPICE cell data structures"""
293
    pass
294

295
class Cell_Double(SpiceCell):
296
    """Double precision floating point cell"""
297
    pass
298

299
class Cell_Int(SpiceCell):
300
    """Integer cell"""
301
    pass
302

303
class Cell_Char(SpiceCell):
304
    """Character string cell"""
305
    pass
306

307
# Exception hierarchy
308
class SpiceyError(Exception):
309
    """Base SPICE exception"""
310
    pass
311

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

316
# Common type aliases
317
Vector3 = ndarray  # 3-element numpy array
318
Vector6 = ndarray  # 6-element numpy array  
319
Matrix3x3 = ndarray  # 3x3 numpy array
320
Matrix6x6 = ndarray  # 6x6 numpy array
321
```