orbitops 0.1.0__tar.gz

orbitops-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.3
+Name: orbitops
+Version: 0.1.0
+Summary: A command-line toolkit for satellite tracking and orbital analysis.
+Requires-Dist: requests>=2.34.2
+Requires-Dist: sgp4>=2.27
+Requires-Dist: skyfield>=1.55
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# OrbitOps
+
+OrbitOps is a Python command-line toolkit for satellite tracking and basic orbital analysis using publicly available CelesTrak data.
+
+It uses Two-Line Element (TLE) data and the SGP4 propagation model to calculate spacecraft positions, velocities, and distances.
+
+## Features
+
+- Calculate current latitude, longitude, and altitude
+- Display TEME Cartesian position and velocity
+- View satellite catalog information
+- Search satellites by name
+- Calculate 3D distance between two spacecraft
+- Continuously monitor a spacecraft's calculated position
+
+## Installation
+
+OrbitOps requires **Python 3.14 or later**.
+
+Install from PyPI:
+
+```bash
+pip install orbitops
+```
+
+Then verify the installation:
+
+```bash
+orbitops help
+```
+
+## Usage
+
+OrbitOps uses NORAD Catalog Numbers to identify spacecraft.
+
+For example, the International Space Station (ISS) has catalog number `25544`.
+
+### Position
+
+Show the calculated latitude, longitude, and altitude of a spacecraft.
+
+```bash
+orbitops position 25544
+```
+
+Example:
+
+```text
+Geographic position of ISS (ZARYA)
+--------------------
+Latitude:  -32.7625°
+Longitude: -54.1085°
+Altitude:  432.53 km
+```
+
+### TEME State
+
+Show the spacecraft's TEME Cartesian position and velocity.
+
+```bash
+orbitops teme 25544
+```
+
+Position is reported in kilometers and velocity in kilometers per second.
+
+### Satellite Information
+
+View catalog information for a spacecraft.
+
+```bash
+orbitops info 25544
+```
+
+This may include information such as the spacecraft name, NORAD catalog number, launch date, owner, inclination, apogee, and perigee.
+
+### Search
+
+Search the satellite catalog by name.
+
+```bash
+orbitops search ISS
+```
+
+You can also use broader searches:
+
+```bash
+orbitops search STARLINK
+```
+
+Broad searches may match many spacecraft. The current version of OrbitOps displays the first returned result.
+
+### Distance
+
+Calculate the current straight-line 3D distance between two spacecraft.
+
+```bash
+orbitops distance 25544 69012
+```
+
+The result is reported in kilometers.
+
+The distance is calculated from both spacecraft's propagated TEME Cartesian positions and represents their instantaneous 3D separation, not distance along Earth's surface.
+
+### Watch
+
+Continuously monitor the calculated geographic position of a spacecraft.
+
+```bash
+orbitops watch 25544
+```
+
+Example:
+
+```text
+ISS (ZARYA) | Lat: 38.2841° | Lon: -72.1832° | Alt: 421.72 km
+```
+
+Press `Ctrl+C` to stop.
+
+## Command Reference
+
+| Command | Usage | Description |
+| --- | --- | --- |
+| `position` | `orbitops position <CATNR>` | Show latitude, longitude, and altitude |
+| `teme` | `orbitops teme <CATNR>` | Show TEME position and velocity |
+| `info` | `orbitops info <CATNR>` | Show satellite catalog information |
+| `search` | `orbitops search <name>` | Search satellites by name |
+| `distance` | `orbitops distance <CATNR1> <CATNR2>` | Calculate 3D spacecraft separation |
+| `watch` | `orbitops watch <CATNR>` | Continuously monitor spacecraft position |
+| `help` | `orbitops help` | Display the help menu |
+
+## How It Works
+
+OrbitOps retrieves publicly available orbital data from CelesTrak.
+
+For position calculations, OrbitOps retrieves a spacecraft's TLE and uses SGP4 to propagate its orbit to the current time.
+
+```text
+CelesTrak
+    |
+    | TLE
+    v
+OrbitOps
+    |
+    | SGP4
+    v
+Calculated spacecraft state
+    |
+    +--> TEME position and velocity
+    |
+    +--> Latitude / Longitude / Altitude
+```
+
+For continuous tracking, the TLE does not need to be downloaded every second. OrbitOps retrieves the orbital elements and performs subsequent propagation locally.
+
+## Data and Accuracy
+
+OrbitOps does **not** receive live spacecraft telemetry.
+
+Positions are calculated from publicly available orbital elements using SGP4. They should therefore be treated as **calculated or predicted positions**, not authoritative spacecraft positions.
+
+Accuracy can be affected by factors including:
+
+- Age of the orbital elements
+- Atmospheric drag
+- Spacecraft maneuvers
+- Spacecraft orbit
+- Time elapsed from the TLE epoch
+
+OrbitOps is intended for educational, informational, satellite-tracking, visualization, and general orbital-analysis purposes.
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone <repository-url>
+cd OrbitOps
+```
+
+Install the development environment:
+
+```bash
+uv sync
+```
+
+Run OrbitOps:
+
+```bash
+uv run orbitops position 25544
+```
+
+Run tests and checks:
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run pyright
+```
+
+## License
+
+OrbitOps is licensed under the MIT License.
+
+See the `LICENSE` file for the full license terms.
+
+## Disclaimer
+
+OrbitOps is provided for educational, informational, and general satellite tracking purposes only.
+
+OrbitOps does not provide authoritative spacecraft telemetry, precision orbit determination, or mission-operational data. Satellite positions and other orbital information produced by OrbitOps are calculated from publicly available orbital elements using mathematical propagation models and may contain errors or become inaccurate over time.
+
+OrbitOps is not intended for spacecraft navigation, collision avoidance, rendezvous operations, launch operations, flight safety, mission-critical decision-making, or any other safety-critical application.
+
+Users are responsible for independently verifying any data produced by OrbitOps before relying on it for operational purposes.
+
+THE SOFTWARE AND ALL OUTPUT GENERATED BY THE SOFTWARE ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. USE OF ORBITOPS AND RELIANCE ON ITS OUTPUT IS AT THE USER'S OWN RISK.

