🛰️ ISS Orbit Tracker & Celestial Telemetry Engine

A high-precision orbital mechanics and satellite telemetry suite for real-time tracking of the International Space Station (ISS). Powered by the SGP4 analytical orbital propagation model, Skyfield, and WGS84 ellipsoidal geometry, this application delivers real-time sub-satellite coordinate propagation, horizon footprint coverage, observer ground-pass forecasting, polar sky-radar plotting, and historical TLE orbital decay analysis.

---

🌟 Key Features

• 🛰️ Real-Time SGP4 Orbit Propagation: Live ingestion of two-line element (TLE) datasets from CelesTrak with sub-second orbital position and velocity vector updates.
• 🗺️ Interactive Global Ground Track: Visualizes past (-90 min) and future (+90 min) orbital ground tracks with automatic antimeridian wrap handling and line-of-sight footprint horizon circle.
• 🔭 Observer Ground-Pass Forecasting: Topocentric altitude-azimuth pass predictions for customizable ground stations (rise/culmination/set times, maximum elevation, duration, and naked-eye optical visibility).
• 🧭 Polar Sky-Radar Trajectory: Interactive radar projection displaying the exact celestial trajectory of the ISS from horizon ascension to zenith culmination.
• 📈 Long-Term TLE Orbital Drift Analytics: Multi-epoch evaluation of semi-major axis atmospheric decay ($a$), mean motion drift ($n$), inclination perturbations ($i$), and BSTAR aerodynamic drag ($B^*$).
• 🌐 3D Celestial Orbit Viewer: Interactive 3D Cartesian visualization of Earth and the ISS orbital shell.

---

🏗️ System Architecture

flowchart TD
    A[CelesTrak / NORAD Ephemeris API] -->|Live TLE Stream| B[TLE Fetcher & Parser]
    B -->|Keplerian Elements| C[SGP4 Orbital Propagator]
    C -->|ECI / TEME State Vectors| D[WGS84 Coordinate Transformer]
    
    D -->|Sub-satellite Lat / Lon / Alt| E[Global Ground Track Engine]
    D -->|Velocity / Period / Footprint| F[Telemetry Dashboard]
    
    G[Observer Ground Station] -->|Topocentric Alt / Azimuth| H[Pass Predictor Engine]
    C --> H
    H -->|Pass Schedule & Sky Radar| I[Streamlit Web UI]
    
    J[Historical TLE Archives] -->|Multi-Epoch Series| K[Orbital Drift Analyzer]
    K -->|Decay Curves & Perturbations| I
    E --> I
    F --> I

Loading

---

📐 Mathematical & Orbital Mechanics Foundations

1. SGP4 Analytical Propagation & Drag Modeling

The SGP4 algorithm models gravitational perturbations ($J_2, J_3, J_4$ zonal harmonics) and atmospheric drag via the BSTAR drag term $B^$: $$B^ = \frac{C_D A}{2 m} \rho_0$$

2. Semi-Major Axis via Kepler's Third Law

From the satellite mean motion $n$ (in $\text{rad/s}$), the semi-major axis $a$ is computed as: $$a = \left( \frac{\mu_{\oplus}}{n^2} \right)^{1/3}, \quad \text{where } \mu_{\oplus} = 3.986004418 \times 10^5 \text{ km}^3/\text{s}^2$$

3. Satellite Line-of-Sight Horizon Footprint

The circular horizon ground radius $R_{\text{footprint}}$ for satellite altitude $h$ above an Earth of radius $R_E \approx 6378.137\text{ km}$ is governed by the central angle $\theta_0$: $$\theta_0 = \arccos\left( \frac{R_E}{R_E + h} \right) \implies R_{\text{footprint}} = R_E \cdot \theta_0$$

4. Topocentric Alt-Azimuth Transformation

For an observer at position $\vec{r}{\text{obs}}$ and satellite at $\vec{r}{\text{sat}}$, the topocentric range vector $\vec{\rho} = \vec{r}{\text{sat}} - \vec{r}{\text{obs}}$ yields Elevation ($El$) and Azimuth ($Az$): $$El = \arcsin\left(\frac{\rho_{\text{Up}}}{|\vec{\rho}|}\right), \quad Az = \text{atan2}(\rho_{\text{East}}, \rho_{\text{North}})$$

---

📂 Repository Structure

iss_orbit-track/
├── app.py                     # Streamlit Interactive Web Application
├── requirements.txt           # Python Dependencies
├── LICENSE                    # MIT License
├── README.md                  # System Documentation
├── data/
│   ├── locations.csv          # Ground Observation Station Coordinates
│   ├── tle_data.csv           # Historical TLE Dataset
│   ├── iss_passes_results.csv # Pre-computed Pass Predictions
│   └── Daily_TLE_Files_TXT/   # Archive of Daily TLE Records
├── notebooks/
│   └── ISS_Orbital_Tracking_Tutorial.ipynb  # Interactive Jupyter Notebook
├── src/
│   ├── __init__.py            # Package Init
│   ├── tle_fetcher.py         # Live Ingestion & TLE Parser
│   ├── propagator.py          # SGP4 Engine & Coordinate Transformations
│   ├── pass_predictor.py      # Topocentric Alt-Azimuth Pass Engine
│   └── drift_analyzer.py      # Historical Decay & Perturbation Analytics
└── tests/
    └── test_tracker.py        # Pytest Unit Test Suite

---

🚀 Quickstart & Installation

1. Clone the Repository

git clone https://github.com/The-Fallen-Phoenix/iss_orbit-track.git
cd iss_orbit-track

2. Create and Activate Virtual Environment

python -m venv venv
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Run the Streamlit Dashboard

streamlit run app.py

5. Run Unit Tests

pytest tests/

---

👥 Author & Acknowledgments

• Author: Rithwik Sriram
• Academic Program: India Space Academy & India Space Lab
• Data Sources: CelesTrak (Dr. T.S. Kelso), NASA NORAD Ephemeris