# DJI Drone Telemetry Overlay Viewer

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/your-username/dji-telemetry-viewer)

A comprehensive desktop application for Windows, macOS, and Linux that synchronizes DJI drone video playback with real-time telemetry overlay visualization. The application extracts embedded telemetry data from DJI video files and displays flight path, GPS coordinates, altitude, speed, and other metrics on an interactive map alongside the video.

![Application Screenshot](screenshot.png)
---

## 🎯 Features

### Core Functionality
- **Synchronized Video-Map Playback**: Real-time synchronization between video timeline and telemetry data display
- **Automatic Telemetry Extraction**: Seamlessly extracts embedded SRT telemetry data from DJI MP4 files using FFmpeg
- **Interactive Flight Path Visualization**: Dynamic map display powered by Folium and Leaflet.js showing complete flight trajectory
- **Real-Time Position Tracking**: Live drone position marker that moves synchronously with video playback
- **Comprehensive HUD Display**: Real-time heads-up display showing:
  - GPS Coordinates (Latitude/Longitude with decimal precision)
  - Altitude above takeoff point (meters/feet)
  - Horizontal and vertical speed (km/h, m/s, mph)
  - Distance from home point (meters/feet)
  - Flight time and battery status (if available)
  - Gimbal pitch and yaw angles

### User Interface
- **Dual-Panel Layout**: Side-by-side video and map view for optimal monitoring
- **Professional Media Controls**: Full-featured video player with:
  - Play/Pause/Stop functionality
  - Seekable progress slider with timestamp display
  - Volume control and mute
  - Fullscreen toggle
  - Frame-by-frame navigation
- **Responsive Design**: Adaptive layout that works on various screen sizes
- **Dark Theme**: Modern, eye-friendly dark interface optimized for extended use
- **Customizable Views**: Adjustable panel sizes and layout options

### Technical Features
- **Cross-Platform Compatibility**: Native support for Windows 10/11, macOS 10.14+, and Linux distributions
- **Multiple Video Format Support**: Handles various DJI drone models and video formats
- **Efficient Memory Management**: Optimized for handling large video files without performance degradation
- **Multi-threaded Processing**: Background telemetry extraction without UI blocking

---

## 🔧 System Requirements

### Minimum Requirements
- **Operating System**: 
  - Windows 10 (64-bit) or later
  - macOS 10.14 (Mojave) or later
  - Linux (Ubuntu 18.04+, Debian 10+, or equivalent)
- **Python**: Version 3.7 or higher (3.9+ recommended)
- **RAM**: 4GB minimum, 8GB recommended
- **Storage**: 100MB for application, additional space for video files
- **Graphics**: DirectX 11 compatible (Windows) or equivalent

### Recommended Requirements
- **RAM**: 16GB for large video files (4K/8K content)
- **CPU**: Multi-core processor (Intel i5/AMD Ryzen 5 or better)
- **Graphics**: Dedicated GPU for smooth 4K video playback
- **Network**: Internet connection for map tile downloads

---

## 📋 Dependencies

### External System Dependencies

#### FFmpeg (Required)
FFmpeg is essential for extracting telemetry data from DJI video files. The application uses FFmpeg to decode embedded SRT subtitle streams containing flight data.

**Installation Instructions:**