orbitops-0.1.0/README.md

@@ -0,0 +1,217 @@
+# OrbitOps
+
+OrbitOps is a Python command-line toolkit for satellite tracking and basic orbital analysis using publicly available CelesTrak data.
+
+It uses Two-Line Element (TLE) data and the SGP4 propagation model to calculate spacecraft positions, velocities, and distances.
+
+## Features
+
+- Calculate current latitude, longitude, and altitude
+- Display TEME Cartesian position and velocity
+- View satellite catalog information
+- Search satellites by name
+- Calculate 3D distance between two spacecraft
+- Continuously monitor a spacecraft's calculated position
+
+## Installation
+
+OrbitOps requires **Python 3.14 or later**.
+
+Install from PyPI:
+
+```bash
+pip install orbitops
+```
+
+Then verify the installation:
+
+```bash
+orbitops help
+```
+
+## Usage
+
+OrbitOps uses NORAD Catalog Numbers to identify spacecraft.
+
+For example, the International Space Station (ISS) has catalog number `25544`.
+
+### Position
+
+Show the calculated latitude, longitude, and altitude of a spacecraft.
+
+```bash
+orbitops position 25544
+```
+
+Example:
+
+```text
+Geographic position of ISS (ZARYA)
+--------------------
+Latitude:  -32.7625°
+Longitude: -54.1085°
+Altitude:  432.53 km
+```
+
+### TEME State
+
+Show the spacecraft's TEME Cartesian position and velocity.
+
+```bash
+orbitops teme 25544
+```
+
+Position is reported in kilometers and velocity in kilometers per second.
+
+### Satellite Information
+
+View catalog information for a spacecraft.
+
+```bash
+orbitops info 25544
+```
+
+This may include information such as the spacecraft name, NORAD catalog number, launch date, owner, inclination, apogee, and perigee.
+
+### Search
+
+Search the satellite catalog by name.
+
+```bash
+orbitops search ISS
+```
+
+You can also use broader searches:
+
+```bash
+orbitops search STARLINK
+```
+
+Broad searches may match many spacecraft. The current version of OrbitOps displays the first returned result.
+
+### Distance
+
+Calculate the current straight-line 3D distance between two spacecraft.
+
+```bash
+orbitops distance 25544 69012
+```
+
+The result is reported in kilometers.
+
+The distance is calculated from both spacecraft's propagated TEME Cartesian positions and represents their instantaneous 3D separation, not distance along Earth's surface.
+
+### Watch
+
+Continuously monitor the calculated geographic position of a spacecraft.
+
+```bash
+orbitops watch 25544
+```
+
+Example:
+
+```text
+ISS (ZARYA) | Lat: 38.2841° | Lon: -72.1832° | Alt: 421.72 km
+```
+
+Press `Ctrl+C` to stop.
+
+## Command Reference
+
+| Command | Usage | Description |
+| --- | --- | --- |
+| `position` | `orbitops position <CATNR>` | Show latitude, longitude, and altitude |
+| `teme` | `orbitops teme <CATNR>` | Show TEME position and velocity |
+| `info` | `orbitops info <CATNR>` | Show satellite catalog information |
+| `search` | `orbitops search <name>` | Search satellites by name |
+| `distance` | `orbitops distance <CATNR1> <CATNR2>` | Calculate 3D spacecraft separation |
+| `watch` | `orbitops watch <CATNR>` | Continuously monitor spacecraft position |
+| `help` | `orbitops help` | Display the help menu |
+
+## How It Works
+
+OrbitOps retrieves publicly available orbital data from CelesTrak.
+
+For position calculations, OrbitOps retrieves a spacecraft's TLE and uses SGP4 to propagate its orbit to the current time.
+
+```text
+CelesTrak
+    |
+    | TLE
+    v
+OrbitOps
+    |
+    | SGP4
+    v
+Calculated spacecraft state
+    |
+    +--> TEME position and velocity
+    |
+    +--> Latitude / Longitude / Altitude
+```
+
+For continuous tracking, the TLE does not need to be downloaded every second. OrbitOps retrieves the orbital elements and performs subsequent propagation locally.
+
+## Data and Accuracy
+
+OrbitOps does **not** receive live spacecraft telemetry.
+
+Positions are calculated from publicly available orbital elements using SGP4. They should therefore be treated as **calculated or predicted positions**, not authoritative spacecraft positions.
+
+Accuracy can be affected by factors including:
+
+- Age of the orbital elements
+- Atmospheric drag
+- Spacecraft maneuvers
+- Spacecraft orbit
+- Time elapsed from the TLE epoch
+
+OrbitOps is intended for educational, informational, satellite-tracking, visualization, and general orbital-analysis purposes.
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone <repository-url>
+cd OrbitOps
+```
+
+Install the development environment:
+
+```bash
+uv sync
+```
+
+Run OrbitOps:
+
+```bash
+uv run orbitops position 25544
+```
+
+Run tests and checks:
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run pyright
+```
+
+## License
+
+OrbitOps is licensed under the MIT License.
+
+See the `LICENSE` file for the full license terms.
+
+## Disclaimer
+
+OrbitOps is provided for educational, informational, and general satellite tracking purposes only.
+
+OrbitOps does not provide authoritative spacecraft telemetry, precision orbit determination, or mission-operational data. Satellite positions and other orbital information produced by OrbitOps are calculated from publicly available orbital elements using mathematical propagation models and may contain errors or become inaccurate over time.
+
+OrbitOps is not intended for spacecraft navigation, collision avoidance, rendezvous operations, launch operations, flight safety, mission-critical decision-making, or any other safety-critical application.
+
+Users are responsible for independently verifying any data produced by OrbitOps before relying on it for operational purposes.
+
+THE SOFTWARE AND ALL OUTPUT GENERATED BY THE SOFTWARE ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. USE OF ORBITOPS AND RELIANCE ON ITS OUTPUT IS AT THE USER'S OWN RISK.

