tessl/pypi-spiceypy

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

Overview

Eval results

Files

Ephemeris and Trajectories

Name: tessl/pypi-spiceypy
Author: tessl

Functions for computing positions and velocities of celestial bodies, spacecraft, and other objects in the Solar System with high precision. These are the core functions for trajectory analysis and spacecraft navigation.

Capabilities

Position Computations

Compute the position of target objects relative to observers with various aberration corrections.

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]]:
    """
    Return the position of a target body relative to an observer.
    
    Parameters:
    - targ: Union[int, str], target body name or NAIF ID
    - et: Union[float, ndarray], ephemeris time(s) in seconds past J2000
    - ref: str, reference frame ("J2000", "IAU_EARTH", etc.)
    - abcorr: str, aberration correction ("NONE", "LT", "LT+S", "CN", "CN+S")
    - obs: Union[int, str], observer body name or NAIF ID
    
    Returns:
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]: 
    - For scalar ET: (position_vector, light_time)
    - For array ET: (position_vectors, light_times)
    
    position_vector: 3-element array [x, y, z] in km
    light_time: one-way light time in seconds
    """

def spkgeo(targ: int, et: Union[float, ndarray], ref: str, obs: int) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
    """
    Compute geometric position (no aberration corrections).
    
    Parameters:
    - targ: int, target body NAIF ID
    - et: Union[float, ndarray], ephemeris time(s)
    - ref: str, reference frame
    - obs: int, observer body NAIF ID
    
    Returns:
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]: (position, light_time)
    """

Usage example:

import spiceypy as spice

# Load kernels
spice.furnsh("metakernel.mk")

# Get Mars position relative to Earth
et = spice.str2et("2023-07-01T12:00:00")
position, light_time = spice.spkpos(
    "MARS",       # Target
    et,           # Time
    "J2000",      # Reference frame  
    "LT+S",       # Light time + stellar aberration correction
    "EARTH"       # Observer
)

print(f"Mars position: {position} km")
print(f"Light time: {light_time:.2f} seconds")
print(f"Distance: {spice.vnorm(position):.0f} km")

State Vector Computations

Compute both position and velocity (6-element state vectors) for complete kinematic information.

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]]:
    """
    Return the state (position and velocity) of a target relative to observer.
    
    Parameters:
    - targ: Union[int, str], target body name or NAIF ID
    - et: Union[float, ndarray], ephemeris time(s)
    - ref: str, reference frame
    - abcorr: str, aberration correction
    - obs: Union[int, str], observer body name or NAIF ID
    
    Returns:
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
    - For scalar ET: (state_vector, light_time)
    - For array ET: (state_vectors, light_times)
    
    state_vector: 6-element array [x, y, z, vx, vy, vz]
    - Position in km, velocity in km/s
    """

def spkgps(targ: int, et: Union[float, ndarray], ref: str, obs: int) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
    """
    Geometric state (no aberration corrections).
    
    Parameters:
    - targ: int, target body NAIF ID
    - et: Union[float, ndarray], ephemeris time(s)
    - ref: str, reference frame
    - obs: int, observer body NAIF ID
    
    Returns:
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]: (state, light_time)
    """

Advanced Position Functions

Specialized position computation functions for specific use cases.

def spkcpo(target: str, et: float, outref: str, refloc: str, abcorr: str, obspos: ndarray, obsctr: str, obsref: str) -> Tuple[ndarray, float]:
    """
    Return position of target relative to constant observer position.
    
    Parameters:
    - target: str, target body name
    - et: float, ephemeris time
    - outref: str, output reference frame
    - refloc: str, reference location ("CENTER", "OBSERVER")
    - abcorr: str, aberration correction
    - obspos: ndarray, observer position vector
    - obsctr: str, observer frame center
    - obsref: str, observer reference frame
    
    Returns:
    Tuple[ndarray, float]: (position, light_time)
    """

def spkcpt(trgpos: ndarray, trgctr: str, trgref: str, et: float, outref: str, refloc: str, abcorr: str, obsrvr: str) -> Tuple[ndarray, float]:
    """
    Return position of constant target position relative to observer.
    
    Parameters:
    - trgpos: ndarray, target position vector
    - trgctr: str, target frame center  
    - trgref: str, target reference frame
    - et: float, ephemeris time
    - outref: str, output reference frame
    - refloc: str, reference location
    - abcorr: str, aberration correction
    - obsrvr: str, observer body name
    
    Returns:
    Tuple[ndarray, float]: (position, light_time)
    """

