From e4505448db5184ef5d4dc7927ad69b97d743753d Mon Sep 17 00:00:00 2001 From: Ramon Roche Date: Thu, 2 Apr 2026 22:59:36 -0700 Subject: [PATCH] docs(simulation): add Hawkeye visualizer page, replace jMAVSim in SIH docs Hawkeye is a real-time 3D flight visualizer (not a simulator) that replaces jMAVSim's display-only mode for SIH. Adds a dedicated Hawkeye docs page covering installation, SIH SITL usage, multi-vehicle support, and ULog replay. Updates the SIH page to recommend Hawkeye instead of jMAVSim for visualization. Signed-off-by: Ramon Roche --- docs/en/SUMMARY.md | 1 + docs/en/sim_hawkeye/index.md | 143 +++++++++++++++++++++++++++++++++++ docs/en/sim_sih/index.md | 20 +++-- 3 files changed, 153 insertions(+), 11 deletions(-) create mode 100644 docs/en/sim_hawkeye/index.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index e76b33dafc..fb702c8980 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -468,6 +468,7 @@ - [Gazebo Models Repository](sim_gazebo_gz/gazebo_models.md) - [Multi-Vehicle Sim](sim_gazebo_gz/multi_vehicle_simulation.md) - [SIH Simulation](sim_sih/index.md) + - [Hawkeye Visualizer](sim_hawkeye/index.md) - [Gazebo Classic Simulation](sim_gazebo_classic/index.md) - [Vehicles](sim_gazebo_classic/vehicles.md) - [Worlds](sim_gazebo_classic/worlds.md) diff --git a/docs/en/sim_hawkeye/index.md b/docs/en/sim_hawkeye/index.md new file mode 100644 index 0000000000..32eba699fb --- /dev/null +++ b/docs/en/sim_hawkeye/index.md @@ -0,0 +1,143 @@ +# Hawkeye Flight Visualizer + +[Hawkeye](https://github.com/PX4/Hawkeye) is a real-time 3D flight visualizer 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. + +Hawkeye is a **visualizer**, not a simulator. +It does not model physics or generate sensor data — it only renders what PX4 is doing. +This makes it the recommended visual companion for [SIH](../sim_sih/index.md), which runs its own physics internally. + +Built in C with [Raylib](https://www.raylib.com/), Hawkeye has zero runtime dependencies. + +## Features + +- Real-time 3D rendering of vehicle state via MAVLink +- Multi-vehicle swarm visualization (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 visualization 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 ` | Set UDP listen port (default: 19410) | +| `-n ` | Number of vehicles to visualize | +| `-origin ` | Set map origin | +| `-mc` | Multicopter model | +| `-fw` | Fixed-wing model | +| `-ts` | Tailsitter model | +| `--replay ` | Replay a ULog file | +| `--ghost ` | 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 visualize diff --git a/docs/en/sim_sih/index.md b/docs/en/sim_sih/index.md index ca7d4cb1c5..293ec16407 100644 --- a/docs/en/sim_sih/index.md +++ b/docs/en/sim_sih/index.md @@ -74,27 +74,25 @@ The `px4_sitl` target will work, but will also build Gazebo libraries. ### Visualization (Optional) {#sitl-visualization} SIH is intentionally headless by default. -If you need a visual aid to see what the vehicle is doing you can use QGroundControl to track path over ground, and/or jMAVSim as a 3D viewer. +If you need a visual aid to see what the vehicle is doing you can use QGroundControl to track path over ground, and/or [Hawkeye](../sim_hawkeye/index.md) as a 3D viewer. #### QGroundControl QGC auto-connects on UDP port 14550. Open QGC while SIH is running and the vehicle appears on the map view with attitude, position, and telemetry. -#### jMAVSim (3D Display-Only) +#### Hawkeye (3D Visualizer) -jMAVSim can render a 3D view of the vehicle using MAVLink position data. No physics are simulated in jMAVSim — it is display-only. +[Hawkeye](../sim_hawkeye/index.md) renders a real-time 3D view of the vehicle using MAVLink position data. No physics are simulated in Hawkeye — it is a visualizer only. + +In a separate terminal, run: ```sh -./Tools/simulation/jmavsim/jmavsim_run.sh -p 19410 -u -q -o +hawkeye ``` -Flags: +Hawkeye connects on UDP port 19410 by default (the same port SIH sends `HIL_STATE_QUATERNION` on). -- `-a` for airplane model -- `-t` for tailsitter model -- `-o` enable display-only mode. - -See [jMAVSim Display-Only Mode](../sim_jmavsim/index.md#display-only-mode) for details. +Use `-fw` for fixed-wing or `-ts` for tailsitter models. See the [Hawkeye docs](../sim_hawkeye/index.md) for multi-vehicle visualization and ULog replay. ### Environment Configuration @@ -154,7 +152,7 @@ PX4 SITL opens the following UDP ports (all instance-aware, offset by instance n | **14540** (+N) | 14580 (+N) | MAVSDK, MAVROS, offboard APIs | Yes (capped at 14549 for 10+ instances) | | **14030** (+N) | 14280 (+N) | Onboard camera/payload | Yes | | **13280** (+N) | 13030 (+N) | Gimbal control | Yes | -| **19410** (+N) | 19450 (+N) | jMAVSim display-only (SIH only) | Yes | +| **19410** (+N) | 19450 (+N) | Hawkeye visualizer (SIH only) | Yes | | **8888** | - | uXRCE-DDS / ROS 2 | No (use DDS namespace for multi-instance) | QGC auto-connects on port **14550** by default. MAVSDK connects on **14540**. No manual port configuration needed for single-instance use.