mirror of
https://gitee.com/mirrors_PX4/PX4-Autopilot.git
synced 2026-11-01 04:41:36 +08:00
148 lines
4.1 KiB
Markdown
148 lines
4.1 KiB
Markdown
# Hawkeye Flight Visualiser
|
|
|
|
[Hawkeye](https://github.com/PX4/Hawkeye) is a real-time 3D flight visualiser for PX4.
|
|
It connects to any MAVLink source (SITL or hardware) and renders vehicle state from [`HIL_STATE_QUATERNION`](https://mavlink.io/en/messages/common.html#HIL_STATE_QUATERNION) messages.
|
|
|
|
::: tip
|
|
Hawkeye is the recommended visualiser for [SIH Simulation](../sim_sih/index.md) (which doesn't have a default visualiser).
|
|
:::
|
|
|
|
Note that Hawkeye is not a simulator — it doesn't model physics or generate sensor data — it only renders what PX4 is doing.
|
|
|
|
Hawkeye has no runtime dependencies.
|
|
It is built in in C with [Raylib](https://www.raylib.com/).
|
|
|
|
## Features
|
|
|
|
- Real-time 3D rendering of vehicle state via MAVLink
|
|
- Multi-vehicle swarm visualisation (up to 16 vehicles simultaneously)
|
|
- ULog replay with ghost mode for visual flight comparison (e.g. before/after PID tuning)
|
|
- Vehicle models: quadrotor, hexarotor, fixed-wing, tailsitter, VTOL, rover, ROV
|
|
- Three camera modes: Chase, FPV, Free (WASD fly)
|
|
- Orthographic views (sidebar and fullscreen)
|
|
- HUD with compass, attitude indicator, and telemetry badges
|
|
- Theme engine with built-in themes (Grid, Rez, Snow)
|
|
|
|
## Installation
|
|
|
|
### macOS (Homebrew)
|
|
|
|
```sh
|
|
brew tap PX4/px4
|
|
brew install PX4/px4/hawkeye
|
|
```
|
|
|
|
### Linux (Debian/Ubuntu)
|
|
|
|
Download the `.deb` package from the [latest release](https://github.com/PX4/Hawkeye/releases/latest):
|
|
|
|
```sh
|
|
sudo dpkg -i hawkeye_*_amd64.deb
|
|
```
|
|
|
|
### From Source (All Platforms)
|
|
|
|
```sh
|
|
git clone --recursive https://github.com/PX4/Hawkeye.git
|
|
cd Hawkeye
|
|
make release
|
|
```
|
|
|
|
The binary is placed at `build/hawkeye`.
|
|
|
|
On Linux, the following packages are required:
|
|
|
|
```sh
|
|
sudo apt install build-essential cmake libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl-dev
|
|
```
|
|
|
|
On Windows, use Visual Studio with the C/C++ workload and CMake.
|
|
|
|
## Usage with SIH SITL
|
|
|
|
### Single Vehicle
|
|
|
|
In one terminal, start SIH:
|
|
|
|
```sh
|
|
make px4_sitl_sih sihsim_quadx
|
|
```
|
|
|
|
In another terminal, start Hawkeye:
|
|
|
|
```sh
|
|
hawkeye
|
|
```
|
|
|
|
Hawkeye connects on UDP port **19410** by default — the same port SIH sends `HIL_STATE_QUATERNION` on.
|
|
|
|
### Multi-Vehicle
|
|
|
|
Each SIH instance sends visualisation data on port `19410 + N` (where N is the instance number).
|
|
Launch multiple SIH instances, then start Hawkeye with the vehicle count:
|
|
|
|
```sh
|
|
hawkeye -n 3
|
|
```
|
|
|
|
### Vehicle Type Selection
|
|
|
|
By default, Hawkeye renders a quadrotor.
|
|
Use flags to select a different model:
|
|
|
|
| Flag | Vehicle |
|
|
| ----- | --------------------- |
|
|
| `-mc` | Multicopter (default) |
|
|
| `-fw` | Fixed-wing |
|
|
| `-ts` | Tailsitter |
|
|
|
|
Example for fixed-wing:
|
|
|
|
```sh
|
|
hawkeye -fw
|
|
```
|
|
|
|
## ULog Replay
|
|
|
|
Hawkeye can replay flight logs for post-flight review:
|
|
|
|
```sh
|
|
hawkeye --replay flight.ulg
|
|
```
|
|
|
|
### Ghost Mode
|
|
|
|
Overlay a second flight at reduced opacity for visual comparison:
|
|
|
|
```sh
|
|
hawkeye --replay flight_after.ulg --ghost flight_before.ulg
|
|
```
|
|
|
|
This is useful for comparing flights before and after tuning changes.
|
|
|
|
## CLI Reference
|
|
|
|
| Option | Description |
|
|
| --------------------------- | ------------------------------------- |
|
|
| `-udp <port>` | Set UDP listen port (default: 19410) |
|
|
| `-n <count>` | Number of vehicles to visualise |
|
|
| `-origin <lat> <lon> <alt>` | Set map origin |
|
|
| `-mc` | Multicopter model |
|
|
| `-fw` | Fixed-wing model |
|
|
| `-ts` | Tailsitter model |
|
|
| `--replay <file.ulg>` | Replay a ULog file |
|
|
| `--ghost <file.ulg>` | Overlay a ghost flight for comparison |
|
|
|
|
## Camera Controls
|
|
|
|
| Mode | Description |
|
|
| ----- | ------------------------------------ |
|
|
| Chase | Follows behind the vehicle (default) |
|
|
| FPV | First-person view from the vehicle |
|
|
| Free | Fly freely with WASD + mouse |
|
|
|
|
## See Also
|
|
|
|
- [Hawkeye GitHub Repository](https://github.com/PX4/Hawkeye)
|
|
- [SIH Simulation](../sim_sih/index.md) — the headless simulator Hawkeye is designed to visualise
|