The streaming model, in one paragraph

A streamer is the live twin of a file loader. Your program — the publisher — sends timestamped values over a network connection; PlotJuggler’s streamer for that transport receives them, decodes the messages, and the values appear as series you drag onto plots exactly as if they had come from a file, except the right edge of the plot keeps moving. Two choices define any setup: the transport (how the bytes travel: WebSocket, MQTT, ZMQ, UDP) and the encoding (how each message represents its values). PJ3 understands JSON, CBOR, BSON and MessagePack encodings; PJ4 widens that list (adding Protobuf and Apache Arrow, among others) and keeps the same transports, plus WebRTC for live video. Get transport and encoding to match on both ends and streaming is, honestly, the easy part.

Choosing a transport

The message: a labelled example

Whatever the transport, the payload must tell PlotJuggler which values arrived and when. With JSON — the most readable encoding, and the right choice while you are setting up — one message typically carries a timestamp and a set of named values, like this illustrative example:

{
  "timestamp": 1712345678.42,
  "temperature": 24.6,
  "pressure_kpa": 101.3
}
# Illustrative example only — a generic JSON payload shape for explanation,
# not a captured message from a specific device.

Each named value becomes (or updates) a series; the timestamp places it on the timeline. Binary encodings — CBOR, BSON, MessagePack — express the same content more compactly, which is why high-rate streams prefer them once the setup is proven in JSON. The design rule on the publisher side is the same as for CSV files: stable value names and a consistent, honest timestamp on every message. Rename a value mid-stream and you have started a new series whether you meant to or not.

A complete streaming setup, step by step

1. Start the publisher first. Streaming has two ends and only one of them is PlotJuggler; have your device, script or broker demonstrably emitting before debugging the receiving side. Most “PlotJuggler shows nothing” reports end here.
2. Choose the matching streamer in PlotJuggler for your transport, and point it at the publisher (or broker) with the connection details your setup uses — host, port and topic or endpoint as applicable to that transport.
3. Match the encoding. Tell the streamer which encoding the messages use (JSON while proving the link). A transport that connects and an encoding that mismatches produces silence, not errors — this is the second most common setup trap.
4. Watch the series appear. As messages arrive, their named values show up as available series. Drag them onto a plot, as in Getting Started, and confirm the curves move and the values agree with a known reference (a sensor you can warm with a fingertip beats any amount of log staring).
5. Then tune. Switch to a binary encoding if the rate demands it, add a derived series if the raw values need combining, and save the arrangement as a layout so the live view is rebuilt in one step next session.

Streaming in PJ4: what is added

PJ4’s live list — ROS 2, MQTT, ZeroMQ, UDP, WebSocket bridges, WebRTC and Lab Streaming Layer — keeps every PJ3-era transport that matters here and adds the piece PJ3 never had: WebRTC, for live camera streams that join your plots on the shared timeline (the multimodal picture is toured in PJ4 Video and 3D Visualisation). Its encoding list also grows to include ROS 1/2 messages, Protobuf and Apache Arrow alongside JSON, CBOR, BSON and MessagePack. The workflow in this tutorial — publisher first, match transport, match encoding, verify against reality — is unchanged by the generation; only the menu of options grows.

When nothing arrives: the short checklist

• Is the publisher actually publishing? Verify at the source, with its own tools or a second consumer — never debug two ends at once.
• Do the connection details match? Host, port, and topic/endpoint naming must agree exactly; “almost the same topic” is a different topic.
• Do the encodings match? JSON sent to a MessagePack-configured streamer (or vice versa) fails quietly. Set both ends to JSON while diagnosing.
• Is anything between the ends? Firewalls, broker authentication and containers that publish on a different network than you think are the classic in-between culprits — general networking checks, applied in that order.
• Are the timestamps sane? Values arriving with a frozen or wildly wrong timestamp plot somewhere you are not looking; zoom out to the full timeline once before concluding nothing arrived.

Live data handled well becomes the best data: when a stream surprises you, the same session can be inspected with every tool in this series — offsets, XY views, transforms — because streamed series are ordinary series. And when the moment matters, record it and analyse the file with the recorded-data workflows. The full learning path is on the Tutorials hub; install files are on the Download page.

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.

First, exhaust the built-ins

