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.

JavaScript TypeScript Angular React Vue Blazor

<smart-waveform-graph> · 19 properties, 9 methods, 5 events · source/modules/smart.waveformgraph.js

Usage in Angular

The Angular wrapper is WaveformGraphComponent from WaveformGraphModule: every property is an input, every event an output named on<Event>, and the methods are called on the component reference from @ViewChild. A method that returns a value returns a Promise of it, resolved once the component has rendered; its ...Sync() twin returns the value at once, or null before the component has rendered. Unknown bindings are rejected at compile time.

import { WaveformGraphModule, WaveformGraphComponent } from 'smart-industrial/angular/waveformgraph';

<smart-waveform-graph #waveformGraph [layout]="'stacked'"
    (onExportRequest)="onExportRequest($event)"></smart-waveform-graph>

@ViewChild('waveformGraph', { read: WaveformGraphComponent }) waveformGraph!: WaveformGraphComponent;
// methods are called on the component reference
this.waveformGraph.setPlotData('value', {}, {});

Properties

Input	Type, default	Description
`[plots]` 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]` 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]` 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]` xLabel	string	Sets or retrieves the name of the x axis.
`[xUnit]` xUnit	string	Sets or retrieves the unit of the x axis, used in its labels and readouts.
`[xMin]` 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]` 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]` 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]` 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]` 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]` 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]` showGrid	boolean true	Shows the grid lines at the ticks of the axes.
`[showLegend]` showLegend	boolean true	Shows the plot legend, where a plot is hidden and shown.
`[showCursorLegend]` showCursorLegend	boolean true	Shows the cursor legend under the plot.
`[showPalette]` showPalette	boolean true	Shows the tool palette: zoom in, zoom out, fit, auto scale and CSV export.
`[interactive]` 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]` label	string	Sets or retrieves the title shown above the plot and used in the accessible name.
`[precisionDigits]` 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]` 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?: any): 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: any, x: any): Promise<any>` and `valueAtSync(id: any, x: any): 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(): Promise<any>` and `toCSVSync(): 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(): Promise<any>` and `describeSync(): 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.

Output	Description and detail
`(onCursorChange)` 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.
`(onZoom)` 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.
`(onPlotClick)` 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.
`(onPlotVisibilityChange)` 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.
`(onExportRequest)` 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