ADS-Bit/PROJECT_DOCUMENTATION.md

# Pixel ADS-B View - Project Documentation

## Overview
A retro SNES-style side-view flight tracker that displays ADS-B aircraft data in a fun pixel art interface with custom ChatGPT-generated sprites for aircraft, scenery, celestial bodies, and weather.

## Project Structure
```
/root/IceNet-ADS-B/pixel-view/
├── index.html              - Main HTML interface (v=36)
├── pixel-view.js           - JavaScript rendering engine
├── server.py               - Python WebSocket server
├── smallProp.png           - Small propeller aircraft sprite
├── regionalJet.png         - Regional jet sprite
├── narrowBody.png          - Narrow body jet sprite (737/A320)
├── wideBody.png            - Wide body jet sprite (777/787)
├── heavy.png               - Jumbo jet sprite (747/A380)
├── helicopter.png          - Helicopter sprite
├── desert.png              - Vegas desert landscape background
├── base.png                - ADS-B receiver station building with antenna
├── sun.png                 - Animated sun sprite
├── moon_6_phases.png       - Moon sprite sheet (2x3 grid, 6 phases)
├── happycloud.png          - Sunny weather cloud sprite
├── raincloud.png           - Rainy/snowy weather cloud sprite
└── PROJECT_DOCUMENTATION.md - This file
```

## Current Configuration

### Display Settings
- **Canvas Resolution**: 800x600 pixels
- **Container Max Width**: 1400px
- **Aircraft Sprite Size**: 110px tall (scaled from original images)
- **Moon Size**: 120px tall (200% scale)
- **Base Station**: 150px height
- **Cloud Height**: 90px (150% scale)
- **Sun Size**: 50px tall
- **Cache Version**: v=36
- **Frame Rate**: 10 FPS (retro feel)

### Visual Assets
All sprites are **COMPLETE** and integrated:

**Aircraft (6 types):**
- ✅ **smallProp.png** (193K) - Right-facing, transparent background
- ✅ **regionalJet.png** (185K) - Right-facing, transparent background
- ✅ **narrowBody.png** (193K) - Right-facing, transparent background
- ✅ **wideBody.png** (264K) - Right-facing, transparent background
- ✅ **heavy.png** (361K) - Right-facing, transparent background
- ✅ **helicopter.png** (216K) - Right-facing, transparent background

**Scenery:**
- ✅ **desert.png** (371K) - Vegas desert landscape, full-width background
- ✅ **base.png** - ADS-B receiver station with antenna tower, transparent background

**Celestial:**
- ✅ **sun.png** - Animated sun sprite
- ✅ **moon_6_phases.png** (1.4M) - Sprite sheet with 6 moon phases

**Weather:**
- ✅ **happycloud.png** - Clear weather clouds
- ✅ **raincloud.png** - Rain/snow weather clouds

## Features Implemented

### 1. Custom Pixel Art Aircraft Rendering
- **PNG image-based rendering** with fallback to sprite arrays
- Images loaded asynchronously via JavaScript Image objects
- Scaled dynamically to 110px height while maintaining aspect ratio
- **Horizontal flipping** for westbound aircraft (track > 90° and < 270°)
- Visual feedback:
  - **Approaching**: Full brightness, saturated colors
  - **Departing**: 85% opacity, desaturated
- Located in: `pixel-view.js:1347-1395`

### 2. Aircraft Type Categorization
Six aircraft categories with intelligent detection:

1. **Helicopter**
   - Detection: altitude < 5000 ft AND speed < 150 knots
   - Priority: Checked first before other types

2. **Heavy** (747, A380)
   - Callsigns: CPA, UAE, ETH, QTR, SIA, etc.
   - OR: altitude > 42000 ft OR speed > 550 knots
   - Features: Upper deck hump visible in sprite

3. **Wide Body** (777, 787, A350)
   - High altitude: > 40000 ft OR speed > 500 knots
   - Larger twin-engine design

4. **Narrow Body** (737, A320)
   - Default category for most commercial aircraft
   - Typical cruise altitudes and speeds

