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 TypeScript

The package ships its definitions: WaveformGraph is the element type and WaveformGraphProperties the properties, both exported from smart-industrial/source/typescript/smart.industrial. document.querySelector('smart-waveform-graph') is typed as WaveformGraph.

import { WaveformGraph, WaveformGraphProperties } from 'smart-industrial/source/typescript/smart.industrial';

const waveformGraph = document.querySelector('smart-waveform-graph') as WaveformGraph;

waveformGraph.layout = 'stacked';
waveformGraph.addEventListener('exportRequest', (event: CustomEvent) => console.log(event.detail));
waveformGraph.setPlotData('value', {}, {});

Properties

Property	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 overlaid	Sets or retrieves how the scales are laid out: overlaid on one plot area, or stacked with a band per scale.
xLabel	string	Sets or retrieves the name of the x axis.
xUnit	string	Sets or retrieves the unit of the x axis, used in its labels and readouts.
xMin	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.
xMax	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.
xLogarithmic	boolean false	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.
xFormat	WaveformGraphXFormat si	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.
showGrid	boolean true	Shows the grid lines at the ticks of the axes.
showLegend	boolean true	Shows the plot legend, where a plot is hidden and shown.
showCursorLegend	boolean true	Shows the cursor legend under the plot.
showPalette	boolean true	Shows the tool palette: zoom in, zoom out, fit, auto scale and CSV export.
interactive	boolean true	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.
precisionDigits	number 4	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.
lineWidth	number 1.5	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