Repository files navigation

PixEagle is a powerful, modular image-processing and tracking suite for drones running thePX4 autopilot — with optional support for ArduPilot and integration-ready for custom systems. It combinesMAVSDK Python,OpenCV, andYOLO object detection to deliver high-performance visual tracking and autonomous following.

WithPixEagle 3.0, we’ve taken things to the next level — introducing a new GPU-acceleratedSmart Tracker, seamlessYOLO integration, a redesigned web-based GCS dashboard, and automatic model conversion tools. PixEagle is now more intelligent, flexible, and field-ready than ever before.

Whether you're using a Raspberry Pi, Jetson, or x86 companion computer — PixEagle is built for real-time, on-board vision-based autonomy.

🎬Watch the PixEagle 2.0 Demo Video:

🎬 **Watch the PixEagle 3.0 Demo Video: (Soon...) **
Your Drone Can Now Think — Smart Tracking with YOLO + PX4

• Built-inYOLO-powered tracking engine, running in real-time
• Supports any custom YOLO model — auto-detection with bounding box or click-to-track
• Works alongside classic trackers (e.g. CSRT) for hybrid tracking scenarios
• User-friendly switching between Classic / Smart modes via updated Dashboard

• EnableGPU support with a single config switch
• Automatically falls back to CPU if needed
• Works seamlessly on Jetson, NVIDIA GPUs, or CPU-only setups

• Clean toggle UI for Smart vs Classic Mode
• Visual mode indicators and status feedback
• Fully responsive layout for GCS use in the field

• Newadd_yolo_model.py utility to:
  • Download YOLO models from Ultralytics
  • Auto-convert and register them for GPU/CPU usage

• Better tracker fallback and recovery logic
• Updated GStreamer streaming support
• Added support forRTSP camera feeds
• Improved logging, error handling, and startup detection

Make sure your system meets the following requirements before installing PixEagle:

• Operating System:

  • Linux (🟢 Recommended for all use cases)
  • Windows (🟡 Supported only for simulation/SITL testing via X-Plane + WSL)
    →X-Plane SITL Guide

• Python: 3.9 or higher

• Virtual Environment Tool:venv

• Python Packages: Listed inrequirements.txt

• Node.js & npm: Required for the Dashboard UI

• Other Tools:tmux,lsof,curl (for automatic setups)

sudo apt updatesudo apt install -y python3 python3-venv python3-pip tmux lsof curl

1. Clone the Repository:

cd~git clone https://github.com/alireza787b/PixEagle.gitcd PixEagle

2. Initialize the Project (Recommended):

bash init_pixeagle.sh

This script will:

• Create a Python virtual environment
• Install all required Python packages
• Generateconfig.yaml and.env files if missing
• Download the requiredmavsdk_server_bin if not present
• Provide guidance for installing Node.js if not already installed

🧠Manual setup available if preferred — just activatevenv, install requirements, and create configs manually.

PixEagle 3.0 includesadd_yolo_model.py, a utility to download and prepare YOLO models for use in the Smart Tracker (GPU or CPU compatible).

python src/tools/add_yolo_model.py

This will:

• Download a model (e.g.yolo11s.pt) from Ultralytics
• Export to ONNX
• Optionally optimize for GPU inference
• Register the model inconfigs/config.yaml

💡 Supports custom or fine-tuned YOLO models too!

Open the configuration file to customize your setup:

nano configs/config.yaml

Edit values such as:

• Video input (webcam, RTSP, CSI, or test files)
• PID tuning
• Tracker options
• SmartTracker mode selection: GPU vs CPU, fallback behavior
• Camera field of view and orientation

Configure dashboard networking (API and streaming ports):

nano dashboard/.env

Make sure the backend IP/port matches the one used by your drone or dev machine.

🧪 Test your installation anytime with:

python src/test_Ver.py

PixEagle integrates with PX4 via MAVLink for real-time command and telemetry. Follow the steps below to set up MAVLink routing and required bridge components.

1. Clone and Install:

cd~git clone https://github.com/alireza787b/mavlink-anywhere.gitcd mavlink-anywherebash install_mavlink_router.sh

2. Configure Serial & Endpoints:

bash~/mavlink-anywhere/configure_mavlink_router.sh

• Input: e.g.,/dev/ttyAMA0,/dev/ttyS0, or/dev/ttyTHS1
• Output: e.g.,127.0.0.1:14540,127.0.0.1:14550,127.0.0.1:14569

