CtrlK
BlogDocsLog inGet started
Tessl Logo

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

coordinate-systems.mddocs/

Coordinate Systems

Comprehensive coordinate system transformations including rectangular, spherical, cylindrical, latitudinal, and various planetary coordinate systems. These functions enable conversion between different geometric representations used in space science.

Capabilities

Spherical Coordinates

Convert between rectangular (Cartesian) and spherical coordinate systems.

def sphrec(r: float, colat: float, lon: float) -> ndarray:
    """
    Convert spherical coordinates to rectangular coordinates.
    
    Parameters:
    - r: float, distance from origin
    - colat: float, colatitude in radians (angle from +Z axis)
    - lon: float, longitude in radians
    
    Returns:
    ndarray: 3-element rectangular coordinate vector [x, y, z]
    """

def recsph(rectan: ndarray) -> Tuple[float, float, float]:
    """
    Convert rectangular coordinates to spherical coordinates.
    
    Parameters:
    - rectan: ndarray, 3-element rectangular coordinate vector
    
    Returns:
    Tuple[float, float, float]: (r, colat, lon)
    - r: distance from origin
    - colat: colatitude in radians
    - lon: longitude in radians
    """

Latitudinal Coordinates

Convert between rectangular and latitudinal coordinate systems (latitude/longitude).

def latrec(radius: float, lon: float, lat: float) -> ndarray:
    """
    Convert latitudinal coordinates to rectangular coordinates.
    
    Parameters:
    - radius: float, distance from origin
    - lon: float, longitude in radians
    - lat: float, latitude in radians
    
    Returns:
    ndarray: 3-element rectangular coordinate vector [x, y, z]
    """

def reclat(rectan: ndarray) -> Tuple[float, float, float]:
    """
    Convert rectangular coordinates to latitudinal coordinates.
    
    Parameters:
    - rectan: ndarray, 3-element rectangular coordinate vector
    
    Returns:
    Tuple[float, float, float]: (radius, lon, lat)
    - radius: distance from origin
    - lon: longitude in radians
    - lat: latitude in radians
    """

Cylindrical Coordinates

Convert between rectangular and cylindrical coordinate systems.

def cylrec(r: float, lon: float, z: float) -> ndarray:
    """
    Convert cylindrical coordinates to rectangular coordinates.
    
    Parameters:
    - r: float, radial distance from Z-axis
    - lon: float, longitude in radians
    - z: float, height above XY-plane
    
    Returns:
    ndarray: 3-element rectangular coordinate vector [x, y, z]
    """

def reccyl(rectan: ndarray) -> Tuple[float, float, float]:
    """
    Convert rectangular coordinates to cylindrical coordinates.
    
    Parameters:
    - rectan: ndarray, 3-element rectangular coordinate vector
    
    Returns:
    Tuple[float, float, float]: (r, lon, z)
    - r: radial distance from Z-axis
    - lon: longitude in radians
    - z: height above XY-plane
    """

Coordinate System Conversions

Convert between different coordinate systems directly.

def sphlat(r: float, colat: float, lon: float) -> Tuple[float, float, float]:
    """
    Convert spherical coordinates to latitudinal coordinates.
    
    Parameters:
    - r: float, distance from origin
    - colat: float, colatitude in radians
    - lon: float, longitude in radians
    
    Returns:
    Tuple[float, float, float]: (radius, longitude, latitude)
    """

def latsph(radius: float, lon: float, lat: float) -> Tuple[float, float, float]:
    """
    Convert latitudinal coordinates to spherical coordinates.
    
    Parameters:
    - radius: float, distance from origin
    - lon: float, longitude in radians
    - lat: float, latitude in radians
    
    Returns:
    Tuple[float, float, float]: (r, colatitude, longitude)
    """

def cyllat(r: float, lonc: float, z: float) -> Tuple[float, float, float]:
    """
    Convert cylindrical coordinates to latitudinal coordinates.
    
    Parameters:
    - r: float, radial distance from Z-axis
    - lonc: float, longitude in radians
    - z: float, height above XY-plane
    
    Returns:
    Tuple[float, float, float]: (radius, longitude, latitude)
    """

def latcyl(radius: float, lon: float, lat: float) -> Tuple[float, float, float]:
    """
    Convert latitudinal coordinates to cylindrical coordinates.
    
    Parameters:
    - radius: float, distance from origin
    - lon: float, longitude in radians
    - lat: float, latitude in radians
    
    Returns:
    Tuple[float, float, float]: (r, longitude, z)
    """

