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 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.stripchart.js';
<smart-strip-chart ref="stripChart" :auto-scale="'perPen'"
@penVisibilityChange="onEvent"></smart-strip-chart>
// methods are called on the element the ref holds
stripChart.value.clear();
// an array or an object is set as a property, not converted to an attribute: use .prop
<smart-strip-chart :pens.prop="pens"></smart-strip-chart>
Properties
| Binding | Type, default | Description |
|---|---|---|
:auto-scale | StripChartAutoScale | Sets or retrieves how the vertical range is chosen. |
:grid-columns | number | 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. |
:grid-rows | number | 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. |
:history-length | number | 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. |
:line-width | number | Sets or retrieves the trace width in pixels. |
:max | number | Sets or retrieves the top of the vertical range, for pens that do not set their own. Ignored unless autoScale is none. |
:min | number | Sets or retrieves the bottom of the vertical range, for pens that do not set their own. Ignored unless autoScale is none. |
:mode | StripChartMode | Sets or retrieves how new samples move across the display. |
:paused | boolean | 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. |
:precision-digits | number | 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. |
:show-digital-display | boolean | 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. |
:show-grid | boolean | Sets or retrieves whether the grid is drawn. Boolean attributes are presence-based, so set the property from script to turn it off. |
:show-scales | boolean | 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. |
:show-legend | boolean | 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. |
:time-field | string | 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. |
:time-span | number | 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. |
:x-axis-mode | StripChartXAxisMode | 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 |
|---|---|
@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. |
@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. |
@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