Trends and signals

Spectrum <smart-spectrum>

Spectrum is a spectrum analyzer display.

<smart-spectrum> · 28 properties, 5 methods, 1 events · source/modules/smart.spectrum.js

Usage in Angular

The Angular wrapper is SpectrumComponent from SpectrumModule: 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 { SpectrumModule, SpectrumComponent } from 'smart-industrial/angular/spectrum';

<smart-spectrum #spectrum [sampleRate]="42"
    (onSpectrumChange)="onSpectrumChange($event)"></smart-spectrum>

@ViewChild('spectrum', { read: SpectrumComponent }) spectrum!: SpectrumComponent;
// methods are called on the component reference; this one returns a Promise
const result = await this.spectrum.push([]);

Properties

Input	Type, default	Description
[signal] signal	array | null	Sets or retrieves the most recent block of samples, as an array or a typed array. push sets it; an application with a complete record can assign it directly.
[sampleRate] sampleRate	number 1	Sets or retrieves the sample rate in samples per second. Every frequency on the display follows from it; the default of 1 reads frequencies in cycles per sample. A value that is not a positive number (0, negative, NaN) analyses nothing rather than computing a spectrum on a made-up rate: the header and the plot say "Sample rate 0 is not valid", the accessible name says the same, and one console warning names the value.
[size] size	number 0	Sets or retrieves the FFT size. 0 uses the next power of two above the block length. A size larger than the block zero-pads the transform, which interpolates the display but does not add resolution; the bin width is still the sample rate divided by the length of the real data. Held to 0 to 16,777,216; not a number uses 0. Either is said once in a console warning.
[window] window	SpectrumWindow hann	Sets or retrieves the window function applied before the transform. A flat-top window reads amplitude to within 0.01 dB but spreads the peak in frequency; a rectangular window does the opposite. The amplitude is corrected for the coherent gain of the window in every case.
[scaling] scaling	SpectrumScaling amplitude	Sets or retrieves what a bin's value means: amplitude reads a sine's peak, power its square, density its power per hertz. They are not interchangeable, and the header says which one is showing.
[levelScale] levelScale	SpectrumLevelScale db	Sets or retrieves whether levels are shown in decibels against reference or as linear magnitudes.
[reference] reference	number 1	Sets or retrieves the level that corresponds to 0 dB. 1 gives dBV levels for a signal in volts; the full scale of a converter gives dBFS.
[frequencyScale] frequencyScale	SpectrumFrequencyScale linear	Sets or retrieves the frequency axis. A log axis starts at the first bin above DC, since it has no zero, and carries decade ticks with 2 and 5 minors.
[minFrequency] minFrequency	number	Sets or retrieves the lowest frequency shown. null follows the data: 0, or the first bin on a log axis. Set above maxFrequency, the two are swapped; a span that leaves nothing to show (equal limits, or a limit beyond the other end of the data or below the first bin on a log axis) shows the whole spectrum instead. Each is said once in a console warning.
[maxFrequency] maxFrequency	number	Sets or retrieves the highest frequency shown. null follows the data to the Nyquist frequency. See minFrequency for limits set the wrong way round.
[minLevel] minLevel	number	Sets or retrieves the bottom of the level axis. null follows the data with some headroom; a fixed value keeps the trace from rescaling as the signal changes, as on an analyzer. Set above maxLevel, the two are swapped; equal limits, or one limit that leaves no room against the data, let the axis follow the data. Each is said once in a console warning.
[maxLevel] maxLevel	number	Sets or retrieves the top of the level axis. null follows the data with headroom. See minLevel for limits set the wrong way round.
[averaging] averaging	SpectrumAveraging none	Sets or retrieves the spectrum averaging mode. none draws each block as it arrives. linear averages the first averages blocks and then holds the result until clear restarts the average, like a bench analyzer. exponential weights each new block by 1/averages and continues indefinitely. Averaging is performed in the power domain regardless of the display scaling, because averaging amplitudes or decibels biases the noise floor.
[averages] averages	number 8	Sets or retrieves how many blocks the average spans. Held to 1 to 10,000; not a number uses 8. Either is said once in a console warning.
[peakHold] peakHold	boolean false	Determines whether the highest level ever seen in each bin is kept as a second trace, until clear.
[showPeaks] showPeaks	number 3	Sets or retrieves how many peaks are marked on the trace and listed in the readout, strongest first. 0 marks none. Peaks are found on the displayed trace, after averaging, by prominence, not height. Held to 0 to 100.
[minProminence] minProminence	number 6	Sets or retrieves how far a peak must stand above its surroundings to be marked, in the level scale's own unit, decibels, or linear magnitude. It keeps one strong tone's sidelobes from being reported as three peaks. Not below 0; not a number uses 6.
[showThd] showThd	boolean false	Determines whether total harmonic distortion is measured against the strongest peak and shown in the readout, as a percentage and in dB. Requires amplitude scaling.
[harmonics] harmonics	number 5	Sets or retrieves how many harmonics the THD measurement includes. Held to 1 to 100.
[markers] markers	array	Sets or retrieves markers placed by the application as [{ frequency, label }], drawn as labelled vertical lines, for example at the line frequency, a shaft speed, a bearing defect frequency or a filter corner, so the peaks can be compared with the expected frequencies.
[showGrid] showGrid	boolean true	Determines whether the grid and axis labels are drawn.
[showReadout] showReadout	boolean true	Determines whether the peak list and the THD value are shown as text under the plot. The readout is what a screen reader and a report receive; the markers on the canvas show the same information graphically.
[showHeader] showHeader	boolean true	Determines whether the header, sample rate, transform size, bin width, window, scaling and averaging state, is shown.
[paused] paused	boolean false	Determines whether pushed blocks are dropped. The display holds its last spectrum.
[label] label	string	Sets or retrieves the name of the channel, shown in the header and in the accessible name.
[unit] unit	string	Sets or retrieves the unit of the signal, for example V, g or Pa, so that a level is shown as dBV rather than dB and a linear level carries its unit.
[precisionDigits] precisionDigits	number 1	Sets or retrieves how many decimal places a level is printed with in the readout and peak labels. Held to 0 to 20.
[lineWidth] lineWidth	number 1.2	Sets or retrieves the width of the trace in pixels.

Methods

Method	Description
push(samples: any): Promise<any> and pushSync(samples: any): boolean	Analyses the next block of samples and redraws. The block is copied, so a DAQ can pass the same buffer each time. Averaging and max hold accumulate across pushes. Samples that are not numbers (NaN, null, an infinite value) are analysed as zeros, which lowers the levels by an amount that depends on how many there were, so the block is never passed off as clean: the header shows "2 of 4096 samples were not numbers (analysed as 0)", the accessible name and spectrumChange carry the count, and the console says so once per run of such blocks. A block with no number in it is not analysed. Returns false when the analyzer is paused and the block was dropped. samples array The samples, as an array or a typed array.
clear(): void	Clears the running average and the held maximum and restarts them from the block on screen.
spectrum(): Promise<any> and spectrumSync(): any	Returns the spectrum as currently shown, as { frequencies, magnitudes, levels, hold, binWidth, size, window, invalidSamples }, where levels are in the level scale, magnitudes are the linear values after averaging, hold is the max-hold trace or null, and invalidSamples is how many samples of the block were not numbers. Returns null before the first signal, and while the sample rate is not a positive number.
peaks(): Promise<any> and peaksSync(): any	Returns the marked peaks, strongest first, as [{ frequency, level, magnitude, index, prominence }].
invalidate(): void	Redraws the plot on the next animation frame, so that many pushes between two frames cost one draw.

Events

The data of an event is in event.detail. spectrumChange reports a new analysis after the application pushes a block or sets signal. Blocks pushed while paused is true are dropped and raise nothing.

Output

Description and detail

(onSpectrumChange) spectrumChange

This event is triggered after each block is analysed, with the peaks found on the displayed trace. peaks any[] The marked peaks, strongest first, as [{ frequency, level, magnitude, index, prominence }]. binWidth number The frequency resolution in hertz. size number The transform size. invalidSamples number How many samples of the block were not numbers and were analysed as zeros; 0 for a clean block.

Types

type SpectrumWindow

'rectangular' | 'hann' | 'hamming' | 'blackman' | 'blackman-harris' | 'flat-top'

type SpectrumScaling

'amplitude' | 'power' | 'density'

type SpectrumLevelScale

'db' | 'linear'

type SpectrumFrequencyScale

'linear' | 'log'

type SpectrumAveraging

'none' | 'linear' | 'exponential'

CSS variables

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

--smart-spectrum-height --smart-spectrum-plot-background --smart-spectrum-grid-color