Custom code is the second resort, not the first — a built-in transform is maintained, tested and instant. PlotJuggler’s built-in editor offers transforms including derivative (rate of change), moving average (smoothing), integral (accumulated quantity) and scale (unit conversions and calibration factors), among others; PJ4’s analysis set also names filters and FFT. Reach for Lua when the computation genuinely combines signals — a ratio, a magnitude from components, an angle from a quaternion — or applies logic a fixed transform cannot express. A useful rule: if the formula fits in one arithmetic expression over several series, it is custom-function territory; if it is one operation on one series, a built-in almost certainly already does it.

The model: multiple inputs, one output

Everything about the Custom Function Editor follows from one sentence in the project’s own description: custom functions are multi-input, single-output functions written in Lua. Concretely:

• Inputs: you select the recorded series the computation reads — one, two, or several. At each timestamp, the function sees the inputs’ values at that moment.
• The function: your Lua code combines those values into a single result for that timestamp — arithmetic, trigonometry, conditionals, whatever the language offers.
• Output: the results form one new series. It is a normal PlotJuggler series in every respect: plot it, overlay it, feed it into further transforms, save it in a layout.
• One output per function: need three derived quantities? Define three functions. That constraint keeps each definition small, nameable and reusable — embrace it rather than fighting it.

A real-world pattern: quaternion to Euler angles (PX4)

The best-documented real use of this feature comes from the PX4 ecosystem: the official PX4 documentation carries a full “Log Analysis using PlotJuggler” guide whose workflow uses Lua custom series to convert a logged quaternion attitude into roll, pitch and yaw. Described conceptually — which is how you should design any custom function before writing it — the pattern is:

• Inputs: the four quaternion component series from the ULog (the vehicle’s attitude estimate, as recorded).
• Computation: the standard quaternion-to-Euler conversion, applied sample by sample — trigonometry over the four inputs, nothing more exotic.
• Outputs: three separate custom functions, one each for roll, pitch and yaw, each emitting a single angle series — the multi-input/single-output model, applied three times.
• Payoff: angles a human can read, plotted against time and against each other, from a log that only ever stored quaternions.

We deliberately describe the inputs and outputs rather than printing “the API”: exact editor mechanics belong to the application in front of you and the PX4 guide itself, and copied signatures rot quickly. The transferable skill is the decomposition — inputs, per-sample computation, one output — which fits every custom function you will ever write here, from a two-input power calculation (voltage × current, straight from a CSV) to a four-input attitude conversion.

Your first custom function, step by step

1. Pick a computation you can verify by hand. A scale-and-combine you can check at one timestamp with a calculator — power from voltage and current is perfect. First functions are for learning the workflow, not for solving the hard problem.
2. Load data containing the inputs and plot the inputs themselves first. If an input is wrong, the function will be wrong more confusingly.
3. Create the custom function in the Custom Function Editor, select the input series, and write the Lua expression of your formula: read the inputs, compute, return the single output value.
4. Plot the output against its inputs. Check the hand-verifiable timestamp. Check a second one. Check behaviour at the interesting event (the step, the peak) — not just at rest.
5. Name it like you mean it. The output series joins your signal list and your layouts; a name that states quantity and unit (“power_watts”) saves every future reader a trip back into the editor.
6. Save the layout. Custom functions are part of the view you built; saving the layout is how the derived series survives to the next session and the next recording (see layouts).

-- Illustrative pattern only — pseudocode showing the shape of a custom function,
-- NOT PlotJuggler editor syntax. Real mechanics: the Custom Function Editor
-- and, for the quaternion case, the PX4 documentation guide.
inputs:  voltage, current        -- recorded series, selected in the editor
output:  power = voltage * current   -- one derived value per timestamp

Design habits that pay off

• Keep functions small and single-purpose. Chain two clear functions instead of writing one cryptic one; the intermediate series is often worth plotting in its own right.
• Mind the edges. Decide what your function should do where inputs are missing or zero — a division that is elegant mid-flight can be a spike factory at the boundary. A conditional in Lua is cheap insurance.
• Prefer built-ins inside functions sparingly. Smooth an input with a moving average first if the raw signal is too noisy for stable derivatives or ratios; transforms compose, in the editor as elsewhere.
• Re-verify after changing inputs. Pointing an existing function at a different recording assumes the same series names and units. The two-timestamp hand check takes a minute and catches both assumptions.

