# Charts

> The toolbar every chart carries and what each button does, the scale, statistics and reference-line panels, the detached chart window, where charts appear in the app, and the one engine behind all of them.

Every chart in the application is drawn by one engine (ECharts) through one chart view,
whatever put it on screen: the [Line chart](component-line-chart),
[Bar chart](component-bar-chart) and [Pie chart](component-pie-chart) components on a
dashboard, the Channels card of a [unit panel](view-unit-panels), the live chart of a run
on the Process page, the datalog chart of a recorded run in [Histories](histories), the
recipe profile preview in a [recipe](process-recipes) or a procedure, the criterion preview
of an [evaluation](process-evaluations), and the two detached windows below. What differs
between them is where the configuration comes from, never the drawing: a gap in the data is
always a hole in the line, never a bridge, and every number and instant the chart writes
follows the station's own [localization](settings-localization). The PDF report renders
the same drawing without any of the tools on this page.

## The toolbar {#the-toolbar}

A chart carries a row of buttons over its plot: the same bar everywhere, told per chart
which buttons to draw. On a dashboard component that list is the **Toolbox** section of
its properties ([The dashboard editor](view-editor#toolbox)); a surface with nobody to ask
(a recorded run, a recipe preview) offers every tool a time chart can honour. With no tool
at all no bar is drawn.

| Button (its tooltip) | What it does | Offered on | On by default on a screen |
|---|---|---|---|
| Open in another window | Opens the same chart in a window of its own (see below). Only where the chart has an address of its own: a recorded run in Histories, a recipe profile. Never on a chart placed on a screen. | Recorded runs, recipe profiles | not offered |
| Select an area to zoom | Arms box-select zoom: the next drag over the plot frames the box it draws instead of panning. The button stays lit while armed. | Time charts | yes |
| Reset zoom | Returns the frame to the whole of what is plotted. | Time charts | yes |
| Set the scale by hand | Opens the scale panel below. Lit while anything is pinned, so a scale that stopped following the data says so without being opened. | Time charts | no |
| Minimum, average and maximum of the window shown | Opens the statistics panel below. Measured only while the panel is open. | Time charts | no |
| Draw a reference line | Opens the reference-line panel below. Lit while any line is drawn. | Time charts | no |
| Save PNG | Downloads the drawing as a PNG at twice the screen resolution, on the theme's background, named after the chart's title ("chart" when it has none). | All charts | yes |
| Copy PNG | Puts the same PNG on the clipboard. A browser that refuses clipboard writes does nothing, in silence. | All charts | yes |
| Show or hide series | Opens a list of the plotted series with a tick box each, read straight off the chart; unticking hides a series for as long as the screen stays open. "No series" when nothing is plotted. | Time charts | yes |
| The tooltip is off / The tooltip is on | Turns the hover readout on or off. It opens off, so a hand crossing the plot never covers it with a box nobody asked for; the choice lasts for the session. | Time charts | yes |
| Full screen | Fills the window with this one chart, through the browser's element fullscreen; pressing it again, or Esc, hands the window back. On a dashboard already full screen it expands the chart, and Esc leaves the chart before it leaves the dashboard. | All charts | yes |

A Bar chart or Pie chart can honour only the PNG pair and Full screen: a comparison read
at this instant has no axis to walk, no window to measure and nothing to lay a line on.
Only one panel is open at a time, and a press anywhere else closes it.

Zooming and panning themselves are the chart's **Navigation** setting (a fixed frame,
wheel and drag, or wheel and drag plus a navigation bar under the plot showing where the
frame sits in the whole recording); a chart with stacked plots moves every plot together,
because they share one time axis. A gesture never touches what is stored: the chart draws
what reaches the canvas from the visible range, so zooming in always reveals the real data,
and a corner mark can say whether the picture is the measurement or a reduction of it
([Line chart](component-line-chart#fidelity-and-performance)).

## Set the scale by hand {#set-the-scale-by-hand}

The panel pins a period of the time axis and a range of the value axis, each side
independently. Every field commits when you leave it; an empty field is a side left free,
still fitting itself.

| Field | What it takes |
|---|---|
| Period / Period (s from now) / Samples | The two ends of the time axis, asked in the words the axis is drawn in: two date-and-time pickers on a clock axis, two numbers of seconds on a relative axis, two sample counts on a sample axis. |
| Value axis, minimum and maximum | The ends of the chart's own value axis. On a chart with stacked plots this is the top plot's ruler alone; the time period moves every plot together. |
| Automatic (one per axis) | Hands that axis back to the frame the chart built: a rolling window rolls again, an axis authored with held ends returns to them, one authored with none returns to its free fit. Greyed while nothing is pinned on that axis. |
| Load the window shown | Fills all four fields from the frame really on screen, after every zoom and pan you made, so pinning what you are looking at costs one press. |

The pin belongs to this chart on this connection: it is never saved with the screen,
another browser looking at the same chart has its own, and closing the screen releases it.
A pinned frame that holds none of the samples still draws, and says so under the plot:
"Nothing was measured inside the scale you pinned."

## Minimum, average and maximum {#minimum-average-and-maximum}

The panel is a table with one row per plotted series (a series the screen's author turned
off is not on the screen and not in the table; one hidden with the legend still is),
coloured by its ink, with **Minimum**, **Average** and **Maximum** over the samples inside
the window shown, written the way the station writes numbers. The line above the table
says which window that is: "The window shown, up to the newest sample." or "The window
shown. The newest sample is past its right edge." when you walked back into the history. A
row's tooltip says how many of the window's samples were readings; a gap counts as a
sample the window held and as nothing in the three numbers, so no average is taken across
a hole. A row with nothing to read writes gaps and says which silence it is: "Nothing of
this series was sampled in the window shown." or "Every sample of this series in the window
shown is a gap." The numbers follow the live data while the panel is open and are measured
over the samples themselves, never over the reduced drawing.

## Reference lines {#reference-lines}

A reference line is a line at a value across the plot, or at an instant down it, with words
for why it is there and a colour to tell it from the next. The panel lists what is drawn,
each with its ✕, and **Remove all**; under the list one small form draws the next:

| Field | What it takes |
|---|---|
| Which axis | **At a value**, or the time axis in its own words: **At an instant** (a date-and-time picker), **At a second (from now)** or **At a sample**. Changing the axis empties the position, since a value and an instant are not the same number. |
| Where the line goes | The position on that axis. **Draw the line** is greyed until it holds one. |
| What the line says | Optional text drawn on the line. |
| The line's color | A colour picker; a line starts amber. |
| Draw the line | Draws it. The position and the text empty for the next line; the axis and the colour stay. |

Lines belong to the chart in front of you and to nothing else: they are not saved, the
screen's author is never told, another connection does not see them, and closing the
screen ends them. An annotation that has to outlive the looking belongs to a run, where the
run's own file records it ([Runs and comments](process-runs)).

## The detached chart window {#the-detached-chart-window}

**Open in another window** opens the chart's own route in a new window: a real window of
the application on the station, a new tab in a remote browser. Pressing it again brings the
existing window forward instead of opening a second one. Two routes exist:

| Route | What it shows | Opened from |
|---|---|---|
| `/chart/run/{id}` | The datalog chart of one recorded run, reloaded from the run file: its series, annotations, comments and the approved bands of its procedure as currently configured. "Run not found" when the id resolves to nothing. | The chart of a run in [Histories](histories) |
| `/chart/recipe/{id}` | The Step, Ramp and Soak profile of one recipe, rebuilt from the saved models. "Recipe not found" when the id resolves to nothing. | The recipe editor and a procedure's recipe preview |

The window renders without the shell: no rail, no title bar, no status bar, just a top bar
with the chart's title and **Sync X with the main chart** ("Mirror the X axis zoom and pan
with the main chart"), on by default, over the chart with its full toolbar. While the sync
is on the window joins a channel keyed by its route and follows the main chart's zoom and
pan on the time axis; turned off, it navigates on its own. Each route demands what admits
an identity to what it draws: the run window asks for View histories, the same permission
that admits the recorded-run browser it is opened from, and the recipe window asks for the
Process page's own policy, which any of the four Process switches or View histories opens.
A role without what its own route asks, or one demoted while the window is open, cannot
read that chart by its address. The window is read-only: comments and annotations are
edited in Histories, not here.

## What the tools do not do {#what-the-tools-do-not-do}

Nothing on the bar changes the screen: a hidden series, a pin, a line and the tooltip state
are all state of this chart on this connection, and a screen reopened tomorrow opens clean.
Nothing on the bar reaches a report: the PDF renders the drawing its own producer builds,
without pins, lines or tools. The bar exports no data, only pictures: the numbers of a run
leave through the exports of [Histories](histories). And the bar offers no tool the drawing
cannot honour: a comparison of categories never gets zoom, scale, statistics or lines, and
a chart on a screen never gets a window of its own.