Flight-Trajectory-Prediction-System

Stars
6
Language
Python
Updated
View on GitHub

Flight Trajectory Prediction Platform

A comprehensive, real-time flight trajectory prediction and analysis platform combining physics-based modeling, deep learning, and interactive 3D visualization.

🏗️ Architecture Overview

Backend (Python/FastAPI)

  • ADS-B Data Ingestion: OpenSky Network API + synthetic data generation
  • Trajectory Processing: Physics baseline + LSTM/Transformer ML models + hybrid fusion
  • Real-time API: REST endpoints + WebSocket streaming
  • Evaluation: Haversine distance, altitude, velocity error metrics

Frontend (Next.js/TypeScript)

  • Dashboard: System health, model performance, active flights
  • Trajectory Viewer: 2D Mapbox + 3D Three.js visualization
  • Scenario Comparison: Side-by-side model evaluation
  • Model Inspector: Feature importance, prediction explainability

🚀 Quick Start

Prerequisites

  • Python 3.11+
  • Node.js 18+
  • Docker (optional)

Backend Setup

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn api.main:socket_app --host 0.0.0.0 --port 8000 --reload

Frontend Setup

cd frontend
npm install
npm run dev

Access Points

📊 Core Features

Real-time Trajectory Prediction

  • Physics Model: Constant velocity/heading with geodesic calculations
  • ML Models: LSTM sequence-to-sequence, Transformer with attention
  • Hybrid Approach: Physics baseline + ML corrections
  • WebSocket Streaming: Real-time prediction updates (<500ms latency)

Advanced Visualization

  • 2D Maps: Mapbox GL JS with flight tracks and uncertainty bands
  • 3D Globe: Three.js earth-curvature rendering with altitude extrusion
  • Playback Controls: Time scrubbing, pause/resume, event jumping
  • Multi-model Overlay: Compare ground truth vs predictions

Explainability & Monitoring

  • Model Transparency: Physics baseline vs ML correction vectors
  • Feature Importance: Input feature contribution analysis
  • Error Decomposition: Per-timestep prediction accuracy
  • System Health: Model status, latency monitoring, data drift detection

🛠️ Technical Stack

Backend

  • Framework: FastAPI + Socket.IO
  • ML: PyTorch (LSTM, Transformer)
  • Data: Pandas, NumPy, Geopy, Traffic library
  • Visualization: Plotly, Matplotlib

Frontend

  • Framework: Next.js 14 (App Router)
  • Language: TypeScript
  • 2D Maps: Mapbox GL JS
  • 3D Graphics: Three.js + React Three Fiber
  • Charts: Recharts
  • Styling: Tailwind CSS

Infrastructure

  • Containerization: Docker + docker-compose
  • Deployment: Local, AWS/GCP/Azure VM
  • Monitoring: Custom health checks, performance metrics

📈 API Reference

REST Endpoints

GET  /health                    # System health check
POST /predict/trajectory        # Single trajectory prediction
POST /predict/batch            # Batch trajectory predictions
GET  /evaluations              # Model evaluation results

WebSocket Events

// Subscribe to flight updates
socket.emit('subscribe_flight', { icao24: 'ABC123' });

// Request real-time predictions
socket.emit('request_predictions', { icao24: 'ABC123', model_type: 'hybrid' });

// Listen for updates
socket.on('prediction_update', (data) => { ... });
socket.on('system_status', (data) => { ... });

🎯 Model Performance

Baseline Metrics (Synthetic Data)

  • Horizontal Error: ~10-50 meters (physics), ~5-20 meters (hybrid)
  • Altitude Error: ~10-30 feet
  • Velocity Error: ~2-5 knots
  • Latency: <50ms (physics), <200ms (ML models)

Real-world Performance

  • ADS-B Integration: OpenSky Network API
  • Data Quality: Automatic outlier detection and interpolation
  • Scalability: Batch processing for multiple flights

🔧 Configuration

Environment Variables

# Backend
MODEL_PATH=models/best_lstm_model.pth
MODEL_TYPE=lstm
CORRECTION_WEIGHT=0.3
PORT=8000

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token