And in PlotJuggler 4: Lua, or Python

PJ4 keeps this entire model and adds Python scripting as an alternative to Lua for custom transforms — the subject of our PJ4 Python scripting guide. Nothing about the decomposition changes: inputs in, one derived series out. If your team lives in Python, PJ4 lets the transform live there too; if your Lua functions already work, they remain the right tool. Either way, the derived series you build become candidates for the two views that exploit them best — XY plots and the multi-recording overlays in comparing bag files. The full series is indexed on the Tutorials hub, and the program itself is on the Download page.

Time plot vs XY plot: the one idea

In a time plot, each curve is a function of time: at every timestamp, a value. In an XY plot, time steps aside and becomes the invisible parameter that walks the point along its path: the horizontal position comes from one signal (X), the vertical position from another (Y), and each timestamp contributes one point. Connect the points in time order and the plot draws the path of the relationship itself — a trajectory through the space the two signals define. That is why XY plots reveal things time plots hide: loops, limits, dead zones and phase differences become shapes you can see at a glance, instead of two wiggly lines you must mentally correlate.

Step-by-step: your first XY plot

1. Load data with at least two related numeric signals. A CSV with two position columns, or a bag with a robot’s x and y fields, is ideal. Loading is the usual drag-and-drop workflow from Getting Started or the CSV tutorial.
2. Create an XY view of the data. PlotJuggler’s workflow is drag-based in both generations: you build an XY plot by bringing the two chosen signals into an XY plotting area, designating which signal plays the X role and which plays the Y role. X is the reference — the signal you want to read the other “against”.
3. Check the pairing makes sense. Both signals must describe the same moments. Signals recorded together in one file pair naturally; signals from different files need their timelines aligned first — that is the time offset workflow, and skipping it is the main way XY plots lie.
4. Read the path, then zoom. The whole-recording view shows the overall shape; zoom into a section of interest to inspect a single manoeuvre, limit cycle or excursion in detail, exactly as you would on a time plot.
5. Save the arrangement. If the pairing answers a recurring question, capture it in a layout alongside your time plots — the two views side by side are worth more than either alone.

Three jobs XY plots do better than time plots

How to read what it draws

• Straight diagonal line: the signals are proportional. The slope is the ratio between them — a calibration error often shows up here before it shows up anywhere else.
• Closed loop: the pair returns to its start with Y lagging or leading X. Loop area grows with phase difference; a loop in a position-vs-position plot is simply a closed path travelled.
• Loop that does not close: the system drifted during the recording — the end state differs from the start state. Compare with the time plot to find when.
• dense scribble in one region: the system spent most of its time there — dwell, oscillation around a setpoint, or noise dominating a near-constant signal.
• Direction matters: the path is traced in time order. Where the story is ambiguous, drop back to the time plot for the same interval and read the two views together.

Combining XY with the rest of the toolkit

XY plots get stronger with derived signals. Plot velocity against position by first computing the velocity with the built-in derivative transform, or define a combined quantity with a Lua custom function and use its output as an axis. Compare two runs by building the same XY view for each recording — the multiple-recording comparison workflow — and aligning their timelines first so the pairings are honest. In PJ4, XY plots also sit next to the new video and 3D views on the same timeline, so the abstract relationship and the physical scene can be inspected in the same pass.

Limits, honestly stated

An XY plot is only as trustworthy as the pairing behind it: mismatched sample times, unaligned recordings and signals in different units all produce confident-looking nonsense. It also discards time as an axis — when “when” is the question, the time plot is still the right tool. Used for the questions it suits, though, it is the fastest diagnostic in this entire series: one picture, and the relationship is either healthy or it is not. Continue with Lua custom functions to build the derived axes you just read about, or return to the Tutorials hub for the full path. If PlotJuggler is not installed yet, the Install guides and the Download page will get you there first.

The problem, precisely

A time offset problem exists when the relative timing inside each recording is correct, but the recordings (or signals) do not share a common zero. Each file is honest about its own timeline; they simply started counting at different moments — a logger armed before the controller booted, a bag recorded a breath after the test rig’s CSV export began. No amount of zooming fixes that, because the data itself needs to move. That is what an offset does: it adds a constant shift to a timeline, leaving every interval inside the recording untouched. If intervals themselves are stretched or drifting, you have a clock-rate problem instead — offsets will align one event and misalign the rest, which is exactly the diagnostic the verification step below exploits.