Geodetic Coordinates

Convert between rectangular and geodetic coordinate systems for planetary surfaces.

def georec(lon: float, lat: float, alt: float, re: float, f: float) -> ndarray:
    """
    Convert geodetic coordinates to rectangular coordinates.
    
    Parameters:
    - lon: float, longitude in radians
    - lat: float, latitude in radians  
    - alt: float, altitude above reference ellipsoid
    - re: float, equatorial radius of reference ellipsoid
    - f: float, flattening coefficient
    
    Returns:
    ndarray: 3-element rectangular coordinate vector [x, y, z]
    """

def recgeo(rectan: ndarray, re: float, f: float) -> Tuple[float, float, float]:
    """
    Convert rectangular coordinates to geodetic coordinates.
    
    Parameters:
    - rectan: ndarray, 3-element rectangular coordinate vector
    - re: float, equatorial radius of reference ellipsoid
    - f: float, flattening coefficient
    
    Returns:
    Tuple[float, float, float]: (lon, lat, alt)
    - lon: longitude in radians
    - lat: latitude in radians
    - alt: altitude above reference ellipsoid
    """

Planetographic Coordinates

Convert between rectangular and planetographic coordinate systems.

def pgrrec(body: str, lon: float, lat: float, alt: float, re: float, f: float) -> ndarray:
    """
    Convert planetographic coordinates to rectangular coordinates.
    
    Parameters:
    - body: str, name of central body
    - lon: float, longitude in radians
    - lat: float, latitude in radians
    - alt: float, altitude above reference ellipsoid
    - re: float, equatorial radius
    - f: float, flattening coefficient
    
    Returns:
    ndarray: 3-element rectangular coordinate vector [x, y, z]
    """

def recpgr(body: str, rectan: ndarray, re: float, f: float) -> Tuple[float, float, float]:
    """
    Convert rectangular coordinates to planetographic coordinates.
    
    Parameters:
    - body: str, name of central body
    - rectan: ndarray, 3-element rectangular coordinate vector
    - re: float, equatorial radius
    - f: float, flattening coefficient
    
    Returns:
    Tuple[float, float, float]: (lon, lat, alt)
    - lon: longitude in radians
    - lat: latitude in radians  
    - alt: altitude above reference ellipsoid
    """

Range/RA/DEC Coordinates

Convert between rectangular and range/right ascension/declination coordinates.

def radrec(range: float, ra: float, dec: float) -> ndarray:
    """
    Convert range, right ascension, and declination to rectangular coordinates.
    
    Parameters:
    - range: float, distance from origin
    - ra: float, right ascension in radians
    - dec: float, declination in radians
    
    Returns:
    ndarray: 3-element rectangular coordinate vector [x, y, z]
    """

def recrad(rectan: ndarray) -> Tuple[float, float, float]:
    """
    Convert rectangular coordinates to range, right ascension, declination.
    
    Parameters:
    - rectan: ndarray, 3-element rectangular coordinate vector
    
    Returns:
    Tuple[float, float, float]: (range, ra, dec)
    - range: distance from origin
    - ra: right ascension in radians
    - dec: declination in radians
    """

Azimuth/Elevation Coordinates

Convert between rectangular and azimuth/elevation coordinates.

def azlrec(r: float, az: float, el: float) -> ndarray:
    """
    Convert azimuth and elevation to rectangular coordinates.
    
    Parameters:
    - r: float, distance from origin
    - az: float, azimuth in radians
    - el: float, elevation in radians
    
    Returns:
    ndarray: 3-element rectangular coordinate vector [x, y, z]
    """

def recazl(rectan: ndarray, azccw: bool, elplsz: bool) -> Tuple[float, float, float]:
    """
    Convert rectangular coordinates to azimuth and elevation.
    
    Parameters:
    - rectan: ndarray, 3-element rectangular coordinate vector
    - azccw: bool, azimuth counter-clockwise flag
    - elplsz: bool, elevation plus Z flag
    
    Returns:
    Tuple[float, float, float]: (range, azimuth, elevation)
    - range: distance from origin
    - azimuth: azimuth in radians
    - elevation: elevation in radians
    """

