Skip to content

gps_frames

Reference frame representation, transformations, and operations for GPS.

Test Python package Coverage PyPI version PyPI pyversions License CodeQL Upload Python Package

Documentation | GitHub | PyPI

Installation

This module can be installed using PyPI: 

pip install gps-frames

Quick Start

Here is a simple example of how to calculate the distance between a ground station and a satellite.

import numpy as np
from datetime import datetime
from gps_time import GPSTime
from gps_frames import Position, distance

# 1. Define the time of interest
time = GPSTime.from_datetime(datetime(2023, 1, 1, 12, 0, 0))

# 2. Define a Ground Station (Los Angeles) in Geodetic coordinates (LLA)
ground_station = Position(
    np.array([34.05 * np.pi / 180, -118.25 * np.pi / 180, 100.0]), # Lat (rad), Lon (rad), Alt (m)
    time,
    "LLA"
)

# 3. Define a Satellite (GPS) in ECEF coordinates
# (Simplified position for demonstration)
satellite = Position(
    np.array([15000e3, 15000e3, 15000e3]), # x, y, z in meters
    time,
    "ECEF"
)

# 4. Calculate distance
dist = distance(ground_station, satellite)
print(f"Distance: {dist/1000:.2f} km")

# 5. Convert frames easily
ground_station_ecef = ground_station.get_position("ECEF")
print(f"Ground Station ECEF: {ground_station_ecef.coordinates}")

Running Tests

This module includes tests for all of the major functionality. To run the tests, you can use the commands in the makefile make test. Because some of the functions use JIT compilation via Numba, make test-nojit runs all of the tests without JIT compilation to enable better code coverage analysis.

Using gps_frames

The motivating use case of this module is to determine distances between two points in space while accounting for non-inertial reference frames and non-simultaneous position measures. The examples/ directory contains scripts demonstrating the library's capabilities:

  • examples/example.py: A basic walkthrough of creating Positions, checking visibility, and calculating ranges/azimuths.
  • examples/case_study_satellite_tracking.py: An advanced case study simulating a 3-day satellite pass from a ground station, demonstrating orbit propagation, coordinate frame rotations, and custom basis projections.

To run the examples: 

# Basic example
python examples/example.py

# Advanced Case Study (requires matplotlib)
pip install .[examples]
python examples/case_study_satellite_tracking.py

Note: When first run, gps-frames has significant overhead due to JIT compliation. This should only occur on the first run. Additionally, you may see NumbaPerformanceWarning messages related to the @ (matrix multiplication) operator. These can be disregarded and should only appear the first time gps-frames is run.

AI Disclosure

Generative AI was used to assist in the development of this module. All logic and techniques were developed without the use of AI. Following AI models were used: Gemini 3 Pro (High), Gemini 3 Flash, Claude Opus 4.5. The first version containing any AI generated information is version 3.0.0. The final version without any AI generated information is version 2.8.2.

Licence

The gps_frames module is released under the GNU AGPL v3 license.

Copyright (c) 2022 The Aerospace Corportation.

Open Source Licenses

EGM96 Data Source

This module makes use of data related to the EGM96 gravity model. This data was generated by the National Geospatial-intelligence Agency (NGA) and the data used is derived from https://github.com/vectorstofinal/geoid_heights, used under the MIT License Copyright (c) 2015 vectorstofinal.

pdoc3

An earlier version of this module used pdoc3 for documentation. The documentation templates are based on the default template provided from pdoc3 and used under the AGPL v3 license.