The T=0 concept

Alignment needs a reference. The PJ3 interface expresses this with a “T=0” time-offset control: in effect, you declare which moment counts as zero, and the curves are viewed relative to it. The mental model generalises to both generations: pick one event as the anchor — the instant the test truly began — and express everything else relative to that anchor. PJ4 formalises the same idea at the dataset level: its layouts and views work with per-dataset time offsets, one shift per loaded recording, stored in the layout (schema v4) together with the viewport. PJ3’s offsets, by contrast, are applied per curve. Same goal, different granularity — and the granularity matters when a recording holds thirty signals you need to move together.

Step-by-step: aligning two signals

1. Load both signals and plot them together. Overlay is essential — you cannot align what you cannot see together. The loading workflows are in Getting Started and the bag and MCAP tutorial.
2. Choose a reference event that exists in both. The best anchors are sharp and unambiguous: a step command and its response, a mode switch, a distinctive spike. Slow ramps and periodic waves make poor anchors — a repeating wave aligns at every period, most of them wrong.
3. Measure the gap. Read the event’s time in the first signal and in the second. The difference is your candidate offset. (Illustrative numbers: if the step appears at 14.2 s in one recording and 15.0 s in the other, the second recording’s timeline needs to move 0.8 s earlier to coincide.)
4. Apply the offset to the late signal. In PJ3, apply the time shift to the curve; in PJ4, set the dataset’s offset so the whole recording moves as one. Direction matters: you are moving the late recording earlier (or, equivalently, delaying the early one) — if the gap doubles instead of closing, you shifted the wrong way; undo and reverse the sign.
5. Verify on a second, independent event. Find a different event later in the recording and check it also lines up. One event can always be forced into alignment; two events aligning after a single constant shift is real evidence the offset is right.
6. Save the layout. An alignment you do not save is an alignment you will redo. Layouts are covered in Saving and Sharing PlotJuggler Layouts — and in PJ4 the offsets themselves are part of what the layout stores.

Per-curve or per-dataset: which are you moving?

Pitfalls worth knowing

• Aligning on a periodic signal. A sine wave matches itself every period. Anchor on an aperiodic event, then use the wave only as a fine check.
• Chasing drift with offsets. If event one aligns and event two, minutes later, does not — with the error growing over time — the clocks ran at different rates. A constant offset cannot fix drift; align near the interval you are analysing and say so in your notes.
• Forgetting the offset is active. An offset left on a curve makes later absolute-time readings wrong. Note offsets in the layout name or your test log, especially when sharing the layout with colleagues.
• Over-aligning noise. On noisy signals, align on the feature (the step, the edge), not on the nearest noise peak.

Master this one control and two other tutorials unlock: fair multi-recording comparisons and meaningful XY plots between signals recorded together. The rest of the series is on the Tutorials hub; the program and its checksums are on the Download page.

What a fair comparison requires

Overlaying two recordings is easy; overlaying them fairly is the skill. Three conditions decide whether the picture means anything:

• The same signals. The same topics and fields from each recording, plotted the same way — ideally by reusing one layout for both, so nothing about the view changes except the data.
• Aligned timelines. Recordings almost never start at the same instant. Until their starts are aligned on a shared reference event, every difference you see may be nothing but a time shift. Alignment uses time offsets — the whole subject of the time offset tutorial.
• The same conditions, noted. Different firmware, a different course, a windy afternoon — write down what else changed, or the prettier curve will get credit it has not earned.

In PlotJuggler 4: several recordings, one timeline

PJ4 was designed for this job. Its documented workflow is to load several recordings, align their timelines, and overlay the signals, with a per-dataset time offset available for each loaded recording so you can shift an entire run earlier or later as one unit. The practical sequence:

1. Load the first recording and build the view you want — the signals, the plots, the arrangement — following the bag and MCAP workflow.
2. Load the second recording alongside it. Its signals join the workspace as their own dataset, distinguishable from the first.
3. Plot the corresponding signals from both datasets on the same axes. Same topic, same field, two runs — the overlay is the comparison.
4. Align before judging: pick an event that exists in both runs (a launch, a step input, a distinctive manoeuvre), measure how far apart it sits in the two datasets, and apply a per-dataset offset to the later-starting run so the events coincide. The method is worked through in the time offset tutorial.
5. Save the result as a layout. PJ4 layouts (schema v4) store the viewport and the per-dataset offsets, so the aligned comparison reopens as you left it instead of needing re-alignment every session.