orbitops-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "orbitops"
+version = "0.1.0"
+description = "A command-line toolkit for satellite tracking and orbital analysis."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "requests>=2.34.2",
+    "sgp4>=2.27",
+    "skyfield>=1.55",
+]
+
+[project.scripts]
+orbitops = "orbitops.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+    "ruff>=0.16.4",
+]

orbitops-0.1.0/pyproject.toml.orig

@@ -0,0 +1,25 @@
+[project]
+name = "orbitops"
+version = "0.1.0"
+description = "A command-line toolkit for satellite tracking and orbital analysis."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "requests>=2.34.2",
+    "sgp4>=2.27",
+    "skyfield>=1.55",
+]
+
+[project.scripts]
+orbitops = "orbitops.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+    "ruff>=0.16.4",
+]

orbitops-0.1.0/src/orbitops/api.py

@@ -0,0 +1,190 @@
+import math
+import time
+
+import requests
+
+from . import propagation
+
+
+def get_sat_info_tle(catalog_number: int) -> list[str]:
+    """Returns the cartesian state of the spacecraft in TLE format."""
+
+    returnArr = []
+
+    url = "https://celestrak.org/NORAD/elements/gp.php"
+
+    params = {
+        "CATNR": catalog_number,
+        "FORMAT": "TLE"
+    }
+
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+
+        data = response.text.splitlines()
+
+        if len(data) < 3:
+            return []
+
+        for line in data:
+            returnArr.append(line)
+
+        return returnArr
+
+    except requests.RequestException as error:
+        print(f"Failed to retrieve satellite data: {error}")
+
+        return []
+
+
+def get_satcat_data(catalog_number: int) -> dict:
+    """Returns information about a given spacecraft."""
+
+    url = "https://celestrak.org/satcat/records.php"
+
+    params = {
+        "CATNR": catalog_number,
+        "FORMAT": "JSON"
+    }
+
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+
+        data = response.json()
+
+        if not data:
+            return {}
+
+        return data[0]
+
+    except requests.RequestException as error:
+        print(f"Failed to retrieve satellite data: {error}")
+
+        return {}
+
+
+def search_by_name(name: str) -> list[dict]:
+    """Searches Celestrack by name, returns most relevant results."""
+
+    url = "https://celestrak.org/satcat/records.php"
+
+    params = {
+        "NAME": name,
+        "FORMAT": "JSON",
+    }
+
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+
+        return response.json()
+
+    except requests.RequestException as error:
+        print(f"Failed to retrieve satellite data: {error}")
+
+        return []
+
+
+def get_distance_sats(catalog_num1: int, catalog_num2: int) -> None:
+    """Returns the 3D Euclidean distance between two spacecraft."""
+
+    url = "https://celestrak.org/NORAD/elements/gp.php"
+
+    params = {
+        "CATNR": catalog_num1,
+        "FORMAT": "TLE"
+    }
+
+    params2 = {
+        "CATNR": catalog_num2,
+        "FORMAT": "TLE"
+    }
+
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+
+        first_sat_data = response.text.splitlines()
+
+        if len(first_sat_data) < 3:
+            print(
+                f"No valid TLE found for catalog number "
+                f"{catalog_num1}."
+            )
+            return
+
+        tle_1_first_sat = first_sat_data[1]
+        tle_2_first_sat = first_sat_data[2]
+
+        teme_first_sat = propagation.get_teme_cartesian(
+            tle_1_first_sat,
+            tle_2_first_sat
+        )[0]
+
+        response2 = requests.get(url, params=params2)
+        response2.raise_for_status()
+
+        second_sat_data = response2.text.splitlines()
+
+        if len(second_sat_data) < 3:
+            print(
+                f"No valid TLE found for catalog number "
+                f"{catalog_num2}."
+            )
+            return
+
+        tle_1_second_sat = second_sat_data[1]
+        tle_2_second_sat = second_sat_data[2]
+
+        teme_second_sat = propagation.get_teme_cartesian(
+            tle_1_second_sat,
+            tle_2_second_sat
+        )[0]
+
+        print(
+            f"The distance between "
+            f"{first_sat_data[0].strip()} and "
+            f"{second_sat_data[0].strip()} is "
+            f"{math.dist(teme_first_sat, teme_second_sat):.3f}km."
+        )
+
+    except requests.RequestException as error:
+        print(f"Failed to retrieve satellite data: {error}")
+
+
+def watch(catalog_number: int) -> None:
+    """Returns the latitude, longitude, and altitude of a spacecraft."""
+
+    sat_data = get_sat_info_tle(catalog_number)
+
+    if len(sat_data) < 3:
+        print(
+            f"No valid TLE found for catalog number "
+            f"{catalog_number}."
+        )
+        return
+
+    sat_name, tle_line1, tle_line2 = sat_data
+
+    print("Press 'Ctrl+C' to stop watching.")
+
+    while True:
+        latitude, longitude, altitude = (
+            propagation.get_geographic_position(
+                tle_line1,
+                tle_line2,
+            )
+        )
+
+        print(
+            f"\r{sat_name} | "
+            f"Lat: {latitude:.4f}° | "
+            f"Lon: {longitude:.4f}° | "
+            f"Alt: {altitude:.2f} km",
+            end="",
+            flush=True
+        )
+
+        time.sleep(1)

