Skip to content

SPICE Fundamentals

OpenSpace relies on NASA's NAIF SPICE toolkit to compute high-precision positions, orientations, and reference frames for planets, moons, and spacecraft across past and future mission timelines.

Core SPICE Kernel Types

SPICE data is distributed in modular binary or text files called kernels, each handling a specific piece of ephemeris or timekeeping math:

Extension Kernel Type Purpose in OpenSpace
.bsp SPK (Spacecraft & Planet Ephemeris) Stores 3D position and velocity trajectories (X, Y, Z, VX, VY, VZ) over time.
.tls LSK (Leapseconds Kernel) Converts UTC calendar strings into SPICE Ephemeris Time (ET / TDB).
.tpc PCK (Planetary Constants Kernel) Defines planetary radii, triaxial shapes, and prime meridian spin rates.
.tf FK (Frame Kernel) Defines custom coordinate frames relative to standard frames like J2000.
.bc CK (Camera / Attitude Kernel) Stores spacecraft orientation and instrument pointing telemetry.
.tsc SCLK (Spacecraft Clock Kernel) Correlates onboard spacecraft mission elapsed ticks with UTC/ET.

How SpiceTranslation Resolves Positions

When OpenSpace evaluates a SpiceTranslation block, it traces a chain of frames and bodies between Observer and Target using every loaded .bsp and .tls kernel in memory:

Translation = {
    Type = "SpiceTranslation",
    Target = "CASSINI",             -- (1)!
    Observer = "SATURN BARYCENTER", -- (2)!
    Kernels = {                     -- (3)!
        asset.localResource("cassini_tour.bsp"),
        asset.localResource("naif0012.tls")
    }
}
  1. Target: The NAIF body name or integer ID of the object being positioned (e.g., "JUNO", "-82", or "MARS").
  2. Observer: The origin point for the vector calculation—usually matches your SceneGraphNode's Parent (e.g., "EARTH", "SUN", or "SATURN BARYCENTER").
  3. Kernels: Accepts a single file path or a table of multiple .bsp, .tls, and .tf files required to bridge the chain between Observer and Target.

Use NAIF Body Names or Integer IDs Interchangeably

SPICE recognizes both official string names ("ISS", "MARS RECONNAISSANCE ORBITER") and integer NAIF IDs ("-125544", "-74"). Custom mkspk trajectories that do not have a built-in name mapping in NAIF's dictionary must be referenced by their stringified integer ID (e.g., "-999001").

Inspecting Kernels Before Loading (brief & spacit)

Before adding a downloaded NAIF .bsp file into OpenSpace, inspect which bodies and time windows it actually covers so you don't hit runtime SPICE lookup errors:

.\brief.exe -c -t custom_mission.bsp naif0012.tls

.\spacit.exe
# Select: S (Summarize SPK file)
# Enter leapseconds kernel: naif0012.tls
# Enter SPK file: custom_mission.bsp

Screenshot Placeholder: spice-observer-target-diagram.png

  • Diagram / Crop: A clean vector diagram showing the Observer (e.g., Earth at center), Target (Spacecraft), the J2000 inertial axes, and how SpiceTranslation connects Parent Observer Target.
  • Callouts: (1) Observer origin matching Parent node, (2) Relative state vector from .bsp, (3) J2000 reference frame axes.

Common SPICE Errors in log.html

Error Message in logs/log.html Root Cause Fix
SPICE(SPKINSUFFDATA) Simulation clock is outside the .bsp file's start/stop dates, or a bridging body kernel is missing. Check valid dates with brief.exe and ensure your profile starts inside that window.
SPICE(BODIESNOTDISTINCT) Target and Observer resolve to the exact same NAIF ID. Set Observer to the parent planet/barycenter rather than the spacecraft itself.
SPICE(NOLEAPSECONDS) No .tls kernel was loaded before evaluating a UTC date string. Include naif0012.tls in Kernels or require the base solar system SPICE asset first.