PixEagle

Vision-based autonomous tracking system for drones and ground vehicles

PixEagle is a modular image-processing and tracking suite for drones running PX4 autopilot. It combines MAVSDK Python, OpenCV, and YOLO object detection to deliver high-performance visual tracking and autonomous following.

Full Documentation | Changelog | YouTube Demo

Features

Feature	Description	Documentation
Tracker System	5 tracker types: CSRT, KCF, YOLO, SmartTracker, Gimbal	Tracker Docs
Follower System	10 control modes: velocity, position, attitude, gimbal pursuit	Follower Docs
Video & Streaming	7 input sources, GStreamer, MJPEG/WebSocket streaming	Video Docs
Professional OSD	Aviation-grade on-screen display with layered real-time pipeline and TrueType fonts	OSD Guide
Drone Interface	PX4 integration via MAVSDK & MAVLink2REST	Drone Docs
Core App	REST API, WebSocket, schema-driven configuration	Core Docs
GPU Acceleration	CUDA support for 60+ FPS, automatic CPU fallback	Installation
Web Dashboard	Real-time monitoring, model management, config UI	-

Documentation

System	Description	Guide
Trackers	CSRT, KCF, YOLO, SmartTracker, Gimbal tracking	docs/trackers/
Followers	10 control modes (velocity, position, attitude)	docs/followers/
Video	7 input sources, GStreamer, OSD, streaming	docs/video/
Drone Interface	PX4, MAVLink, MAVSDK setup & troubleshooting	docs/drone-interface/
Core App	REST API, WebSocket, configuration system	docs/core-app/
Development	Schema architecture, custom components	docs/developers/

Quick Links: Installation | Configuration | Troubleshooting

Demo

Full YouTube Playlist

Quick Start

Prerequisites

Ubuntu 22.04+ / Raspbian / Windows 10+
Python 3.9+
4GB+ RAM

One-Liner Installation

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/alireza787b/PixEagle/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/alireza787b/PixEagle/main/install.ps1 | iex

Manual Installation

Linux:

# Install system dependencies
sudo apt update && sudo apt install -y python3 python3-venv python3-pip tmux lsof curl git

# Clone and initialize
git clone https://github.com/alireza787b/PixEagle.git
cd PixEagle
make init

Windows:

# Clone and initialize
git clone https://github.com/alireza787b/PixEagle.git
cd PixEagle
scripts\init.bat

Windows Guide: Windows Setup Documentation

The init script runs a 9-step automated setup including Python venv, Node.js, dashboard, and MAVSDK/MAVLink2REST binaries.

Installation Profiles:

Core - Essential features (recommended for ARM/Raspberry Pi)
Full - All features including AI/YOLO detection

The script auto-detects your platform and recommends the appropriate profile.

AI install behavior in Full profile: Core dependencies are installed first, then init offers deterministic PyTorch setup (setup-pytorch.sh) for your platform (x86 CUDA, Jetson, macOS, or CPU).
After that, AI packages (ultralytics, lap, optional ncnn) are installed and verified. If verification fails, init can roll back to Core-safe mode and prints recovery commands.

Detailed Guide: Installation Documentation

Run

Linux/macOS:

make run           # Run all services
make dev           # Development mode with hot-reload
make stop          # Stop all services
make sync          # Pull latest updates from upstream
make help          # Show all commands

Windows:

scripts\run.bat            # Run all services
scripts\run.bat --dev      # Development mode
scripts\stop.bat           # Stop all services

Access Dashboard

Local: http://localhost:3040
LAN: http://:3040 (auto-detected)

Project Structure

PixEagle/
├── Makefile                 # Primary entry point (make help, make run)
├── install.sh               # Bootstrap installer (Linux/macOS)
├── install.ps1              # Bootstrap installer (Windows)
├── scripts/                 # All scripts organized here
│   ├── init.sh/bat          # Main setup scripts
│   ├── run.sh/bat           # Main launcher scripts
│   ├── stop.sh/bat          # Stop services
│   ├── lib/                 # Shared utilities
│   ├── components/          # Component runners
│   └── setup/               # Setup utilities
├── bin/                     # Downloaded binaries
├── src/                     # Python source code
├── configs/                 # Configuration files
├── dashboard/               # React web dashboard
└── docs/                    # Documentation

Configuration

Most settings can be configured via the Web Dashboard UI (Settings page).

For manual configuration, edit configs/config.yaml:

nano configs/config.yaml

Note: config.yaml is gitignored. Default values are in configs/config_default.yaml.

Detailed Guide: Configuration Documentation | Config Service

PX4 Integration

PixEagle requires MAVLink communication with PX4.

Component	Purpose	Default Port
MAVSDK	Offboard control & telemetry	UDP 14540
MAVLink2REST	REST API for OSD/telemetry	UDP 14569
QGC	Ground Control Station	UDP 14550 (optional)

Setup Options:

mavlink-anywhere - Guided setup (Recommended) | Video Tutorial
Manual mavlink-router - Advanced users

Full Guide: Drone Interface Documentation | Port Configuration

Network Requirements

Port	Service	Required
3040	Dashboard	Yes
5077	Backend API	Yes
5551	WebSocket (video)	Yes
8088	MAVLink2REST API	For OSD
14540	MAVSDK	For PX4

# Ubuntu/Raspbian firewall
sudo ufw allow 3040/tcp && sudo ufw allow 5077/tcp && sudo ufw allow 5551/tcp && sudo ufw allow 8088/tcp

Full Guide: Port Configuration

Running Options

Using Makefile (Linux/macOS):