Model Training

# Generate training data
python generate_synthetic_data.py

# Train models
python train.py --model lstm --epochs 100

# Evaluate performance
python evaluation.py --compare-all

🚢 Deployment

Automated Deployment Script

The easiest way to deploy the full system is using the provided deployment script:

# Full production deployment
./deploy.sh deploy

# Individual commands
./deploy.sh setup    # Setup development environment
./deploy.sh build    # Build Docker images
./deploy.sh start    # Start services
./deploy.sh test     # Run validation tests
./deploy.sh demo     # Run demo scenarios
./deploy.sh stop     # Stop services
./deploy.sh clean    # Clean up containers

Manual Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Or build images separately
docker build -f Dockerfile.backend -t flight-prediction-backend .
docker build -f frontend/Dockerfile -t flight-prediction-frontend .
docker-compose up

Production Deployment Checklist

  • Environment variables configured
  • SSL certificates for HTTPS
  • Reverse proxy (nginx) configured
  • Monitoring and logging setup
  • Backup strategy implemented
  • Performance testing completed

Cloud Deployment Options

  • AWS: ECS Fargate + CloudFront + RDS
  • GCP: Cloud Run + Cloud Storage + BigQuery
  • Azure: Container Instances + CDN + CosmosDB

🧪 Testing & Validation

System Validation Tests

Run comprehensive system tests to validate all components:

# Run all validation tests
python test_system.py

# Or using deployment script
./deploy.sh test

Tests include:

  • ✅ Health endpoint validation
  • ✅ Single trajectory prediction
  • ✅ Batch prediction processing
  • ✅ Model comparison functionality
  • ✅ WebSocket connection testing
  • ✅ Performance requirements (<500ms latency)
  • ✅ API response validation

Demo Scenarios

Experience the system with pre-built demo scenarios:

# Run demo scenarios
python demo_runner.py

# Or using deployment script
./deploy.sh demo

Demo features:

  • Health check verification
  • Single and batch predictions
  • Model performance comparison
  • WebSocket real-time streaming
  • Performance benchmarking

Performance Benchmarks

Expected performance metrics:

  • API Latency: <500ms for single predictions
  • WebSocket Latency: <100ms for real-time updates
  • Batch Processing: <2s for 10 trajectories
  • Memory Usage: <2GB for ML models
  • CPU Usage: <50% during normal operation

📊 Monitoring & Observability

Health Checks

The system provides comprehensive health monitoring:

# API health check
curl http://localhost:8000/health

# Frontend health
curl http://localhost:3000/api/health

Metrics Endpoints

  • GET /health - System status and model information
  • GET /evaluate/metrics - Model performance metrics
  • GET /system/status - Real-time system statistics

Logging

  • Backend: Structured JSON logging with log levels
  • Frontend: Client-side error tracking and performance monitoring
  • Infrastructure: Docker container logs and nginx access logs

📚 Documentation

Architecture Decisions

  1. Modular Design: Clear separation between data ingestion, modeling, and visualization
  2. WebSocket Streaming: Real-time updates with <500ms latency budget
  3. Hybrid Modeling: Physics baseline ensures robustness, ML provides accuracy
  4. 3D Visualization: Earth-curvature awareness for accurate representation
  5. Explainability: Model transparency for safety-critical aviation applications

Data Flow

ADS-B Data → Validation → Trajectory Building → Feature Engineering → Model Prediction → Visualization

Performance Optimizations

  • Caching: Prediction results cached for 30 seconds
  • Async Processing: Non-blocking WebSocket handlers
  • Batch Inference: Multiple trajectories processed simultaneously
  • Lazy Loading: Models loaded on-demand

🤝 Contributing

Development Setup

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/new-feature
  3. Install dependencies: pip install -r requirements.txt && npm install
  4. Run tests: python -m pytest && npm test
  5. Submit pull request

Code Quality

  • Backend: Black formatting, mypy type checking, pytest coverage
  • Frontend: ESLint, Prettier, TypeScript strict mode
  • Documentation: Inline docstrings, API documentation