orbitops-0.1.0/src/orbitops/cli.py

@@ -0,0 +1,174 @@
+import sys
+
+from . import api, etc, propagation
+
+VALID_COMMANDS = (
+    "help",
+    "--help",
+    "-h",
+    "teme",
+    "position",
+    "info",
+    "search",
+    "distance",
+    "watch",
+)
+
+
+def main() -> None:
+    """Main CLI tool, accepts commands."""
+
+    try:
+        # No command entered
+        if len(sys.argv) == 1:
+            etc.print_help_menu()
+            return
+
+        command = sys.argv[1]
+
+        # Help command
+        if command in ("help", "--help", "-h"):
+            etc.print_help_menu()
+            return
+
+        # Invalid command
+        if command not in VALID_COMMANDS:
+            print(f"Invalid command: {command}")
+            print("Use 'orbitops help' to view available commands.")
+            return
+
+        # Search requires a name
+        if command == "search" and len(sys.argv) < 3:
+            print("Missing satellite name.")
+            print("Usage: orbitops search <name>")
+            return
+
+        # Distance requires two catalog numbers
+        if command == "distance" and len(sys.argv) < 4:
+            print("Two satellite catalog numbers are required.")
+            print("Usage: orbitops distance <CATNR1> <CATNR2>")
+            return
+
+        # All remaining commands require one catalog number
+        if command not in ("search", "distance"):
+
+            if len(sys.argv) < 3:
+                print("Missing satellite catalog number.")
+                print(f"Usage: orbitops {command} <CATNR>")
+                return
+
+            try:
+                catalog_number = int(sys.argv[2])
+
+            except ValueError:
+                print("Satellite catalog number must be an integer.")
+                return
+
+            sat_data = api.get_sat_info_tle(catalog_number)
+
+            if not sat_data:
+                print(
+                    f"No satellite found with catalog number "
+                    f"{catalog_number}."
+                )
+                return
+
+            sat_name, tle_line1, tle_line2 = sat_data
+
+        if command == "teme":
+
+            position, velocity = propagation.get_teme_cartesian(
+                tle_line1,
+                tle_line2
+            )
+
+            print(f"\nTEME Cartesian State of {sat_name}")
+            print("--------------------")
+
+            print("Position:")
+            print(f"  X: {position[0]:10.2f} km")
+            print(f"  Y: {position[1]:10.2f} km")
+            print(f"  Z: {position[2]:10.2f} km")
+
+            print("Velocity:")
+            print(f"  X: {velocity[0]:10.3f} km/s")
+            print(f"  Y: {velocity[1]:10.3f} km/s")
+            print(f"  Z: {velocity[2]:10.3f} km/s")
+
+        if command == "position":
+
+            print(f"\nGeographic position of {sat_name}")
+            print("--------------------")
+
+            latitude, longitude, altitude = (
+                propagation.get_geographic_position(
+                    tle_line1,
+                    tle_line2,
+                )
+            )
+
+            print(f"Latitude:  {latitude:.4f}°")
+            print(f"Longitude: {longitude:.4f}°")
+            print(f"Altitude:  {altitude:.2f} km")
+
+        if command == "info":
+
+            data = api.get_satcat_data(catalog_number)
+
+            if not data:
+                print(
+                    f"No satellite catalog information found for "
+                    f"{catalog_number}."
+                )
+                return
+
+            for key, value in data.items():
+                print(f"{key}: {value}")
+
+        if command == "search":
+
+            results = api.search_by_name(sys.argv[2])
+
+            if not results:
+                print(
+                    f"No satellites found matching "
+                    f"'{sys.argv[2]}'."
+                )
+                return
+
+            data = results[0]
+
+            for key, value in data.items():
+                print(f"{key}: {value}")
+
+        if command == "distance":
+
+            try:
+                catalog_number_1 = int(sys.argv[2])
+                catalog_number_2 = int(sys.argv[3])
+
+            except ValueError:
+                print("Satellite catalog numbers must be integers.")
+                return
+
+            api.get_distance_sats(
+                catalog_number_1,
+                catalog_number_2
+            )
+
+        if command == "watch":
+
+            api.watch(catalog_number)
+
+    except IndexError as error:
+        print(f"Invalid satellite catalog number (CATNR): {error}")
+
+    except KeyboardInterrupt:
+        print("\nOrbitOps stopped.")
+
+    except Exception as error:
+        print(f"OrbitOps error: {error}")
+
+
+if __name__ == "__main__":
+    main()

