🛰️ OrbitGuard AI

Advanced Satellite Tracking & Collision Detection System

Real-time satellite tracking • Conjunction detection • Visibility predictions • High-performance analytics

Features • Installation • Performance • Usage • Documentation

🌟 Highlights

OrbitGuard AI is a high-performance satellite tracking and monitoring platform with:

🚀 Real-time TLE Data - Automatic retrieval from Space-Track.org
⚠️ Collision Detection - Advanced proximity analysis between satellites
📡 Visibility Predictions - Ground station pass forecasting
🗺️ Interactive Visualization - 2D (Folium) and 3D (Plotly) globe views
📊 Performance Optimized - Redis caching, async processing, Rust engine
💾 Data Export - CSV and HTML reports for post-analysis

🚀 Features

Core Capabilities

Feature	Description	Status
🛰️ TLE Retrieval	Automatic satellite data fetching from Space-Track.org	✅ Active
⚠️ Conjunction Analysis	Satellite-to-satellite close approach detection	✅ Active
📡 Visibility Passes	Ground station visibility predictions	✅ Active
🗺️ 2D Visualization	Interactive Folium maps with satellite tracks	✅ Active
🌍 3D Globe	Three.js + Plotly 3D Earth visualization	✅ Active
📊 CSV/HTML Export	Downloadable analysis reports	✅ Active
🎨 Theme System	Nadir.space, Dracula, Solarized & Custom Builder	✅ NEW

🔥 Performance Optimization (Step 1) ✅

Feature	Improvement	Technology
💾 Redis Caching	450x faster (cache hit)	Redis + hiredis
⚡ Async Fetching	5-10x speedup	aiohttp + asyncio
🦀 Rust Engine	100x faster computations	PyO3 + Rayon
📈 Batch Processing	Handle 1000+ satellites	Multi-threaded

Performance Metrics:

100 satellite analysis: 45s → 5s (9x faster)
Cached queries: 45s → 0.1s (450x faster)
1000 satellite conjunction: timeout → 30s (100x+ faster)

🌐 Web-First Architecture (Step 2) ✅

Feature	Description	Technology
🚀 FastAPI Backend	Modern REST API with auto-docs	FastAPI + Uvicorn
📡 WebSocket Support	Real-time satellite updates	WebSockets
🔐 CORS Middleware	Frontend integration ready	CORS headers
📖 Auto Documentation	Interactive API docs at `/api/docs`	OpenAPI/Swagger

API Endpoints:

GET /api/health - Service health check
POST /api/tle/fetch - Fetch TLE data
POST /api/analysis/conjunction - Conjunction analysis
GET /api/satellites/search - Search satellites
WS /ws/updates - Real-time updates

🗄️ Full Catalog System (Step 3) ✅

Feature	Description	Technology
📊 SQLite Database	66k+ satellite catalog storage	SQLite3
🔄 Auto-Sync	Daily TLE updates (24h interval)	APScheduler
🔍 Advanced Search	Search by name, NORAD ID, country	SQL indexing
📈 Statistics	Launch stats, country breakdowns	Aggregate queries

Database Features:

Automatic TLE updates every 24 hours
Search and filtering (name, country, type)
Update history tracking
Performance indexing

� Installation

Prerequisites

Python 3.8 or higher
Redis (optional, for caching)
Rust (optional, for Rust engine)

Quick Start

# 1. Clone the repository
git clone https://github.com/recepsuluker/OrbitGuardAI.git
cd OrbitGuardAI

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. (Optional) Set up environment variables
cp .env.example .env
# Edit .env with your Space-Track credentials

# 4. Run the application
streamlit run app.py

Advanced Setup (Performance Optimization)

For maximum performance, enable Redis cache and Rust engine:

# Install Redis (Windows - Chocolatey)
choco install redis-64
redis-server

# OR use Redis Cloud (free tier)
# https://redis.com/try-free/