� Project Structure

├── api/                    # FastAPI backend with WebSocket support
│   ├── main.py            # Main application with Socket.IO integration
│   └── routes/            # API route handlers
├── frontend/               # Next.js frontend application
│   ├── src/
│   │   ├── app/           # Next.js app router pages
│   │   ├── components/    # React components (UI, 3D viewer)
│   │   ├── lib/           # Utility functions and API clients
│   │   └── types/         # TypeScript type definitions
│   ├── public/            # Static assets
│   └── Dockerfile         # Frontend container definition
├── models/                 # ML model implementations and training
├── data/                   # Data processing and synthetic generation
├── utils/                  # Shared utility functions
├── docker-compose.yml      # Multi-service container orchestration
├── Dockerfile.backend      # Backend container definition
├── nginx.conf             # Reverse proxy configuration
├── deploy.sh              # Automated deployment script
├── demo_runner.py         # Demo scenarios and examples
├── test_system.py         # Comprehensive system validation tests
├── requirements.txt       # Python dependencies
└── README.md              # This documentation

🔧 Development Workflow

Local Development Setup

  1. Clone and setup:

    git clone <repository-url>
cd flight-trajectory-system
./deploy.sh setup

  2. Start development servers:

    # Terminal 1: Backend
cd api && python main.py

# Terminal 2: Frontend
cd frontend && npm run dev

  3. Run tests and validation:

    ./deploy.sh test
./deploy.sh demo

Contributing Guidelines

  1. Code Standards:

    • Follow PEP 8 for Python code
    • Use TypeScript strict mode for frontend
    • Add comprehensive docstrings and comments
    • Write tests for new functionality

  2. Testing:

    • Run full test suite before committing
    • Add integration tests for new features
    • Validate performance requirements

  3. Documentation:

    • Update README for significant changes
    • Add API documentation for new endpoints
    • Include examples and usage patterns

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

  • OpenSky Network for ADS-B data
  • Traffic library for aviation data processing
  • Mapbox for mapping capabilities
  • Three.js community for 3D visualization
  • FastAPI and Socket.IO communities

Built for aviation safety and operational efficiency ✈️


### 3. Start API Server

