Test and measurement

Polar Plot `<smart-polar-plot>`

PolarPlot displays data on a circular grid: a radius against an angle, or an x and a y about a centre.

JavaScript TypeScript Angular React Vue Blazor

<smart-polar-plot> · 15 properties, 4 methods, 2 events · source/modules/smart.polarplot.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.polarplot.js';

<smart-polar-plot ref="polarPlot" :angle-origin="'top'"
    @cursorChange="onEvent"></smart-polar-plot>

// methods are called on the element the ref holds
polarPlot.value.valueAt('value', 42);

// an array or an object is set as a property, not converted to an attribute: use .prop
<smart-polar-plot :plots.prop="plots"></smart-polar-plot>

Properties

Binding	Type, default	Description
`:plots` plots	array	Sets or retrieves the plots. Each is an object with id, label, color, lineWidth, visible, style (line or points), closed (joins the last point to the first) and either angles and radii or x and y about the centre. A point without a reading - null, NaN or an infinite value on either axis - is a gap in the trace: not drawn, not read by the cursor, not in the radius range, and counted in the readout and the accessible name ("no reading at 2 of 360 points"), with one console warning. An item that is not an object is skipped, with one console warning.
`:markers` markers	array	Sets or retrieves the markers: named points, each an object with label, color and either angle and radius or x and y. They are drawn on the plot and listed under it. An item that is not an object is skipped, with one console warning.
`:angle-unit` angleUnit	PolarPlotAngleUnit deg	Sets or retrieves the unit of angles given and shown.
`:angle-origin` angleOrigin	PolarPlotAngleOrigin right	Sets or retrieves where angle zero points.
`:angle-direction` angleDirection	PolarPlotAngleDirection counterclockwise	Sets or retrieves the direction angles increase in.
`:radius-min` radiusMin	number?	Sets or retrieves the radius at the centre. Null uses zero, or the smallest negative value in the data. A value that is not a finite number is ignored; set above radiusMax, the two are swapped. Each is said once in a console warning.
`:radius-max` radiusMax	number?	Sets or retrieves the radius at the rim. Null follows the data, rounded up to a nice number. A value that is not above the centre (radiusMin equal to radiusMax, for one) leaves no radius axis, so it is ignored and the rim follows the data; this, a value that is not a finite number, and limits set the wrong way round (swapped) are each said once in a console warning.
`:radius-unit` radiusUnit	string	Sets or retrieves the unit of the radius, used in the ring labels and the readouts.
`:show-grid` showGrid	boolean true	Shows the rings and the spokes.
`:show-legend` showLegend	boolean true	Shows the legend, where a plot is hidden and shown.
`:cursor` cursor	number?	Sets or retrieves the angle of the cursor, which reads every plot. Null hides it. The cursor is placed by clicking the plot and moved with the arrow keys; the arrows rotate it on screen, the same in a right-to-left layout. Where a plot has nothing drawn at the cursor's angle - beyond the ends of an open trace, or across a gap - its reading is "--".
`:interactive` interactive	boolean true	Enables placing and moving the cursor with the pointer and the keyboard.
`:label` label	string	Sets or retrieves the title shown above the plot and used in the accessible name.
`:precision-digits` precisionDigits	number 4	Sets or retrieves the number of significant digits in radii. 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` lineWidth	number 1.6	Sets or retrieves the line width of the plots, in pixels. A plot can carry its own.

Methods

Method	Description
`valueAt(id: string, angle: number): number`	Returns a plot's radius at an angle, interpolated between the neighbouring points that span it - from the last point back to the first only when the plot is closed, as drawn. Returns NaN where the plot has nothing drawn at that angle: beyond the ends of an open trace, across a gap, or for an unknown plot. `id` string The plot. `angle` number In the element's angle unit.
`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.
`describe(): string`	Returns a sentence describing what the plot shows, as used in its accessible name: the number of plots, the radius range, where the largest radius is, and how many points of a plot have no reading.
`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 polar plot moves cursor as the operator drags or presses an arrow key, only while interactive is true, and then raises cursorChange. plotVisibilityChange follows a legend click or a togglePlot() call after the plot is already shown or hidden.

Event	Description and detail
`@cursorChange`	This event is triggered when the cursor is placed or moved by the operator. `angle` number The cursor angle, in the element's angle unit.
`@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.

Types

`type PolarPlotAngleUnit`

'deg' | 'rad'

`type PolarPlotAngleOrigin`

'right' | 'top'

`type PolarPlotAngleDirection`

'counterclockwise' | 'clockwise'

CSS variables

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

--smart-polar-height --smart-polar-plot-background --smart-polar-grid-color --smart-polar-axis-color