5. **Regional Jet** (CRJ, ERJ)
   - Callsigns: SKW, RPA, ASH, PDT, CHQ, ENY
   - OR: altitude < 25000 ft AND speed < 350 knots

6. **Small Prop** (Cessna, GA)
   - Callsigns starting with 'N' or very short
   - OR: altitude < 10000 ft AND speed < 200 knots

### 3. Vegas Desert Landscape Background
- **Full-width background image** (desert.png)
- Cropped Vegas desert scene with mountains
- Scales to canvas width while maintaining aspect ratio
- Transparent background removed for clean integration
- Positioned at bottom of display
- Located in: `pixel-view.js:1138-1147`

### 4. ADS-B Receiver Station
- **Base.png sprite** overlaid on desert background
- Shows receiver building with antenna tower
- 150px height, maintains aspect ratio
- Centered horizontally at screen bottom
- Transparent background allows desert to show through
- Located in: `pixel-view.js:1149-1161`

### 5. Dynamic Sky Colors (Based on Sun Position)
Sky colors change throughout the day based on actual sunrise/sunset times:
- **Night**: Dark blue/purple (#1c2c4c → #2c3c5c)
- **Dawn**: Orange/pink sunrise (#4c5c8c → #dc8c5c)
- **Day**: Bright blue (#6ca4dc → #b4d4ec)
- **Dusk**: Orange/purple sunset (#6c5c9c → #dc9c6c)
- 30-minute transition periods for smooth changes
- Weather adjustments (darker for rain/snow)
- Located in: `pixel-view.js:678-795`

### 6. Accurate Sun Positioning & Sprite
**Sun:**
- PNG sprite rendering (sun.png)
- Astronomical calculations for altitude (0-90°) and azimuth (90-270°)
- Moves from east (sunrise) to west (sunset)
- 50px height display size
- Dims when cloudy, hidden during rain/snow
- Located in: `pixel-view.js:940-1027`

### 7. Realistic Moon Phases
**Moon Sprite System:**
- **6-phase sprite sheet** (moon_6_phases.png)
- 2x3 grid layout:
  - Row 1: Waxing Crescent, First Quarter, Waxing Gibbous
  - Row 2: Full Moon, Waning Gibbous, Last Quarter
- Waning crescent uses mirrored waxing crescent
- **Phase calculation** based on 29.53-day lunar cycle
- Scaled to 120px height (200% of original design)
- Maintains aspect ratio automatically
- Brighter at night (100% alpha), dimmer during day (60% alpha)
- Opposite positioning from sun (12-hour offset)
- New moon phase not displayed
- Located in: `pixel-view.js:876-938`, `pixel-view.js:1029-1138`

**Moon Phases:**
- Phase 0.00-0.05: New Moon (not displayed)
- Phase 0.05-0.20: Waxing Crescent
- Phase 0.20-0.30: First Quarter
- Phase 0.30-0.48: Waxing Gibbous
- Phase 0.48-0.52: Full Moon
- Phase 0.52-0.70: Waning Gibbous
- Phase 0.70-0.80: Last Quarter
- Phase 0.80-0.95: Waning Crescent (mirrored)
- Phase 0.95-1.00: New Moon (not displayed)

### 8. Weather Cloud Sprites
**Cloud System:**
- Automatic cloud type selection based on weather conditions
- **happycloud.png**: Clear/normal weather
- **raincloud.png**: Rain or snow conditions
- 90px height (150% scale), maintains aspect ratio
- Animated horizontal scrolling
- Randomized vertical positions for natural distribution
- Varying speeds for depth effect
- 4 clouds for clear weather, 8 clouds for rain/cloudy
- NO pixelated weather effects - clouds represent weather visually
- Located in: `pixel-view.js:797-850`

### 9. Sunrise/Sunset Display
- Actual sunrise and sunset times from Open-Meteo API
- Format: "☀ 6:45 AM / 🌙 5:30 PM"
- Updates every 10 minutes
- Located in: `index.html:169`

### 10. Weather Integration
- Real-time weather from Open-Meteo API
- Conditions:
  - **Clear**: Sunny clouds, full brightness
  - **Cloudy**: More clouds, dimmed sun
  - **Rain**: Rain clouds, darker sky, no sun
  - **Snow**: Rain clouds, darker sky, no sun
- Temperature in Fahrenheit
- Updates every 10 minutes
- Located in: `pixel-view.js:797-850`

## Technical Details

### Image Loading System
```javascript
// Aircraft images
this.aircraftImages = {
    smallProp: new Image(),
    regionalJet: new Image(),
    narrowBody: new Image(),
    wideBody: new Image(),
    heavy: new Image(),
    helicopter: new Image()
};

// Environment images
this.desertImage = new Image();          // Vegas desert landscape
this.baseImage = new Image();            // Receiver station
this.sunImage = new Image();             // Sun sprite
this.moonSprite = new Image();           // Moon phases sprite sheet
this.happyCloudImage = new Image();      // Clear weather clouds
this.rainCloudImage = new Image();       // Rain weather clouds
```

### Rendering Pipeline & Layer Order
Layers drawn from bottom to top:

1. **Sky gradient** - Dynamic colors based on time of day
2. **Clouds** - Happy or rain clouds based on weather
3. **Sun** - Moves across sky based on actual sun position
4. **Moon** - Phase-accurate sprite from sheet
5. **Desert background** - Full-width Vegas landscape
6. **Grid lines** - Altitude reference (every 10,000 feet)
7. **Base station** - ADS-B receiver building with antenna
8. **Aircraft** - Scaled, positioned, and oriented correctly
9. **Scale indicators** - Altitude labels on left side
10. **Compass indicators** - North/South directional arrows

### Aircraft Direction Logic
```javascript
// Sprites face right (eastward) by default
// Flip horizontally when heading west
const isFacingLeft = flight.track > 90 && flight.track < 270;

// Heading ranges:
// 0°-90°   (N to E): Face right ➡️
// 90°-180° (E to S): Face right ➡️
// 180°-270° (S to W): Flip left ⬅️
// 270°-360° (W to N): Flip left ⬅️
```

### Moon Sprite Sheet Cropping
```javascript
// 2x3 grid: 3 columns, 2 rows
const spriteWidth = moonSprite.width / 3;
const spriteHeight = moonSprite.height / 2;

// Select sprite based on phase
const sx = spritePos.col * spriteWidth;  // X position in sheet
const sy = spritePos.row * spriteHeight; // Y position in sheet

// Draw cropped section
ctx.drawImage(moonSprite,
    sx, sy, spriteWidth, spriteHeight,  // Source rectangle
    destX, destY, targetWidth, targetHeight  // Destination
);
```

### API Endpoints Used
- **Open-Meteo Forecast API**: Weather and sunrise/sunset
  - Endpoint: `https://api.open-meteo.com/v1/forecast`
  - Parameters: latitude, longitude, current_weather, daily
  - Update interval: 10 minutes

### WebSocket Communication
- **Server**: Python 3 with aiohttp
- **Port**: 2001
- **Protocol**: JSON messages
- **Update Rate**: 1 second
- **Message Format**:
  ```json
  {
    "type": "flights",
    "flights": [
      {
        "icao": "ABC123",
        "callsign": "UAL123",
        "lat": 36.1,
        "lon": -115.2,
        "altitude": 35000,
        "speed": 450,
        "track": 90
      }
    ]
  }
  ```

### ADS-B Data Processing
- Server scans network for SBS receivers (port 30003)
- Common receiver IPs: .38, .100, .101
- Parses SBS/BaseStation format messages
- Broadcasts to WebSocket clients every 1 second
- Cleans up flights not seen in 60 seconds

### Receiver Location
- **Default**: Las Vegas, NV (36.2788°N, 115.2283°W)
- **API**: `/api/receiver-location`
- **Uses**: Distance calculations, weather data, sun/moon positioning

## Image Processing Details

### Original Source
- Generated via ChatGPT/DALL-E with custom prompts
- Downloaded from SMB share: `\\192.168.0.150\allen\Projects\PixelADSB`
- Credentials: allen / *69ChopsOne69*

### Processing Commands
```bash
# Download from SMB
smbclient //192.168.0.150/allen -U 'allen%*69ChopsOne69*' \
  -c "cd Projects\\PixelADSB; prompt OFF; mget *.png"

# Flip aircraft sprites (originally facing left)
for img in smallProp.png regionalJet.png narrowBody.png \
           wideBody.png heavy.png helicopter.png
do
  convert "$img" -flop "$img"
done

# Rename background
mv VegasDesertBackground.png desert.png
```

### Image Specifications
**Aircraft:**
- Original: High-resolution PNG (185K - 361K)
- Facing: RIGHT (east) after horizontal flip
- Background: Transparent
- Display: 110px height, aspect ratio maintained

**Desert:**
- Original: 839K → Cropped: 371K
- White background removed (transparent)
- Display: Full canvas width, aspect ratio maintained

**Base Station:**
- Transparent background
- Display: 150px height, centered

**Moon:**
- Sprite sheet: 1.4M (2x3 grid)
- Display: 120px height per phase
- Aspect ratio maintained for each phase

**Sun:**
- Display: 50px tall

**Clouds:**
- Display: 90px height
- Two variants: happy (clear), rain (bad weather)

## Server Management

### Running the Server
```bash
cd /root/IceNet-ADS-B/pixel-view
python3 server.py
```

### Server Access
- **Local**: http://192.168.0.254:2001
- **WebSocket**: ws://192.168.0.254:2001/ws
- **Tailscale Funnel**: Available (check tailscale status)

### Background Processes
Multiple server instances may be running in background.
- Check: `ps aux | grep server.py`
- Kill all: `pkill -9 -f server.py`

## Version History
- **v=36** (Current): Removed pixelated weather effects
- **v=35**: Moon scaled to 200% (120px)
- **v=34**: Moon aspect ratio fix
- **v=33**: Moon sprite sheet implementation (6 phases)
- **v=32**: Aircraft direction logic fixed
- **v=31**: Desert background implementation
- **v=30**: Desert + base layering
- **v=29**: Base station sprite added
- **v=24**: Cloud sprites (happy + rain)
- **v=20**: Aircraft size 110px
- **v=16**: PNG image rendering with custom sprites

## Key Code Locations

### Aircraft
- `pixel-view.js:85-92` - Aircraft image loading
- `pixel-view.js:1347-1349` - Direction logic (flip when westbound)
- `pixel-view.js:1374-1393` - PNG rendering with flip

### Scenery
- `pixel-view.js:95-113` - Desert and base image loading
- `pixel-view.js:1138-1147` - Desert background rendering (full width)
- `pixel-view.js:1149-1161` - Base station rendering (on top)

### Celestial
- `pixel-view.js:115-123` - Sun image loading
- `pixel-view.js:145-153` - Moon sprite sheet loading
- `pixel-view.js:940-1027` - Sun sprite rendering
- `pixel-view.js:1029-1059` - Moon phase calculation
- `pixel-view.js:1061-1138` - Moon sprite rendering with cropping

### Weather
- `pixel-view.js:125-143` - Cloud sprite loading
- `pixel-view.js:797-850` - Cloud rendering (auto-selects rain vs happy)

### Sky
- `pixel-view.js:678-795` - Dynamic sky colors

## Removed Features
The following pixel-generated features were removed and replaced with sprite images:
- ❌ Pixel-generated mountains (replaced by desert.png)
- ❌ Pixel-generated cacti (included in desert.png)
- ❌ Pixel-generated ADS-B tower (replaced by base.png)
- ❌ Pixelated rain/snow effects (weather shown via cloud sprites)

## Status
✅ **COMPLETE** - All features implemented and working
- All 6 aircraft sprites integrated
- Vegas desert landscape background
- ADS-B receiver station sprite
- 6-phase moon sprite system
- Sun sprite
- Weather cloud sprites (happy + rain)
- Helicopter detection active
- Accurate celestial positioning
- Weather-reactive visuals
- All sprites properly layered

---
Last Updated: December 30, 2025
Project Status: Complete and Operational
Current Version: v=36