Metadata-Version: 2.4
Name: gps_frames
Version: 3.0.0
Summary: Reference frames representations and transformations
Author-email: David William Allen <david.w.allen@aero.org>
License: GNU AGPL v3
Project-URL: Repository, https://github.com/the-aerospace-corporation/gps_frames
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gps-time
Requires-Dist: numpy
Requires-Dist: numba
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: setuptools; extra == "test"
Requires-Dist: genbadge[coverage]; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: pymdown-extensions; extra == "docs"
Requires-Dist: mike; extra == "docs"
Provides-Extra: examples
Requires-Dist: matplotlib; extra == "examples"
Dynamic: license-file

# gps_frames
Reference frame representation, transformations, and operations for GPS.

[![Test Python package](https://github.com/the-aerospace-corporation/gps_frames/actions/workflows/python-package.yml/badge.svg)](https://github.com/the-aerospace-corporation/gps_frames/actions/workflows/python-package.yml)
![Coverage](coverage-badge.svg)
[![PyPI version](https://img.shields.io/pypi/v/gps-frames.svg)](https://pypi.org/project/gps-frames/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/gps-frames.svg)](https://pypi.org/project/gps-frames/)
[![License](https://img.shields.io/pypi/l/gps-frames.svg)](https://github.com/the-aerospace-corporation/gps_frames/blob/main/LICENSE)
[![CodeQL](https://github.com/the-aerospace-corporation/gps_frames/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/the-aerospace-corporation/gps_frames/actions/workflows/codeql-analysis.yml)
[![Upload Python Package](https://github.com/the-aerospace-corporation/gps_frames/actions/workflows/python-publish.yml/badge.svg)](https://github.com/the-aerospace-corporation/gps_frames/actions/workflows/python-publish.yml)

[**Documentation**](https://the-aerospace-corporation.github.io/gps_frames/) | [**GitHub**](https://github.com/the-aerospace-corporation/gps_frames) | [**PyPI**](https://pypi.org/project/gps-frames/)
## 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.

```python
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:
```bash
# 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](https://github.com/the-aerospace-corporation/gps_frames/releases/tag/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](https://pdoc3.github.io/pdoc/) and used under the AGPL v3 license.