🧠 You can runls /dev/tty* to locate the right serial port.

mavlink-routerd \  -e 127.0.0.1:14540 \  -e 127.0.0.1:14550 \  -e 127.0.0.1:14569 \  0.0.0.0:14550

Use IPs that match your SITL, companion, or GCS network setup.

1. Start MAVLink2REST:

bash~/PixEagle/src/tools/mavlink2rest/run_mavlink2rest.sh

• Default port:14569
• Binaries are auto-installed, or you can build manually from source.

PixEagle usesmavsdk_server_bin for all MAVSDK functionality.

Make sure it's in the root directory:

~/PixEagle/mavsdk_server_bin

The main startup script (run_pixeagle.sh) will prompt to install it if missing.

bash~/PixEagle/src/tools/download_mavsdk_server.sh

Or grab it from theMAVSDK Releases page and rename it tomavsdk_server_bin.

If you want to use GStreamer, you need to build opencv manually. You can use the step by step instructionhere or use (auto_opencv_build.sh) sciprt.

bash~/PixEagle/auto_opencv_build.sh

Start the full PixEagle suite with a single command:

bash run_pixeagle.sh

• ✅ Launch:
  • Main Python app (classic + smart tracking)
  • FastAPI backend
  • Web dashboard (React)
  • MAVSDK server
  • MAVLink2REST
• 🧼 Clean ports (8088,5077,3000) if in use
• ⚙️ Setup all tmux panes automatically

• Switch panes/windows:
  Ctrl + B, then arrow keys or window number
• Detach session:
  Ctrl + B, thenD
• Reattach session:

  tmux attach -t PixEagle

bash run_pixeagle.sh [-m] [-d] [-p] [-k]

• -m: Skip MAVLink2REST
• -d: Skip Dashboard
• -p: Skip Python main app
• -k: Skip MAVSDK server

Once running, open in your browser:

http://localhost:3000

From a remote device, use the host's IP address instead oflocalhost. Ensure the firewall permits port3000.

PixEagle supports RTSP, CSI, and GStreamer pipelines.

To enable, set theVIDEO_SOURCE inconfigs/config.yaml. Example:

VIDEO_SOURCE:"gst-pipeline://nvarguscamerasrc ! video/x-raw(memory:NVMM), width=640, height=480, framerate=30/1 ! nvvidconv ! video/x-raw, format=BGRx ! videoconvert ! appsink"

⚠️ Ensure OpenCV is built with GStreamer support!
GStreamer OpenCV Build Guide

Test camera and config:

python src/test_Ver.py

PixEagle is compatible with Windows forSITL/X-Plane simulation. Use WSL for routing tools and terminal scripts.

Manual steps:

1. Main App:

python src/main.py

2. Dashboard:

cd dashboardnpm installnpm start

3. MAVLink2REST:

Use WSL or Linux machine. You may need to port-forward if testing across devices.

4. Reference Guide:
   Follow Mode + X-Plane setup on Windows Guide

While in the video window, these key bindings are available:

PixEagle issupported on Windows forSITL/X-Plane only. You’ll need to manually execute certain components as bash scripts won’t work out of the box.

1. Main Application:

python src/main.py

2. Run Dashboard:

cd dashboardnpm installnpm start

3. MAVLink2REST & MAVLink Router:

To run on Windows, useWSL (Windows Subsystem for Linux) or adapt the commands accordingly.

📄For detailed SITL/X-Plane setup on Windows, refer toFollow Mode + X-Plane Guide.

• 📁 PixEagle GitHub Repository:
  https://github.com/alireza787b/PixEagle

• 📄 X-Plane SITL Instructions:
  Follow Mode Xplane Guide

• 📂 PX4Xplane Repository:
  https://github.com/alireza787b/px4xplane

• 📺 PixEagle YouTube Playlist:
  PixEagle Series

PixEagle 3.0 is currently in an experimental stage and has not been tested in real-world scenarios. Use at your own risk. The developers are not responsible for any misuse or damages resulting from the use of this software.

• 🔔 Subscribe to ourYouTube Channel for more updates and tutorials on PixEagle 2.0.
• 💬 Share your thoughts and suggestions in theissues section of our GitHub repository!
• 🔗 Join our community by contributing onGitHub.

Enjoyed PixEagle 3.0?Star ⭐ the repository,fork 🔀 it for your projects, andcontribute to help us continue to innovate and improve PixEagle. Your support is invaluable!