Test and measurement

Bode Plot `<smart-bode-plot>`

BodePlot displays magnitude and phase against a logarithmic frequency axis, one band above the other.

JavaScript TypeScript Angular React Vue Blazor

<smart-bode-plot> · 18 properties, 5 methods, 2 events · source/modules/smart.bodeplot.js

Usage in React

The React wrapper is the BodePlot 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 { BodePlot } from 'smart-industrial/react/bodeplot';

const ref = useRef<BodePlot>(null);

<BodePlot ref={ref} showMargins={true}
    onCursorChange={(event: CustomEvent) => console.log(event.detail)} />

// methods are called on the wrapper the ref holds, which calls the element
ref.current?.valueAt('value', 42);

Properties

Prop	Type, default	Description
`plots`	array	Sets or retrieves the responses. Each is an object with id, label, color, lineWidth, visible and either frequencies, magnitude and phase (measured points, magnitude in dB or linear per magnitudeUnit, phase in degrees) or transferFunction ({ numerator, denominator } as polynomial coefficients in s, highest power first).
`frequencyMin`	number?	Sets or retrieves the start of the frequency axis. With frequencyMax, fixes the axis and the range a transfer function is evaluated over; null follows the measured points.
`frequencyMax`	number?	Sets or retrieves the end of the frequency axis.
`frequencyUnit`	BodePlotFrequencyUnit Hz	Sets or retrieves the unit of the frequency axis. A transfer function is evaluated at s = jω with ω in rad/s either way.
`magnitudeUnit`	BodePlotMagnitudeUnit dB	Sets or retrieves how measured magnitude is given. Linear values are converted to dB; the plot always shows dB.
`magnitudeMin`	number?	Sets or retrieves the bottom of the magnitude band in dB. Null follows the data.
`magnitudeMax`	number?	Sets or retrieves the top of the magnitude band in dB. Null follows the data.
`phaseMin`	number?	Sets or retrieves the bottom of the phase band in degrees. Null follows the data.
`phaseMax`	number?	Sets or retrieves the top of the phase band in degrees. Null follows the data.
`showMargins`	boolean false	Marks the gain and phase margins of the first visible response on both bands and writes them out under the plot. A margin at or below zero is marked as failing. The phase margin is measured to the nearest -180° + k·360° line, so it lies between -180° and 180° and is negative for an unstable loop. With several crossings the smallest phase margin and the gain margin closest to 0 dB are shown; margins() lists every crossing.
`showPhase`	boolean true	Shows the phase band under the magnitude band.
`showGrid`	boolean true	Shows the grid lines at the decades and the ticks.
`showLegend`	boolean true	Shows the legend, where a response is hidden and shown.
`cursor`	number?	Sets or retrieves the frequency of the cursor, which reads every response. Null hides it. The cursor is placed by clicking the plot, moved with the arrow keys (Shift for larger steps, Home and End for the ends) and cleared with Escape.
`interactive`	boolean true	Enables placing and moving the cursor with the pointer and the keyboard.
`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 frequencies.
`lineWidth`	number 1.6	Sets or retrieves the line width of the responses, in pixels. A response can carry its own.

Methods

Method	Description
`valueAt(id: string, frequency: number): object`	Returns a response at a frequency as { magnitude, phase } in dB and degrees, interpolated on the log axis, or NaN outside the record. `id` string The response. `frequency` number The frequency.
`margins(id?: string): object`	Returns the stability margins of a response as { gainMargin, gainMarginFrequency, phaseMargin, phaseMarginFrequency, gainMargins, phaseMargins }, NaN where there is no crossing. The phase margin at a gain crossover is measured to the nearest -180° + k·360° line (between -180° and 180°, negative when the loop is unstable there); the gain margin is read at every frequency where the phase crosses -180° + k·360°. With several crossings, phaseMargin is the smallest phase margin and gainMargin the one closest to 0 dB; gainMargins and phaseMargins list every crossing as { margin, frequency } in ascending frequency. `id` string The response; the first visible one when omitted.
`evaluate(transferFunction: object, frequency: number): object`	Evaluates a transfer function at a frequency and returns { magnitude, phase } in dB and degrees. The phase is the continuous phase of the response, anchored at its low-frequency asymptote (-90° for each integrator, +90° for each differentiator, -180° more for a negative gain), not an angle folded into -180°..180°. `transferFunction` object { numerator, denominator } as coefficients in s, highest power first. `frequency` number In the element's frequency unit.
`togglePlot(id: string, visible?: boolean): void`	Shows or hides a response. `id` string The response. `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, with the margins when they are shown.

Events

The data of an event is in event.detail. The Bode 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 response is already shown or hidden.

Event	Description and detail
`onCursorChange` cursorChange	This event is triggered when the cursor is placed or moved by the operator. `frequency` number The cursor frequency.
`onPlotVisibilityChange` plotVisibilityChange	This event is triggered when a response is hidden or shown from the legend. `id` string The response. `visible` boolean Whether it is now shown.

Types

`type BodePlotFrequencyUnit`

'Hz' | 'rad/s'

`type BodePlotMagnitudeUnit`

'dB' | 'linear'

CSS variables

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

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