docs(sim_hawkeye): comprehensive guide with screenshots, diagrams, and GIFs#27056
Conversation
…iagrams Expand the Hawkeye visualizer docs from a single index.md to a full multi-page guide covering all features: - index.md: hero, installation, getting started (3 progressive paths) - cli.md: command-line reference with all flags and examples - views.md: camera modes, ortho views, themes, vehicle models - hud.md: Console + Tactical HUD modes, debug overlay, annunciators - world_indicators.md: trails (directional/speed ribbon/drone color), ground track, correlation line and curtain overlays - replay.md: ULog replay, transport controls, markers - multi_drone.md: deconfliction, takeoff alignment, correlation analysis - sitl.md: single vehicle + multi-instance swarm + MAVSDK test script - reference.md: keyboard shortcuts, position data tiers, coordinate systems - troubleshooting.md: common problems and fixes by symptom Includes 36 assets: annotated HUD diagrams (SVG), screenshots (PNG), interaction GIFs, marker types diagram, position tier flowchart, and coordinate system reference. YouTube embed for SITL quickstart video.
hamishwillee
left a comment
hamishwillee
left a comment
There was a problem hiding this comment.
I'll look at this next week.
In the meantime.
- Please prettier the markdown.
- The smaller the images are the more accessible the pages are on poor networks, and the less time it takes for editors to sync to github when editing. Normally I consider 1MB a big file. This has some very large files, including one at least 28Mb.
Options?
Reduced total asset size from ~110 MB to 10 MB. Every file now under 1 MB. Large GIFs cropped and scaled down, converted to animated WebP where needed.
|
I made cuts to the gifs and shrank them. I also cut frames down on the theme one. In the worst case scenarios I switched them to webp. They should all total 10mb or so now. |
|
|
||
|  | ||
|
|
||
| _<!-- 06-img-03: 3×3 vs 3×4 vs 4×4 triptych. -->_ |
There was a problem hiding this comment.
What are all these comments for, and why are they wrapped in underscores?
| ::: tip | ||
| Hawkeye is the recommended visualiser for [SIH Simulation](../sim_sih/index.md) (which doesn't have a default visualiser). | ||
| ::: | ||
| <video src="https://github.com/user-attachments/assets/PLACEHOLDER-HERO-VIDEO" autoplay loop muted playsinline></video> |
| Three progressive paths, each standalone. Pick whichever matches what you have on hand. No PX4 source build required for replay, no log files required for live SITL. | ||
|
|
||
| In one terminal, start SIH: | ||
| ::: tip Press `?` at any time in Hawkeye to open the help overlay with the full keybind reference. This is the fastest way to discover what the viewer can do. ::: |
There was a problem hiding this comment.
FYI the format of tips matters. I'll fix this up, but it should be:
| ::: tip Press `?` at any time in Hawkeye to open the help overlay with the full keybind reference. This is the fastest way to discover what the viewer can do. ::: | |
| ::: tip | |
| Press `?` at any time in Hawkeye to open the help overlay with the full keybind reference. | |
| This is the fastest way to discover what the viewer can do. | |
| ::: |
This matters because it made the whole rest of the page render wrong. You might want to build this locally - it is easy. In your PX4 clone, navigate to the /docs directory and enter yarn start. Of course you also need nodejs and yarn.
For style I always use sentence line breaks, but this is not required by Vitepress. It just makes github reviewing easier.
There was a problem hiding this comment.
Apologies, I wrote in Obsidian locally, and it looks like most of this wouldn't have been a problem if I had done it from the docs. I'll fix tings up Thursday
| @@ -0,0 +1,89 @@ | |||
| # Command-Line Reference | |||
There was a problem hiding this comment.
All of these have to be added to en/SUMMARY. md or they don't appear in the sidebar. I will do this.
When you search the search tool shows both the sidebar summary and the heading. It is important the page includes context. So this will be
| # Command-Line Reference | |
| # Hawkeye Command-Line Reference |
hamishwillee
merged commit 62609f8
into
PX4:mrpollo/docs-hawkeye-visualizer
|
@MikePehel @mrpollo I did not intend to merge this - no idea how it could have happened - I didn't press any merge button or anything :-( I have pushed a whole lot more fixes on this to @mrpollo branch - you can see the changes here main...mrpollo/docs-hawkeye-visualizer - basically added images that were renamed, fixed up headings, added the sub pages to sidebars. I haven't actually "reviewed" it as such, but it looks sane. Warning BUT, are we sure this is the right place for this information to go? IF this was from a third party I'd say "Add this docs to your own repo and publish. We can then link a minimum version from PX4". If you want to host these docs on the visualizer github pages that would be easy - and we can link If you want to keep it here then we can. Please create a new PR for us to work off! |
2 participants
Addendum to #26965. Expands the Hawkeye docs from a single index.md to a full multi-page guide.
What's added
9 new doc pages (~11,000 words total):
cli.md- command-line referenceviews.md- camera modes, ortho views, themes, vehicle modelshud.md- Console + Tactical HUD modes, debug overlay, 5 annunciator animationsworld_indicators.md- trails (directional/speed ribbon/drone color), ground track, correlation overlaysreplay.md- ULog replay, transport controls, markersmulti_drone.md- deconfliction, takeoff alignment, correlation analysissitl.md- single vehicle + multi-instance swarm + MAVSDK test scriptreference.md- keyboard shortcuts, position data tiers, coordinate systemstroubleshooting.md- common problems and fixes36 assets in
docs/assets/simulation/hawkeye/:Expanded index.md with hero section, installation (Homebrew/deb/source), and three progressive Getting Started walkthroughs (SITL, single-log replay, multi-drone swarm).
Test plan