In PlotJuggler 3: the careful manual workflow

PJ3 predates the per-dataset model, so be precise about what it offers. PJ3 loads data files, plots their series, saves and reloads layouts, and — the key tool here — supports per-curve time offset / time-shift alignment, a long-standing PJ3 feature. A careful PJ3 comparison therefore goes like this: open the recordings, plot the matching curves, and use the per-curve time-shift controls to bring the shared reference event into alignment curve by curve. It reaches the same picture, but the alignment lives on individual curves rather than on a dataset as a whole, which has two consequences you should plan around: it takes longer as the number of compared signals grows, and it is easier to shift one curve of a run and forget another. Work systematically — align every compared curve against the same reference event, then verify with a second event elsewhere in the recording (see the checks in the time offset tutorial) — and save the aligned view as a layout immediately.

Reading the overlay without fooling yourself

• Compare shapes first, peaks second. A run that reaches the same peak more smoothly is usually the better run; a single higher spike is often noise wearing a costume.
• Zoom to the event, not the whole run. Differences that matter happen at transitions — starts, stops, disturbances. The shared timeline lets you inspect the same seconds in both runs.
• Quantify one thing. Pick a number the overlay suggests (settling time, overshoot, steady error) and verify it with the curves — or with a derived series from a Lua custom function — before declaring a winner.
• Distrust perfect alignment. If every event lines up to the sample after shifting, suspect that you aligned on the event you are now “discovering”. Check against an independent second event.

A worked example (illustrative)

A test team records a bag before and after a controller tuning change. They load both recordings, overlay the commanded and measured velocity from each, and find the “after” run apparently responding a full second sooner. Before celebrating, they align on the step input that exists in both bags — and discover the second recording simply started half a second later relative to the manoeuvre. After applying that offset, a real improvement remains, but it is a faster settle, not a magical one-second gain. The offset step is what separated the two conclusions; skip it and the comparison would have published the wrong one. (This example is illustrative — the workflow it demonstrates is the documented one above.)

When the recordings are not bags but repeated CSV exports, the same workflow applies unchanged — see CSV import. And when the runs are still being produced, live streaming plus saved layouts gives you the comparison view in real time. The install routes for both lines are in the Install guides, the files themselves are on the Download page, and everything in the series is indexed on the Tutorials hub.

The three recording types, in one paragraph each

• ROS 1 bags (.bag). The original rosbag format: messages recorded from ROS 1 topics into a single file. In PlotJuggler, opening them is a PJ3 + ROS plugins workflow — the plugins are what understand the bag and expose its topics as series.
• ROS 2 bags (rosbag2). ROS 2’s recorder stores recordings in its own layout, with MCAP among its storage options. The fact-base position is precise here: rosbag2/MCAP support in the PJ3 world lives in the ROS 2 / MCAP plugin set for PlotJuggler.
• MCAP files. A container format for timestamped, topic-structured recordings, used well beyond ROS. This is where the generations split: PJ3 reaches MCAP through that plugin set, while PJ4 lists MCAP as a natively supported file format — and can even attempt to read corrupted MCAP files, a capability added during the 3.999.x previews.

Which line should open your file?

Before you open anything: the install check

Most failures happen before the file is involved. On the PJ3 route, PlotJuggler and its ROS plugins arrive together through the ROS packages — sudo apt install ros-$ROS_DISTRO-plotjuggler-ros, launched with ros2 run plotjuggler plotjuggler, for the distributions the ROS Index lists (humble, jazzy, kilted, lyrical, rolling). If you installed a standalone PJ3 binary without the ROS plugin set, bag files have no loader and will not open — that is an install gap, not a corrupt file. The full walkthrough is the ROS 2 install guide in our Install section. On the PJ4 route, no ROS install is needed for MCAP files themselves, because MCAP reading is built into the application’s file support.

The opening workflow, step by step