make run                # Full system (recommended)
make dev                # Development mode with hot-reload
make stop               # Stop all services
make sync               # Pull latest updates safely
make reset-config       # Reset config files to defaults
make status             # Show service status
make logs               # Attach to tmux session
make help               # Show all commands

Using scripts directly:

bash scripts/run.sh          # Full system (recommended)
bash scripts/run.sh --dev    # Development mode with hot-reload
bash scripts/run.sh --rebuild # Force rebuild
bash scripts/run.sh -d       # Skip dashboard
bash scripts/run.sh -p       # Skip Python app
bash scripts/run.sh -m       # Skip MAVLink2REST
bash scripts/stop.sh         # Stop all services

Tmux Controls: Ctrl+B + arrows (switch panes) | Ctrl+B D (detach) | tmux attach -t pixeagle (reattach)

Troubleshooting: Troubleshooting Guide

GPU Setup (Optional)

For accelerator-aware PyTorch setup (CUDA/MPS/CPU auto-detection):

bash scripts/setup/setup-pytorch.sh --mode auto
bash scripts/setup/check-ai-runtime.sh

Use --mode gpu (strict GPU) or --mode cpu (force CPU) when needed.

More Info: Installation Guide

Service Management

PixEagle supports two service management modes:

Standalone Mode

Production auto-start (Raspberry Pi/Jetson/Linux with systemd):

# Install canonical management command
sudo bash scripts/service/install.sh

# Runtime management
pixeagle-service start
pixeagle-service stop
pixeagle-service status
pixeagle-service attach

# Boot auto-start
sudo pixeagle-service enable
sudo pixeagle-service disable

# Logs
pixeagle-service logs -f

# Optional SSH login hint (interactive SSH sessions only)
pixeagle-service login-hint enable
pixeagle-service login-hint disable

# System-wide SSH login hint (all users on the board)
sudo pixeagle-service login-hint enable --system
sudo pixeagle-service login-hint disable --system

System login hint now shows:

PixEagle ASCII banner
service and boot state
per-interface dashboard/backend URLs
repo metadata (branch, commit, date, origin)
quick operations commands

If hint format still looks old after updating code, regenerate it:

sudo pixeagle-service login-hint disable --system
sudo pixeagle-service login-hint enable --system

Tmux session name: pixeagle.

During make init on Linux/systemd, PixEagle prompts for:

auto-start enablement
system-wide SSH login hint
optional immediate start and optional reboot validation

Platform-Managed Mode (ARK-OS, etc.)

When installed through a platform like ARK-OS, the platform manages the service lifecycle:

Runs as a user-level systemd service managed by the platform
make init automatically skips standalone service setup (no conflict)
Use the platform's web UI or systemctl --user {start|stop|status} pixeagle
Dashboard accessible at http://<host>/pixeagle/ through the platform's nginx

Note: Standalone and platform-managed modes are mutually exclusive. PixEagle auto-detects the active mode and prevents conflicts.

More Info: Service Management Runbook | Installation Guide

Key Bindings

Key	Action
`t`	Select ROI (Classic Tracker)
`c`	Cancel Tracking
`y`	Trigger YOLO Detection
`f`	Start Following
`s`	Toggle Smart Tracker Mode
`q`	Quit

Windows Support

PixEagle provides full Windows support with enterprise-grade batch scripts matching the Linux experience:

# Initialize (one-time setup)
scripts\init.bat

# Run PixEagle
scripts\run.bat
scripts\run.bat --dev      # Development mode

# Stop services
scripts\stop.bat

Features:

Windows Terminal tabs support (similar to tmux)
Automatic fallback to separate windows
Full 9-step setup wizard
All component runners

Guide: Windows Setup Documentation | Windows SITL Setup

Resources

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Submit a pull request

Report issues at GitHub Issues.

License

Apache License 2.0 - see LICENSE for details.

Commercial use: Allowed with attribution. You must include the copyright notice and license in any distribution.

Disclaimer

PixEagle is experimental software. Use at your own risk. The developers are not responsible for any misuse or damages.

Star this repo if you find it useful!

Name		Name	Last commit message	Last commit date
Latest commit History 850 Commits
.github/workflows		.github/workflows
bin		bin
configs		configs
dashboard		dashboard
docs		docs
resources		resources
scripts		scripts
src		src
tests		tests
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SYNC_GUIDE.md		SYNC_GUIDE.md
add_model.py		add_model.py
init_pixeagle.bat		init_pixeagle.bat
init_pixeagle.sh		init_pixeagle.sh
install.ps1		install.ps1
install.sh		install.sh
pytest.ini		pytest.ini
requirements.txt		requirements.txt
run_pixeagle.bat		run_pixeagle.bat
run_pixeagle.sh		run_pixeagle.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

PixEagle

Features

Documentation

Demo

Quick Start

Prerequisites

One-Liner Installation

Manual Installation

Run

Access Dashboard

Project Structure

Configuration

PX4 Integration

Network Requirements

Running Options

GPU Setup (Optional)

Service Management

Standalone Mode

Platform-Managed Mode (ARK-OS, etc.)

Key Bindings

Windows Support

Resources

Contributing

License

Disclaimer

About

Uh oh!

Releases 5

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

License

alireza787b/PixEagle

Folders and files

Latest commit

History

Repository files navigation

PixEagle

Features

Documentation

Demo

Quick Start

Prerequisites

One-Liner Installation

Manual Installation

Run

Access Dashboard

Project Structure

Configuration

PX4 Integration

Network Requirements

Running Options

GPU Setup (Optional)

Service Management

Standalone Mode

Platform-Managed Mode (ARK-OS, etc.)

Key Bindings

Windows Support

Resources

Contributing

License

Disclaimer

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages