diff --git a/.env.example b/.env.example index d1491d1..2879b8d 100644 --- a/.env.example +++ b/.env.example @@ -5,7 +5,9 @@ CANOPY_BASE_URL=http://localhost:8000 # VITE_CANOPY_BASE_PATH is /trace/api/canopy: the container injects the API key # and proxies it to the in-cluster Canopy service. When it is set, the dev proxy # also serves that one prefix (stripped before forwarding) instead of the -# per-module paths below. +# per-module paths below. VITE_CANOPY_BASE_PATH=.. puts the modules in the +# directory above the page instead (a page at /x/y/trace/ calls /x/y/mole/...); +# the dev proxy treats it as unset. VITE_BASE_PATH=/ VITE_CANOPY_BASE_PATH= diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index f330a17..a259006 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -12,3 +12,32 @@ concurrency: jobs: test: uses: slaclab/swapps-ci-helpers/.github/workflows/js-test.yml@afaac9fd67e0b31c887a48c19d9a6b219ea72a8f + + e2e: + name: Browser tests (Playwright) + runs-on: ubuntu-latest + + permissions: + contents: read + + steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + + - name: Setup pnpm + uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6 + + - name: Setup Node.js + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 + with: + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install + + - name: Install Chromium + run: pnpm exec playwright install --with-deps chromium + + # The @perf specs time the main thread and need a quiet machine; they run + # locally with `pnpm test:e2e --grep @perf`. + - name: Run browser tests + run: pnpm test:e2e --grep-invert @perf diff --git a/.gitignore b/.gitignore index 8dcad5d..57cf04f 100644 --- a/.gitignore +++ b/.gitignore @@ -37,8 +37,8 @@ lerna-debug.log* *.sln *.sw? -# MkDocs -site/ +# MkDocs / Zensical build output (the repo root's site/ only) +/site/ # Tauri src-tauri/target/ diff --git a/.prettierignore b/.prettierignore index 7cb0afe..08bf60c 100644 --- a/.prettierignore +++ b/.prettierignore @@ -17,3 +17,5 @@ src/routeTree.gen.ts # Must stay byte-identical to the Canopy license LICENSE.md +# Byte-pinned wire fixtures (sha256-asserted); never reformat +src/tools/correlation/__fixtures__ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b4ff9c..2c30434 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,85 @@ pnpm format:check `pnpm build` type-checks the app and the Vite config (`tsc -b`) before bundling; run it before opening a pull request. +### Chrome literals: colors and fonts come from the theme tokens + +Trace's own interface (its "chrome") takes its colors and fonts from the +`--canopy-*` contract variables, so a host application can restyle it from one +stylesheet. A color or font written as a literal in the chrome escapes that +contract. `scripts/check-chrome-literals.mjs` enforces this. `pnpm test` runs it +first, and you can run it alone: + +```bash +node scripts/check-chrome-literals.mjs # every guarded file +node scripts/check-chrome-literals.mjs src/App.css # only the named files +``` + +**What it checks.** Each guarded file is checked for: + +- a color literal: a hex color (`#fff`, `#0f62fe80`), a color function + (`rgb()`, `rgba()`, `hsl()`, `hsla()`, and `hwb()`, `lab()`, `lch()`, + `oklab()`, `oklch()`, `color(srgb ...)`; one that wraps a `var()` is fine), + or a CSS color name (all 148, such as `red` or `rebeccapurple`); +- a `font` or `font-family` that is not `inherit` or a `--canopy-font-*` + variable; +- in the workbench only (`src/workbench/`), a `font-size` that is not `inherit` + or a `--canopy-text-*` variable. + +Use `var(--canopy-...)` (colors, text sizes, fonts) instead. + +**Where it looks.** The guarded files are the list in `DEFAULT_FILES` plus +every file under `GUARDED_TREES` in the script: all production modules and +stylesheets of `src/workbench`, `src/plot` and `src/annotations`, and the +stylesheets of `src/tools/waveform` and `src/statistics`. Tests and +`__fixtures__` hold sample data and are not guarded. A new file in a guarded +tree is guarded without editing the script. + +**How a file is read.** The guard reads each file the way its syntax works, so +ordinary code is not mistaken for a style: + +- In a `.css` file only declarations are read: a selector such as `#feed {`, a + `url(#id)` and quoted text are not colors, and a color name counts only in + the value of a color property (`color`, `background`, `border`, `fill`, + custom properties and so on), so `white-space` and `var(--x-red)` pass. +- In a `.ts`/`.tsx` file only string literals, template literals and style + objects (`style={{...}}`, `style: {...}`, a `CSSProperties` value) are read. + Types (`font: string`), identifiers, JSX text, comments, object keys and + import paths are not. A string's context counts too: `href="#a11"`, a + selector passed to `querySelector` or `closest`, and a message passed to + `new Error()` or `console.*` are not styles, and a color name counts only + under a color key (`color`, `backgroundColor`, `fill`, `stroke`, `border...`) + or a color attribute (`fill="red"`), so `` passes. +- Any other file is read line by line as raw text, with hex colors, color + functions and fonts checked but not color names. + +**How to exempt a line.** Put a comment on the line before it: + +```css +/* canopy-allow-literal: document background */ +background: #161616; +``` + +In TypeScript use `// canopy-allow-literal: `, or +`{/* canopy-allow-literal: */}` in JSX. The reason must be one of the +accepted reasons below, and every exemption must also be counted in +`scripts/chrome-literals.allow` (`: : `, one line per file +and reason), which the full run checks in both directions, so an exemption is +never added or dropped silently. Run the guard on its own to see the exempt +lines it found. + +**Accepted reasons.** + +| Reason | Use it for | +| --------------------- | ------------------------------------------------------------------------------------------- | +| `document background` | the page background behind the app, which no host variable replaces | +| `@media print` | a print stylesheet, where the theme variables do not apply | +| `widget prop default` | the default of a widget prop that takes a color, before a host sets it | +| `Carbon danger pair` | the text color paired with a Carbon danger background token, which has no contract variable | +| `not a style literal` | a string the guard reads as a color or font that is not one (an id, a label, sample data) | + +A line that is not really a style is better rewritten so that the guard no +longer sees it than exempted. Use `not a style literal` only when it can't be. + ## Documentation The user guide in `docs/` is built with [Zensical](https://zensical.org/), which needs [uv](https://docs.astral.sh/uv/): diff --git a/README.md b/README.md index 0f28585..d7f5a9f 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,23 @@ React + Vite frontend for the Canopy / Trace plotting tool. Reads archive data f Canopy's Mole module (`/mole/v1/...`), live PVs from Hare and formulas from the Formula Engine, and posts e-log entries through Canopy's e-log module (`/elog/v1/apps/trace/...`). +## User docs + +The **Docs** action in every tool opens the documentation site. Its source lives in +`docs/`. It is a [Zensical](https://zensical.org/) site, built with +`uv run zensical build --clean`, or previewed with `uv run zensical serve`: + +- [The properties panel](docs/workbench.md): signals and cards, the plot-wide + sections, the modified dot and reset, More, the chart source, and where + actions live. +- [Waveform](docs/waveform.md): its lists, Snapshot → reference, Δ, + persistence and averaging, the X-axis PV rule, its statistics. +- [Correlation](docs/correlation.md): its built-in metrics, variables, units. +- [Statistics](docs/statistics.md): the shared panel, the Metrics list, + writing a metric, the function reference, the token grammar. +- [Drawing tools](docs/drawing-tools.md): time and axis gestures, range + controls, drawing and measuring on a plot, keys, and how drawings are saved. + ## Local dev ### 1. Run the Canopy backend @@ -33,7 +50,9 @@ cp .env.example .env e-log app path (`/elog/v1/apps/trace/`), to `CANOPY_BASE_URL` and injects the `X-API-Key` header, so the key never reaches the browser bundle. If `VITE_CANOPY_BASE_PATH` is set (for example `/trace/api/canopy`), the dev server proxies that one prefix instead and strips it -before forwarding, like the container's nginx. +before forwarding, like the container's nginx. `VITE_CANOPY_BASE_PATH=..` is for a gateway +that serves the modules beside Trace: a page at `/x/y/trace/` then calls `/x/y/mole/...`. +The dev server treats `..` as unset. Trace uses two Canopy keys: @@ -99,7 +118,32 @@ reach Canopy. The header's bug and help buttons open this repo's GitHub issues and the public docs site. A deployment can point them elsewhere with `VITE_BUG_REPORT_URL` and `VITE_DOCS_URL` at build time; the image build reads them from the -`BUG_REPORT_URL` and `DOCS_URL` repository variables. +`BUG_REPORT_URL` and `DOCS_URL` repository variables. A site's `config.json` +overrides both at runtime (below). + +#### Site defaults (optional) + +A deployment sets its own defaults without a rebuild: the header prefix and +links, the plot gestures, and what a new plot, curve or view opens with. Every +page reads `config.json` next to it (the image ships a neutral one at +`/usr/share/nginx/html/config.json`; mount your own over it) and Canopy's +site settings (`GET /magpie/v1/settings/trace`), which win over +the file. `config.example.json` lists every key; `docs/site-defaults.md` +explains them. The file is served to every browser: no secrets in it. (The +desktop app's `src-tauri/config.json`, which holds keys, is a different file +and is never served.) + +#### Channel catalog (optional) + +Every PV field suggests names from two sources: Mole's archiver index, and a +channel catalog the host may serve beside it. The catalog is +`GET /channels`, where `` is the prefix the Mole, +Hare and Formula Engine routes sit under (`VITE_CANOPY_BASE_PATH` when set, +else the site root; `src/api/connection.ts`). It answers with a +JSON array of PV names (`string[]`) and a strong `ETag`; Trace fetches it once +per page and ranks it in the browser (`src/pvSearch/`). A `404` means the +deployment has no catalog, and suggestions then come from Mole alone. A +network error or a body that is not a string array is treated the same way. ### 3. Run the dev server @@ -112,9 +156,93 @@ pnpm dev ```bash pnpm dev # vite dev server -pnpm build # tsc -b && vite build +pnpm build # tsc -b && vite build, then the dist check pnpm typecheck # tsc -b -pnpm test # vitest +pnpm test # chrome-literal guard, then vitest +pnpm test:e2e # Playwright browser tests (e2e/*.e2e.ts) against a fresh build pnpm lint # eslint pnpm format # prettier --write ``` + +The browser tests need Chromium once per machine +(`pnpm exec playwright install chromium`). CI runs them with +`--grep-invert @perf`; the `@perf` specs time the main thread, so run them +alone on a quiet machine with `pnpm test:e2e --grep @perf`. + +## Adding a tool to the workbench + +Trace, Correlation and Waveform are the three tools on the workbench +(`src/workbench/`). The workbench owns the layout, the sidebar, the +properties panel and the actions bar. A tool supplies data and rules, and writes no layout +code. The worked example is the stub fourth tool in +`src/workbench/__fixtures__/stubTool.ts` (`createStubTool`, `stubSchema`). +The panel and layout tests run against it, and it has one of +everything described below. + +### `ToolDefinition` + +A tool hands `WorkbenchLayout` (from `src/workbench/index.ts`) a +`ToolDefinition` (`src/workbench/types.ts`), along with its `state`, `model`, +`ui`, a single writer `update(fn)` and its `capabilities`. The canvas goes in +as `children`. The definition has two halves: + +- **`schema: ToolSchema`** is static. Build it once at module level, never + per render. It holds the tool-level object and the `sections` and `items` + by kind. Each object declares its field groups (`tabs`), and each group its + fields (`FieldDef`, levels `L1` to `L3`; `L3` goes under More). The panel + shows an item's groups as the titled blocks of its card, and the tool's as + the plot-wide sections (ids and labels from `src/tools/vocabulary.ts`, each + with a one-line `summary`). A section kind names its top-block `group` + (Signals, Reference, …) and whether its fields sit under its cards or in + Axes (`placement`). The tool's `code` group is the one chart-source link, + printed by `src/tools/codeFragment.ts`. Fields read `ctx.target`, never + the selection, and write only through `ctx.update`. +- **`binding: ToolBinding`** is rebuilt per render and read through a + latest-ref. It holds `outline(state, model)` (the lists of the top block), + `ops` (`add`, which is async and may resolve to an `AddRefusal`, plus + `remove` and `move`), `moveRefusal(item, section)` (the one rule the Plot on + select and card drags share) and optional `footer` actions. + +See `src/tools/waveform/tool.ts` for a real tool. It builds its schema at +module level and its binding with `useWaveformDefinition`. + +Canvas actions are registered from inside the canvas with `useCanvasActions` +(`src/workbench/useCanvasActions.ts`), and end with +`standardActions({ embedded, theme, bugUrl, docsUrl })`. Leave out an action +the deployment cannot support. Register a temporarily unusable one with +`disabled: ''`. + +### Dot helpers + +The workbench never knows a default. A field that has an automatic value +spreads a `Dot` (`modified(ctx)`, `reset(ctx)`) built by one of the helpers +in `src/tools/dotHelpers.ts`: + +- `optionalPath`: the value is optional. It is modified when present, and + reset writes `undefined`. +- `recordKey`: the value is an entry in a per-PV record. It is modified when + the entry exists, and reset deletes it. +- `stampedValue`: the tool stamps an automatic value (a palette color, an + axis slot). It is modified when the tool's rule rejects the stored value, + and reset writes the object's own automatic value. + +A field with no automatic rule uses no helper and shows no dot. + +### Import allow-list + +`src/workbench/**` must never reach into a tool. The ESLint rule +`workbench/import-allowlist` (`eslint.config.js`) allows only `react`, +`@carbon/*`, `@dnd-kit/*`, `react-resizable-panels`, `src/workbench/**` and +the shared PV field modules. Tests and `src/workbench/__fixtures__/` may also +use `vitest`, `@testing-library/*`, `src/tools/dotHelpers` and +`src/tools/codeFragment`. Tool code lives under `src/tools//` and +imports the workbench, never the reverse. `pnpm lint` enforces this. + +### Test ids are a contract + +The `data-testid` values in `src/workbench/testids.ts` (`TESTIDS`, and +`inspectorTab(id)` → `inspector-tab-`) are used by the sdk-js host probes +as well as the e2e specs, so they are a cross-repo contract. +`src/workbench/testids.test.ts` pins the set. A rename fails there first and +must be made in the probes too. Test ids are for chrome. Fields are reached by +their `#id`, and a control never has both. diff --git a/config.example.json b/config.example.json new file mode 100644 index 0000000..839459d --- /dev/null +++ b/config.example.json @@ -0,0 +1,89 @@ +{ + "$comment": "Site defaults: every key, at the built-in value (the links are placeholders). Copy the keys you want to change into the config.json next to the app; leave the rest out so later built-in changes still reach you. Shown on public pages: never put a secret here. See docs/site-defaults.md.", + "version": 1, + "header": { + "$comment": "Trace's heading, standalone only. prefix shows before the product name; brand paints both in the shell's brand color. The links open from the help menu of every tool (http or https only; built in: the build's VITE_BUG_REPORT_URL and VITE_DOCS_URL, else this project's issues and docs).", + "prefix": "", + "brand": false, + "bugReportUrl": "https://example.org/report-a-bug", + "docsUrl": "https://example.org/trace-docs/" + }, + "plot": { + "$comment": "The plot behavior of all three tools; a tool's own plot section overrides it. wheel: x (the wheel zooms X only, Alt+wheel X and every Y) or xy (X and every Y, Alt+wheel the primary Y). yAxisDrag: pan or stretch (Shift or Alt does the other). doubleClick: reset (every axis of the plot) or none (a double-click on an axis still resets that axis). tooltip: cursor or docked (in Trace, whether a new plot's Dock data tooltip is on). The values here are Correlation's and Waveform's built-ins; Trace's are in trace.plot.", + "wheel": "xy", + "yAxisDrag": "stretch", + "doubleClick": "reset", + "tooltip": "docked" + }, + "trace": { + "plot": { + "$comment": "What a new Trace plot opens with: Add plot, a fresh tab, and a link or host query that names PVs or a range but carries no plot settings. Also takes the plot-behavior keys; Trace's own built-in values for them are below. timeRange is a relative range (-1h, -30m). archiver is the plot's default archiver; null means Canopy's default, and a name that does not exist leaves every new plot without archive data. palette is a palette id; a user's own palette pick wins.", + "wheel": "x", + "yAxisDrag": "pan", + "tooltip": "cursor", + "showCrosshair": true, + "dragMode": "zoom", + "showLegend": true, + "showXGridlines": true, + "showYGridlines": true, + "gridStyle": "solid", + "gridOpacity": 1, + "tickFontSize": 11, + "refreshIntervalS": 5, + "palette": "default", + "timeRange": "-1h", + "archiver": null, + "showDrawingTools": true + }, + "trace": { + "$comment": "What a new Trace curve opens with. lineType: step or direct (formulas stay direct and take the width and symbols only).", + "lineWidth": 2, + "lineType": "step", + "showSymbol": false + } + }, + "correlation": { + "$comment": "What a fresh Correlation view opens with (no state beyond its PVs). lookback: 1m to 24h. dt: the Timer period in seconds, at least 0.1. metrics: the statistics columns, in order, as the link's m= tokens (a leading - lists a metric but leaves it out of the table).", + "plot": {}, + "lookback": "1h", + "dt": 1, + "metrics": [ + "n", + "mean", + "std", + "r", + "slope", + "-r2", + "-intercept", + "-min", + "-max", + "-p2p", + "-rms", + "-xmean", + "-xstd" + ], + "drawingTools": true + }, + "waveform": { + "$comment": "What a fresh Waveform view opens with (no state beyond its PVs). rollS: the Rolling mean window, 1 to 3600 s. metrics as in Correlation.", + "plot": {}, + "rollS": 60, + "metrics": [ + "n", + "mean", + "std", + "rms", + "p2p", + "-min", + "-max", + "-median", + "-peak", + "-trough", + "-devrms", + "-devmax", + "-devsig", + "-worst" + ], + "drawingTools": true + } +} diff --git a/correlation.html b/correlation.html new file mode 100644 index 0000000..c4f0fa0 --- /dev/null +++ b/correlation.html @@ -0,0 +1,13 @@ + + + + + + + Correlation + + +
+ + + diff --git a/docker/Dockerfile b/docker/Dockerfile index 7ce20ad..94424ae 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -10,6 +10,7 @@ COPY . . ARG VITE_BASE_PATH=/trace/ ARG VITE_CANOPY_BASE_PATH=/trace/api/canopy # Empty means the app's defaults: this repo's GitHub issues and public docs site. +# A config.json's header.bugReportUrl and header.docsUrl override them at runtime. ARG VITE_BUG_REPORT_URL= ARG VITE_DOCS_URL= ENV VITE_BASE_PATH=$VITE_BASE_PATH @@ -21,6 +22,10 @@ RUN pnpm build FROM nginx:1.29-alpine +# dist/ carries a neutral config.json (the built-in site defaults). A +# deployment sets its own without a rebuild by mounting a file over it, e.g. +# -v ./config.json:/usr/share/nginx/html/config.json:ro +# (docs/site-defaults.md; every key in config.example.json). COPY --from=build /app/dist /usr/share/nginx/html COPY docker/nginx.conf.template /app/nginx.conf.template COPY docker/start-nginx.sh /app/start-nginx.sh diff --git a/docker/nginx.conf.template b/docker/nginx.conf.template index e9666a4..b86df68 100644 --- a/docker/nginx.conf.template +++ b/docker/nginx.conf.template @@ -61,6 +61,15 @@ http { proxy_send_timeout 3600; } + # The site defaults (docs/site-defaults.md). A deployment mounts its + # own file over the image's neutral one. Revalidated on every load, so + # an edit takes effect on the next page load; a missing file is a 404, + # never the SPA page below. + location = /config.json { + add_header Cache-Control "no-cache" always; + try_files $uri =404; + } + location / { try_files $uri $uri/ /index.html; } diff --git a/docs/correlation.md b/docs/correlation.md new file mode 100644 index 0000000..ae273e3 --- /dev/null +++ b/docs/correlation.md @@ -0,0 +1,79 @@ +--- +icon: lucide/chart-scatter +--- + +# Correlation + +Correlation plots one PV (the X) against up to eight others (the Ys), as a +scatter or a density plot. It uses the shared +[properties panel](workbench.md): the Ys are its **Signals**, the X is the +**X axis PV**, and the **Trigger** list sets when a point is taken. + +This page covers what is specific to Correlation's **statistics**. The +panel, the Metrics editor, the expression language and the URL grammar are +the same in every tool and are described on the [Statistics](statistics.md) +page. + +## Statistics + +Turn on **Show statistics** (the **Statistics** section) and the readout table +docks under the plot: one row per Y and one column per metric. Each value is +computed over the points on screen, so it changes when you change Max points +or Lookback. Below the table, optional **strip charts** plot a metric over +time, one line per Y, on the data clock (the newest row on screen); _Clear_ +empties their history. + +**The quiet default.** The table shows five columns: n, mean, std, r and +slope. Every strip chart is off. The other built-in metrics are in the list, +turned off. + +### Built-in metrics + +| Id | Label | Expression | Unit | On by default | +| ----------- | --------- | ----------------- | ------- | ------------- | +| `n` | n | `n` | none | yes | +| `mean` | mean | `mean(y)` | Y | yes | +| `std` | std | `std(y)` | Y | yes | +| `r` | r | `corr(x, y)` | none | yes | +| `slope` | slope | `slope(x, y)` | Y per X | yes | +| `r2` | R² | `r2(x, y)` | none | no | +| `intercept` | intercept | `intercept(x, y)` | Y | no | +| `min` | min | `min(y)` | Y | no | +| `max` | max | `max(y)` | Y | no | +| `p2p` | p2p | `ptp(y)` | Y | no | +| `rms` | rms | `rms(y)` | Y | no | +| `xmean` | X mean | `mean(x)` | X | no | +| `xstd` | X std | `std(x)` | X | no | + +X statistics are metrics too (_X mean_, _X std_), so the table has rows for +the Ys only. An X metric is computed over the rows where X and that row's Y +are both valid, so it can differ slightly between rows when a Y has gaps. +The r strip is fixed to −1 … 1 and the R² strip to 0 … 1; the others scale +to their data. + +### Variables + +- `x` is the X PV and `y` is the Y of the row being computed. +- `y1` … `y8` are the Ys by position in the Y list, the same in every row. +- `t` is the time of each point in seconds relative to the newest one, so it + is 0 or negative. +- `n` is the number of points, and `pi` and `e` are constants. + +**Unit** picks the unit shown after the value: none, the Y's unit, the X's +unit, or Y per X. + +### In the URL + +`readout=1` turns the panel on; the metric list is written as repeated +`m=` keys, as the [Statistics](statistics.md#in-the-url) page describes. +When a URL grows past its 4 KB budget, the `m=` keys are dropped after the +labels, colors, markers and hidden list, and Ys only after that. + +## Drawings + +Correlation draws lines, boxes, notes and measurements like Trace; see +[Drawing in Correlation and Waveform](drawing-tools.md#other-plots). A +**Measure** card reads Δx, Δy and Δy/Δx (the slope of its diagonal), then +the number of points of its Y series inside the box, their mean (ȳ) and σ. +It shows no Δ%. Right-click a drawing, or its card under **Drawings**, to +edit, lock or delete it. diff --git a/docs/drawing-tools.md b/docs/drawing-tools.md new file mode 100644 index 0000000..864132e --- /dev/null +++ b/docs/drawing-tools.md @@ -0,0 +1,427 @@ +--- +icon: lucide/pencil-ruler +--- + +# Drawing tools + +Trace lets you move through time and scale the axes straight on the plot, and +draw on it: horizontal and vertical lines, time ranges, trend lines, boxes, +notes and measurements. Drawings sit in data coordinates, so they stay on the +value and time they mark while you zoom, pan or follow live data. They are +listed under **Drawings** in the properties panel, edited in their cards, undone with +⌘Z / Ctrl+Z, and saved with the plot. + +Every plot behaves the same way wherever it is shown: as a tab, as a cell of +the grid, full screen, or in a detached window. + +The same drawing tools work in [Correlation](correlation.md) and +[Waveform](waveform.md); see [Drawing in Correlation and +Waveform](#other-plots) for what differs there. + +## Moving through time { #navigation } + +The plot shows a _view window_ of time. Any gesture that moves it stops the +plot from following live data; **Now** (below) turns following back on. + +- **Wheel** over the plot zooms time around the cursor; auto-scaled Y axes + refit to what is visible. **Alt + wheel** zooms time and every Y axis. +- **Shift + wheel**, or a mostly sideways trackpad scroll, pans time; so do + the **←** and **→** keys while the plot has focus. +- **Drag** the plot with the left button to draw a zoom box; the plot zooms to + it when you let go, and a thin box zooms only time or only the Y axes. With + the rail's drag toggle set to pan, the drag pans time instead: every Y axis + you have scaled by hand moves with it, auto-scaled axes refit to what is + visible. +- **Double-click** the plot returns time to the plot's range (for example the + last hour) and turns auto-scale back on for every Y axis. +- **Wheel** over the time axis labels zooms time around the cursor. +- **Drag** along the time axis labels stretches time with the right edge + held still: drag right to zoom in, left to zoom out. When the right edge is + at now, the plot keeps following live data with the new span. +- **Double-click** the time axis labels returns time to the plot's range. +- **Right-click** the time axis labels for a **Time range** menu: _All_ and + every preset of the Time range field. + +The plot's tab bar (and the header of a grid cell, the full-screen view and a +detached window) carries the range controls: + +- **1h**, **6h**, **24h** pick the last hour, six hours or day. +- **All** shows from the earliest loaded sample to now. +- **Go to** takes a date and time and centers a window of the current span on + it. +- **Now** follows live data again with the last relative span you used, or + the last hour if there was none. + +## Scaling the Y axes { #axes } + +- **Drag** a Y axis up or down to move that axis alone. **Shift + drag** (or + **Alt + drag**) zooms it instead: up to zoom in about its center, down to + zoom out. Either way the axis stops auto-scaling. +- **Wheel** over a Y axis zooms it around the value under the cursor. +- **Alt + wheel** over the plot zooms time and every Y axis around the + cursor. +- **Double-click** a Y axis, or click the **A** badge that appears above a + hand-scaled axis, to turn auto-scale back on. +- **Right-click** a Y axis for its options menu: _Auto-scale_, _Logarithmic_, + _Reset scale_. _Invert_ is listed but not available yet. + +Right-click inside the plot for the point's menu: _Add horizontal line here_, +_Add vertical line here_, _Add note here_ (which opens the new note's text +box), _Reset zoom_ (the time range and every hand-scaled axis back) and the +copy and share actions; see [Right-click menus](workbench.md#right-click). +Right-click a drawing instead for the drawing's own menu (see +[Editing](#editing)). + +## Drawing { #drawing } + +The drawing rail sits on the plot. Its tools stand in groups: lines +(horizontal, vertical, trend), areas (time range, box), then measure and +note. Hover any button for its name and key. + +Pick a tool, then: + +- **Horizontal line**, **Vertical line** and **Note** place with one click. +- **Trend line**, **Time range**, **Box** and **Measure** take two points: + drag from the first to the second, or click twice. (Shift-drag measures + without picking the tool; see [Measuring](#measuring).) + +A new note opens its text box right on the plot: type, then press Enter or +click elsewhere to keep it. Escape on a new note removes it (⌘Z / Ctrl+Z +brings it back); on a note you reopen, Escape leaves it as it was. +Double-click a note to change its text later. A locked note keeps its text. + +Drawings look like the marks in a printed figure: a fine line in ink (dark on +a light plot, light on a dark one), labels in a small italic serif, and no +filled shapes except a faint tint on a time range. + +After placing, the rail goes back to the pointer. The toggles below the tools +are the same in every plot tool: + +- **Magnet** snaps each point to the nearest drawn sample within 24 px. The + drawing then belongs to that curve's axis and keeps the sample's exact + value. +- **Keep drawing** keeps the tool armed after drawing, so you can place + several in a row. +- **Data tooltip** shows the values under the cursor (on by default). The + crosshair has its own setting. In Trace the tooltip follows the cursor; + turn on **Dock data tooltip** in **Display** to keep it in a corner of the + plot, away from the cursor, as Correlation and Waveform always do. A + docked tooltip has a grip (⋮⋮): drag it to put the tooltip anywhere in the + plot; double-click it to send the tooltip back to its corner. +- **Hide all drawings** hides every drawing of the plot (click again to show + them). Hidden drawings also stay out of exported images. +- **Zoom box** sets what a left-drag in the plot does: draw a zoom box + (pressed) or pan. Every tool zooms by default. + +### Hiding the rail { #hiding-the-rail } + +Turn off **Drawing tools** in the plot's **Display** section to hide the +rail. While it is off, an +armed tool goes back to the pointer and the drawing keys (Alt+H … Alt+M) +do nothing. The drawings you already have stay on the plot: open them from +their cards under **Drawings**, or right-click one, to edit, lock or delete +them. + +While the rail is hidden, **Display** lists three of its toggles in its +place: **Data tooltip**, **Mouse drag** for the zoom box, and **Drawings**, +which shows or hides the plot's drawings. **Drawings** is the rail's **Hide +all drawings** button under another name, so the two always agree. While the +rail is shown, only the rail has them. **Magnet** and **Keep drawing** have +no place in **Display**: they only matter while drawing, and they keep their +last setting while the rail is hidden (the magnet still applies to **Add … +here** and to dragging a drawing's handles). + +A vertical line and a time range span the whole height of the plot; every +other drawing belongs to one Y axis. + +### Measuring { #measuring } + +Hold **Shift** and drag in the plot for a quick measurement shown while you +drag; it disappears when you let go. The **Measure** tool (drag, or click +twice) draws one that stays. In Trace both show Δ of the value, Δ% against +the first point, Δt, and the number of samples, mean and σ of the curve +under the measurement, written as a figure would (`Δy = −186.5`, +`x̄ = 2950`, `σ = 25.02`). When that curve shows binned archive data, the +count reads in bins and σ is marked approximate. Select a measurement to +drag its readout by the grip beside it; double-click the grip to put the +readout back. Its card in **Drawings** is named for the change it measures, +with the same minus sign (`Measure Δ−21.49 mA / 4 s`). + +In Correlation and Waveform x is a value, so the card shows Δx instead of +Δt, and no Δ%: + +- **Correlation**: Δx, Δy and Δy/Δx (the slope of the drawn diagonal), then + the number of points of the drawing's Y series inside the box, their mean + (ȳ) and σ. +- **Waveform**: Δx and Δy, then for each live curve shown, the number of + its elements whose x lies inside the measured span, their mean (x̄) and σ. + With more than one curve, each line starts with the curve's name. + +### Editing { #editing } + +- **Click** a drawing to select it; **drag** it to move it; drag one of its + handles to reshape it. +- **Right-click** a drawing, on the plot or its card under **Drawings**, for + its menu, headed by its name: **Edit** (selects it and opens its card), + **Lock** or **Unlock**, and **Delete**. +- A selected drawing shows a round **style** button. It opens the drawing's + color (ink, the color of each plotted curve, or an accent), its line + width (0.5 to 2 px) and solid or dashed. +- A locked drawing cannot be moved, reshaped or restyled and shows a lock + instead of handles. On its card, **Color**, **Width**, **Style**, + **Axis**, **Value** and **Extend** are unavailable ("Locked"), and so is a + locked note's **Label**. It can still be hidden, unlocked and deleted. +- **Esc** cancels a drawing in progress, then disarms the tool. +- **Delete** or **Backspace** deletes the selected drawing, unless it is + locked. +- **⌘Z** (macOS) or **Ctrl+Z** undoes the last drawing change of the current + plot (the selected plot, or the fullscreen or detached plot you are in), + from any place you made it: the plot, the properties panel or a menu. Each + plot keeps its own history. There is no redo. Undo history lasts for the + session; opening a workspace clears it. + +### The Drawings list + +When a plot has drawings, the properties panel shows a **Drawings** list after +the signals, one card per drawing, named for what it marks (for example +`H-line 2.35 mA` or `Range 12 m 30 s`). The list's eye hides or shows all +of them; each card has its own eye, lock and delete. Drawings stay in +Drawings: they cannot be dragged onto an axis. + +Click a drawing's card (or select the drawing on the plot) and it offers: + +- **Kind** (read only), **Label**, **Color**, **Width**, **Style** + (_Solid_ or _Dashed_). +- **Axis**, for the drawings that carry a value. +- **Value**, for a horizontal line. +- **Extend** (_None_, _Right_, _Both_), for a trend line. +- **Delete**. **Locked** and **Visible** are not fields: they are the lock + and eye buttons on the card's head. + +## Drawing in Correlation and Waveform { #other-plots } + +Correlation and Waveform offer the same rail, toggles, editing, keys and +properties panel as Trace, and the same drag and double-click gestures on +both axes (a left-drag draws a zoom box by default, as in Trace; a zoom sets +the X and Y scale in **Axes**). The differences: + +- The wheel over the plot zooms both axes (**Alt + wheel**: the Y axis + alone), and dragging a Y axis zooms it (**Shift + drag**: moves it). A + site can change these ([Site defaults](site-defaults.md)). + +- Their x axis is a value, not time, so there is no **Time range** tool + (Alt+R does nothing) and x reads as a value in labels and the status line. +- In **Correlation** a drawing belongs to one Y series (with **Magnet**, the + series of the sample it snapped to). Lines, boxes, notes and measurements + that use x also remember the X PV they were drawn against. +- In **Waveform** every drawing belongs to the one Y axis. A drawing + remembers the x it was drawn against (element index or the X axis PV) + and whether **Δ** (_Subtract reference_) was on. While the X axis PV is + still loading, nothing can be placed. + +### Hidden drawings { #hidden-by-context } + +A drawing that no longer fits what the plot shows is kept but not drawn. +It stays in the Drawings list, dimmed, with the reason next to it, and comes back by +itself as soon as the plot matches again; nothing is deleted. The reasons: + +| Plot | Reason | When | +| ----------- | ------------------- | ----------------------------------------------------------- | +| Correlation | _series removed_ | its Y series is no longer on the plot | +| Correlation | _series hidden_ | its Y series is hidden | +| Correlation | _not the density Y_ | the density view shows a different Y | +| Correlation | _x source changed_ | the X PV is not the one it was drawn against | +| Waveform | _x source changed_ | the plot's x is not the one it was drawn against | +| Waveform | _Δ changed_ | Δ is on and it was drawn with Δ off, or the other way round | + +A horizontal line uses no x, so it never hides for _x source changed_. + +### Drawings in the link { #link-notices } + +Correlation and Waveform keep their drawings in the page link, which has a +fixed size. When a link would be too long, Trace makes it fit: note texts are +first shortened to 24 characters, then emptied, and then the last drawings +are left out, one at a time. Only the link is shortened; the drawings on +your plot are unchanged. The status line says what the link lost: + +- _N drawings not saved in the link_ when drawings were left out. +- _Note text shortened in the link_ when only note text was cut. + +## Keys { #keys } + +The keys act on the plot that has focus; clicking a plot, or picking a rail +tool, gives it focus. ⌘Z / Ctrl+Z works anywhere in the window and undoes the +current plot. Keys do nothing while you type in a field. + +| Key | Action | +| ------------------ | ---------------------------------------------------- | +| Alt+H | Horizontal line | +| Alt+V | Vertical line | +| Alt+L | Trend line (Alt+T is the theme toggle) | +| Alt+R | Time range | +| Alt+B | Box | +| Alt+N | Note | +| Alt+M | Measure | +| ← / → | Pan time by 10 % of the span | +| + / − | Zoom time in / out by 1.25 about the center | +| Esc | Cancel the drawing in progress, then disarm the tool | +| Delete / Backspace | Delete the selected drawing (not a locked one) | +| ⌘Z / Ctrl+Z | Undo the last drawing change of the current plot | + +The tool keys (Alt+H … Alt+M) do nothing while the plot's **Drawing tools** +is off; Esc and Delete still act on the drawings you have. + +## What the plot tells you { #status-line } + +The **status line** under the plot shows the time and the first Y axis's +value under the cursor, and, while a tool is armed, what to do next. Turn it +off with **Status line** in the plot's **Display** section. + +**Pin data window**, also in **Display**, fixes the hover readout at the plot's +top-right, so it never covers what is under the pointer. **Dock data +tooltip** keeps it in a corner of the plot instead, moving out of the +cursor's way. + +## Saving { #saving } + +Drawings are part of the plot: + +- A **.trc.json** workspace keeps every drawing of every plot. +- Exported images, printouts and E-Log attachments show the drawings as you + see them, unless they are hidden. +- An embedded Trace tile keeps the drawings of its **first plot** in its URL, + up to 64 of them. When the URL runs out of room, the last drawings are + dropped first (the browser console logs how many were kept); if not even + one fits, none are kept. A tile always reopens with everything its URL + kept, also from **Copy link to this view**; a link that is over the limit + when it arrives (one edited by hand) opens without its drawings, or + without its plot settings, rather than empty. The status line of + any other plot in an embedded tile says _Drawings on this plot are not + saved in the tile_. + +Correlation and Waveform links keep drawings as described in [Drawings in +the link](#link-notices). + +**Drawing tools** off is saved with the plot: in Trace, in the **.trc.json** +workspace, the config store and the link's `plot=` settings (as +`"showDrawingTools":false`); in Correlation and Waveform, as `rail=0` in the +link. Without that key a plot +opens with the rail shown. **Drawings** (hide all) is not saved. + +## For developers { #developers } + +The drawing core lives in `src/annotations/`. It knows no plot: everything a +plot differs in comes in through a catalog of tools and a `HostConfig`. The +plot interaction layer it builds on (gestures, projection, strip toggles, +read-out dock, PNG capture) lives in `src/plot/` and is shared by every plot +tool, with or without drawings. + +### Adding a tool { #adding-a-tool } + +A new tool is **one module, one catalog entry, one line per plot**: + +1. **One module.** Create `src/annotations/catalog//` with `def.ts` + (exporting `_TOOL: DrawingTool`), `Shape.tsx` and `def.test.tsx`. + `def.ts` imports only `../types`, `../shapeKit` and `../format`. A + `DrawingTool` carries everything about the tool: identity (`kind`, + `code`, `label`, `icon`), placement (`arity` 1 or 2, `axes` `'x'`, `'y'` + or `'xy'`, the Alt `key`, `menuAdd`, `inlineText`), shape (`shapePoint`, + `geometry`, `Shape`), text (`objName`, `hint`), its own panel + `fields` and `validate`, and its link `codec`. Behavior keys on these + fields, never on a `kind` string. +2. **One catalog entry.** Build the plot's catalog with `makeCatalog` from + `src/annotations/catalog/index.ts`, for example + `makeCatalog([...BUILTIN_TOOLS, NEW_TOOL])`. `BUILTIN_TOOLS` is the seven + built-ins in rail order; `BUILTIN_CATALOG` (Trace) holds all seven, + `CORRELATION_CATALOG` and `WAVEFORM_CATALOG` the six without the time + range. There is no module-level tool lookup: everything goes through a + catalog. +3. **One line per plot.** Pass the catalog as `HostConfig.catalog` in each + plot that should offer the tool. + +`makeCatalog` throws on a duplicate `kind`, `code` or key, on an arity other +than 1 or 2, and on a codec layout whose point count disagrees with the +arity. + +Tool **codes** are the wire format of saved files and links, so a code is +never reused: + +| Range | Use | +| ----- | -------------------- | +| 0–6 | the built-in tools | +| 100+ | any other (new) tool | +| 900+ | test-only tools | + +The worked example is the test-only crosshair, +`src/annotations/catalog/__fixtures__/cross/def.ts` (code 900), which +`src/annotations/catalog/extensibility.test.tsx` adds to Trace and +Correlation by one catalog line each and round-trips through both link +codecs. `src/annotations/catalog/hline/def.ts` is a small built-in to copy. + +### HostConfig { #host-config } + +A plot hands its drawing overlay one `HostConfig` +(`src/annotations/catalog/types.ts`), built with `useMemo` and never keyed on +the data frame: + +- `catalog` — the tools the plot offers. +- `xAxis` — `TIME_X_AXIS` or `VALUE_X_AXIS` (`catalog/xAxis.ts`): how x is + formatted and quantized. +- `snap` — the `SnapSource` a Magnet press uses; reads live data through a + getter. +- `measure` — the `MeasureProvider` for the measure card rows. +- `frames` — the `FrameStore` the plot bumps on each data frame + (`createFrameStore`, `src/annotations/host/frameStore.ts`); only the + measure card subscribes. +- `shed` — the `ShedStore` the link writer publishes into; the status line + reads it for the link notices. +- `ownerAxisAt(px, py, snapHit)` — the axis a new drawing belongs to, or + null to place nothing. +- `hiddenReason(a)` — why a drawing is hidden right now, or null. + +Trace builds its config in `src/tools/trace/drawing/hostConfig.ts` +(`createTraceHostConfig`), Correlation in `src/tools/correlation/Plot.tsx` with +`correlationHiddenReason` from `src/tools/correlation/drawings.ts`, and Waveform +in `src/tools/waveform/Plot.tsx` with `waveformHiddenReason` from +`src/tools/waveform/drawings.ts`. + +### Host parts { #host-parts } + +`src/annotations/host/` holds the pieces a plot assembles: + +- `useDrawingHost` — the `DrawingHost` (config, document and handle), the + plot menu and wrapper listeners; `shedNoticeOf` turns a shed snapshot into + the notice text. +- `useDrawingDocument` — the `DrawingDocument` over the host's state and + undo history. +- `DrawingLayers`, `DrawingRailFor` — the drawing layer with the in-place + note editor, and the rail. +- `DrawingStatusLine` — the status line, with the link notice. +- `workbench.ts` — `createDrawingSchema` and `createDrawingsSectionSchema` + for a drawing's card, and `drawingsSection` for the Drawings list, dimmed as stale + with their hide reason. +- `shedStore.ts`, `hostKeys.ts` (`routeDrawingKey`) and `UndoKeyListener`. + +The rail's toggles come from one registry, `PLOT_TOGGLES` in +`src/plot/plotToggles.ts`: a toggle added there appears in every +plot. A plot passes only the values and writers (`DrawingRailFor`'s `view` +and `onView` for the tooltip and drag mode; hide-all appears when the +document has `setHidden`). The plot gestures (wheel, drag, zoom box, +double-click) are `usePlotGestures` in `src/plot/gestures.ts`; a plot +supplies a `PlotGestureSurface`: its grids, axes, value mapping and scale +writers. + +The `ann=` link codec Correlation and Waveform share is +`src/annotations/contextLink.ts`; Trace's `plot=` codec is +`src/annotations/config.ts`. + +### The import boundary { #import-boundary } + +The lint rule `annotations/import-allowlist` (`eslint.config.js`) keeps the +core plot-free: a production module under `src/annotations/` may import only +`src/annotations/**`, `src/plot/**`, `src/workbench/**`, `src/statistics/**`, +`src/chartTheme` and third-party packages. Tests and `__fixtures__` are +exempt. The rule `plot/import-allowlist` keeps `src/plot/` to itself and +third-party packages. Code only Trace needs belongs in `src/tools/trace/drawing/`; +Correlation and Waveform keep theirs in `src/tools/correlation/` and +`src/tools/waveform/`. diff --git a/docs/images/axes.png b/docs/images/axes.png index 0bade33..70e3e68 100644 Binary files a/docs/images/axes.png and b/docs/images/axes.png differ diff --git a/docs/images/data_insight.png b/docs/images/data_insight.png index 94fd39c..9f0c7b7 100644 Binary files a/docs/images/data_insight.png and b/docs/images/data_insight.png differ diff --git a/docs/images/formula.png b/docs/images/formula.png index 920e080..abf0bca 100644 Binary files a/docs/images/formula.png and b/docs/images/formula.png differ diff --git a/docs/images/icons/archive.png b/docs/images/icons/archive.png deleted file mode 100644 index 8a5f9e9..0000000 Binary files a/docs/images/icons/archive.png and /dev/null differ diff --git a/docs/images/icons/live.png b/docs/images/icons/live.png deleted file mode 100644 index 0086be9..0000000 Binary files a/docs/images/icons/live.png and /dev/null differ diff --git a/docs/images/multiple_plots.png b/docs/images/multiple_plots.png index c010082..9aec71c 100644 Binary files a/docs/images/multiple_plots.png and b/docs/images/multiple_plots.png differ diff --git a/docs/images/palette.png b/docs/images/palette.png index ad6f09f..cbc49cd 100644 Binary files a/docs/images/palette.png and b/docs/images/palette.png differ diff --git a/docs/images/plot_pv_add_trace.png b/docs/images/plot_pv_add_trace.png index 03d6d1c..d1ce912 100644 Binary files a/docs/images/plot_pv_add_trace.png and b/docs/images/plot_pv_add_trace.png differ diff --git a/docs/images/plot_pv_plotted.png b/docs/images/plot_pv_plotted.png index 53e19a6..d3e2f03 100644 Binary files a/docs/images/plot_pv_plotted.png and b/docs/images/plot_pv_plotted.png differ diff --git a/docs/images/plot_pv_search.png b/docs/images/plot_pv_search.png index 7d5cdd8..1eabed5 100644 Binary files a/docs/images/plot_pv_search.png and b/docs/images/plot_pv_search.png differ diff --git a/docs/images/post_elog.png b/docs/images/post_elog.png index 1edbc0e..7b98590 100644 Binary files a/docs/images/post_elog.png and b/docs/images/post_elog.png differ diff --git a/docs/images/read_values.png b/docs/images/read_values.png index cdab175..d286aee 100644 Binary files a/docs/images/read_values.png and b/docs/images/read_values.png differ diff --git a/docs/images/time_range.png b/docs/images/time_range.png index f1de961..81f3767 100644 Binary files a/docs/images/time_range.png and b/docs/images/time_range.png differ diff --git a/docs/images/trace_style.png b/docs/images/trace_style.png index f22e72e..c424213 100644 Binary files a/docs/images/trace_style.png and b/docs/images/trace_style.png differ diff --git a/docs/images/trace_window.png b/docs/images/trace_window.png index 6a8b04b..fdd8b1f 100644 Binary files a/docs/images/trace_window.png and b/docs/images/trace_window.png differ diff --git a/docs/index.md b/docs/index.md index e67fba6..53297ff 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,13 +12,36 @@ This guide is intended for: Open Trace in a web browser. No installation is needed. -Trace remembers your light/dark mode and color palette choices in the browser. To keep a set of plots, save it as a workspace (see [Save and Open Workspaces](users/user_guide.md#save-and-open-workspaces)). +Trace remembers your light/dark mode in the browser. To keep a set of plots, save it as a workspace (see [Save and Open Workspaces](users/user_guide.md#save-and-open-workspaces)). + +## Tools + +Trace comes as three tools that share one layout: a canvas, an actions bar +above it and a properties panel beside it. + +- **Trace**: PVs over time, from the archiver and live. +- **Correlation**: one PV against others, as a scatter or a density plot. +- **Waveform**: array PVs drawn element by element, live. + +These pages describe them: + +- [The properties panel](workbench.md): signals and cards, the plot-wide + sections, the modified dot and reset, More, the chart source, collapsing + and resizing, and where the actions are. +- [Waveform](waveform.md): its lists, Snapshot → reference, Δ, persistence + and averaging, the X-axis PV rule and what its statistics compute over. +- [Correlation](correlation.md): its built-in metrics, variables and units. +- [Statistics](statistics.md): the panel every tool docks under its chart, + the Metrics list, writing your own metric, the function reference and the + URL grammar. +- [Drawing tools](drawing-tools.md): time and axis gestures, range controls, + drawing and measuring on a plot, keys, and how drawings are saved. ## Support and Contact Information ### Feedback/Issue Reporting -Users can submit feedback or report issues by clicking the bug icon in Trace's header. +Users can submit feedback or report issues by clicking the bug icon in Trace's actions bar. Please include as much detail as possible, such as: diff --git a/docs/site-defaults.md b/docs/site-defaults.md new file mode 100644 index 0000000..3157d01 --- /dev/null +++ b/docs/site-defaults.md @@ -0,0 +1,179 @@ +--- +icon: lucide/settings +--- + +# Site defaults + +Many of Trace's behavior choices are only "which default ships": what the +wheel zooms, whether a new plot shows the crosshair, what the header says. A +deployment sets its own defaults without rebuilding or forking, for all three +tools (Trace, Correlation and Waveform) at once. + +## Where they come from + +Each page reads its defaults once, when it loads, from these sources. A later +source wins, key by key: + +1. **Built-in defaults**: the values the product ships. +2. **`config.json` next to the app**: one file for all three pages, with a + section per tool. It is read relative to the page, so it works under any + base path. +3. **Canopy's site settings**: the document at + `GET /magpie/v1/settings/trace`, with the same shape as + `config.json`. An administrator can change it at runtime, so it wins over + the file. While it is unset, Canopy answers 404. +4. **The user's own choices**: their palette pick, their theme, and any + setting they changed on a plot. +5. **What a file, link or host query says.** + +`config.example.json` in the repository lists every key at its built-in value. +Copy only the keys you want to change into your `config.json`; a key you leave +out keeps following the built-in default when that changes in a later version. + +The file is served to every browser: never put a secret in it. + +### Loading + +Both sources are fetched in parallel before the first render, each for at most +1.5 s: + +- A missing file, or one that is not valid JSON, means the built-ins (an + invalid file logs one warning). +- If Canopy is down, slow or answers 404, the page starts with the file's + values. +- An answer that arrives after the timeout is ignored until the next page load, + so defaults never change under a user mid-session. +- A single bad value is dropped with one console warning per source naming + every dropped key. Values are checked like the tool's own fields: a site + cannot set anything a user could not. Keys starting with `$` (such as + `$comment`) are notes and are ignored. +- A `version` other than `1` makes the page ignore that source. + +## What they change, and what they never change + +Site defaults apply in two places: + +- **Where a tool creates something**: Add plot, a new curve or formula, a + fresh tab, a fresh Correlation or Waveform view. +- **App-level behavior**: the mouse gestures, where the read-out sits, and the + header with its links. + +They never change what a saved file, a stored view or a link with settings +means. A Trace link with a `plot=` key, a `.trc.json` file or a config-store +view reads any key it leaves out at the product's fixed baseline. So does a +Correlation or Waveform link with any setting beyond its PVs. A new plot whose +values differ from that baseline writes them into its links and files, so they +open the same everywhere. + +A link that names only PVs (and, for Trace, a range; for Correlation, a lookback), such as "Open in Trace" +from another tool, carries no settings. It opens as a new plot or view, with +this site's defaults. If a plot's or view's settings are all back at the +baseline while this site's new ones differ from it, its links carry a marker +(an empty `plot={"v":1}` in Trace, `rail=1` in Waveform), so they still reopen +at the baseline values. Correlation's links always state their settings. + +## Keys + +### `header` + +Trace's heading when it runs standalone (embedded, the host's tile bar names +the tool), and the links in every tool's help menu. + +| Key | Built in | Meaning | +| -------------- | ------------------------------ | ------------------------------------------------------------------------------- | +| `prefix` | `""` | Text before the product name, at most 40 characters. | +| `brand` | `false` | The prefix and name in the shell's brand color, as canopy-shell's `brandColor`. | +| `bugReportUrl` | the build's, else this project | The bug-report link (http or https). Overrides `VITE_BUG_REPORT_URL`. | +| `docsUrl` | the build's, else this project | The documentation link (http or https). Overrides `VITE_DOCS_URL`. | + +### `plot`: the mouse and the read-out + +These apply to all three tools. Each tool's own `plot` section (`trace.plot`, +`correlation.plot`, `waveform.plot`) can override any of them. + +| Key | Values | Built in | Meaning | +| ------------- | ------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `wheel` | `xy`, `x` | Trace `x`; Correlation, Waveform `xy` | `xy`: the wheel over the plot zooms X and every Y axis, and Alt+wheel the first Y axis alone. `x`: the wheel zooms X (time, in Trace) only, and Alt+wheel zooms X and every Y. Auto-scaled Y axes stay auto-scaled. | +| `yAxisDrag` | `stretch`, `pan` | Trace `pan`; Correlation, Waveform `stretch` | What dragging a Y axis does. Shift+drag or Alt+drag does the other. | +| `doubleClick` | `reset`, `none` | `reset` | `reset`: a double-click in the plot resets every axis (Y axes to auto-scale; in Trace, time back to the range the plot was set to, such as Last 1 h). `none`: it does nothing. A double-click on an axis always resets that axis. | +| `tooltip` | `docked`, `cursor` | Trace `cursor`; Correlation, Waveform `docked` | Where the data read-out sits: docked in a corner of the plot, or following the cursor. In Trace it is whether a new plot's **Dock data tooltip** (Display) is on; Correlation and Waveform have no such setting. | + +Over an axis, the wheel always zooms that axis alone, and Shift+wheel pans X. + +### `trace.plot`: a new Trace plot + +Used for Add plot, a fresh tab, and a link or host query without `plot=`. +Takes the `plot` keys above as well. + +| Key | Built in | Meaning | +| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `showCrosshair` | `true` | Crosshair. | +| `dragMode` | `zoom` | A left-drag in the plot: `zoom` (a zoom box) or `pan`. | +| `showLegend` | `true` | Legend. | +| `showXGridlines`, `showYGridlines` | `true` | Gridlines. | +| `gridStyle` | `solid` | `solid`, `dashed` or `dotted`. | +| `gridOpacity` | `1` | 0 to 1. | +| `tickFontSize` | `11` | 6 to 48 px. | +| `refreshIntervalS` | `5` | 1 to 60 s. | +| `palette` | `default` | A palette id. A user's own palette pick wins. | +| `timeRange` | `-1h` | A relative range (`-30m`, `-1h`, `-1d`). A link's `range` wins. | +| `archiver` | `null` | The plot's default archiver; `null` is Canopy's default. Only the name's form is checked: a name Canopy does not know leaves every new plot showing "No archiver". | +| `showDrawingTools` | `true` | The drawing rail. | + +### `trace.trace`: a new Trace curve + +| Key | Built in | Meaning | +| ------------ | -------- | ------------------------------------------------- | +| `lineWidth` | `2` | 0.5 to 20 px; formulas too. | +| `lineType` | `step` | `step` or `direct`; formulas are always `direct`. | +| `showSymbol` | `false` | Markers at the samples; formulas too. | + +Live retention is not a site default: it follows the plot's span (at most +30 min) unless a user pins it on a curve. + +### `correlation`: a fresh Correlation view + +Used when the page opens with no state beyond its PVs (`x`, `y`, `trig`) and a `lookback`, as another tool's Open in Correlation writes; a `lookback` it carries wins over the site's. + +| Key | Built in | Meaning | +| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `lookback` | `1h` | 1m to 24h. | +| `dt` | `1` | The Timer trigger's period in seconds, at least 0.1; also where switching back to Timer starts. | +| `metrics` | the [defaults](correlation.md#statistics) | The statistics columns, in order, as the link's `m=` tokens (`-` first: listed but not a column). | +| `drawingTools` | `true` | The drawing rail. | + +### `waveform`: a fresh Waveform view + +Used when the page opens with no state beyond its PVs (`pv`, `ref`, `xs`). + +| Key | Built in | Meaning | +| -------------- | ------------ | -------------------------------------------------------------- | +| `rollS` | `60` | The Rolling mean window, 1 to 3600 s, when a user turns it on. | +| `metrics` | the defaults | As in Correlation. | +| `drawingTools` | `true` | The drawing rail. | + +## Modified dots and Reset + +For the keys a site sets, a field's modified dot compares against the site's +value, and its reset writes the site's value back: Refresh interval, Default +archiver, Mouse drag, Dock data tooltip, Drawing tools and Palette in Trace. Reset metrics in +Correlation and Waveform returns to the site's metric list. + +## Deploying + +**Container image.** The image ships a neutral `config.json` (no settings) +at `/usr/share/nginx/html/config.json`. Mount your own over it: + +```bash +docker run ... -v ./config.json:/usr/share/nginx/html/config.json:ro +``` + +The file is served with `Cache-Control: no-cache`, so an edit takes effect on +each user's next page load. + +**Desktop app.** The bundle serves the `dist/config.json` it was built with. +Edit `public/config.json` before building. This is not `src-tauri/config.json`, +which holds the Canopy URL and keys and is never served to the page. + +**Development.** `pnpm dev` serves `public/config.json`. Edit it and reload +the page. diff --git a/docs/statistics.md b/docs/statistics.md new file mode 100644 index 0000000..6c2fc3d --- /dev/null +++ b/docs/statistics.md @@ -0,0 +1,206 @@ +--- +icon: lucide/sigma +--- + +# Statistics + +Every tool — Trace, Correlation and Waveform — shows statistics the same way. +The chart fills the canvas and the statistics are **off** by default. Turn +them on and a panel docks under the chart: a **readout table** first, one row +per curve and one column per metric, the **distribution** of each curve when +you ask for it, and **strip charts** below, one per metric you asked for, +plotting that metric over time. The panel takes what it needs up to about +half the canvas and scrolls inside; the chart shrinks to the rest. + +The settings are in the **Statistics** section of the properties panel. In +Trace each plot has its own. + +- **Show statistics** shows or hides the whole panel. +- **Show distribution** (while statistics are shown) adds one small chart per + curve: its values over the tool's frame as a **probability density** — the + area under each is one, so a curve of 50 samples and one of 5000 sit on one + scale — with the mean (dashed) and mean ± σ (dotted) as guides, and n, mean + and σ in the title. Bins follow the Freedman–Diaconis rule, 8 to 64 of them. + The values are the row's `y`: the view window in Trace, the points on + screen in Correlation, the elements in range (Δ when Δ is on) in Waveform. +- **Metrics** is the list of metrics. Each row has a checkbox, the metric's + name over its formula, a strip-chart button and an edit chevron. + - The **checkbox** makes the metric a column of the table. + - The **strip-chart button** draws the metric as a strip chart. A metric + can be a strip without being a column. + - The **chevron** opens the row. A built-in metric shows its formula, + _Move up_ / _Move down_ and _Delete_. Your own metric has _Label_, + _Expression_, _Unit_, _Move up_ / _Move down_ and _Delete_. + - Deleting a built-in metric removes it from the list. **Reset metrics** + brings it back. + - The list order is the column order. + - **Add metric** appends a new metric, "Metric 1", and opens it with the + cursor in _Expression_. +- **Reset metrics**, below the list, puts the list back to the default, + including any built-in metric you deleted. It is disabled while the list + already is the default. + +A strip chart keeps a history of every metric, even one that is not drawn, +so turning a strip on shows its past points at once. _Clear_ (Correlation) +empties the history; it is never saved. + +## What each tool computes over + +| Tool | A row is | The values are | Variables | +| ----------- | ----------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| Trace | a curve of the plot (hidden ones are not shown) | its samples inside the view window (the panned window, else the time range) | `y`, `t` (s to the window end, ≤ 0), `y1…yN`, `n` | +| Correlation | a Y PV | the points on screen where X and that Y are both valid | `x`, `y`, `y1…y8`, `t` (s to the newest row), `n` | +| Waveform | a drawn live curve | its elements in the element range, after Δ when Δ is on | `y`, `i` (element index), `x` (X axis PV), `r`, `s`, `d` (reference, its σ, raw − reference), `y1…y8`, `n` | + +`y1`, `y2`… name another row by its position in the tool's **Signals** list +(hidden or undrawn entries count), so a +metric can compare curves: `mean(y) - mean(y1)`. In Correlation every row +shares the same points, so `y - y1` is a vector like any other. In Trace each +curve is sampled at its own times, so a referenced curve is first held onto +this curve's sample times (its last value at or before each one): `y - y1` +then compares the two at the same instants. In Waveform curves may differ in +length: mix them element-wise only at equal lengths (`y - y1`, `corr(y, y1)`); +an element-wise mix of unequal lengths is undefined and shows "–". + +### Built-in metrics + +**Trace** (on by default in bold): **n · mean · std · min · max**, then last, +first, p-p, rms, median and slope (`slope(t, y)`, in the axis unit per +second). + +**Correlation**: **n · mean · std · r · slope**, then R², intercept, min, +max, p2p, rms, X mean and X std. X statistics are metrics too, so the table +has rows for the Ys only. The r strip is fixed to −1 … 1 and the R² strip +to 0 … 1. + +**Waveform**: **n · mean · std · rms · p-p**, then min, max, median, _peak +at_ (`at(i, argmax(y))`, the element index of the largest value), _trough +at_, and against the reference _dev rms_ (`rms(d)`), _dev max_ +(`max(abs(d))`), _dev σ_ (`max(abs(d) / s)`) and _worst at_ (`at(i, +argmax(abs(d) / s))`); the last four read "–" without a reference (or, for +the σ ones, without a rolling mean or a snapshot frozen from one). + +## Writing a metric + +Open a metric you added and type its **Expression**. The expression is +checked as you type. A mistake is shown under the field and on the row, but +the expression is still kept, and the table shows "–" for it until it works. + +**Rows used.** An expression uses only the points where every variable it +mentions has a finite value. `n` is the number of those points. + +**Vectors and scalars.** The column variables (`y`, `x`, `t`, `i`, `y1`…) +are vectors, one value per point. Arithmetic (`+ - * / ^`) works point by +point, and a scalar combines with every point: `y - mean(y)` subtracts the +mean from each point. Aggregates such as `mean`, `std` or `corr` reduce a +vector to one number. The whole expression must end in one number. An +expression that is still a vector, such as `y * 2`, is an error. + +**Undefined values** show as "–", never as 0. For example, std needs two +points, r needs three points and spread in both, and slope needs spread in +its first argument. + +**Unit** picks the unit shown after the value. The choices depend on the +tool: the curve's axis unit (and per second) in Trace; the Y's unit, the X's +unit or Y per X in Correlation; the axis unit or the X axis PV's unit in +Waveform. + +**Examples.** + +| Purpose | Expression | Where | +| ------------------------ | -------------------- | ----------- | +| Noise around the mean | `std(y - mean(y))` | any | +| Drift per second | `slope(t, y)` | Trace, Corr | +| Largest excursion | `max(abs(y))` | any | +| Difference of two curves | `mean(y) - mean(y1)` | any | +| Ratio of means | `mean(y) / mean(x)` | Correlation | +| Correlation of two Ys | `corr(y1, y2)` | Correlation | +| Element of the peak | `at(i, argmax(y))` | Waveform | +| Value at a given element | `at(y, 100)` | Waveform | +| Largest deviation, in σ | `max(abs(d) / s)` | Waveform | +| Mean offset from the ref | `mean(d)` | Waveform | + +## Function reference + +Element-wise functions return a vector for a vector argument. Aggregates +return one number. Standard deviation, variance and covariance are sample +statistics (divided by n − 1). + +| Function | What it returns | +| ------------------------- | ---------------------------------------------------------- | +| `abs(v)` | Absolute value, element-wise. | +| `sqrt(v)` | Square root, element-wise. | +| `exp(v)` | e raised to v, element-wise. | +| `ln(v)` | Natural logarithm, element-wise. | +| `log10(v)` | Base-10 logarithm, element-wise. | +| `log2(v)` | Base-2 logarithm, element-wise. | +| `sin(v)` | Sine of radians, element-wise. | +| `cos(v)` | Cosine of radians, element-wise. | +| `tan(v)` | Tangent of radians, element-wise. | +| `floor(v)` | Round down, element-wise. | +| `ceil(v)` | Round up, element-wise. | +| `round(v)` | Round to nearest, halves away from zero, element-wise. | +| `sign(v)` | −1, 0 or 1 by sign, element-wise. | +| `pow(a, b)` | a raised to b, element-wise; same as `a ^ b`. | +| `count(v)` | Number of values. | +| `sum(v)` | Sum of the values. | +| `mean(v)` | Arithmetic mean (needs 1 value). | +| `median(v)` | Middle value; mean of the two middle ones for even counts. | +| `std(v)` | Sample standard deviation, ddof = 1 (needs 2 values). | +| `var(v)` | Sample variance, ddof = 1 (needs 2 values). | +| `rms(v)` | Root mean square, sqrt(mean(v²)); not centered. | +| `ptp(v)` | Peak to peak: max(v) − min(v). | +| `first(v)` | The oldest value. | +| `last(v)` | The newest value. | +| `argmin(v)` | 0-based position of the smallest value. | +| `argmax(v)` | 0-based position of the largest value. | +| `min(v)` · `min(a, b, …)` | Smallest value; with several arguments, element-wise. | +| `max(v)` · `max(a, b, …)` | Largest value; with several arguments, element-wise. | +| `percentile(v, p)` | p-th percentile, p in 0..100, linear interpolation. | +| `at(v, k)` | The k-th value of v (0-based), e.g. `at(i, argmax(y))`. | +| `corr(a, b)` | Pearson r (needs 3 rows and spread in both). | +| `cov(a, b)` | Sample covariance, ddof = 1 (needs 2 rows). | +| `slope(a, b)` | Least-squares slope of b against a (needs spread in a). | +| `intercept(a, b)` | Least-squares intercept of b against a. | +| `r2(a, b)` | Coefficient of determination, corr(a, b)². | + +The same list is in the editor, under **Expression reference** below the +Metrics list. + +## In the URL + +The metric list is saved as **tokens**, one per metric in column order, and +only when the list differs from the default. When any token is present, the +list is exactly those metrics. + +```text +token = flags body +flags = [ "-" ] [ "~" ] "-": not a table column, "~": a strip chart +body = preset-id | custom +custom = label "=" expr [ "=" unit ] unit: a kind the tool knows +``` + +- **Correlation** and **Waveform** write repeated `m=` keys, the toggle as + `readout=1` (Correlation) or `stats=1` (Waveform), and the distribution as + `dist=1`. For example, + `m=n&m=mean&m=~std&m=-r&m=Noise=std(y-mean(y))=y` shows n, mean, std and + Noise as columns, draws std as a strip, and keeps r in the list but off. + Tokens are URL-encoded: in a hand-written link, write `+` as `%2B`, since + a bare `+` in a query means a space. +- **Trace** carries them inside the plot's `plot=` JSON as `"showStats": +true`, `"showDist": true` and `"metrics": ["n", "~mean", …]`, and in saved + workspaces as the plot's `showStats`, `showDist` and `metrics` fields. + +**An empty list** (every metric deleted) has no token to write: Correlation +and Waveform reopen it at the default, Trace keeps it in its plot config. + +**Limits.** A label is at most 32 characters and an expression at most 160; +neither may contain `=`. The list holds at most 16 metrics in all, built-in +or your own. Delete built-in metrics you do not need to make room for more of +your own. A token that cannot be read, such as an unknown built-in id, is +dropped. An expression with a mistake is kept. + +When a URL grows past its 4 KB budget, Correlation drops the `m=` keys after +the labels, colors, markers and hidden list and before any Y; Waveform +drops them with the curve styles; Trace drops them with the rest of the +plot config. The metrics then reopen at the default. diff --git a/docs/users/user_guide.md b/docs/users/user_guide.md index a9c493e..cef63fb 100644 --- a/docs/users/user_guide.md +++ b/docs/users/user_guide.md @@ -4,46 +4,47 @@ ## The Trace Window -The Trace window has four areas: +The Trace window has three areas: -- **① Header** — the toolbar for saving, exporting, printing, and other actions. The counter next to **SLAC Trace** shows how many traces on the current plot use live and archive data. -- **② Layers** — the plot's axes and the traces on each axis. Click an item to edit it. -- **③ Plot area** — the plot itself, with plot tabs and view controls above it. -- **④ Properties** — settings for whatever is selected in **Layers**: the plot, an axis, or a trace. +- **① Actions bar** — searching for PVs, saving, exporting, printing, and other actions. It starts with Trace's name and a counter, such as **2 Live • 3 Archive**, of how many traces on the active plot use live and archive data. A trace that uses both counts in each. +- **② Properties panel** — the plot's traces, grouped by Y-axis, and the plot-wide sections **Acquisition**, **Axes**, **Display**, and **Statistics**. See [The properties panel](../workbench.md). +- **③ Plot area** — the plot itself, with plot tabs, range controls, and view controls above it and the drawing tools beside it.
The Trace window
+When Trace is embedded in another page, the counter is shown without the name, since the page around it already names the tool. + ### Resize and Collapse Panels -Drag the border between two panels to resize them. Click the chevron in the **Layers** or **Properties** header to collapse that panel to a thin strip, and click the strip to open it again. Useful when you want more room for the plot. +Drag the separator between the properties panel and the plot to resize the panel, or collapse it with the button in its header when you want more room for the plot. See [Collapsing and resizing](../workbench.md#collapsing-and-resizing). --- ## Plot a PV -Every plot starts with one empty Y-axis. To plot a process variable (PV), add a trace to an axis and choose the PV it should follow. New traces show both archived and live data, so the plot fills the whole time range and keeps updating. +Every plot starts with one empty Y-axis. To plot a process variable (PV), add it to an axis's list in the properties panel. New traces show both archived and live data, so the plot fills the whole time range and keeps updating. **Workflow:** -1. In the **Layers** panel on the left, click **Add Trace** under the axis you want to use (①). The new trace is selected, and its settings open in the **Properties** panel on the right. -2. Click the **PV Name** field and type part of the PV name (②). Matching PVs from the archiver appear in a list as you type. +1. Click the **Add PV** field under the axis you want to use (①). +2. Type part of the PV name (②). Matching PVs from the archiver appear in a list as you type. 3. Click the PV you want (③), or press **Enter** to use exactly what you typed.
- Add Trace button in the Layers panel + Add PV field in the properties panel
- Searching for a PV in the PV Name field + Searching for a PV in the Add PV field
Once you choose a PV, the trace starts drawing: -- **④ Layers** — the trace is listed under its axis, with icons showing that live and archive data are on. Click the row any time to edit the trace again. -- **⑤ Units axis** — the trace moves to an axis named after the PV's units (here **mJ**). See [Axes and Units](#axes-and-units). -- **⑥ Status** — the bottom of the **Data Sources** section shows **Live Status** and **Archive Status**. Useful when a trace isn't drawing and you want to know why. +- **④ Card** — the trace's card in the list of its axis. Click it any time to open its settings in place; see [Signals and cards](../workbench.md#signals-and-cards). +- **⑤ Units axis** — the trace moves to an axis named after the PV's units (here **mm**). See [Axes and Units](#axes-and-units). +- **⑥ Status** — the status lines at the end of the card's **Data** block, among them **Live status** and **Archive status**. Useful when a trace isn't drawing and you want to know why; see [When a Trace Doesn't Draw](#when-a-trace-doesnt-draw).
A PV plotted with live and archive data @@ -51,67 +52,99 @@ Once you choose a PV, the trace starts drawing: ### Add Several PVs at Once -To add many PVs in one go, click the **Search PVs** icon in the header, or the **Search PVs** button below a plot's axes in the **Layers** panel. +To add many PVs in one go, click **Search PVs**, the first icon in the actions bar, or the search button next to any **Add PV** field. Both open the **Search PVs** dialog for the active plot. -1. Type part of a PV name in **Pattern**. Matches from the archiver appear as you type. `*` matches any run of characters and `?` matches one, so `KLYS:LI2*:PDES` finds every PV that starts with `KLYS:LI2` and ends with `:PDES`. +1. Type part of a PV name in **Pattern**. Matches from the plot's archiver appear as you type. `*` matches any run of characters and `?` matches one, so `SIM:BPM*:X` finds every PV that starts with `SIM:BPM` and ends with `:X`. 2. Tick the PVs you want, or use **Select all** at the top of the list. Matches are listed alphabetically. Ticks are kept when you change the pattern, so you can gather PVs from several searches; the **Selected** row shows them and lets you remove one or clear them all. 3. Click **Add N PVs**. Double-clicking a match adds it straight away, together with anything already selected. -The new traces appear under the plot's first axis and move to their units axes as the lookups finish (see [Axes and Units](#axes-and-units)). PVs that are already on the plot are marked **on plot**; you can still add them again. The dialog lists at most 500 matches, so narrow the pattern if the PV you want isn't shown. With more than one plot open, the dialog starts on the current plot and **Add to plot** lets you pick another. +The new traces appear under the plot's first axis and move to their units axes as the lookups finish (see [Axes and Units](#axes-and-units)). The last one added is selected, so its card opens. PVs that are already on the plot are marked **on plot**; you can still add them again. The dialog lists at most 500 matches; when there are more, it says **Showing the first 500 matches**, so narrow the pattern if the PV you want isn't shown. -### Axes and Units +With more than one plot open, the dialog starts on the current plot and **Add to plot** lets you pick another. The search uses that plot's **Default archiver**, and if you pick a plot with a different archiver, your ticks are cleared. After adding, Trace switches to that plot. -When you choose a PV, Trace looks up its engineering units and moves the trace to the axis with the same units. If there isn't one, Trace creates a new axis named after the units, alternating between the left and right sides of the plot. Traces with the same units share an axis, so they are easy to compare. +### Axes and Units -You can always move a trace yourself: pick a different axis from the **Y-Axis** dropdown, or drag the trace onto another axis in the **Layers** panel. The original **Y-Axis 1** stays even when it is empty; click its trash icon to remove it if you don't need it. +When you add a PV, Trace looks up its engineering units and moves the trace to the axis with the same units. If there isn't one, Trace creates a new axis named after the units, alternating between the left and right sides of the plot. Traces with the same units share an axis, so they are easy to compare. -_Note: A newly created axis currently starts collapsed in the **Layers** panel. Click the chevron next to the axis name to see its traces._ +You can always move a trace yourself: pick a different axis under **Plot on** in its card, or drag the card onto another axis's list. The original **Y-Axis 1** stays even when it is empty; click **Remove axis** in its block under **Axes** if you don't need it. ### Live and Archive Data **Data sources:** -- **Live Data** — streams new values as they arrive. **Live retention (s)** sets how much live history is kept (default 300 seconds). -- **Archive Data** — loads the plot's time range from the archiver. For ranges longer than 30 minutes, the archiver returns averaged bins, and Trace draws a shaded min/max band behind the line. Turn the band off with **Show min/max band**. +- **Live** — streams new values as they arrive. **Live retention** sets how much live history is kept; left empty, it follows the time range. +- **Archive** — loads the plot's time range from the archiver. For ranges longer than 30 minutes, the archiver returns averaged bins, and Trace draws a shaded min/max band behind the line. Turn the band off with **Min/max band**. -With both on, archive data covers the past and live data takes over from the last archived sample. Each trace uses the plot's **Default Archiver** unless you choose a different one under **Archiver**. +Both switches are in the card's **Data** block; the other settings are under its **More**. With both on, archive data covers the past and live data takes over from the last archived sample. Each trace uses the plot's **Default archiver** (in **Acquisition**) unless you choose a different one under **Archiver**. ### When a Trace Doesn't Draw -Check the status lines at the bottom of **Data Sources**, or the label next to the trace in the **Layers** panel. Hover over a label to see the full error. +Check the status lines at the end of the card's **Data** block. Each line shows only when it applies: + +- **Data points** — how many samples the trace holds: the archive's while **Archive** is on, otherwise the live data's. +- **Live status** — **Connecting…**, **Connected**, **Waiting for value**, **Disconnected**, or **Disabled**. +- **Severity** — the PV's alarm severity, while it is connected. +- **Live error** — the live connection's error message. +- **Archive status** — **Idle**, **Loading…**, **Loaded (raw)** or **Loaded (binned)** (with **· decimated** when the archiver thinned out the samples), **Disabled**, or the name of an archive error. +- **Source** — the archiver that answered. +- **Archive error** — the full message of an archive error. + +The dot at the left of the card shows problems too. Hover over it to see the full message for each source that failed, live and archive. + +- **Disconnected** (Live status) — the live connection dropped. Trace reconnects on its own; see [Live Outages](#live-outages). +- **Waiting for value** (Live status) — connected, but no value has arrived for this PV yet. +- **Archiver down** — the archiver isn't responding. +- **Timeout** — the archiver took too long to answer. +- **Bad response** — the archiver's answer couldn't be read. +- **Auth error** — Trace isn't allowed to read the archive. +- **Offline** — the network between Trace and the archiver is down. +- **Not archived** — the archiver has no PV with that name. Check the spelling in **PV name**, or choose another archiver. +- **No archiver** — no archiver is configured for this PV. Choose one in the plot's **Default archiver** setting or the trace's **Archiver** setting. +- Any other archive error shows its error code. -- **Disconnected** (Live Status) — the live connection dropped. Trace reconnects on its own. -- **Waiting for value** (Live Status) — connected, but no value has arrived for this PV yet. -- **Unknown PV** — the archiver has no PV with that name. Check the spelling in **PV Name**. -- **No archiver** — no archiver is set for this plot. Choose one in the plot's **Default Archiver** setting or the trace's **Archiver** setting. -- **Archiver down**, **Timeout**, or **Offline** — the archiver or network isn't responding. Click the refresh icon in the header to try again. +Trace retries most archive errors by itself, waiting a little longer after each try. Two are different: + +- **Not archived** is asked again when the length of the time range changes (a new range, or a zoom) or when you choose another archiver. +- **No archiver** isn't retried by itself; choosing another archiver asks again. + +Click the refresh icon (**Refresh archive data**) in the actions bar to ask the archiver again for every trace, whatever its error. + +### Live Outages + +When the live connection drops, the line holds its last value up to the moment of the disconnect, then leaves a gap. When the PV reconnects, the line picks up again from that moment with the new value. + +If only Trace's connection to the server dropped, and the server's live buffer kept recording the PV in the meantime, Trace fills the gap from that buffer once it answers. A gap where the PV itself disconnected stays. --- ## Set the Time Range -Each plot has its own time range. Select **Plot Settings** in the **Layers** panel, then scroll to **X-Axis (Time)** in the **Properties** panel. +Each plot has its own time range. Open **Axes** in the properties panel; the time settings are under **X axis**. **Time settings:** -- **① Time Range** — choose a preset from **Last 1 Hour** to **Last 1 Month**, or **Custom Range...** for fixed start and end times. -- **② Span** — type any length of time, such as `90m`, `1.5h`, or `2w`, and press **Enter**. Units are `m` (minutes), `h` (hours), `d` (days), `w` (weeks), and `M` (months). +- **① Time range** — choose a preset from **Last 30 Seconds** to **Last 1 Month**, or **Custom Range...** for fixed start and end times. +- **② Span** — type any length of time, such as `30s`, `90m`, `1.5h`, or `2w`, and press **Enter**. Units are `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), and `M` (months). - **③ Autoscroll (track now)** — keeps the current time at the right edge of the plot. -- **④ Refresh interval (s)** — how often, from 1 to 60 seconds, the plot moves forward while autoscroll is on. + +**Refresh interval**, in **Acquisition**, sets how often, from 1 to 60 seconds, archive and formula data refresh while autoscroll is on. The buttons above the plot (**1h**, **6h**, **24h**, **All**, **Now**) and its date field change the range in one click; see [Moving through time](../drawing-tools.md#navigation).
- X-Axis (Time) settings + X axis time settings
### Custom Range -Choose **Custom Range...**, then set **From** and **To**. Leave **To** blank to end the range at the current time. If the range isn't valid (for example, **From** is after **To**), an error appears below the fields and the plot shows the last hour instead. +Choose **Custom Range...**, then set **From** and **To (blank = now)**. Leave **To** blank to end the range at the current time. If the range isn't valid (for example, **From** is after **To**), an error appears below the fields and the plot shows the last hour instead. ### Returning to the Full Range -Autoscroll turns off by itself when you zoom or pan the plot. To return to the full time range and follow the current time again, choose a different **Time Range** or enter a different **Span**. To keep the same range, choose another one and then switch back. +Zooming or panning the plot stops it from following the current time and turns **Autoscroll** off. Any of these returns to the full time range and follows the current time again: -_Note: Switching **Autoscroll** back on, or re-entering the same **Span**, does not undo a zoom or pan. Change the range as described above._ +- Turn **Autoscroll** back on. +- Click **1h**, **6h**, or **24h** above the plot, even the one that is already selected. +- Click in **Span** and press **Enter**, even without changing it. Leaving the field without pressing **Enter** keeps the zoom. +- Click **Now** above the plot to use the last span you used, or choose a different **Time range** or **Span**. --- @@ -119,20 +152,21 @@ _Note: Switching **Autoscroll** back on, or re-entering the same **Span**, does **Mouse controls:** -- **Scroll inside the plot** — zoom the time axis in or out. -- **Drag inside the plot** — move along the time axis. +- **Scroll inside the plot** — zoom time around the pointer; auto-scaled Y-axes refit. **Alt** + scroll zooms the Y-axes too; **Shift** + scroll moves along the time axis. +- **Drag inside the plot** — draw a zoom box; the plot zooms to it when you let go. Click the **Zoom box** button on the drawing rail to switch to panning along the time axis instead (with the rail hidden, set **Mouse drag** in **Display** to **Pan**). - **Scroll over a Y-axis** (②) — zoom only that axis, around the mouse pointer. -- **Drag up or down on a Y-axis** — move only that axis. +- **Drag up or down on a Y-axis** — move only that axis. **Shift** + drag zooms it in or out instead. +- **Double-click inside the plot** — go back to the plot's time range (for example the last hour) and auto-scale every Y-axis. -Zooming or panning time turns off autoscroll (see [Returning to the Full Range](#returning-to-the-full-range)). Zooming or panning a Y-axis switches it from **Auto Scale** to fixed limits; turn **Auto Scale** back on in the axis settings to undo it. +See [Moving through time](../drawing-tools.md#navigation) and [Scaling the Y axes](../drawing-tools.md#axes) for every gesture. Zooming or panning time stops following the current time (see [Returning to the Full Range](#returning-to-the-full-range)). Zooming or moving a Y-axis switches it from **Auto-scale** to fixed limits; double-click the axis to undo it. -Move the mouse over the plot to see a tooltip (①) with each trace's value at that time. Each value is the sample nearest the pointer, and the time in parentheses shows how far that sample is from the pointer (for example **+2s**). Turn **Show Crosshair** off in **Plot Settings** to hide the dashed crosshair lines; the tooltip still appears. +Move the mouse over the plot to see the data tooltip (①) with each trace's value at that time. Each value is the sample nearest the pointer, and the time in parentheses shows how far that sample is from the pointer (for example **+2s**). The tooltip follows the pointer; turn **Dock data tooltip** on in **Display** to keep it in a corner of the plot instead, where its grip moves it. Crosshair lines are on in a new plot; turn **Crosshair** off in **Display** to hide them, or click **Data tooltip** on the drawing rail to hide the tooltip.
- Tooltip and Y-axis zoom area + Data tooltip and Y-axis zoom area
-The legend below the plot lists the visible traces. Clicking it doesn't hide a trace; use the **Visible** switch in the trace's settings instead. +The legend below the plot lists the visible traces. Clicking it doesn't hide a trace; use the eye on the trace's card instead, or right-click the entry for the trace's menu (see [Right-click menus](../workbench.md#right-click)). --- @@ -142,16 +176,17 @@ A plot can have several Y-axes, each with its own scale, on the left or right si **Workflow:** -1. In the **Layers** panel, click **Add Axis** (②) below the plot's axes. New axes alternate between the left and right sides. -2. Click the axis row (①) to open its settings in the **Properties** panel. +1. In the properties panel, click **Add axis** (②) below the lists. New axes alternate between the left and right sides. +2. Open **Axes**: each Y-axis has its own block there, headed by its name (①). **Axis settings:** -- **Label** — the axis name shown in **Layers** and along the axis. -- **Orientation** — **Left** or **Right**. +- **Label** — the axis name shown in the list and along the axis. +- **Unit** — the units shown for the axis; they start from the PV's units. +- **Side** — **Left** or **Right**. - **Visible** — show or hide the axis. Hiding an axis also hides its traces. -- **Auto Scale** (③) — fit the axis to the data. Turn it off to set **Min Value** and **Max Value** yourself; they start from the range currently shown. -- **Log Scale** (④) — switch between a linear and a logarithmic scale. +- **Auto-scale** (③) — fit the axis to the data. Turn it off to set **Min** and **Max** yourself. +- **Log scale** (④) — switch between a linear and a logarithmic scale.
Axis settings @@ -159,11 +194,11 @@ A plot can have several Y-axes, each with its own scale, on the left or right si ### Move Traces Between Axes -Drag a trace in **Layers** onto another axis, or pick an axis from **Y-Axis** in the trace's settings. In grid view, you can also drag a trace onto an axis in another plot. +Drag a trace's card onto another axis's list, pick an axis under **Plot on** in its card, or right-click the card and use **Move to axis**. ### Delete an Axis -Click the trash icon on the axis row. Its traces move to another axis on the same plot. A plot always keeps at least one axis. +Click **Remove axis** in the axis's block under **Axes**. Its traces move to another axis on the same plot. A plot always keeps at least one axis. _Note: Deleting an axis, trace, or plot happens immediately, without asking for confirmation._ @@ -171,38 +206,31 @@ _Note: Deleting an axis, trace, or plot happens immediately, without asking for ## Style Traces -Select a trace in **Layers** to change how it looks. On the **General** tab, **Display Name** sets the name used in the legend, tooltip, and **Layers** (leave it blank to use the PV name), and **Visible** shows or hides the trace. +Click a trace's card to change how it looks. In its **Signal** block, **Label** sets the name used in the legend, tooltip, and card (leave it blank to use the PV name); the eye on the card shows or hides the trace. -**Line tab:** +**Style block:** -- **① Tabs** — switch between **General**, **Line**, **Symbol**, and **Code**. If the panel is narrow, use the arrow at the end of the tab row to reach **Code**. -- **② Color** — pick a color or type a hex value. -- **Type** — **Step** (holds each value until the next sample; the default) or **Direct** (straight lines between samples). -- **Line Width** — 1 to 5. -- **③ Style** — solid, dashed, dotted, and mixed patterns, or **NoLine** to show only symbols. -- **④ Extend to current time** — draw a dashed line from the last value to the end of the time range. +- **① Color** — pick a color. +- **② Line** — **Step** (holds each value until the next sample; the default) or **Line** (straight lines between samples). +- **Width** — 0.5 to 20 px. +- **③ Dash** — solid, dashed, dotted, and mixed patterns, or **None** to show only markers. +- **④ Extend to now** — draw a dashed line from the last value to the end of the time range. +- **Alarm coloring** — tint the live curve by each sample's alarm severity.
- Line style settings + Style settings
-On the **Symbol** tab, turn on **Show Symbols** to mark each sample, then choose a **Shape** and **Size**. - -_Note: The **Code** tab is a preview of the chart settings behind the trace. Its **Apply Changes** and **Format** buttons don't do anything yet._ +Turn on **Markers** to mark each sample, then choose a **Marker** and **Marker size**. A dot next to a field means it differs from its automatic value; see [The modified dot and reset](../workbench.md#the-modified-dot-and-reset). **Show chart source**, at the bottom of the panel, shows the chart settings behind the plot. ### Color Palettes -New traces get their colors from a palette. Select **Plot Settings** and scroll to **Color Palette**: - -- **① Palette** — choose one of 13 palettes. New traces on every plot use it from then on, and Trace remembers your choice. -- **② Apply to all traces** — recolor every trace on this plot from the palette. +New traces get their colors from the plot's palette. Open **Display**, then **More**, and choose one of 13 palettes under **Palette** (①). Every trace on the plot that still has a palette color is recolored; colors you picked yourself stay.
Color palette settings
-To recolor only one axis's traces, select the axis and use **Apply to this axis** in its **Color Palette** section. Choosing a palette there doesn't change the palette for new traces. - --- ## Formulas @@ -211,10 +239,10 @@ A formula curve calculates new values from other traces, for example the ratio o **Workflow:** -1. Click **Add Formula** (①) under the axis where the result should appear. The new curve (④) is added to that axis and selected. -2. Enter a **Display Name**. -3. Type an expression in the **Formula** box (②). Refer to other traces with variables in braces, such as `{x1}` and `{x2}`. Trace checks the expression as you type and shows **Valid** or an error. -4. Under **Variables** (③), choose the trace each variable stands for. +1. Click **Add formula** below the lists. The new formula's card (③) is added to the first axis and opens; move it with **Plot on**. +2. Enter a **Label**. +3. Type an expression in the **Formula** box (①). Refer to other traces with variables in braces, such as `{x1}` and `{x2}`. Trace checks the expression as you type and shows **Valid** or an error. +4. Below the box (②), choose the trace each variable stands for. 5. The curve draws once every variable is bound.
@@ -227,7 +255,7 @@ Formula curves are recalculated whenever the plot's time range moves, including ### Create a Formula from a Trace -Select a PV trace and click **Create formula from this curve** in the **Derived** section. Trace adds a formula curve with `{x1}` already bound to that trace; edit the expression from there. The original trace is unchanged. +Click **Create formula from this curve** in a PV trace's **Data** block, or in its right-click menu. Trace adds a formula curve with `{x1}` already bound to that trace; edit the expression from there. The original trace is unchanged. _Note: Variables can refer only to PV traces on the same plot, not to other formulas._ @@ -245,10 +273,10 @@ Add more plots to view different groups of PVs side by side. Each plot has its o **Managing plots:** -- **Rename a plot** — select **Plot Settings** and edit **Title**. +- **Rename a plot** — open **Display** and edit **Title**. - **Close a plot** — click **×** on its tab, or in the corner of its grid cell. This appears only when there is more than one plot. -In grid view, the **Layers** panel lists every plot, so you can edit any of them and drag traces between plots. +The properties panel shows the active plot. In grid view, click a plot to make it active.
Grid view with four plots @@ -256,9 +284,9 @@ In grid view, the **Layers** panel lists every plot, so you can edit any of them ### Fullscreen and Separate Windows -Each plot tab and grid cell (②) has two more buttons: +Each plot tab and grid cell (②) has the plot's own buttons, among them: -- **Fullscreen** — show the plot over the whole window. Click **×** in its title bar to return (**Escape** doesn't close it). +- **Fullscreen** — show the plot over the whole window. Click **×** in its title bar, or press **Escape**, to return. - **Detach to window** — move the plot into its own browser window. Useful with a second monitor. Click **Reattach** in that window, or close it, to bring the plot back. _Note: If your browser blocks pop-up windows, the plot stays in the main window. Allow pop-ups for Trace to detach plots._ @@ -271,8 +299,8 @@ The Data Insight tool lists a PV's samples in a table. Useful when you need exac **Open it by:** -- Clicking the Data Insight icon in the header (++option+d++ on macOS, ++alt+d++ elsewhere) -- Clicking **Inspect data** at the bottom of a trace's **Data Sources** settings +- Clicking the Data Insight icon in the actions bar (++option+d++ on macOS, ++alt+d++ elsewhere) +- Clicking **Inspect data** in a trace's **Data** block, or in its right-click menu
Data Insight tool @@ -295,13 +323,23 @@ The table covers the plot's current time range and shows each sample's **Datetim A workspace stores your plots, axes, traces, styles, time ranges, and theme. It doesn't store data; Trace loads the data again when you open the workspace. -- **Save** (++cmd+s++ / ++ctrl+s++) — click the save icon in the header to download the workspace as a `.trc.json` file. +- **Save** (++cmd+s++ / ++ctrl+s++) — click the save icon in the actions bar to download the workspace as a `.trc.json` file. - **Import** (++cmd+o++ / ++ctrl+o++) — click the import icon and choose a workspace file. It replaces whatever is open. Trace can also open `.trc` files from the older PyDM-based Trace. Settings that have no equivalent are skipped, and Trace lists them in a message after importing. _Note: Importing replaces the current workspace without asking. Save first if you want to keep it._ +### The Config Store + +The config store keeps workspaces on the server, so you can open them again or share them as a link. Click the **Config store** icon, just after the save icon in the actions bar, to open it. + +- **Save** — under **Save current workspace**, enter a **Name** and, optionally, a **Description**, then click **Save & copy share link**. Trace saves the workspace and copies its link to the clipboard. If the browser doesn't allow the copy, the message shows the link so you can copy it yourself. +- **Open** — under **Saved configs**, click **Load** on a row. It replaces the open workspace without asking. +- **Manage** — **Rename** changes a config's name, the copy icon copies its share link, and the delete icon removes it after you confirm. Deleting a config breaks every link to it and can't be undone. + +A share link is Trace's address with `?config=`, where the slug is the short id shown under each config's name. Opening it loads that workspace when Trace starts. A `config` link wins over any other plot settings in the same address, such as `pv`, `range`, or `plot`; those are ignored. Afterwards, whether or not the workspace loaded, Trace removes `config` from the address bar, so reloading the page doesn't load the stored workspace over your changes. When Trace is embedded in another page, it never changes that page's address. + --- ## Export and Print @@ -316,7 +354,7 @@ Plots detached into separate windows are left out of PNG exports and printouts. ## Post to E-Log -Click the E-Log icon in the header (++cmd+e++ / ++ctrl+e++) to post the plots on screen to the E-Log. The icon appears only when Trace is connected to an E-Log. +Click the E-Log icon in the actions bar (++cmd+e++ / ++ctrl+e++) to post the plots on screen to the E-Log. The icon appears only when Trace is connected to an E-Log.
Post to E-Log dialog @@ -344,7 +382,7 @@ Click the E-Log icon in the header (++cmd+e++ / ++ctrl+e++) to post the plots on | Data Insight | ++option+d++ | ++alt+d++ | | Switch light/dark mode | ++option+t++ | ++alt+t++ | -Shortcuts don't run while you are typing in a text field. +Shortcuts don't run while you are typing in a text field. The drawing tools have their own keys; see [Keys](../drawing-tools.md#keys). --- @@ -377,9 +415,7 @@ Every icon in Trace has a tooltip that appears on hover. Here's a quick referenc Tab view iconTab view Grid view iconGrid view Add plot iconAdd a plot - Live data iconTrace uses live data - Archive data iconTrace uses archive data - Delete iconDelete the trace or axis + Delete iconRemove the trace or drawing (on its card) @@ -387,10 +423,18 @@ Every icon in Trace has a tooltip that appears on hover. Here's a quick referenc ## Dark Mode -Click the sun/moon icon in the header (++option+t++ / ++alt+t++) to switch between dark and light mode. Your choice is saved in the browser and used on future visits. Plots with the default background follow the theme; a plot with a custom **Background Color** keeps it. +Click the sun/moon icon in the actions bar (++option+t++ / ++alt+t++) to switch between dark and light mode. Your choice is saved in the browser and used on future visits. Plots with the default background follow the theme; a plot with a custom **Background color** keeps it. + +--- + +## When Part of Trace Fails + +If one part of the window runs into an error, only that part stops: the **Signals** list, the plot-wide sections, the plot area or a single plot, a fullscreen or detached plot, or Data Insight. It shows the error message with **Try again**, which redraws just that part, and **Reload**, which reloads the page. The rest of Trace keeps working, so you can still save your workspace first. Data Insight also offers **Close Data Insight**. + +The **Signals** list and the plot-wide sections also try again by themselves when you switch plots, select something else, or open a workspace. --- ## Getting Help -Click the bug icon in the header to report a problem or request a feature. See [Support and Contact Information](../index.md#support-and-contact-information) for what to include. +Click the bug icon in the actions bar to report a problem or request a feature. See [Support and Contact Information](../index.md#support-and-contact-information) for what to include. diff --git a/docs/waveform.md b/docs/waveform.md new file mode 100644 index 0000000..84cc044 --- /dev/null +++ b/docs/waveform.md @@ -0,0 +1,245 @@ +--- +icon: lucide/audio-waveform +--- + +# Waveform + +Waveform draws array PVs live, one curve per PV, with the element index (or +another PV) on the X axis. It uses the shared +[properties panel](workbench.md). + +## Lists + +The panel's top block has three lists: + +| List | Holds | Notes | +| ------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | +| **Signals** | up to 8 waveform PVs | Drawn on one Y axis; **Axes › Y axis** sets Unit, Auto-scale, Min, Max and Log scale. | +| **Reference** | one PV, a snapshot, or a rolling mean | Drawn as a dashed line or a shaded band (_Draw as_, under the Reference's cards). | +| **X axis PV** | one PV | Its values become the X axis. Its card's _Label_ titles the X axis. | + +Only waveform PVs can be added. A scalar PV is refused at the add row. + +To move a curve between lists, use its **Plot on** field or drag its card. +Moves never lose a PV. Moving into an occupied Reference or X axis PV swaps +the two PVs, and a snapshot reference is replaced. The only move that is +refused is one into a full Signals list ("Live is full (8/8)"). Styles +(Label, Color, Line, Width, Dash) belong to the PV, so a curve keeps them +when it moves between Signals and Reference. + +**One axis, one unit.** The Live axis takes the engineering unit of the first +PV, in order, that has one. A PV with a different unit stays in its list +but is not drawn, and its card tells you to open a new Waveform tab for it. + +## Snapshot → reference + +**Snapshot → reference** in the actions bar copies the last drawn frame of +every visible live curve into the Reference list as a _snapshot_. It +happens at once, with one click and no dialog. + +A snapshot is **session-only**. It is never written to the URL, a saved view +or the page state, so a reload or a shared link does not have it. To keep a +reference, use a Reference **PV** instead. + +The Reference list shows its **Source** under its cards, for example +"Snapshot 14:02:31 of 3 curves — this session only". + +The button is disabled, with its reason, until some curve has data. + +Right-click a curve's card or legend entry and choose **Take snapshot as +reference** for the same snapshot, or **Use as reference** to make that PV the +reference. Right-click the plot for **Use this shot as reference** and +**Freeze this shot** ([Right-click menus](workbench.md#right-click)). + +## Rolling mean reference { #rolling-reference } + +Turn on **Rolling mean** (under the Reference's cards) +and every live curve gets its own reference: the element-by-element **mean of +its frames over the last _Window_ seconds** (default 60 s, 1 s to 1 h). With +it comes a **σ per element** over the same frames, drawn as the **Spread +band** (±1σ by default; ±2σ, ±3σ or none) in the curve's color. The band is +the probability picture along the index: how far each element usually +strays. With Δ on, the live curve is drawn as its deviation from its rolling +mean and the band sits around zero, so an element outside the band is +deviating more than it has over the window. + +- Turning Rolling mean on replaces any PV or snapshot reference, exactly as + Snapshot → reference does; turning it off clears the reference. +- The reference row reads **collecting** until some curve's window holds two + frames (a σ exists). Δ never waits for it: a curve subtracts its own mean as + soon as it has a frame. +- The window keeps at most 600 frames per curve (fewer for long waveforms: + 32 MB per curve), thinning fast arrivals, so a 60 s window of a 10 Hz PV + keeps every frame and a 1 kHz PV one in ten. It starts again when the PV + reconnects or its length changes. Shortening the Window and lengthening it + again keeps the frames in between. +- On a logarithmic Live axis the band is not drawn (its lower edge can be + zero or negative); the rolling mean and Δ still are. +- Averaging (_Average_) does not feed the window: it is the raw frames. +- The rolling reference **is** written to the URL (`roll=60`) and to a saved + view, with Δ (`delta=1`) and the band (`spread=2`), since a reload rebuilds + it. Its history is not: a reopened page starts collecting again. + +**Record a minute, then hold it.** Let the window fill, then click +**Snapshot → reference**: with a rolling reference in place the button +freezes the current rolling mean _and its σ_ into a snapshot ("Snapshot +14:02:31 of 3 curves of rolling 60 s"). The band stays, the reference stops +moving. Like any snapshot, it is session-only. + +## Δ: subtract reference { #subtract-reference } + +Turn on **Subtract reference** (under the Reference's cards) to draw +**live − reference** element by element instead of the raw curves. The field +appears once there is a reference. + +- **Against a reference PV**: every live curve subtracts that PV's latest + frame. Until the reference has sent a frame, no live curve is drawn, and the + canvas reads "Δ needs a reference frame — waiting for …". +- **Against a snapshot**: each curve subtracts _its own_ entry in the + snapshot. A curve that was not in the snapshot, or whose data restarted + after the snapshot was taken (reconnect or length change), is not drawn and + is marked **not in snapshot**. +- **Against a rolling mean**: each curve subtracts its own rolling mean; see + [Rolling mean reference](#rolling-reference). +- A curve whose length differs from its reference frame is not drawn and is + marked **length mismatch**. + +Δ is written to the URL (`delta=1`) only together with a reference PV or a +rolling mean. Δ against a snapshot is session-only, like the snapshot. + +## Persistence and averaging + +Both are in the **Acquisition** section: + +- **Persistence** (1–16; 1 = off) overlays the last N frames of each curve, + older frames fading out. Curves drawn as bars show only the latest frame. +- **Average** (1–64; 1 = off) draws each element as the mean of the last N + frames. Missing or non-numeric samples are skipped, not counted as zero. + +Each curve keeps as many frames as the larger of the two settings. Its history +starts again when the PV reconnects, when its length changes, and when the +curve is hidden. + +Under **More**: + +- **Element range** draws only elements _first_ to _last_ (0-based, + inclusive; leave a side empty for "to the end"). +- **Decimation** caps the points drawn per curve (default 4096; 0 draws + every point). +- **Update-rate cap** (1–10 Hz; 10 follows every update). + +**Pause** in the actions bar freezes the drawing. Data keeps arriving in the +background and is drawn again when you resume. + +## The X-axis PV rule + +With a PV in **X axis PV**, the X axis can use that PV's values instead of +the element index (**Axes › X axis**, **Plot against**: _Element #_ or +_X axis PV_). + +One rule decides whether the X axis PV can be used. A live curve is a +_candidate_ when it is connected, has data, has an accepted unit and, with Δ +on, has its reference's length. The X axis PV is **usable** when it is +connected, has data, is numeric and has the same length as at least one +candidate. + +- **Usable**: candidates are drawn against the X axis PV's values. A curve of + another length is hidden and marked **length mismatch**. +- **Not usable**: every curve is drawn against the element index, the X axis + reads **Element**, and the X axis PV's card says why. + +## Statistics + +Turn on **Show statistics** (the **Statistics** section) and the shared +statistics panel docks under the chart, one row per drawn live curve. The +panel, the Metrics editor and the expression language are described on the +[Statistics](statistics.md) page. What Waveform computes over: + +- the elements of the published frame inside the **element range**, after Δ + when Δ is on, never over decimated data; +- `y` is the curve's values, `i` the element index of each, `x` the X axis + PV's value of each (the index without a usable X axis PV), `y1` … `y8` another + live curve by list order, `n` the number of finite elements in range; +- `r` is the reference the curve subtracts (PV frame, snapshot entry or + rolling mean), `s` its σ per element (a rolling mean, or a snapshot frozen + from one) and `d = raw − r` the deviation, whether or not Δ is drawn; + without a reference (or σ) a metric that uses them reads "–"; +- the default columns are **n · mean · std · rms · p-p**; min, max, median, + _peak at_ (`at(i, argmax(y))`), _trough at_, _dev rms_ (`rms(d)`), _dev + max_ (`max(abs(d))`), _dev σ_ (`max(abs(d) / s)`, the largest deviation in + units of σ) and _worst at_ (the element of that deviation) are in the list, + off; +- strip charts tick once per published frame; **Show distribution** adds the + density of each curve's values (see [Statistics](statistics.md)). + +In the URL `stats=1` turns the panel on, `dist=1` the distribution block, +and repeated `m=` keys carry the metric list when it differs from the default. + +## What the canvas tells you + +When nothing can be drawn, the canvas shows the first of these messages that +applies: + +1. **Add a waveform PV**: the Signals list is empty. +2. **Δ needs a reference frame — waiting for …**: see [Δ](#subtract-reference). +3. **No curve can be drawn — see the Waveforms list**, with counts. Each row + says why it is not drawn. +4. **waiting for data**. + +## Drawings + +Waveform draws lines, boxes, notes and measurements like Trace; see +[Drawing in Correlation and Waveform](drawing-tools.md#other-plots). A +**Measure** card reads Δx and Δy, then, for each live curve shown, the +number of its elements whose x lies inside the measured span, their mean +(x̄) and σ; with more than one curve, each line starts with the curve's +name. It shows no Δ%. Right-click a drawing, or its card under +**Drawings**, to edit, lock or delete it. + +## Link format { #link-format } + +The tool's state travels in its page URL: the query a host page, a saved +view or a link opens the tool with, and the one it reports back to an +embedding host. `src/tools/waveform/query/` is the only parser of this +grammar. + +| Key | Meaning | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `pv=` | A Live waveform, repeated, in color order; deduplicated, at most 8. | +| `ref=` | The Reference PV (0–1). A snapshot reference is session data and is never written. | +| `roll=<1..3600>` | A rolling reference instead: per live curve, the mean of its frames over the last N seconds. | +| `spread=<0..3>` | The ±kσ band around a reference that has a σ (rolling, or a snapshot frozen from one); default 1, 0 = none. | +| `xs=` | The X-source PV (0–1); absent means element index. | +| `xl=