def spkcvo(target: str, et: float, outref: str, refloc: str, abcorr: str, obssta: ndarray, obsepc: float, obsctr: str, obsref: str) -> Tuple[ndarray, float]:
    """
    Return state of target relative to constant observer state.
    
    Parameters:
    - target: str, target body name
    - et: float, ephemeris time
    - outref: str, output reference frame
    - refloc: str, reference location
    - abcorr: str, aberration correction
    - obssta: ndarray, observer state vector
    - obsepc: float, observer epoch
    - obsctr: str, observer frame center
    - obsref: str, observer reference frame
    
    Returns:
    Tuple[ndarray, float]: (state, light_time)
    """

Apparent Positions

Functions for computing apparent positions accounting for light time and stellar aberration.

def spkapp(targ: Union[int, str], et: float, ref: str, sobs: ndarray, abcorr: str) -> Tuple[ndarray, float]:
    """
    Return apparent state of target as seen by observer.
    
    Parameters:
    - targ: Union[int, str], target body
    - et: float, ephemeris time
    - ref: str, reference frame
    - sobs: ndarray, observer state vector
    - abcorr: str, aberration correction
    
    Returns:
    Tuple[ndarray, float]: (apparent_state, light_time)
    """

def spkapo(targ: Union[int, str], et: float, ref: str, sobs: ndarray, abcorr: str) -> Tuple[ndarray, float]:
    """
    Return apparent position of target as seen by observer.
    
    Parameters:
    - targ: Union[int, str], target body
    - et: float, ephemeris time
    - ref: str, reference frame
    - sobs: ndarray, observer state vector
    - abcorr: str, aberration correction
    
    Returns:
    Tuple[ndarray, float]: (apparent_position, light_time)
    """

Solar System Barycenter Functions

Functions for computing states relative to the solar system barycenter.

def spkssb(targ: Union[int, str], et: Union[float, ndarray], ref: str) -> Union[ndarray, ndarray]:
    """
    Return state of target relative to solar system barycenter.
    
    Parameters:
    - targ: Union[int, str], target body
    - et: Union[float, ndarray], ephemeris time(s)
    - ref: str, reference frame
    
    Returns:
    Union[ndarray, ndarray]: state vector(s) relative to SSB
    """

def spkssb_c(targ: int, et: float, ref: str) -> ndarray:
    """
    Return state of target relative to solar system barycenter (C version).
    
    Parameters:
    - targ: int, target body NAIF ID
    - et: float, ephemeris time
    - ref: str, reference frame
    
    Returns:
    ndarray: 6-element state vector [x, y, z, vx, vy, vz]
    """

Aberration Corrections

Understanding aberration correction options is crucial for accurate ephemeris computations:

"NONE": No corrections applied (geometric positions)
"LT": One-way light time correction only
"LT+S": Light time plus stellar aberration correction
"CN": Converged Newtonian light time correction
"CN+S": Converged Newtonian light time plus stellar aberration
"XLT": Transmission case light time correction
"XLT+S": Transmission case light time plus stellar aberration
"XCN": Transmission case converged Newtonian correction
"XCN+S": Transmission case converged Newtonian plus stellar aberration

Common Usage Patterns

Basic Position Query

import spiceypy as spice
import numpy as np

# Load kernels
spice.furnsh("metakernel.mk")

# Get current position of Mars relative to Earth
et = spice.str2et("now")
pos, lt = spice.spkpos("MARS", et, "J2000", "LT+S", "EARTH")

# Calculate distance and direction
distance = spice.vnorm(pos)  # km
unit_vector = spice.vhat(pos)  # direction

print(f"Mars distance: {distance:,.0f} km")
print(f"Light time: {lt/60:.1f} minutes")

spice.kclear()

Trajectory Analysis Over Time

# Create time array (24 hours with 1-hour intervals)
start_et = spice.str2et("2023-01-01T00:00:00")
times = [start_et + i * 3600 for i in range(24)]  # 24 hours

# Get Mars positions over 24 hours
positions, light_times = spice.spkpos("MARS", times, "J2000", "LT+S", "EARTH")

# Analyze trajectory
distances = [spice.vnorm(pos) for pos in positions]
print(f"Distance range: {min(distances):,.0f} - {max(distances):,.0f} km")

Multiple Body Positions

# Get positions of multiple planets at the same time
et = spice.str2et("2023-01-01T12:00:00")
bodies = ["MERCURY", "VENUS", "MARS", "JUPITER", "SATURN"]

for body in bodies:
    pos, lt = spice.spkpos(body, et, "J2000", "LT+S", "EARTH")
    distance = spice.vnorm(pos)
    print(f"{body}: {distance:,.0f} km")

State Vector Analysis

# Get complete state vector (position + velocity)
state, lt = spice.spkezr("MARS", et, "J2000", "LT+S", "EARTH")

# Extract position and velocity components
position = state[:3]  # First 3 elements: x, y, z (km)
velocity = state[3:]  # Last 3 elements: vx, vy, vz (km/s)

speed = spice.vnorm(velocity)  # km/s
print(f"Mars relative speed: {speed:.3f} km/s")

Install with Tessl CLI