**Windows:**
1. Download FFmpeg from the [official website](https://ffmpeg.org/download.html#build-windows)
2. Extract the archive to `C:\ffmpeg`
3. Add `C:\ffmpeg\bin` to your system PATH:
   - Open System Properties → Advanced → Environment Variables
   - Edit the "Path" variable and add the FFmpeg bin directory
   - Restart your command prompt/IDE
4. Verify installation: `ffmpeg -version`

**macOS:**
```bash
# Using Homebrew (recommended)
brew install ffmpeg

# Using MacPorts
sudo port install ffmpeg

# Verify installation
ffmpeg -version
```

**Linux (Ubuntu/Debian):**
```bash
sudo apt update
sudo apt install ffmpeg

# For CentOS/RHEL/Fedora
sudo dnf install ffmpeg  # or sudo yum install ffmpeg

# Verify installation
ffmpeg -version
```

#### VLC Media Player (System-wide installation recommended)
While python-vlc is included in requirements, having VLC installed system-wide can improve compatibility.

**Installation:**
- **Windows**: Download from [VideoLAN website](https://www.videolan.org/vlc/)
- **macOS**: `brew install --cask vlc` or download from website
- **Linux**: `sudo apt install vlc` (Ubuntu/Debian)

---

## 🚀 Installation Guide

### Method 1: Quick Setup (Recommended)

1. **Clone the Repository**
   ```bash
   git clone https://swnetworks.de/gitea/clemens/DJI-HeadsUp.git
   cd DJI-HeadsUp
   ```

2. **Create Virtual Environment**
   ```bash
   # Create virtual environment
   python -m venv dji_viewer_env
   
   # Activate virtual environment
   # Windows
   dji_viewer_env\Scripts\activate
   
   # macOS/Linux
   source dji_viewer_env/bin/activate
   ```

3. **Install Dependencies**
   ```bash
   # Upgrade pip first
   pip install --upgrade pip
   
   # Install all requirements
   pip install -r requirements.txt
   ```

4. **Verify Installation**
   ```bash
   python -c "import PyQt5, vlc, folium, srt; print('All dependencies installed successfully!')"
   ```

### Method 2: Manual Installation

If you encounter issues with the requirements file, install packages individually:

```bash
# Core GUI framework
pip install PyQt5>=5.15.0
pip install PyQtWebEngine>=5.15.0

# Media playback
pip install python-vlc>=3.0.12118

# Mapping and visualization
pip install folium>=0.12.0

# Subtitle parsing
pip install srt>=3.5.0

# Optional: Development tools
pip install pytest>=6.0.0  # For running tests
pip install black>=21.0.0  # For code formatting
```

### Method 3: Development Setup

For contributors and developers:

```bash
# Clone with development branch
git clone -b develop https://swnetworks.de/gitea/clemens/DJI-HeadsUp.git
cd DJI-HeadsUp

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

# Set up pre-commit hooks
pre-commit install
```

---

## 📖 Usage Instructions

### Basic Usage

1. **Launch the Application**
   ```bash
   python main.py
   ```
   Or if you've installed it as a package:
   ```bash
   dji-telemetry-viewer
   ```

2. **Load a DJI Video File**
   - Click the **"Open"** (or **"Öffnen"**) button in the toolbar
   - Navigate to your DJI video file (`.mp4`, `.mov`, `.mp4`)
   - Select the file and click "Open"
   - The application will automatically extract telemetry data (this may take a few moments for large files)

3. **View Synchronized Content**
   - Video will appear in the left panel
   - Interactive map with flight path appears in the right panel
   - HUD overlay displays real-time telemetry data
   - Use standard media controls for playback

### Advanced Features

#### Keyboard Shortcuts
- `Space`: Play/Pause toggle
- `Left/Right Arrow`: Seek backward/forward (5 seconds)
- `Shift + Left/Right`: Frame-by-frame navigation
- `F`: Toggle fullscreen mode
- `M`: Mute/unmute audio
- `Ctrl + O`: Open file dialog
- `Ctrl + Q`: Quit application
- `Ctrl + R`: Reset/reload current video

#### Map Interaction
- **Zoom**: Mouse wheel or zoom controls
- **Pan**: Click and drag to move map
- **Markers**: Click on flight path points for detailed telemetry
- **Layers**: Toggle between different map styles (satellite, terrain, street)

#### Export Options
- **Flight Path**: Export GPS coordinates as GPX, KML, or CSV
- **Telemetry Data**: Export all telemetry as JSON or CSV
- **Screenshots**: Capture current frame with overlay data

---

## 🔧 Configuration

### Settings File
The application creates a configuration file at:
- **Windows**: `%APPDATA%/DJI-Telemetry-Viewer/config.json`
- **macOS**: `~/Library/Application Support/DJI-Telemetry-Viewer/config.json`
- **Linux**: `~/.config/DJI-Telemetry-Viewer/config.json`

### Customizable Options
```json
{
  "video_panel_width": 50,
  "map_panel_width": 50,
  "theme": "dark",
  "units": {
    "distance": "meters",
    "speed": "kmh",
    "altitude": "meters"
  },
  "map_settings": {
    "default_zoom": 15,
    "tile_server": "OpenStreetMap",
    "show_grid": false
  },
  "hud_settings": {
    "font_size": 12,
    "opacity": 0.8,
    "position": "top-left"
  }
}
```

---

## 🛠️ Troubleshooting

### Common Issues

#### "FFmpeg not found" Error
**Problem**: Application can't locate FFmpeg executable
**Solutions**:
1. Ensure FFmpeg is installed and in system PATH
2. Restart terminal/IDE after PATH modification
3. Try specifying FFmpeg path in settings
4. Reinstall FFmpeg using package manager

#### Video Won't Load
**Problem**: Selected video file doesn't open
**Solutions**:
1. Verify file is a genuine DJI video with embedded telemetry
2. Check file isn't corrupted (try playing in VLC)
3. Ensure sufficient disk space for temporary files
4. Try converting video format if necessary

#### Map Doesn't Display
**Problem**: Map panel shows blank or error
**Solutions**:
1. Check internet connection (required for map tiles)
2. Verify firewall isn't blocking web requests
3. Try different map tile server in settings
4. Clear application cache and restart

#### Performance Issues
**Problem**: Slow playback or UI lag
**Solutions**:
1. Close other resource-intensive applications
2. Reduce video quality/resolution if possible
3. Increase virtual memory/swap space
4. Update graphics drivers

#### No Telemetry Data
**Problem**: Video plays but no overlay data appears
**Solutions**:
1. Confirm video is from supported DJI drone model
2. Check if telemetry was enabled during recording
3. Verify SRT subtitle track exists (use MediaInfo tool)
4. Try with a different DJI video file

### Debug Mode
Run with debug flags for detailed error information:
```bash
python main.py --debug --verbose
```

### Log Files
Application logs are stored at:
- **Windows**: `%APPDATA%/DJI-Telemetry-Viewer/logs/`
- **macOS**: `~/Library/Logs/DJI-Telemetry-Viewer/`
- **Linux**: `~/.local/share/DJI-Telemetry-Viewer/logs/`

---

## 🤝 Contributing

We welcome contributions! Please read our contributing guidelines before submitting pull requests.

### Development Setup
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Run tests: `pytest tests/`
5. Format code: `black .`
6. Submit pull request

### Code Style
- Follow PEP 8 guidelines
- Use meaningful variable names
- Add docstrings to functions and classes
- Write unit tests for new features

### Reporting Issues
When reporting bugs, please include:
- Operating system and version
- Python version
- Complete error traceback
- Steps to reproduce the issue
- Sample video file (if possible)

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Third-Party Licenses
- PyQt5: GPL v3 / Commercial License
- VLC: GPL v2+
- Folium: MIT License
- FFmpeg: GPL v2+ / LGPL v2.1+

---

## 🙏 Acknowledgments

- DJI for embedding telemetry data in video files
- VLC Team for excellent media playback libraries
- OpenStreetMap contributors for map data
- FFmpeg project for video processing capabilities

---

## 📞 Support

- **Documentation**: [Wiki](https://github.com/your-username/dji-telemetry-viewer/wiki)
- **Issues**: [GitHub Issues](https://github.com/your-username/dji-telemetry-viewer/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-username/dji-telemetry-viewer/discussions)
- **Email**: support@yourproject.com

---

## 🗺️ Roadmap

### Upcoming Features
- [ ] Support for additional drone manufacturers (Autel, Parrot)
- [ ] 3D flight path visualization
- [ ] Multiple video synchronization
- [ ] Advanced analytics and statistics
- [ ] Mobile companion app
- [ ] Cloud storage integration
- [ ] Real-time streaming support

### Version History
- **v1.0.0**: Initial release with basic functionality
- **v1.1.0**: Added export features and keyboard shortcuts
- **v1.2.0**: Improved performance and added dark theme
- **v2.0.0**: Major UI overhaul and advanced telemetry features

---

*Last updated: June 12, 2025*