Skip to content

feat(plot): draw uploaded annotations on the plots - #345

Open
yuhongherald wants to merge 1 commit into
PX4:mainfrom
yuhongherald:herald/add-annotations
Open

yuhongherald wants to merge 1 commit into
PX4:mainfrom
yuhongherald:herald/add-annotations

Conversation

@yuhongherald

Copy link
Copy Markdown

Summary

Adds an optional Annotations field to the upload form: YAML files marking intervals of a flight,
listed in a table above the plots and drawn onto the plots they name.

annotated-plot

Problem

A log is usually reviewed against something already known about the flight - a test sheet, an
operator's notes, the verdict of an external analyzer. That context lives outside Flight Review
today, so the reviewer reads a time off one document and hunts for it on the plot. There is no way
to put "this is the interval in question" on the page next to the data.

Solution

plot_app/annotations.py validates the uploaded YAML and renders it. A file declares one or more
sources, each with a colour and a set of categories; a category names a graph (the plot's title,
or a Nav-... fragment id) and carries intervals with a start, an optional end, and optional
annotation / value text. Times are read the way the x-axis is labelled, so an annotation time is
whatever you read off the plot.

  • Upload - the files are parsed before anything is written; a bad file fails the upload with a
    400 rather than storing a half-annotated log. The result is stored as JSON in a new
    Logs.Annotations column, which setup_db.py adds to an existing database on its next run.
  • Rendering - runs after generate_plots, so a graph is matched against the titles the plots
    actually got. Bands are drawn in a screen-unit strip below the data, the same way plotting.py
    draws the VTOL strip, so they never occlude the trace; value text is revealed on hover, capped
    at three stacked lines. Unmatched categories still appear in the table.
  • Limits - upload-derived strings truncate and counts reject (1 MB per file, 1000 intervals,
    6 rows per plot). Every field is escaped on the way into the table, and hover tooltips are passed
    to Bokeh as field pairs rather than as an HTML string, so uploaded text is inserted as text.

A log uploaded without annotations renders exactly as it does today; the section and the strip are
simply absent.

ss5 *The table above the plots.* annotations-upload *The one addition to the upload page.*

Adds pyyaml to app/requirements.txt. Format and design notes in docs/annotations.md - that is a
new directory, since at 253 lines the spec would more than double the root README; happy to move or
trim it if you would rather it lived somewhere else.

@bkueng

bkueng commented Sep 3, 2026

Copy link
Copy Markdown
Member

Hi, the implementation looks good, but I'm hesitant to add this.
One reason is that it's a quite specific feature and still somewhat cumbersome to use. I think eventually you'll also want an interactive way to add descriptions and annotations. Which requires a bit more infrastructure like user login.

It seems better suited for the next generation of flight review (it already includes automated checks).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants