spicekit 0.2.2

Pure-Rust reader for NASA/NAIF SPICE kernel formats (DAF, SPK, PCK, text kernels). Independent of the CSpice toolkit.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# spicekit

[![crates.io](https://img.shields.io/crates/v/spicekit.svg)](https://crates.io/crates/spicekit)
[![docs.rs](https://docs.rs/spicekit/badge.svg)](https://docs.rs/spicekit)
[![PyPI](https://img.shields.io/pypi/v/spicekit.svg)](https://pypi.org/project/spicekit/)
[![CI](https://github.com/B612-Asteroid-Institute/spicekit/actions/workflows/ci.yml/badge.svg)](https://github.com/B612-Asteroid-Institute/spicekit/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

spicekit is an independent, pure-Rust reader for the SPICE kernel formats
(DAF containers, SPK ephemeris files, binary PCK rotation files, and the
supported text-kernel subset used for body-name bindings, leapseconds,
and the Earth→ITRF93 frame association). It is **not affiliated
with or endorsed by NAIF/JPL, and it is not a port of the CSpice
toolkit** — all executable logic is an independent implementation
written from the published NAIF file-format specifications, with no
CSpice linkage and no translated CSpice source. The only CSpice-derived
artifact shipped in this crate is the 692-entry body-name table in
`src/naif_builtin_table.rs`, which is reproduced under NAIF's
distribution terms (see [`LICENSE-NOTICES`](./LICENSE-NOTICES)).

## Install

### Rust

```toml
[dependencies]
spicekit = "0.2"
```

### Python

```bash
pip install spicekit
```

## Scope

`spicekit` implements a focused, embeddable subset of SPICE kernel I/O
and frame evaluation:

- **DAF**: memory-mapped container parser (shared by SPK and PCK)
- **SPK**: reader for Types 2, 3, 9, 13; writer for Types 3 and 9
- **PCK**: binary PCK reader producing J2000↔ITRF93 rotations and their
  time derivatives at machine precision
- **Text kernels**: parser for `NAIF_BODY_NAME` / `NAIF_BODY_CODE` paired
  arrays (custom name ↔ code bindings used by mission kernels),
  leapseconds-kernel `DELTET/*` values from `KPL/LSK`, and the narrow
  `OBJECT_EARTH_FRAME = 'ITRF93'` FK association used with binary Earth
  PCKs. Other text-kernel assignments are skipped by the parser on a
  best-effort basis; furnsh-style loaders should reject otherwise-empty
  unsupported text kernels instead of silently dropping them.
- **Built-in NAIF body table**: the 692-entry name ↔ ID map mirrored from
  CSpice's `zzidmap.c`, with case-insensitive whitespace-tolerant
  matching.

## Non-goals

- No async I/O — sync memory-mapped reads only.
- No CSpice linkage and no FFI in the base crate. CSpice parity is
  verified in the sibling `spicekit-bench` crate, which links `cspice-sys`
  behind a feature flag and compares every code path against CSpice at
  machine-epsilon tolerance.
- No CLI tool.
- PCK support is read-only.

## Python bindings

Python bindings are provided by the `spicekit-py` crate in this
workspace (shipped to PyPI as the `spicekit` package). Build and install
with [maturin](https://github.com/PyO3/maturin):

```bash
maturin develop --release --manifest-path crates/spicekit-py/Cargo.toml
```

Then:

```python
import spicekit
spk = spicekit.NaifSpk("/path/to/de440.bsp")
```

## Parity testing and benchmarks

`spicekit-bench` keeps an FFI-based CSpice reference installation and
asserts that every spicekit numeric path and supported text-kernel
semantic matches CSpice at a science-grade tolerance. It also runs
side-by-side latency microbenchmarks on matched inputs; the latest
numbers (regenerated by CI on every push to `main`) live in
[`BENCHMARKS.md`](./BENCHMARKS.md).

The base crate's MSRV is the workspace `rust-version`; local
`--features cspice` runs may require a newer stable toolchain because
transitive `cspice-sys` build dependencies can outpace the base MSRV, so
use `cargo +stable ... --features cspice` when needed.

See each module's rustdoc for details.

## License and attribution

Licensed under the [MIT License](./LICENSE).

The file `src/naif_builtin_table.rs` contains data extracted from the
NAIF CSpice toolkit (specifically, the NPERM table in `zzidmap.c`). The
NAIF toolkit is distributed by the Jet Propulsion Laboratory under terms
that permit redistribution with attribution — see `LICENSE-NOTICES` for
the full attribution and the relevant NAIF distribution-terms excerpt.

## Test layers

spicekit's own test suite verifies internal correctness (DAF round-trip,
Chebyshev polynomial exactness on coefficient tables, Lagrange exactness
at knot points, text-kernel parsing for body bindings, LSK `DELTET/*`,
and the Earth→ITRF93 FK association, etc.). CSpice-parity testing —
confirming that spicekit's numeric output and supported text-kernel
semantics match CSpice at a science-grade tolerance — lives in
`crates/spicekit-bench`, which links the CSpice toolkit and asserts
parity on every code path.