Struct FrequencySpectrum 

pub struct FrequencySpectrum { /* private fields */ }

Convenient wrapper around the processed FFT result.

This is the result produced by samples_fft_to_spectrum. It describes each frequency and its corresponding value (magnitude) from the analyzed samples, according to the provided input parameters. The data is scaled/normalized according to the optionally applied scaling function.

Unless frequencies were explicitly excluded, the spectrum covers the full range from the DC component (0 Hz) up to the Nyquist frequency with the frequency resolution derived from the input data.

Implementations

impl FrequencySpectrum

pub fn apply_scaling_fn( &mut self, scaling_fn: &SpectrumScalingFunction, ) -> Result<(), SpectrumAnalyzerError>

Applies the function scaling_fn to each element and updates several metrics about the spectrum, such as min and max, afterwards accordingly. It ensures that no value is NaN or Infinity (regarding IEEE-754) after scaling_fn was applied. Otherwise, SpectrumAnalyzerError::ScalingError is returned.

Parameters

• scaling_fn See SpectrumScalingFunction.

pub const fn average(&self) -> FrequencyValue

Returns the average frequency value of the spectrum.

pub const fn max(&self) -> (Frequency, FrequencyValue)

Returns the maximum (frequency, frequency value)-pair of the spectrum regarding the frequency value.

pub const fn min(&self) -> (Frequency, FrequencyValue)

Returns the minimum (frequency, frequency value)-pair of the spectrum regarding the frequency value.

pub fn range(&self) -> FrequencyValue

Returns FrequencySpectrum::max().1 subtracted by FrequencySpectrum::min().1, i.e. the range of the frequency values (not the frequencies itself, but their values).

pub fn data(&self) -> &[(Frequency, FrequencyValue)]

Returns the underlying sorted data.

pub const fn frequency_resolution(&self) -> Frequency

Returns the frequency resolution of this spectrum.

pub const fn samples_len(&self) -> u32

Returns the number of samples used to obtain this spectrum.

pub fn max_fr(&self) -> Frequency

Getter for the highest frequency that is captured inside this spectrum. Shortcut for spectrum.data()[spectrum.data().len() - 1].0. This corresponds to the crate::limit::FrequencyLimit of the spectrum.

This method could return the Nyquist frequency, if there was no Frequency limit while obtaining the spectrum.

pub fn min_fr(&self) -> Frequency

Getter for the lowest frequency that is captured inside this spectrum. Shortcut for spectrum.data()[0].0. This corresponds to the crate::limit::FrequencyLimit of the spectrum.

This method could return the DC component, see Self::dc_component.

pub fn dc_component(&self) -> Option<FrequencyValue>

Returns the DC Component or also called DC bias which corresponds to the FFT result at index 0 which corresponds to 0Hz. This is only present if the frequencies were not limited to for example 100 <= f <= 10000 when the libraries main function was called.

Note that the unscaled value is N times the mean of the (windowed) samples, not the mean itself. See crate::samples_fft_to_spectrum.

More information: https://dsp.stackexchange.com/questions/12972/discrete-fourier-transform-what-is-the-dc-term-really

Excerpt: As far as practical applications go, the DC or 0 Hz term is not particularly useful. In many cases it will be close to zero, as most signal processing applications will tend to filter out any DC component at the analogue level. In cases where you might be interested it can be calculated directly as an average in the usual way, without resorting to a DFT/FFT. - Paul R.

pub fn freq_val_exact(&self, search_fr: f32) -> Option<FrequencyValue>

Returns the value of the given frequency from the spectrum either exactly or approximated.

If the value is out of bounds, the function returns None.

If search_fr is not exactly given in the spectrum, i.e. due to the Self::frequency_resolution, this function takes the two closest neighbors/points (A, B), put a linear function through them and calculates the point C in the middle. This is done by the private function calculate_y_coord_between_points.

The interpolated value only follows the shape of the spectrum. It is not the value a sine wave of exactly search_fr would have, because such a sine wave leaks into the neighboring bins.

Parameters

• search_fr The frequency of that you want the value in the spectrum.

pub fn freq_val_closest( &self, search_fr: f32, ) -> Option<(Frequency, FrequencyValue)>

Returns the frequency closest to parameter search_fr in the spectrum.

If the value is out of bounds, the function returns None.

For example, if the spectrum looks like this:

Vector:    [0]      [1]      [2]      [3]
Frequency  100 Hz   200 Hz   300 Hz   400 Hz
Fr Value   0.0      1.0      0.5      0.1

then get_frequency_value_closest(320) will return (300.0, 0.5).

Parameters

• search_fr The frequency of that you want the value in the spectrum.

pub fn to_vec(&self) -> Vec<(f32, f32)>

Returns a sorted Vec with all value pairs as f32.

Trait Implementations

impl Debug for FrequencySpectrum

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.