# Build Rust engine (optional)
cd rust_engine
pip install maturin
maturin develop --release
cd ..

📖 Detailed setup guide: PERFORMANCE_OPTIMIZATION.md

🖥️ Usage

Basic Workflow

Launch the app:
```
streamlit run app.py
```
Enter Space-Track credentials (free registration: https://www.space-track.org/auth/login)
Input NORAD IDs (e.g., 25544,48274,52740,55012,56210)
Set ground station location (latitude, longitude, elevation)
Run analysis and view results:
- 📊 Conjunction warnings
- 📡 Visibility passes
- �️ 2D/3D visualizations
- 💾 Download CSV/HTML reports

Example NORAD IDs

25544  - ISS (ZARYA)
48274  - STARLINK-1007
52740  - STARLINK-2278
55012  - STARLINK-3038
56210  - STARLINK-3291

📁 Project Structure

OrbitGuardAI/
│
├── 🎯 Core Application
│   ├── app.py                      # Streamlit web interface
│   ├── orbit_agent.py              # TLE fetching & Space-Track API
│   ├── orbit_engine.py             # Orbital mechanics (Keplerian)
│   ├── visualization.py            # 2D/3D plotting
│   ├── globe_3d.py                 # Three.js integration
│   ├── themes.py                   # UI theme system (Step 8)
│   └── components.py               # Reusable UI components
│
├── ⚡ Performance Optimization (Step 1)
│   ├── cache_manager.py            # Redis caching system
│   ├── orbit_agent_async.py        # Async TLE fetcher
│   ├── benchmark.py                # Performance testing
│   └── rust_engine/                # Rust orbital calculations
│
├── 🌐 Web Backend (Step 2)
│   ├── api_server.py               # FastAPI REST API
│   └── (frontend/)                 # React frontend (future)
│
├── 🗄️ Database System (Step 3)
│   ├── database_manager.py         # SQLite manager
│   ├── auto_catalog_sync.py        # Auto-sync daemon
│   └── orbitguard.db              # SQLite database
│
├── 🧪 Testing
│   ├── tests/                      # Pytest suite
│   ├── pytest.ini
│   └── benchmark.py
│
├── 📄 Configuration
│   ├── requirements.txt
│   ├── .env.example
│   └── .gitignore
│
└── 📚 Documentation
    ├── README.md                   # This file
    └── PERFORMANCE_OPTIMIZATION.md # Setup guide

Output Files

File	Description	Format
`conjunction-warning.csv`	Satellite close encounter report	CSV
`plan_s_satellite_passes.csv`	Ground station visibility passes	CSV
`satellite_track_2d.html`	Interactive 2D Folium map	HTML
`satellite_track_3d.html`	Interactive 3D Plotly globe	HTML

🧪 Testing & Benchmarking

# Run all tests
pytest tests/ -v

# Quick performance test
python benchmark.py --quick

# Full benchmark (10, 50, 100, 500 satellites)
python benchmark.py

Expected benchmark results:

Test Case         Python (s)    Rust (s)    Speedup
───────────────────────────────────────────────────
10 Satellites     0.234         0.018       13.0x
50 Satellites     5.823         0.465       12.5x
100 Satellites    23.451        1.892       12.4x
500 Satellites    582.123       47.235      12.3x

🔧 Configuration

Create a .env file from .env.example:

# Space-Track.org Credentials
SPACETRACK_USERNAME=your_username
SPACETRACK_PASSWORD=your_password

# Redis Cache (optional)
REDIS_URL=redis://localhost:6379/0
CACHE_TTL_HOURS=24

# Performance Settings
USE_CACHE=true
USE_ASYNC=true
USE_RUST=false

📈 Performance Optimization & New Features

Step 1: Redis Cache

Reduce API calls by 95% with automatic TLE caching:

from cache_manager import TLECacheManager

cache = TLECacheManager()
tle_data = cache.get_tle_data([25544, 48274])

Step 1: Async Agent

Fetch multiple satellites concurrently (5-10x faster):

from orbit_agent_async import run_sync

tle_data = run_sync([25544, 48274, 52740], username, password)

Step 1: Rust Engine

Ultra-fast conjunction detection (100x+ improvement):

import orbit_core

conjunctions = orbit_core.find_conjunctions(satellites, threshold_km=10.0)

Step 2: FastAPI Backend

Modern REST API with WebSocket support:

# Start API server
python api_server.py

# API available at: http://localhost:8000
# Docs at: http://localhost:8000/api/docs

Example API Usage:

import requests

# Fetch TLE data
response = requests.post('http://localhost:8000/api/tle/fetch', json={
    'norad_ids': [25544, 48274],
    'use_cache': True
})

# Search satellites
response = requests.get('http://localhost:8000/api/satellites/search?query=ISS')

Step 3: Full Catalog System

Automatic satellite database with 66k+ satellites:

# Run manual sync
python auto_catalog_sync.py

# Or start daemon for automatic updates (24h interval)
# Edit auto_catalog_sync.py and uncomment sync_daemon.start()

Database Usage:

from database_manager import DatabaseManager

db = DatabaseManager()

# Search satellites
results = db.search_satellites(query='STARLINK', country='USA', limit=100)

# Get statistics
stats = db.get_statistics()
print(f"Total satellites: {stats['total_satellites']}")

Step 8: Advanced Theme System

Personalize your monitoring experience with multiple built-in themes or create your own:

Nadir.space: Exact Gruvbox palette transition.
Dracula: High-contrast cyberpunk aesthetic.
Solarized: Scientifically balanced light/dark modes.
Custom Builder: Full control over background, accent, and text colors.

Access these from the sidebar 🎨 Theme Settings section.

📖 Full guide: PERFORMANCE_OPTIMIZATION.md

📸 Screenshots

3D Globe Visualization

Conjunction Analysis Dashboard

Real-time satellite proximity warnings with risk scoring

Ground Station Visibility

Pass predictions with azimuth/elevation charts

🛣️ Roadmap

v2.0 (Q1 2026)

FastAPI backend + React frontend
PostgreSQL database for TLE history
User authentication system
REST API for external integrations

v2.1 (Q2 2026)

Machine learning collision prediction
WebSocket real-time updates
Multi-station network support
Mobile app (React Native)

v3.0 (Q3 2026)

GPU-accelerated orbital propagation
Distributed caching (Redis Cluster)
Advanced analytics dashboard
Commercial API offering

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

👨‍💻 Author

Recep Suluker

GitHub: @recepsuluker
Project: Real-time LEO traffic analysis with Plan-S constellation
Contact: Open an issue for questions/suggestions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Free for commercial and personal use.

🙏 Acknowledgments

Space-Track.org - TLE data provider
Skyfield - Astronomical computations library
Plotly & Folium - Visualization frameworks
Streamlit - Web UI framework
Rust & PyO3 - High-performance computing

📞 Support

Found a bug? Have a feature request?

⭐ Star this repo if you find it useful!

Made with ❤️ by Recep Suluker

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
rust_engine		rust_engine
tests		tests
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
api_server.py		api_server.py
app.py		app.py
auto_catalog_sync.py		auto_catalog_sync.py
benchmark.py		benchmark.py
cache_manager.py		cache_manager.py
components.py		components.py
database_manager.py		database_manager.py
globe_3d.py		globe_3d.py
orbit_agent.py		orbit_agent.py
orbit_agent_async.py		orbit_agent_async.py
orbit_engine.py		orbit_engine.py
pytest.ini		pytest.ini
requirements.txt		requirements.txt
test_engine.py		test_engine.py
test_large_scale.py		test_large_scale.py
themes.py		themes.py
visibility-passes.csv		visibility-passes.csv
visualization.py		visualization.py

recepsuluker/OrbitGuardAI

Folders and files

Latest commit

History

Repository files navigation