Common Usage Patterns

Basic Coordinate Conversion

import spiceypy as spice
import numpy as np

# Convert spherical to rectangular coordinates
r = 1000.0  # 1000 km
colat = spice.rpd() * 30.0  # 30 degrees colatitude
lon = spice.rpd() * 45.0    # 45 degrees longitude

rect_coords = spice.sphrec(r, colat, lon)
print(f"Rectangular: {rect_coords}")

# Convert back to spherical
r_back, colat_back, lon_back = spice.recsph(rect_coords)
print(f"Spherical: r={r_back:.1f}, colat={spice.dpr()*colat_back:.1f}°, lon={spice.dpr()*lon_back:.1f}°")

Planetary Surface Coordinates

# Convert Earth geodetic coordinates to rectangular
# Location: San Francisco, CA
lon_sf = spice.rpd() * -122.4194  # Longitude (west is negative)
lat_sf = spice.rpd() * 37.7749    # Latitude
alt_sf = 0.052                    # Altitude in km (52 meters)

# Earth parameters
re_earth = 6378.1366              # Equatorial radius in km
f_earth = 0.00335281066           # Flattening coefficient

rect_sf = spice.georec(lon_sf, lat_sf, alt_sf, re_earth, f_earth)
print(f"San Francisco rectangular coordinates: {rect_sf}")

# Convert back to geodetic
lon_back, lat_back, alt_back = spice.recgeo(rect_sf, re_earth, f_earth)
print(f"Geodetic: lon={spice.dpr()*lon_back:.4f}°, lat={spice.dpr()*lat_back:.4f}°, alt={alt_back*1000:.1f}m")

Mars Surface Operations

# Convert Mars planetographic coordinates to rectangular
# Using Olympus Mons coordinates
lon_olympus = spice.rpd() * -133.8  # West longitude
lat_olympus = spice.rpd() * 18.65   # North latitude  
alt_olympus = 21.9                  # Altitude in km above datum

# Mars parameters
re_mars = 3396.19                   # Equatorial radius in km
f_mars = 0.00518498                 # Flattening coefficient

rect_olympus = spice.pgrrec("MARS", lon_olympus, lat_olympus, alt_olympus, re_mars, f_mars)
print(f"Olympus Mons rectangular coordinates: {rect_olympus}")

Astronomical Coordinate Conversion

# Convert astronomical coordinates (RA/DEC) to rectangular
range_star = 50.0  # Distance in parsecs (example)
ra_star = spice.rpd() * 83.633     # Right ascension in degrees (Betelgeuse)
dec_star = spice.rpd() * 7.407     # Declination in degrees

rect_star = spice.radrec(range_star, ra_star, dec_star)
print(f"Star position vector: {rect_star}")

# Convert back to RA/DEC
range_back, ra_back, dec_back = spice.recrad(rect_star)
print(f"RA/DEC: RA={spice.dpr()*ra_back:.3f}°, DEC={spice.dpr()*dec_back:.3f}°, Range={range_back:.1f}")

Vector Coordinate Analysis

# Analyze a position vector in different coordinate systems
position = np.array([1000.0, 1500.0, 2000.0])  # km

# Spherical analysis
r, colat, lon = spice.recsph(position)
print(f"Spherical: r={r:.1f} km, colat={spice.dpr()*colat:.1f}°, lon={spice.dpr()*lon:.1f}°")

# Latitudinal analysis  
radius, lon_lat, lat = spice.reclat(position)
print(f"Latitudinal: r={radius:.1f} km, lon={spice.dpr()*lon_lat:.1f}°, lat={spice.dpr()*lat:.1f}°")

# Cylindrical analysis
r_cyl, lon_cyl, z_cyl = spice.reccyl(position)
print(f"Cylindrical: r={r_cyl:.1f} km, lon={spice.dpr()*lon_cyl:.1f}°, z={z_cyl:.1f} km")

Install with Tessl CLI

npx tessl i tessl/pypi-spiceypy

docs

ck-orientation.md

coordinate-systems.md

data-structures.md

dsk-shape-models.md

e-kernels.md

ephemeris-trajectories.md

error-handling.md

event-finding.md

geometry-surface.md

index.md

kernel-management.md

low-level-file-access.md

physical-constants.md

reference-frames.md

spacecraft-clock.md

time-systems.md

vector-matrix.md

tile.json