Trends and signals

Strip Chart <smart-strip-chart>

StripChart is a real-time chart for continuously acquired samples: the newest sample is drawn at the right and the oldest leaves at the left.

<smart-strip-chart> · 18 properties, 6 methods, 3 events · source/modules/smart.stripchart.js

Usage in React

The React wrapper is the StripChart component: every property is a prop, every event a prop named on<Event> that receives the CustomEvent, and the methods are called on the element through a ref.

import { StripChart } from 'smart-industrial/react/stripchart';

const ref = useRef<StripChart>(null);

<StripChart ref={ref} autoScale={'perPen'}
    onPenVisibilityChange={(event: CustomEvent) => console.log(event.detail)} />

// methods are called on the wrapper the ref holds, which calls the element
ref.current?.clear();

Properties

Prop	Type, default	Description
autoScale	StripChartAutoScale none	Sets or retrieves how the vertical range is chosen.
gridColumns	number 6	Sets or retrieves how many vertical divisions the graticule has, from 1 to 100. A larger value draws 100; NaN, Infinity or a negative value draws the default 6. Either is reported once in a console warning.
gridRows	number 4	Sets or retrieves how many horizontal divisions the graticule has, from 1 to 100. A larger value draws 100; NaN, Infinity or a negative value draws the default 4. Either is reported once in a console warning.
historyLength	number 1000	Sets or retrieves the number of samples the ring buffer holds, from 2 to 1 000 000. A larger value (Infinity included) holds 1 000 000; NaN or a negative value is ignored with a console warning and the buffer is kept. Changing it to another size creates a new buffer and discards the samples held.
lineWidth	number 1.5	Sets or retrieves the trace width in pixels.
max	number 100	Sets or retrieves the top of the vertical range, for pens that do not set their own. Ignored unless autoScale is none.
min	number 0	Sets or retrieves the bottom of the vertical range, for pens that do not set their own. Ignored unless autoScale is none.
mode	StripChartMode scroll	Sets or retrieves how new samples move across the display.
paused	boolean false	Sets or retrieves whether the chart is frozen. A paused chart keeps what it holds and drops anything pushed at it, and push returns false so the application knows the sample was not taken.
pens	array	Sets or retrieves the channels to draw as [{ field, label, unit, color, min, max, visible }]. field is the key under which each sample carries the value; the other members are presentation. With autoScale none, min and max are the pen's scale: a reading beyond them is kept as it is in the digital display, flagged OVER or UNDER beside it and in the chart's accessible name, and its trace is pinned to the edge it left by. An item that is not an object (null, for example) is skipped with a console warning. Assign a new array to update the component; an array modified in place is deep-equal to the current one and does not trigger a redraw.
precisionDigits	number 2	Sets or retrieves how many decimal places the digital readout shows, from 0 to 20; a value outside that is clamped, and one that is not a number shows 2.
showDigitalDisplay	boolean false	Sets or retrieves whether the latest value of each pen is shown as a number above the legend. A sample with no reading for a pen - a missing, null, empty, non-numeric or infinite value - shows "--" (said as "no reading"), never 0; a reading off a fixed scale shows its real value with an OVER or UNDER flag.
showGrid	boolean true	Sets or retrieves whether the grid is drawn. Boolean attributes are presence-based, so set the property from script to turn it off.
showScales	boolean false	Sets or retrieves whether the scales are drawn: a y scale down the left of the plot with a label at every grid row, read on the first pen's range (the shared range, or min and max; with perPen scaling among several pens the labels take the first pen's colour), and an x scale along the bottom with a label at every grid column - seconds before now on a time axis, sample numbers otherwise. A classic waveform chart has both; the plot gives up the margins they take and is clipped to them.
showLegend	boolean true	Sets or retrieves whether the pen legend is shown. The legend is a composite widget: it is one tab stop for the whole group, arrowed between, with Enter or Space showing and hiding a pen.
timeField	string timestamp	Sets or retrieves which key on a sample carries its timestamp, when xAxisMode is time. A sample that arrives without one is stamped on arrival.
timeSpan	number 60000	Sets or retrieves how much time the width covers, in milliseconds, when xAxisMode is time. A value that is not a positive number draws 60 000.
xAxisMode	StripChartXAxisMode sample	Sets or retrieves what the horizontal axis represents: the sample index or the sample time.

Methods

Method	Description
clear(): void	Empties the buffer and redraws. The next time the buffer fills, overflow is raised again.
invalidate(): void	Marks the chart as needing a redraw and redraws it on the next animation frame, so that many pushes between two frames cost one draw. The method is called by push, so an application rarely needs to call it.
push(sample: object): boolean	Appends one sample and schedules a redraw. A pen whose field is missing, null, empty, non-numeric or infinite has no reading at that sample: its trace has a gap there and the digital display shows "--", never 0. Returns false if the chart is paused, or the sample is not an object, and the sample was dropped. sample object Values keyed by pen field, for example { ai0: 4.72, ai1: -1.03 }. In time mode a sample without a timestamp is stamped on arrival.
pushMany(samples: object[]): boolean	Appends a batch of samples with one redraw for the whole batch, so a block read from a DAQ card costs the same as one sample. Items that are not objects (null, for example) are skipped. Returns false when the chart is paused, or no item was a sample, and the batch was dropped. samples object[] The samples, oldest first.
snapshot(): object[]	Returns the samples in the buffer, oldest first, as a new array. The array is a copy, so it can be passed to an exporter or kept without being changed by later pushes.
togglePen(index: number, visible?: boolean): void	Shows or hides one pen. index number Which pen, by its position in the pens array. visible boolean Force a state instead of toggling.

Events

The data of an event is in event.detail. pointsAppended and overflow report samples the strip chart has already stored, and samples pushed while paused is true are dropped and raise nothing. penVisibilityChange follows a pen the chart has already shown or hidden in pens.

Event	Description and detail
onOverflow overflow	This event is triggered once per overflow episode: when the ring buffer is full and the first samples are overwritten. It is raised again only after the buffer has been emptied - by clear() or a historyLength change - and has filled again, not on every push while the buffer stays full. dropped number How many samples the push that started the episode overwrote. capacity number The buffer's size.
onPenVisibilityChange penVisibilityChange	This event is triggered when a pen is shown or hidden, whether from the legend or from togglePen. index number The pen's position in the pens array. field string The pen's field. visible boolean Whether the pen is now drawn.
onPointsAppended pointsAppended	This event is triggered when samples are appended. appended number How many samples were taken. length number How many the buffer now holds. written number How many have been written since the buffer was created, which keeps counting past the buffer's capacity.

Types

type StripChartAutoScale

'none' | 'perPen' | 'shared'

type StripChartMode

'scroll' | 'sweep' | 'scope'

type StripChartXAxisMode

'sample' | 'time'

CSS variables

The component declares 5 CSS variables; the CSS page shows how to set them.

--smart-strip-chart-height --smart-strip-plot-background --smart-strip-grid-color --smart-strip-cursor-color --smart-strip-scale-color