orbitops-0.1.0/src/orbitops/etc.py

@@ -0,0 +1,10 @@
+def print_help_menu() -> None:
+
+    print("=== OrbitOps Help Menu ===")
+    print("position <CATNR>          Show current latitude, longitude, and altitude")
+    print("teme <CATNR>              Show current TEME position and velocity")
+    print("info <CATNR>              Show satellite catalog information")
+    print("search <name>             Search for a satellite by name")
+    print("distance <CATNR1> <CATNR2> Show distance between two satellites")
+    print("watch <CATNR>             Continuously track a satellite's position")
+    print("help                      Show this help menu")

orbitops-0.1.0/src/orbitops/propagation.py

@@ -0,0 +1,51 @@
+from datetime import UTC, datetime
+
+from sgp4.api import Satrec, jday
+from skyfield.api import EarthSatellite, load, wgs84
+
+
+def get_teme_cartesian(tle_line_1: str, tle_line_2: str) -> tuple[
+    tuple[float, float, float],
+    tuple[float, float, float]
+]:
+
+    satellite = Satrec.twoline2rv(tle_line_1, tle_line_2)
+    
+    now = datetime.now(UTC)
+
+    jd, fr = jday(
+    now.year,
+    now.month,
+    now.day,
+    now.hour,
+    now.minute,
+    now.second + now.microsecond / 1_000_000,
+    )
+
+    error, position, velocity = satellite.sgp4(jd, fr)
+
+    return (position, velocity)
+
+def get_geographic_position(
+    tle_line_1: str,
+    tle_line_2: str,
+) -> tuple[float, float, float]:
+
+    timescale = load.timescale()
+    current_time = timescale.now()
+
+    satellite = EarthSatellite(
+        tle_line_1,
+        tle_line_2,
+        ts=timescale,
+    )
+
+    position = satellite.at(current_time)
+
+    geographic = wgs84.geographic_position_of(position)
+
+    latitude = geographic.latitude.degrees
+    longitude = geographic.longitude.degrees
+    altitude = geographic.elevation.km
+
+    return latitude, longitude, altitude