Test and measurement
Waveform Graph <smart-waveform-graph>
WaveformGraph displays complete records against engineering axes: waveforms with a start time and a sample interval, or XY pairs.
<smart-waveform-graph> · 19 properties, 9 methods, 5 events · source/modules/smart.waveformgraph.js
Usage in Vue
Vue uses the custom element directly. A property is bound with :kebab-name; an array or an object needs the .prop modifier so that Vue sets the property rather than an attribute. Events are listened to with @eventName; methods are called on the element through a template ref.
import 'smart-industrial/source/modules/smart.waveformgraph.js';
<smart-waveform-graph ref="waveformGraph" :layout="'stacked'"
@exportRequest="onEvent"></smart-waveform-graph>
// methods are called on the element the ref holds
waveformGraph.value.setPlotData('value', {}, {});
// an array or an object is set as a property, not converted to an attribute: use .prop
<smart-waveform-graph :plots.prop="plots"></smart-waveform-graph>
Properties
| Binding | Type, default | Description |
|---|---|---|
:plots | array | Sets or retrieves the plots. Each is an object with id, label, unit, color, y (the record), t0 and dt (start and interval of a waveform) or x (the x values of an XY plot), scale (the id of the y scale it is read on), style (line, points, step or bars), lineWidth and visible. A sample that is not a number - NaN, null, an empty string - is a gap, never 0. An item that is not an object is skipped, and a dt that is not a number is taken as 1; each is said once in a console warning. |
:scales | array | Sets or retrieves the y scales. Each is an object with id, label, unit, min, max, autoScale, logarithmic and position (left or right). Limits alone fix a scale; empty gives one scale that follows the data. A min above max is swapped, with one console warning. An item that is not an object is skipped, with one console warning. |
:layout | WaveformGraphLayout | Sets or retrieves how the scales are laid out: overlaid on one plot area, or stacked with a band per scale. |
:x-label | string | Sets or retrieves the name of the x axis. |
:x-unit | string | Sets or retrieves the unit of the x axis, used in its labels and readouts. |
:x-min | number? | Sets or retrieves the start of the x axis. With xMax, fixes the axis; null follows the data. Set above xMax, the two are swapped; equal to it, or not a finite number, the axis follows the data. Each is said once in a console warning. |
:x-max | number? | Sets or retrieves the end of the x axis. With xMin, fixes the axis; null follows the data. See xMin for limits set the wrong way round. |
:x-logarithmic | boolean | Draws the x axis on a logarithmic scale. A log axis has no zero: points at x <= 0 are not drawn, and are not dropped silently - the header and the accessible name say how many ("3 points at x ≤ 0 not shown on the log axis"), with one console warning. The axis then starts at the smallest x above zero, also when xMin or a zoom reaches zero or below, and zooming and panning work in decades. |
:x-format | WaveformGraphXFormat | Sets or retrieves how x values are written: si in engineering notation with the x unit, plain as a number, clock as a time of day for x values in epoch milliseconds. |
:cursors | array | Sets or retrieves the cursors. Each is an object with id, label, x, y, plot (the id of the plot it is locked to, which then supplies y), color and visible. Cursors are dragged on the plot and moved with the arrow keys, which follow the x axis as drawn, left to right, also in a right-to-left layout; on a log axis a key press moves a pixel. The cursor legend reads each one and the difference between the first two. An item that is not an object is skipped, with one console warning. |
:annotations | array | Sets or retrieves the annotations: text at a point in data coordinates. Each is an object with x, y, text, plot (the id of a plot that supplies y) and color. An item that is not an object is skipped, with one console warning. |
:show-grid | boolean | Shows the grid lines at the ticks of the axes. |
:show-legend | boolean | Shows the plot legend, where a plot is hidden and shown. |
:show-cursor-legend | boolean | Shows the cursor legend under the plot. |
:show-palette | boolean | Shows the tool palette: zoom in, zoom out, fit, auto scale and CSV export. |
:interactive | boolean | Enables panning by dragging, zooming with the wheel, box zoom with Shift and drag, placing and dragging cursors, double-click to fit, and the keys of the plot area. |
:label | string | Sets or retrieves the title shown above the plot and used in the accessible name. |
:precision-digits | number | Sets or retrieves the number of significant digits in readouts and axis labels. Held to 1 to 21; a value outside that, or not a number (4 is then used), is said once in a console warning. |
:line-width | number | Sets or retrieves the line width of line and step plots, in pixels. A plot can carry its own. |
Methods
| Method | Description |
|---|---|
setPlotData(id: string, y: any, options?: object): void | Replaces one plot's record without re-assigning the plots, for an acquisition that delivers a new record per trigger.id string The plot.y any The record, as an array or a typed array.options object Optional x, t0 and dt to go with it. |
valueAt(id: string, x: number): number | Returns a plot's value at an x, interpolated between its samples. For a waveform it returns NaN before the first sample and from one sample interval past the last. For an XY plot, an x that no segment spans returns the y of the nearest sample, so a cursor on a scatter reads the point it sits on. An unknown plot id returns NaN.id string The plot.x number The position. |
togglePlot(id: string, visible?: boolean): void | Shows or hides a plot.id string The plot.visible boolean Shown when true, hidden when false; toggled when omitted. |
fit(): void | Shows the whole record again, on every axis. |
zoomTo(from: number, to: number): void | Shows a range of x.from number The start.to number The end. |
zoom(factor: number): void | Zooms about the centre of the view - the geometric centre, in decades, on a log x axis.factor number Above 1 zooms in, below 1 zooms out. |
toCSV(): string | Returns the plots that are shown, hidden ones left out, as CSV. Each plot is exported as its whole record, whatever the zoom: one x column when the records share it, otherwise x and y columns per plot. |
describe(): string | Returns a sentence describing what the graph shows, as used in its accessible name: the number of plots, the x range, and on a log axis how many points at x <= 0 are not shown. |
invalidate(): void | Redraws the plot on the next animation frame, so that many changes between two frames cost one draw. |
Events
The data of an event is in event.detail. The waveform graph moves a cursor in cursors, zooms its own view or shows and hides a plot, and then raises cursorChange, zoom or plotVisibilityChange; pointer, wheel and keyboard input count only while interactive is true. plotClick reports where a click landed, and exportRequest hands the CSV text to the application to save.
| Event | Description and detail |
|---|---|
@cursorChange | This event is triggered when a cursor is moved by the operator, with the pointer or the keyboard.id string The cursor.x number Its x position.y number Its y value: read off its plot when locked, its own when free. |
@zoom | This event is triggered when the view changes: a zoom, a pan, a box zoom or a fit.xMin number The start of the view.xMax number The end of the view.fitted boolean True when the view shows the whole record. |
@plotClick | This event is triggered when the plot area is clicked without dragging.x number The x under the pointer.y number The y under the pointer on the first scale. |
@plotVisibilityChange | This event is triggered when a plot is hidden or shown from the legend.id string The plot.visible boolean Whether it is now shown. |
@exportRequest | This event is triggered when the CSV button of the palette is pressed. The application decides what to do with the text: download it, send it, or show it.format string Always csv.data string The CSV text. |
Types
type WaveformGraphLayout
'overlaid' | 'stacked'
type WaveformGraphXFormat
'si' | 'plain' | 'clock'
CSS variables
The component declares 4 CSS variables; the CSS page shows how to set them.
--smart-waveform-height --smart-waveform-plot-background --smart-waveform-grid-color --smart-waveform-axis-color