Metadata-Version: 2.4
Name: flight-display
Version: 0.1.0
Summary: Aircraft Tracker - Airport Departure Board Style Display for nearby aircraft
Project-URL: Homepage, https://github.com/rohankhatua/flight-display
Project-URL: Repository, https://github.com/rohankhatua/flight-display
Project-URL: Issues, https://github.com/rohankhatua/flight-display/issues
Author: Flight Display Team
License: MIT
License-File: LICENSE
Keywords: adsb,aircraft,aviation,flight,radar,tracker
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: colorama>=0.4.6
Requires-Dist: requests>=2.32.4
Requires-Dist: tabulate>=0.9.0
Description-Content-Type: text/markdown

# Flight Display ✈️

**Aircraft Tracker with Airport Departure Board Style Display**

A beautiful Python CLI tool that tracks nearby aircraft and displays them in an airport departure board style interface using real-time ADS-B data from the OpenSky Network.

## ✨ Features

- 🌍 **Auto-location detection** - Automatically detects your location using IP geolocation
- 📡 **Real-time aircraft tracking** - Uses OpenSky Network's free API for live aircraft data
- 🎯 **Adaptive radius search** - Automatically expands search radius to find aircraft
- 🏢 **Airline identification** - Enhanced operator detection with online airline database
- 🎨 **Beautiful display** - Color-coded departure board style interface
- ⚡ **Rate limit handling** - Smart retry logic for API reliability
- 🛠️ **Flexible configuration** - Customizable radius, update intervals, and coordinates

## 🚀 Installation

### Option 1: Install as a CLI tool (Recommended)

```bash
# Clone the repository
git clone <repository-url>
cd flight-display

# Install the package
pip install -e .
# or with uv
uv pip install -e .
```

### Option 2: Run directly with Python

```bash
# Install dependencies
pip install -r requirements.txt
# or with uv
uv pip install -r requirements.txt

# Run directly
python main.py
```

## 🎮 Usage

### CLI Tool (After installation)

```bash
# Auto-detect location and start tracking
flight-display

# Use specific coordinates (latitude, longitude)
flight-display --lat 40.7128 --lon -74.0060

# Set custom search radius (default: 25km)
flight-display --radius 100

# Set update interval (default: 15 seconds)
flight-display --interval 30

# Skip online airline database for faster startup
flight-display --no-online-db

# Use fixed radius (disable adaptive search)
flight-display --no-adaptive --radius 50

# Quiet mode (less verbose output)
flight-display --quiet

# Show help
flight-display --help
```

### Legacy Usage (Backward compatible)

```bash
# Auto-detect location
python main.py

# Manual coordinates
python main.py 40.7128 -74.0060
```

## 📊 Display Information

The departure board displays the following information for each aircraft:

| Column       | Description                           |
| ------------ | ------------------------------------- |
| **CALLSIGN** | Aircraft callsign or registration     |
| **OPERATOR** | Airline or operator name              |
| **TYPE**     | Aircraft type (e.g., B737, A320)      |
| **ALTITUDE** | Current altitude with color coding    |
| **SPEED**    | Ground speed in knots                 |
| **TRACK**    | Heading in degrees                    |
| **V/SPEED**  | Vertical rate with directional arrows |
| **DISTANCE** | Distance from your location           |

### Color Coding

- **🔴 Red**: Close aircraft (<10km), ground level, descending rapidly
- **🟡 Yellow**: Medium distance (10-25km), low altitude (10,000-30,000ft)
- **🟢 Green**: Far aircraft (>25km), cruising altitude (>30,000ft), climbing
- **🔵 Cyan**: High altitude cruise (>30,000ft)

## 🔧 Configuration Options

### Command Line Arguments

```bash
# Location Options
--lat, --latitude FLOAT    Your latitude coordinate
--lon, --longitude FLOAT   Your longitude coordinate

# Display Options
--radius, -r FLOAT         Search radius in km (default: 25)
--interval, -i INT         Update interval in seconds (default: 15)
--max-radius FLOAT         Maximum search radius for adaptive search (default: 200)

# Data Options
--no-online-db            Skip fetching online airline database
--no-adaptive             Disable adaptive radius search

# Output Options
--quiet, -q               Reduce output verbosity
--version, -v             Show version information
--help, -h                Show help message
```

## 🌐 Data Sources

- **OpenSky Network**: Free ADS-B aircraft position data
- **OpenFlights Database**: Airline ICAO codes and operator information
- **IP Geolocation**: Automatic location detection via ipapi.co and ipinfo.io

## 🚨 Rate Limiting

The tool includes smart rate limiting handling:

- **Automatic retries** with exponential backoff
- **Respectful API usage** with appropriate delays
- **User-friendly messages** explaining any delays
- **Graceful fallbacks** when APIs are unavailable

## 🛠️ Development

### Project Structure

```
flight-display/
├── src/flight_display/
│   ├── __init__.py         # Package initialization
│   ├── tracker.py          # Core aircraft tracking logic
│   └── cli.py             # Command-line interface
├── main.py                # Backward compatibility wrapper
├── main_legacy.py         # Legacy implementation
├── pyproject.toml         # Package configuration
└── README.md              # This file
```

### Building and Testing

```bash
# Install in development mode
pip install -e .

# Test the CLI
flight-display --help

# Test with specific coordinates
flight-display --lat 51.5074 --lon -0.1278 --radius 50
```

## 📝 Examples

### Basic Usage

```bash
# Start with auto-detection
flight-display
```

### London Heathrow Area

```bash
flight-display --lat 51.4700 --lon -0.4543 --radius 50
```

### New York Area with Custom Settings

```bash
flight-display --lat 40.7128 --lon -74.0060 --radius 75 --interval 10
```

### Quick Start (No Airline DB)

```bash
flight-display --no-online-db --radius 30
```

## 🔍 Troubleshooting

### No Aircraft Found

- **Check your location**: Make sure you're in an area with air traffic
- **Increase radius**: Try `--radius 100` or higher
- **Check time**: More aircraft during business hours and near airports
- **API issues**: Wait a few minutes and try again

### API Rate Limiting

- The tool handles rate limits automatically with retries
- If persistent, wait 5-10 minutes before trying again
- OpenSky API is free but has usage limits

### Installation Issues

```bash
# Update pip/uv first
pip install --upgrade pip
uv self update

# Clean install
pip uninstall flight-display
pip install -e .
```

## 📜 License

MIT License - See LICENSE file for details.

## 🤝 Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

---

**Happy flight tracking! ✈️**
