Aircraft Patterns - Pattern Detection for ADS-B/TAR1090

Real-time aircraft pattern detection system that monitors TAR1090 feeds to identify and log circular holding patterns, training flights, and grid survey patterns.

🎯 Features

Pattern Detection

• Circle Detection: Identifies aircraft flying in circular patterns (training, holding, orbits)
• Grid Detection: Detects survey/search grid patterns, mapping flights, and search & rescue operations
• Real-time Monitoring: Continuously analyzes aircraft movements from TAR1090 data feeds
• Historical Tracking: Maintains comprehensive logs of all detected patterns with TAR1090 replay links

Web Interface

• Live Map View: Real-time visualization of aircraft and detected patterns
• TAR1090-style Icons: Aircraft displayed with type-appropriate icons and altitude-based coloring
• Track History: Flight path visualization with altitude-based color coding
• Pattern History Page: Browse and filter all historical pattern detections
• Interactive Controls: Toggle aircraft display, tracks, and pattern overlays

Data & Integration

• CSV Logging: Automatic logging of all detections for analysis
• TAR1090 Integration: Direct links to view patterns in TAR1090 with proper time ranges
• Multi-source Support: Works with any TAR1090-compatible data source
• Docker Support: Easy deployment with multi-architecture container support

🚀 Quick Start

Using Docker (Recommended)

docker run -d \
  --name=aircraft-patterns \
  -p 8888:8888 \
  -e TAR1090_URL=http://your-tar1090:80 \
  -v ./data:/app/data \
  --restart unless-stopped \
  ghcr.io/challgren/aircraft-patterns:latest

Using Docker Compose

version: '3.8'

services:
  aircraft-patterns:
    image: ghcr.io/challgren/aircraft-patterns:latest
    container_name: aircraft-patterns
    restart: unless-stopped
    ports:
      - 8888:8888
    environment:
      - TAR1090_URL=http://tar1090:80
      - MIN_RADIUS=0.5
      - MAX_RADIUS=10
      - MIN_TURNS=1.5
    volumes:
      - ./data:/app/data

Manual Installation

# Clone the repository
git clone https://github.com/challgren/aircraft-patterns.git
cd aircraft-patterns

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py --server http://your-tar1090:8080 --web

📋 Configuration

Environment Variables

Variable	Description	Default
TAR1090_URL	URL of your TAR1090 instance	http://tar1090:80
WEB_PORT	Port for web interface	8888
ENABLE_WEB	Enable web interface	true
SHOW_ALL_AIRCRAFT	Show all aircraft on map	true
SHOW_TRACKS	Show aircraft track history	true
MAX_TRACK_POINTS	Maximum track points per aircraft	50

Detection Parameters

Circle Detection

Variable	Description	Default
MIN_RADIUS	Minimum circle radius (km)	0.5
MAX_RADIUS	Maximum circle radius (km)	10
MIN_TURNS	Minimum number of turns	1.5

Grid Detection

Variable	Description	Default
MIN_GRID_LEGS	Minimum parallel legs	3
MIN_LEG_LENGTH	Minimum leg length (km)	2.0

🏥 Health Monitoring

Docker Health Check

The container includes comprehensive health checks that monitor:

• Python process status
• Web server responsiveness (when enabled)
• API endpoint availability
• TAR1090 connection status
• Log file writability

Health check configuration:

• Start Period: 60 seconds (allows service to fully initialize)
• Check Interval: 30 seconds
• Timeout: 10 seconds per check
• Retries: 3 failures before marking unhealthy

Health API Endpoint

Access health status at: http://localhost:8888/api/health

{
  "status": "healthy",
  "timestamp": 1234567890.123,
  "checks": {
    "web_server": true,
    "tar1090_connection": true,
    "last_update": 1234567890.123,
    "aircraft_count": 115,
    "active_circles": 2,
    "active_grids": 1,
    "total_requests": 1000,
    "failed_requests": 5
  }
}

Status values:

• healthy - All systems operational
• degraded - Service running but with issues (e.g., TAR1090 connection lost)

🖥️ Web Interface

Live View

Access at: http://localhost:8888

• Real-time aircraft positions with TAR1090-style icons
• Live pattern detection with visual overlays
• Interactive controls for display options
• Auto-centering on new pattern detections

History View

Access at: http://localhost:8888/history

• Browse all historical pattern detections

Reverse Proxy Support

