Every tutorial in this series ends the same way — “save the layout” — and this one explains why that advice matters. A layout is PlotJuggler’s saved form of a view: which plots you built, which signals sit on them, and how the view is arranged, captured to a file you can reload instead of rebuilding. Save/reload layouts are a long-standing PJ3 feature, and PJ4 keeps the concept while changing the format — its layouts use schema v4. This guide covers what a layout does for you, the save and reload workflows, sharing layouts with a team, and the one migration note PJ4 users must know. Series index: the Tutorials hub.
What a layout is — and is not
Think of the split this way: your data files (a bag, an MCAP, a CSV) hold the measurements; a layout holds the view of measurements — the plots, the chosen series on each, the arrangement you arrived at while analysing. Reloading a layout against data restores that view, which is why the same layout can serve recording after recording from the same rig: the series names recur, the questions recur, only the run changes. PJ4’s schema v4 additionally stores the viewport and the per-dataset time offsets you set, so an aligned comparison reopens aligned. What a layout is not: it is not a copy of your data, and it is not a screenshot. Send a colleague only the layout and they have your questions, not your answers — they still need the data files (and the same loaders or plugins) to see anything.
Saving a layout, step by step
- Build the view worth saving. The plots, overlays and zooms you would want back: for example the standard post-flight arrangement from the bag and MCAP tutorial, or the two-run overlay from comparing multiple recordings.
- Add the derived series. If the view uses built-in transforms or Lua custom functions, make sure they are part of the view before saving — in PJ4, layouts and transforms are saved together, which is what makes a shared layout reproduce its derived curves too.
- Align, then save. If the view depends on time offsets, apply them first; on PJ4 those offsets are stored in the layout, so saving after aligning is the difference between a reusable asset and a recurring chore.
- Save the layout under a deliberate name. Name it for the rig and the question (“quad-postflight-attitude”), not the date or the run — the layout is the reusable thing, the run was just its first use.
- Reload it once, immediately. Close the view, reopen the layout, and confirm the plots, series and offsets come back as saved. A layout verified at birth will not surprise you mid-incident.
Reloading against new data
The payoff workflow is short: record a new run, load the new data file, apply the saved layout. The same signals land on the same plots in the same arrangement — and because the series are matched by their identity in the data, a well-kept rig (consistent topic and column names across runs) makes this nearly free. When a series the layout expects is absent from the new file — a topic renamed, a column dropped by a new exporter — that part of the view simply has nothing to draw; treat a strangely empty plot after a reload as a data-lineage clue first and a PlotJuggler problem second. This reload habit is what turns the other tutorials from one-off analyses into a repeatable process: the CSV view for every export from the same logger, the comparison layout for every A/B test.
Sharing layouts with a team
- Send three things: the layout file, a note of which PlotJuggler line it was saved from (PJ3 vs PJ4 — see the schema note below), and any custom transforms or plugins the view depends on. A layout that silently assumes a Lua function the recipient lacks will under-deliver without explaining itself.
- Agree series naming at the source. Layouts pay compound interest when every logger, exporter and bag in the team uses stable topic and column names. The cheapest team standard you will ever adopt is “we do not rename topics casually”.
- Keep a small team library. A handful of named, verified layouts — post-flight, bench test, regression comparison — beats a folder of personal one-offs. Retire layouts when the rig changes, and say so in the name or the note.
- Share the data expectation, not the data. Because a layout carries the view rather than the measurements, it is safe to circulate where the recordings themselves are not — a genuinely useful property when data is large or sensitive.
The PJ4 note: layout schema v4
PJ4 rewrote the layout format: its layouts are schema v4, which is how they come to store viewports and per-dataset offsets alongside the plots. The practical guidance, stated in our PJ3-to-PJ4 migration guide and repeated here because layout users are exactly who it affects: check your layouts after upgrading. Open each important PJ3 layout in PJ4, confirm the curves, arrangement and offsets look as saved, and re-save from PJ4 once satisfied. Do not assume a silent perfect conversion of every saved view, do not delete the PJ3 copies until the PJ4 versions are verified — and do not expect PJ4-saved layouts to travel backwards into PJ3. Treat the first open as an inspection, and the migration is uneventful.
Layouts as a habit, not a feature
The teams that get the most from PlotJuggler are not the ones with the cleverest single analysis; they are the ones whose tenth analysis starts from the saved form of their best one. Every workflow in this series deposits something into a layout — the first plot, the aligned comparison, the XY view next to its time plots. Save them, name them, share them. The rest of the series is on the Tutorials hub; install files are on the Download page.