1. Load the recording by dragging it into the PlotJuggler window — the same drag-and-drop workflow as any other file. For a rosbag2 recording, you open the recording as the unit it was recorded as, rather than hunting for a single data file inside it.
2. Let the loader enumerate the topics. A bag is many message streams in one container; the loader presents the topics, and the numeric fields inside those messages become the plottable series. Large bags expose a lot of series — that is normal.
3. Choose deliberately. Find the topics your question is about (the command topic and the measured topic, the sensor and the estimate) and ignore the rest for now. Plotting everything is how people conclude, wrongly, that the tool is cluttered.
4. Drag the fields onto plots. Overlay commanded vs measured on one plot; put diagnostics on their own plot below. From here the workflow is the standard one from Getting Started — navigate the timeline, add transforms, save the view.
5. Save a layout. Bag investigations repeat: the same topics, the same arrangement, the next recording. Capture it once with layouts and reopen it against tomorrow’s bag.

Working across recordings

One bag is rarely the whole story. The natural follow-ups all have their own tutorials: overlay yesterday’s and today’s bags to see what a change actually did with comparing multiple bag files; fix recordings that started their clocks at different moments with time offsets; and compute the series the bag does not contain — error signals, magnitudes, rates — with Lua custom functions. If the data is still being produced, the same topics can also be watched live through the ROS topic streaming covered in the streaming tutorial.

When a bag will not open

• “No loader” behaviour on PJ3. Almost always the missing ROS plugin set — install the ROS package route above rather than reinstalling the standalone app.
• An MCAP that opens in PJ4 but not PJ3 (or the reverse expectation). Check which route your install actually has; the generations genuinely differ here, as the table above shows.
• A damaged MCAP. PJ4 added the ability to attempt reading corrupted MCAP files during its preview cycle — a damaged recording that a strict reader rejects is worth one attempt in PJ4 before you declare it lost.
• Everything opens, nothing is findable. A workflow problem, not a file problem: narrow to the topics for your question, name a layout, and reuse it.

Files for both lines, with checksums, are on the Download page; the rest of the series is on the Tutorials hub.

What a PlotJuggler-ready CSV looks like

PlotJuggler plots values against time, so a usable CSV needs three things: a header row naming the columns, one column that carries time, and numeric columns to plot. The illustrative example below shows the shape — a time column first, then one column per signal, one row per sample:

time,voltage,current,temperature
0.00,12.61,1.82,24.5
0.10,12.58,1.85,24.6
0.20,12.55,1.91,24.6
# Illustrative example only — a generic CSV shape, not output from a specific tool.

• The timestamp column is the column PlotJuggler uses as the horizontal axis. It can hold elapsed seconds, epoch time or another consistent time representation — what matters is that it increases monotonically down the file and that PlotJuggler can identify it as the time column during import.
• One column per signal. Each numeric column becomes a series you can drag onto a plot. Name columns meaningfully in the header — those names are what you will see in the signal list.
• Consistent rows. Keep the column count the same on every row, and keep units consistent within a column. Mixed text annotations inside a numeric column are the classic cause of a series that loads partially or not at all.

Step 1 — Prepare the file

Before importing, open the CSV in a text editor or spreadsheet and spend sixty seconds as a sceptic. Confirm the header row exists and names every column. Confirm the time column really is time — sorted, increasing, and in units you can state out loud (seconds? milliseconds?). If your export wrote timestamps as formatted date-time text, consider whether your exporter can emit a numeric epoch or elapsed-seconds column instead; a plain numeric time column is the least ambiguous input you can give any plotting tool. Save a copy rather than editing your only original.

Step 2 — Load the file

The documented workflow is drag-and-drop: drag the CSV file into the PlotJuggler window. The CSV loader reads the file and the import step asks you, in effect, the defining question of this tutorial: which column is time? Designate your timestamp column there. Every other numeric column is then offered as a plottable series, sampled at the times that column provides. Get this choice right and everything downstream — overlays, transforms, XY plots — behaves; get it wrong and the data plots against row index or against one of your signals, which looks bizarre and wastes debugging time.

Step 3 — Choose and plot series

With the file loaded, the signal list shows your columns. Drag the series you care about onto the plotting area, exactly as in the getting started walkthrough: overlay signals that share a story, give unrelated signals their own plots. Two CSV-specific checks are worth doing on first plot:

