Test and measurement

Octave Bands `<smart-octave-bands>`

OctaveBands displays the level in each octave or third-octave band as a bar, with the frequency-weighted overall level and a limit curve the bands are checked against: the display of a sound level meter and of a vibration survey.

JavaScript TypeScript Angular React Vue Blazor

<smart-octave-bands> · 19 properties, 7 methods, 2 events · source/modules/smart.octavebands.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.octavebands.js';

<smart-octave-bands ref="octaveBands" :resolution="'octave'"
    @levelsChange="onEvent"></smart-octave-bands>

// methods are called on the element the ref holds
octaveBands.value.push({});

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

Properties

Binding	Type, default	Description
`:resolution` resolution	OctaveBandsResolution third	Sets or retrieves the band width: whole octaves or third octaves.
`:sample-rate` sampleRate	number 48000	Sets or retrieves the sample rate of pushed blocks, in samples per second. A band is shown only when all of it lies below half the sample rate. A value that is not a positive number analyses nothing: push() returns false, the header says so, and one console warning names the value; assigned levels are still shown.
`:size` size	number 0	Sets or retrieves the FFT size a pushed block is analysed with. 0 uses the block's own length. Held to 16,777,216 at most.
`:frequency-min` frequencyMin	number 20	Sets or retrieves the centre frequency of the lowest band shown. Set above frequencyMax, the two are swapped, with one console warning, rather than leaving the chart empty.
`:frequency-max` frequencyMax	number 20000	Sets or retrieves the centre frequency of the highest band shown. Bands whose upper edge lies above half the sample rate are not shown whatever this says: at a sample rate of 8 kHz the 4 kHz third-octave band, which runs to 4.49 kHz, would be summed from the bins that exist and read low.
`:weighting` weighting	OctaveBandsWeighting Z	Sets or retrieves the frequency weighting applied to each band and to the overall level: Z (none), A or C, per IEC 61672.
`:reference` reference	number 1	Sets or retrieves what reads as 0 dB: 1 for dB re one unit of the signal, 0.00002 for dB SPL of a signal in pascal.
`:unit` unit	string	Sets or retrieves the signal's unit, so a level reads dBV or, with the 20 µPa reference, dB SPL.
`:averaging` averaging	OctaveBandsAveraging fast	Sets or retrieves the exponential time weighting of the bars: none, fast (125 ms) or slow (1 s), as a meter's.
`:peak-hold` peakHold	boolean true	Keeps the highest level of each band as a marker.
`:levels` levels	array	Sets or retrieves the level of each band in dB, in the order of bands(). Assigned by an application with its own filter bank, or computed by push.
`:limit` limit	array	Sets or retrieves the limit the bands are checked against: a level per band in dB, or [{ frequency, level }] points interpolated across the bands on the log axis. A band above its limit is drawn in the exceeded colour and counted in the header. A null or non-numeric per-band value is no limit for that band; a point that is not an object with a frequency and a level is skipped. Either is said once in a console warning.
`:level-min` levelMin	number?	Sets or retrieves the bottom of the level axis in dB. Null follows the data. With levelMax set below it, the two are swapped; set equal, the axis follows the data. Either is said once in a console warning.
`:level-max` levelMax	number?	Sets or retrieves the top of the level axis in dB. Null follows the data. Fixes the axis together with levelMin.
`:show-overall` showOverall	boolean true	Shows the overall level in the header.
`:show-grid` showGrid	boolean true	Shows the grid lines at the level ticks.
`:paused` paused	boolean false	Drops pushed blocks while set.
`:label` label	string	Sets or retrieves the title shown in the header and used in the accessible name.
`:precision-digits` precisionDigits	number 1	Sets or retrieves the number of decimals in levels, held to 0 to 20.

Methods

Method	Description
`push(block: any): boolean`	Analyses a block of samples into band levels and shows them, with averaging and peak hold applied. Samples that are not numbers are analysed as zeros, and never passed off as clean: the header shows how many, levelsChange carries the count, and the console says so once per run of such blocks. Returns false, and analyses nothing, when the analyser is paused, when Smart.DSP is not loaded, when the block is not an array of at least two samples or has no number in it, or when the sample rate is not a positive number. `block` any The samples, as an array or a typed array.
`bands(): array`	Returns the bands shown: [{ centre, low, high, label, index }], centres on the IEC 61260 base-10 series, between frequencyMin and frequencyMax, and only bands whose upper edge lies below half the sample rate.
`overall(): number`	Returns the overall level: the levels of the bands summed on energy, in dB, or NaN with no levels.
`clear(): void`	Clears the levels and the peaks.
`resetPeaks(): void`	Drops the held peaks.
`describe(): string`	Returns a sentence describing what the analyser shows, as used in its accessible name: the bands, the overall level, the highest band and the number above the limit (exceededSummaryOne for one).
`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. levelsChange reports levels the component has already computed from a pushed block and written to levels; blocks pushed while paused is true are dropped and raise nothing. bandClick reports a click on a band and changes nothing.

Event	Description and detail
`@levelsChange`	This event is triggered after a pushed block has been analysed. `levels` array The level of each band, in dB. `overall` number The overall level, in dB. `invalidSamples` number How many samples of the block were not numbers and were analysed as zeros; 0 for a clean block.
`@bandClick`	This event is triggered when a band is clicked. `index` number The band. `centre` number Its centre frequency. `label` string Its nominal frequency. `level` number Its level. `peak` number Its held peak.

Types

`type OctaveBandsResolution`

'octave' | 'third'

`type OctaveBandsWeighting`

'Z' | 'A' | 'C'

`type OctaveBandsAveraging`

'none' | 'fast' | 'slow'

CSS variables

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

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