# AISStream.io Real-Time Integration

## Summary
Added real-time AIS vessel tracking using AISStream.io WebSocket API with dynamic zoom-based filtering.

## Features Added

### Backend (`rf_scythe_api_server.py`)
- ✅ AISStream WebSocket client (connects to wss://stream.aisstream.io/v0/stream)
- ✅ Background thread for async WebSocket handling
- ✅ Dynamic bounding box filtering based on camera viewport
- ✅ Real-time vessel updates broadcast via Socket.IO
- ✅ API endpoints:
  - `POST /api/ais/stream/start` - Start streaming with optional bbox
  - `POST /api/ais/stream/stop` - Stop streaming
  - `GET /api/ais/stream/status` - Get current status

### Frontend (`command-ops-visualization.html`)
- ✅ Socket.IO client library loaded (CDN: socket.io v4.5.4)
- ✅ `AISStreamManager` module for client-side coordination
- ✅ Automatic zoom-based streaming (activates below 100km altitude)
- ✅ Camera change monitoring with throttled bbox updates
- ✅ Real-time vessel position updates via WebSocket
- ✅ Integration with existing `AISModule` for visualization

## API Key
**AISStream API Key:** `fb05649aa20b7b9bbc6192a1074ef72978b58254`

## Installation

### 1. Install websockets library
```bash
pip install websockets
```

### 2. Restart the server
```bash
cd /home/github_bgilbert1984_NerfEngine/NerfEngine
python3 rf_scythe_api_server.py
```

## Usage

### Automatic Mode
1. Open Command Ops Console
2. Click ☰ MENU → 🌐 NETWORK
3. Enable "Show AIS Vessels" checkbox
4. Zoom into any ocean area (below 100km altitude)
5. AIS streaming starts automatically for visible region
6. Real-time vessel updates appear on globe

### Manual Control
```javascript
// Start streaming
await AISStreamManager.startStreaming();

// Stop streaming
await AISStreamManager.stopStreaming();

// Get status
const status = await AISStreamManager.getStatus();
console.log(status); // { active: true, bounding_box: [...], vessel_count: 42 }
```

## Architecture

### Data Flow
```
AISStream.io (WebSocket)
    ↓
Backend (rf_scythe_api_server.py)
    ├─ Update local AIS tracker
    └─ Broadcast via Socket.IO
         ↓
Frontend (Socket.IO client)
    ├─ Receive 'ais_update' events
    └─ Update AISModule entities
         ↓
Cesium Globe (real-time visualization)
```

### Bounding Box Updates
- **Trigger:** Camera change events
- **Throttle:** Max 1 update per second
- **Zoom threshold:** Only stream below 100km altitude
- **Format:** `[[[lon_west, lat_south], [lon_east, lat_north]]]`

## Benefits Over Static AIS
- **Real-time:** Positions update live (not stale)
- **Bandwidth efficient:** Only streams visible region
- **Scalable:** Thousands of vessels without pre-loading
- **Dynamic:** Automatically adjusts to user navigation

## Console Messages
- `🚢 AIS real-time streaming started` - Streaming active
- `🚢 AIS streaming stopped` - Streaming inactive
- `[AISStream] Bounding box updated: [...]` - Region changed
- `[AISStream] Vessel 123456789 @ 34.05,-118.25` - Vessel position received

## Troubleshooting

### Streaming not starting
- Check: `pip list | grep websockets` (must be installed)
- Check browser console for `[AISStream]` messages
- Check server logs for WebSocket connection status

### No vessels appearing
- Verify AIS checkbox is enabled in Network panel
- Verify zoom level < 100km altitude
- Check `/api/ais/stream/status` endpoint
- Verify API key is valid

### High bandwidth usage
- Reduce zoom threshold in `AISStreamManager.zoomThreshold`
- Increase throttle in `AISStreamManager.updateThrottle`