1. Check the time span. The plot’s horizontal extent should match your recording’s real duration. A span of thousands of “seconds” for a one-minute test usually means the time column was in milliseconds — the data is fine, the unit assumption is not.
2. Check a known value. Pick a moment you know (a switch flipped, a motor started) and confirm the curve does what the real system did at that time. This catches swapped columns and off-by-one header mistakes in seconds.

Working with the imported data

Once plotted, a CSV series is a first-class PlotJuggler series. Apply built-in transforms such as a moving average or derivative to it, combine columns with a Lua custom function (total power from the voltage and current columns, in the example above, is the textbook case), plot one column against another in an XY plot, and capture the whole arrangement as a layout so the next CSV from the same rig opens into the same view. If you import several CSVs from repeated runs, the multiple-recording comparison workflow applies to them just as it does to bag files.

Common CSV problems, and fixes

CSV in PJ4: one extra worth knowing

PJ4 keeps CSV import and adds an export direction: the 3.999.9 preview introduced an export tool to CSV and Arrow-Parquet, which shipped in the 4.0 line. That makes CSV a two-way street in PJ4 — bring data in as CSV, and send selected data back out as CSV for a spreadsheet or a colleague. The CSV workflow itself, timestamp column and all, is unchanged between the lines, which is why this tutorial can honestly cover both. For the files themselves and every other format, see the Download page and the Tutorials hub.

Before you start (2 minutes)

• A working install. If PlotJuggler is not on your machine yet, follow the Install guides for your platform first — Windows, Ubuntu, ROS 2 and macOS are covered, and the files with their checksums are on the Download page.
• A small data file. A short CSV export is the friendliest first file; a ROS bag, MCAP recording or PX4 ULog works too. Keep it small for the first run — you are learning the tool, not stress-testing it (PlotJuggler is built for thousands of series and millions of points, but that is for later).
• Know your line. PJ4 and PJ3 look similar and work similarly, but a few details differ. This guide flags the differences where they matter.

Step 1 — Open PlotJuggler and look around

Launch the application and take stock before touching any data. The interface is organised around three ideas: a list of the signals available in your data, a plotting area where signals become curves, and a timeline you can scrub, zoom and pan. PlotJuggler renders with OpenGL, which is why it stays responsive with very large recordings once you get there. Do not worry about panels you do not recognise yet — streaming controls, transform editors and (in PJ4) video and 3D views all build on the basics you are about to use.

Step 2 — Load your first file by drag-and-drop

The documented way to bring data in is deliberately simple: drag the file into the PlotJuggler window and drop it. PlotJuggler works out which loader handles the file — CSV, PX4 ULog, ROS bags and (in PJ4) MCAP, Parquet and more are all supported formats — and reads it in. When the load finishes, the signals contained in the file appear in the signal list. If you used a CSV, you have just exercised the workflow our CSV import tutorial covers in depth, including what to do when a CSV needs a timestamp column sorted out first. Bag and MCAP users get the same treatment in the ROS bag and MCAP tutorial.

Step 3 — Put signals on a plot

This is the gesture the whole tool is named around: drag a signal from the list and drop it onto the plotting area. A curve appears, drawn against time. Drag a second signal onto the same plot to overlay it — comparing related signals on shared axes is the most common analysis move there is. Drag a signal to a fresh area instead if you want it on its own plot, stacked with the others and sharing the timeline. A few habits worth forming immediately:

• Start with two or three signals, not thirty. Add more only when you know what question each one answers.
• Overlay signals that share a unit or a story (commanded vs measured, left vs right). Unrelated signals deserve separate plots.
• If a curve looks flat, check its scale against the others before assuming the data is wrong — a small signal next to a large one is easy to miss.

Step 4 — Navigate the timeline

With curves on screen, learn to move: zoom into a short interval to inspect detail, pan along the recording, and zoom back out to recover context. Everything in PlotJuggler shares one timeline, so zooming reframes every plot at once — and in PJ4 it also reframes any video or 3D view you have open, which is the heart of its multimodal workflow. Practise on an event you can identify in your test file: find it, zoom to it, zoom out. That loop — overview, zoom, inspect, overview — is 90% of daily work in this tool.

Step 5 — Try one transform