```bash
# Using Python
python api/main.py

# Or using Docker
docker build -t trajectory-predictor .
docker run -p 8000:8000 trajectory-predictor

4. Make Predictions

# Single trajectory prediction
curl -X POST "http://localhost:8000/predict/trajectory" \
     -H "Content-Type: application/json" \
     -d '{
       "current_state": {
         "latitude": 37.7749,
         "longitude": -122.4194,
         "altitude": 35000,
         "velocity": 500,
         "heading": 90,
         "vertical_rate": 0
       },
       "prediction_horizon": 60,
       "model_type": "hybrid"
     }'

# Batch prediction
curl -X POST "http://localhost:8000/predict/batch" \
     -H "Content-Type: application/json" \
     -d '{"trajectories": [...]}'

API Endpoints

  • GET /health - Health check
  • POST /predict/trajectory - Single trajectory prediction
  • POST /predict/batch - Batch trajectory prediction

Model Types

  • physics: Constant velocity/heading propagation
  • ml: Pure LSTM/Transformer prediction
  • hybrid: Physics + ML correction

Configuration

Environment variables:

MODEL_PATH=models/best_model.pth      # Path to trained model
MODEL_TYPE=lstm                       # lstm or transformer
CORRECTION_WEIGHT=0.3                 # Hybrid correction weight
PORT=8000                            # API port

Data Format

ADS-B data should include:

{
  "icao24": "4b1613",
  "callsign": "SWR123",
  "timestamp": "2024-01-25T10:00:00Z",
  "latitude": 47.4502,
  "longitude": 8.5621,
  "baro_altitude": 35000,
  "velocity": 500,
  "heading": 90,
  "vertical_rate": 0
}

Evaluation Metrics

  • Horizontal error (meters)
  • Vertical error (feet)
  • Time-based degradation
  • Mean trajectory deviation

Visualization

Generate comprehensive reports:

from visualization import create_trajectory_report

create_trajectory_report(
    prediction=pred,
    target=target,
    evaluation_results=metrics,
    model_name="LSTM",
    output_dir="reports"
)

Development

Project Structure

├── api/                    # FastAPI server
├── models/                 # ML model implementations
├── data/                   # Data processing and storage
├── utils/                  # Utility functions
├── config/                 # Configuration files
├── tests/                  # Unit tests
├── scripts/                # Helper scripts
├── requirements.txt        # Dependencies
├── Dockerfile             # Container definition
└── README.md              # This file

Running Tests

pytest tests/

Code Quality

# Format code
black .

# Lint code
flake8 .

# Type checking
mypy .

Deployment

Docker

# Build image
docker build -t trajectory-predictor .

# Run container
docker run -p 8000:8000 \
  -e MODEL_PATH=/app/models/best_model.pth \
  trajectory-predictor

Docker Compose

version: '3.8'
services:
  trajectory-predictor:
    build: .
    ports:
      - "8000:8000"
    environment:
      - MODEL_PATH=models/best_model.pth
    volumes:
      - ./models:/app/models

Performance Optimization

  • Model quantization for faster inference
  • Batch processing for multiple trajectories
  • GPU support for ML models
  • Redis caching for frequent queries

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Citation

If you use this system in your research, please cite:

@software{trajectory_prediction_2024,
  title={Flight Trajectory Prediction System},
  author={Your Name},
  year={2024},
  url={https://github.com/your-repo}
}

Position deltas and velocities Vertical speed and acceleration Turn rate and heading change Temporal derivatives of motion All features are normalized using statistics computed exclusively from training data to prevent data leakage. Physics-Based Baseline Model A deterministic kinematic model propagates the aircraft state forward using constant velocity and heading assumptions. Geodesic calculations are used for horizontal motion, while vertical propagation is handled using barometric altitude rates. This model serves three purposes: Baseline performance comparison Fallback prediction mechanism Reference trajectory for hybrid correction Machine Learning Models LSTM Trajectory Model A sequence-to-sequence Long Short-Term Memory (LSTM) network predicts future trajectory states from historical observations. The architecture captures short-term temporal dependencies and smooth motion patterns. Transformer Trajectory Model A Transformer-based architecture with multi-head self-attention is implemented to capture long-range temporal dependencies and complex maneuver patterns. Positional encodings are adapted for time-indexed flight data. Both models predict multi-step trajectories directly rather than iteratively, reducing error accumulation. Hybrid Prediction Framework The final prediction is obtained by combining the physics baseline with a learned correction term produced by the neural network: Predicted Trajectory = Physics Propagation + Learned Correction This approach enforces physical plausibility while allowing the model to learn systematic deviations caused by wind, pilot behavior, and operational constraints. Training Methodology Dataset splitting is performed at the flight level to avoid trajectory leakage Teacher forcing is applied during training Early stopping and learning rate scheduling are used to stabilize convergence Loss functions incorporate: Geodesic distance for horizontal error Mean squared error for vertical and kinematic variables Evaluation Framework Performance is evaluated using: Horizontal geodesic error (meters) Vertical altitude error Trajectory deviation over time Error growth with increasing prediction horizon Visual evaluation includes overlaying predicted and true trajectories in both two-dimensional and three-dimensional space. Visualization The system provides visualization utilities for: Geographic trajectory plots Three-dimensional flight paths Temporal error analysis These tools support both offline analysis and debugging of prediction behavior. Inference API A FastAPI-based service exposes prediction functionality through REST endpoints supporting: Single-trajectory inference Batch prediction Configurable prediction horizons Model selection The API is designed for integration into larger air traffic management or analytics systems. Deployment The project includes containerized deployment configurations for reproducible execution across environments. The inference service supports CPU execution with optional GPU acceleration. Applications Air traffic flow management Conflict detection and resolution systems Flight delay and fuel burn analysis Aircraft digital twins Aviation research and simulation platforms Limitations and Disclaimer This system is intended strictly for research and analytical purposes. It is not certified for operational air navigation, flight planning, or safety-critical decision making.