@opencor/plot is a Vue 3 component for plotting data. It is used by OpenCOR, but it can be used by any Vue 3 application.
Key characteristics:
- Built as a Vue 3 component using the Composition API.
- Uses uPlot under the hood, and draws traces using Canvas 2D or WebGL, whichever is faster for the browser and the data.
- It does not rely on any UI framework (e.g., PrimeVue) or CSS framework (e.g., Tailwind CSS).
Contents:
- Installation
- Usage: Types, Data, Large and live data, Props, Events, Properties, Methods, Interaction, and Theming
- Development: Releasing
- License
bun add @opencor/plot # Or npm install @opencor/plot, etc.Vue 3 is a peer dependency. uPlot is our only other runtime dependency and gets installed along with @opencor/plot.
<template>
<div style="height: 640px">
<OpenCORPlot :data="data" />
</div>
</template>
<script setup lang="ts">
import OpenCORPlot, { type PlotData } from '@opencor/plot';
import '@opencor/plot/style.css';
const x = Float64Array.from({ length: 1000 }, (_, i) => i / 100);
const data: PlotData = {
xAxisTitle: 'Time (s)',
yAxisTitle: 'Voltage (mV)',
traces: [
{
name: 'V',
xValue: 'time',
x,
yValue: 'membrane.V',
y: x.map((t) => Math.sin(t)),
color: '#2563eb'
}
]
};
</script>The component fills its container, so the container must have a height. @opencor/plot/style.css contains all the CSS that is needed, including uPlot's.
The component is the default export of @opencor/plot, and is also exported as OpenCORPlot. These types are exported too:
| Type | Definition | Description |
|---|---|---|
PlotData |
{ traces, xAxisTitle?, yAxisTitle?, xAxisRange?, yAxisRange? } |
The data to plot (see Data). |
PlotTrace |
{ name, x, y, xValue, yValue, color, traceId?, legendRank?, runLabel? } |
A trace to plot (see Data). |
PlotMargins |
{ left: number; right: number } |
The left and right margins (in pixels) of a plot, i.e. the space taken by its Y axis and legend (see the margins prop and the marginsUpdated event). |
PlotTheme |
'system' | 'light' | 'dark' |
The value of the theme prop. |
PlotRenderer |
'auto' | 'canvas' | 'webgl' |
The value of the renderer prop. |
PlotActiveRenderer |
'canvas' | 'webgl' | 'none' |
The value of the activeRenderer property ('none' if traces couldn't be drawn). |
PlotCsvExportEvent |
PlotCsvExportStartedEvent | PlotCsvExportProgressEvent | PlotCsvExportFinishedEvent |
The payload of the csvExport event. Use its type to tell which one it is. |
PlotCsvExportStartedEvent |
{ type: 'started' } |
An export to CSV has started. |
PlotCsvExportProgressEvent |
{ type: 'progress'; percent: number } |
An export to CSV has made some progress: percent goes from 0 to 100 (an integer). |
PlotCsvExportFinishedEvent |
{ type: 'finished'; success: boolean } |
An export to CSV has finished, whether successfully (and the file was downloaded) or not. |
PlotContextMenuEvent |
{ clientX: number; clientY: number; usingKeyboard: boolean; items: ContextMenuItem[] } |
The payload of the contextMenu event: where the context menu was requested (in client coordinates), whether it was requested using the keyboard (in which case the custom menu should take the keyboard focus), and the items that our context menu would have shown. |
ContextMenuItem |
ContextMenuAction | ContextMenuSeparator |
An item of a context menu. |
ContextMenuAction |
{ label: string; icon?: IconName; checked?: boolean; command?: () => void; items?: ContextMenuItem[] } |
An action: its label, its icon, whether it is checked (only for a checkable action, e.g. to make an axis logarithmic), the command to call when it is chosen, and its submenu items, if any. |
ContextMenuSeparator |
{ separator: true } |
A separator. |
IconName |
'angle-right' | 'arrows-h' | 'arrows-v' | 'chart-line' | 'check' | 'copy' | 'download' | 'image' | 'refresh' | 'search-minus' | 'search-plus' |
The name of an icon (from PrimeIcons). |
PlotPointCounts |
{ nbOfPoints: number; nbOfDrawnPoints: number } |
The value returned by the pointCounts() method. |
PlotMemoryUsage |
{ levelOfDetail: number; logValues: number; gpu: number } |
The value returned by the memoryUsage() method. |
| Property | Type | Description |
|---|---|---|
traces |
PlotTrace[] |
The traces to plot. |
xAxisTitle, yAxisTitle |
string |
The axis titles. |
xAxisRange, yAxisRange |
[number, number] |
The range of an axis when the zoom is reset. By default, it fits the data. |
| Property | Type | Description |
|---|---|---|
name |
string |
The name of the trace, as shown in the legend, the hover tooltip, and the CSV export. |
x, y |
Float64Array |
The X and Y values of the trace. |
xValue, yValue |
string |
What the X and Y values are (e.g., the name of a model variable), used in the CSV export. |
color |
string |
The colour of the trace. |
traceId |
string |
An optional identifier that keeps the visibility of the trace when the data is updated. Otherwise, the trace is identified by its name, xValue, yValue, and runLabel (and, among traces that have the same ones, by their order), or by its position if it doesn't have a name, xValue, and yValue. |
legendRank |
number |
The optional rank of the trace in the legend (lower ranks first, 1000 by default). |
runLabel |
string |
An optional label that tells apart the X column of the trace from those of other runs in the CSV export. |
Notes:
- Titles and trace names can contain a little HTML (
b,br,code,em,i,strong,sub, andsup). Anything else is removed. - A trace can be a function of X (e.g., against time) or not (e.g., a phase plot). A point with a non-finite X or Y value (e.g.,
NaN) is a gap in its trace. - A trace with fewer than 20 points is also drawn with markers.
The component only goes through the points that are needed for a trace to look the same, so a trace with millions of points can be zoomed, panned, and hovered smoothly.
The data is updated by giving the component a new data object, since changes made to an existing data object (e.g., to its traces array or to one of its traces) are not watched.
When the data is updated, the work that has already been done is reused if the new values of a trace are a continuation of its previous ones, i.e. a view of the same buffer, from the same offset, and at least as long. Only the new values (and the last of the previous values, which may have changed) then get processed. The very same arrays (i.e. not new views) are assumed not to have changed at all. So, for live data (e.g., while a simulation is running), allocate a buffer for all the values, fill it as values become available, and give the component a view of the part that is filled:
const xBuffer = new Float64Array(nbOfPoints);
const yBuffer = new Float64Array(nbOfPoints);
// Each time some new values have been added to the buffers:
data.value = {
...data.value,
traces: [{ ...trace, x: xBuffer.subarray(0, nbOfValues), y: yBuffer.subarray(0, nbOfValues) }]
};Also set the live prop while the data is live, so that the last point of each visible trace gets marked, making its latest value easy to spot (even where a trace overlaps itself, e.g. in a phase plot).
| Prop | Type | Default | Description |
|---|---|---|---|
data |
PlotData |
(required) | The data to plot. |
showLegend |
boolean |
true |
Whether to show the legend. The legend takes at most 40% of the width of the plot (with long trace names truncated, and shown in full when hovered), and is hidden if the plot is too narrow for it to be useful. |
theme |
PlotTheme |
'system' |
Whether to use light or dark mode, or whatever the system uses. |
margins |
PlotMargins |
Margins shared with other plots, so that their plotting areas line up (see marginsUpdated). |
|
appendTo |
HTMLElement | string |
body |
Where to append our overlays (context menu, hover tooltip, etc.). |
customContextMenu |
boolean |
false |
Whether to emit a contextMenu event rather than show our own context menu. To have no context menu at all, set it and don't handle the contextMenu event. |
renderer |
PlotRenderer |
'auto' |
What to draw traces with. 'auto' uses whichever is faster for the browser and the data: WebGL in Firefox, and in other browsers only when Canvas 2D would need to stroke at least 300,000 points for the visible traces (e.g., noisy traces whose X values are not sorted, or traces that are too short for our level of detail to be used, like 100 traces of 10,000 points, but not smooth phase plots, which only need a few thousand points); Canvas 2D otherwise. With 'webgl', traces are not drawn if WebGL is not available. Whenever WebGL is used, Canvas 2D takes over if WebGL is not available (with 'auto') or not precise enough for the current ranges (e.g., when zoomed in a lot). |
levelOfDetail |
boolean |
true |
Whether to only go through the points that are needed for a trace to look the same when drawing it (see Large and live data). Hovering a trace whose X values are sorted always does. Only meant to be disabled to see how much it helps. |
live |
boolean |
false |
Whether the data is live (e.g., while a simulation is running), in which case the last point of each visible trace is marked. |
To draw traces like a plain uPlot plot would, i.e. without our WebGL renderer and our level of detail, use renderer="canvas" and :levelOfDetail="false". uPlot then draws every point of every trace on its canvas, using our path builder. Unlike uPlot's own, our path builder handles gaps (NaN values) and traces whose X values are not sorted (e.g., phase plots) at any number of points. This is also the reference that our optimisations can be benchmarked against.
| Event | Payload | Description |
|---|---|---|
marginsUpdated |
PlotMargins |
The margins that the plot needs have changed. To line up several plots, pass the largest left and right margins of all of them to each plot's margins prop. |
csvExport |
PlotCsvExportEvent |
An export to CSV has 'started', made 'progress' (with a percent), or 'finished' (with whether it was a success), so that its progress can be shown. |
contextMenu |
PlotContextMenuEvent |
Only with customContextMenu: the context menu was requested at clientX/clientY, with the items that our context menu would have shown. If usingKeyboard is true, the custom menu should take the keyboard focus. |
Available through a template ref:
| Property | Type | Description |
|---|---|---|
activeRenderer |
PlotActiveRenderer |
The renderer that was last used to draw traces: 'canvas', 'webgl', or 'none' (if they couldn't be drawn). Read-only. |
Available through a template ref:
| Method | Description |
|---|---|
resetMargins() |
Emit marginsUpdated again, e.g. after the shared margins have been reset. |
contextMenuHidden() |
Tell the plot that a custom context menu (see contextMenu) has been hidden, so that it can get the keyboard focus back. |
pointCounts() |
The number of points of the visible traces (nbOfPoints), and how many of them were last drawn (nbOfDrawnPoints), as an PlotPointCounts. Meant for testing and benchmarking. |
memoryUsage() |
The memory (in bytes) used by the component itself, not counting the data, as an PlotMemoryUsage: by its levels of detail (levelOfDetail), by the logarithm of its values along logarithmic axes (logValues), and on the GPU (gpu). Meant for testing and benchmarking. |
Like with Plotly:
- Plotting area: drag to zoom (along one axis if the drag is mostly horizontal or vertical), Shift+drag to pan, use the mouse wheel to zoom around the mouse pointer, and double-click to reset the zoom.
- Middle of an axis: drag to pan along that axis, use the mouse wheel to zoom along it, and double-click to reset its zoom.
- Ends of an axis and bottom corners: drag to move an end of the axis, or click an end of the axis to type its value.
- Legend: click a trace to show or hide it, double-click it to only show that trace, and hover it to highlight its trace.
- Touch: drag with one finger as with a mouse, or use two fingers to zoom and pan.
- Keyboard (once the plot has the focus):
+and−to zoom in and out,0to reset the zoom, the arrow keys to pan, and Shift+F10 (or the context menu key) to open the context menu. - Escape, or pressing another mouse button, cancels a drag.
Hovering shows the value of each visible trace at the X value under the mouse pointer. For a trace that is not a function of X (e.g., a phase plot), it shows the point closest to the mouse pointer instead.
The context menu can zoom in and out, reset the zoom, make an axis logarithmic, copy the plot to the clipboard, export it as JPEG, PNG, SVG, or WebP, and export its data to CSV.
Set any of these CSS variables on an ancestor of the component. Each has a light and a dark default, based on PrimeVue's Aura theme:
| Variable | Used for |
|---|---|
--opencor-plot-background |
The background of the plot. |
--opencor-plot-text-color |
The axis titles and the legend. |
--opencor-plot-muted-text-color |
Tick labels, the hover guide line, hidden traces in the legend, and secondary text in overlays. |
--opencor-plot-primary-color |
The zoom box (and, by default, the keyboard focus ring). |
--opencor-plot-grid-color |
Grid lines. |
--opencor-plot-zero-line-color |
The zero lines. |
--opencor-plot-hidden-trace-color |
The legend swatch of a hidden trace. |
--opencor-plot-hover-background |
Hovered items (e.g., in the legend and context menu). |
--opencor-plot-overlay-background |
The background of the context menu and hover tooltip. |
--opencor-plot-overlay-border-color |
Their border. |
--opencor-plot-overlay-text-color |
Their text. |
--opencor-plot-overlay-shadow |
Their shadow. |
--opencor-plot-border-radius |
Rounded corners. |
--opencor-plot-focus-ring-width |
The width of the keyboard focus ring. |
--opencor-plot-focus-ring-color |
The colour of the keyboard focus ring (the primary colour by default). |
Bun is required.
bun install # Install the dependencies.
bun run build # Build the library.
bun dev # Run the demo app.
bun build:demo # Build the demo app.
bun format # Format the code.
bun format:check # Check the code formatting (without fixing it).
bun lint # Lint the code.
bun lint:check # Lint the code (without fixing it).
bun test # Run the tests.
bun test --coverage # Run the tests with code coverage (which must be 100%).
bun test --watch # Run the tests in watch mode.
bun typecheck # Type check the code.
bun clean # Remove all generated files.bun dependencies:update # Check for and update outdated dependencies.
bun version:new # Bump the version number.To publish a new version to npm, bump the version number (bun version:new), commit it, and push a tag named after it (i.e. vX.YYYYMMDD.Z for version X.YYYYMMDD.Z). Our CD workflow then tests, builds and publishes it. It fails if the tag doesn't match the version in package.json.