clemens/DJI-HeadsUp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7 Commits 1 Branch 0 Tags
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE
clemens 888b53713b README.md aktualisiert
2025-06-12 15:23:56 +00:00
main.py
main.py
2025-06-09 13:53:19 +00:00
README.md
README.md aktualisiert
2025-06-12 15:23:56 +00:00
requirements.txt
requirements.txt
2025-06-12 15:10:25 +00:00
screenshot.png
Dateien nach "/" hochladen
2025-06-12 15:23:20 +00:00

README.md

DJI Drone Telemetry Overlay Viewer

License: MIT Python Version Platform

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

🎯 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
  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:

# Using Homebrew (recommended)
brew install ffmpeg

# Using MacPorts
sudo port install ffmpeg

# Verify installation
ffmpeg -version

Linux (Ubuntu/Debian):

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
  • 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

    git clone https://swnetworks.de/gitea/clemens/DJI-HeadsUp.git
cd DJI-HeadsUp

  2. Create Virtual Environment

    # 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

    # Upgrade pip first
pip install --upgrade pip

# Install all requirements
pip install -r requirements.txt

  4. Verify Installation

    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:

# 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:

# 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

    python main.py

    Or if you've installed it as a package:

    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

{
  "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:

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 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

🗺️ 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

Description
No description provided
Readme 2.9 MiB
Languages
Python 100%