Transforms turn the series you logged into the series you actually wanted. Before writing anything custom, meet the built-ins: PlotJuggler offers ready-made transforms such as the derivative, moving average, integral and scale operations (PJ4 adds filters and FFT to the same toolbox). Apply a moving average to a noisy signal and plot the result next to the original: the derived series behaves like any other curve. When a built-in is not enough, the Custom Function Editor lets you define your own computation — that is the subject of the Lua custom functions tutorial.

Step 6 — Save the view as a layout

You have built something worth keeping: a chosen set of plots, curves and zoom. PlotJuggler saves that arrangement as a layout you can reload against the same data — or the same kind of data — later, instead of rebuilding it by hand. Save one now, close the plots, and reload it to prove the round trip works. Layouts deserve their own guide, and have one: Saving and Sharing PlotJuggler Layouts covers what is stored, how sharing works, and the PJ4 layout schema v4 note.

If something did not work

• The file loaded but no signals appeared. The file may need a loader or plugin your install lacks — ROS bags in PJ3, for example, come through the ROS plugin set; see the ROS bag and MCAP tutorial.
• The CSV plotted against row numbers. Your file’s time column was not recognised as time — the fix is in the CSV import tutorial.
• Signals start at different times. Normal for multi-device recordings; align them with the time offset tutorial rather than fighting the timeline.

Where to go next

You now hold the core workflow: load, drag, navigate, transform, save. Deepen it in the order that matches your data — CSV import or ROS bags and MCAP for loading, XY plots for signal-against-signal views, and live streaming when you are ready to watch data arrive in real time. The full path is mapped on the Tutorials hub.

What the Marketplace is

The Extensions Marketplace is PJ4’s in-app channel for discovering, installing and updating plugins. It first appeared in the 3.999.3 preview (20 July 2026) and ships in 4.0.0. Behind the interface sits a registry: the project maintains a public repository, pj-plugin-registry, which is the catalogue the Marketplace draws from, alongside an official-plugins repository (pj-official-plugins). The architectural point matters more than the mechanics: PJ4 plugins are no longer things you hunt across the internet — they are published to a registry the application itself can read, which is what makes one-click-style installation and, just as importantly, updates possible.

The four plugin types you will meet

These four categories are the same plugin families the project has used since PJ3 (which also had state publishers in its plugin set) — PJ4’s novelty is not the idea of plugins but their distribution.

Installing a plugin, step by step

1. Open PlotJuggler 4 — the Marketplace exists only in PJ4 (4.0.0 or the later 3.999.x previews); PJ3 has no equivalent menu.
2. Choose File → Marketplace. This is the documented entry point.
3. Browse or search the registry catalogue by what you need — a loader for a format, a streamer for a source, a parser for an encoding, or a toolbox.
4. Install the plugin from its Marketplace entry, and use the same entry later to update it when a new version is published.
5. Use it where its type belongs: an installed loader shows up in the file-open flow, a streamer among the live sources, a parser where encodings are chosen, a toolbox among the tools.

Because we only publish what the project documents, two cautions belong here. First, this guide deliberately names no third-party plugins and no prices: the registry is young and growing, and the Marketplace inside your copy of PJ4 is the authoritative, current catalogue — check names, authors and descriptions there before installing anything. Second, treat plugins with the normal care you would give any extension: prefer entries from the official registry and known authors, especially in work environments.

Building your own: the plugin SDK

For authors, PJ4 ships a dedicated SDK: the plotjuggler_sdk repository, described by the project as the “SDK to create PlotJuggler 4 plugins”, and actively maintained alongside the official plugins. That continues a deliberate project tradition — PJ3’s MPL-2.0 licensing was explicitly noted as allowing closed-source plugins, and a sample-plugins repository existed for PJ3 authors — while giving PJ4 developers a proper, current toolkit and a registry to publish into. If you maintain a PJ3 plugin, the SDK plus the registry are where your PJ4 port begins; the migration guide covers the user side of that transition.

Why this matters for PlotJuggler’s future

A marketplace changes what a small core team has to build. Niche file formats, vendor-specific streamers and specialised toolboxes can be contributed — and kept updated — by the people who need them, without waiting for a core release; users get discovery and updates in one place instead of forum attachments. It is one of the clearest signals that PJ4 is designed as a platform rather than a single-purpose app, alongside the multimodal views in Video and 3D Visualisation and the dual-language scripting in Python Scripting. The full picture is in What’s New in PlotJuggler 4.0.