The application works seamlessly behind reverse proxies including when mounted at a subpath. The application automatically detects its base URL and adjusts all links and API calls accordingly.

Nginx Configuration Example

For mounting at /circles/:

location /circles/ {
    proxy_pass http://aircraft-patterns:8888/;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $http_connection;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_redirect / /circles/;
}

Docker Compose with sdr-enthusiasts/docker-reversewebproxy

services:
  reversewebproxy:
    image: ghcr.io/sdr-enthusiasts/docker-reversewebproxy:latest
    ports:
      - "80:80"
      - "443:443"
    environment:
      - PROXY_HOSTS=aircraft,aircraft-patterns,8888

  aircraft-patterns:
    image: ghcr.io/challgren/aircraft-patterns:latest
    environment:
      - TAR1090_URL=http://tar1090:80

The application automatically handles:

• X-Forwarded-For - Client IP addresses

• X-Forwarded-Proto - HTTP/HTTPS protocol

• X-Forwarded-Host - Original hostname

• X-Forwarded-Prefix - URL path prefix

• Relative URLs for all navigation and API calls

• Automatic base URL detection for subpath mounting

• Filter by date range, pattern type, and callsign

• Visual timeline of detection activity

• Direct links to TAR1090 replay for each pattern

• Interactive map showing all historical patterns

📊 Data Output

CSV Files

Pattern detections are automatically logged to CSV files in the data directory:

• circle_detections.csv - All circular pattern detections
• grid_detections.csv - All grid pattern detections

CSV Fields

• Timestamp, Aircraft ID, Callsign
• Pattern characteristics (radius, turns, coverage area)
• Position data (center lat/lon)
• Flight data (altitude, speed)
• TAR1090 replay URL

🐳 Docker Deployment

Multi-Architecture Support

The container supports multiple architectures:

• linux/amd64 - Standard x86-64
• linux/arm64 - 64-bit ARM (Raspberry Pi 4, etc.)
• linux/arm/v7 - 32-bit ARM

Complete Stack Example

version: '3.8'

services:
  readsb:
    image: ghcr.io/sdr-enthusiasts/docker-readsb-protobuf:latest
    devices:
      - /dev/bus/usb
    environment:
      - READSB_DEVICE_TYPE=rtlsdr
      - READSB_LAT=YOUR_LATITUDE
      - READSB_LON=YOUR_LONGITUDE

  tar1090:
    image: ghcr.io/sdr-enthusiasts/docker-tar1090:latest
    environment:
      - BEASTHOST=readsb
    ports:
      - 8080:80

  aircraft-patterns:
    image: ghcr.io/challgren/aircraft-patterns:latest
    ports:
      - 8888:8888
    environment:
      - TAR1090_URL=http://tar1090:80
    volumes:
      - ./data:/app/data
    depends_on:
      - tar1090

🔧 Command Line Options

python app.py [options]

Options:
  --server URL          TAR1090 server URL
  --web                 Enable web interface
  --web-port PORT       Web interface port (default: 8888)
  --min-radius KM       Minimum circle radius
  --max-radius KM       Maximum circle radius
  --min-turns N         Minimum turns for circle detection
  --min-grid-legs N     Minimum legs for grid detection
  --min-leg-length KM   Minimum leg length for grids
  --compact             Compact display mode
  --quiet               Only show alerts
  --test                Test connection to TAR1090
  --show-log            Display detection history

📈 Pattern Detection Logic

Circle Detection Algorithm

1. Analyzes aircraft track points to identify curved paths
2. Calculates center point and radius of potential circles
3. Counts completed turns (360° rotations)
4. Validates against minimum radius and turn requirements
5. Logs detection with TAR1090 replay link

Grid Detection Algorithm

1. Identifies parallel flight segments
2. Analyzes heading changes between legs
3. Validates grid spacing and coverage area
4. Classifies pattern type (survey, search, mapping)
5. Logs detection with pattern characteristics

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📝 License

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

🙏 Acknowledgments

• sdr-enthusiasts community for Docker patterns and base images
• wiedehopf for TAR1090
• Aircraft icons adapted from TAR1090 marker system

🐛 Issues & Support

• GitHub Issues
• SDR-Enthusiasts Discord

📊 Stats

• Typical detection range: 0.5-10km radius circles
• Processing rate: 100+ aircraft simultaneously
• Detection accuracy: ~95% for standard patterns
• Average memory usage: < 100MB
• CPU usage: < 5% on modern hardware

---

Made with ❤️ for the aviation and SDR community