Struct spectrum_analyzer::FrequencySpectrum

pub struct FrequencySpectrum { /* private fields */ }

Convenient wrapper around the processed FFT result which describes each frequency and its value/amplitude from the analyzed samples. It only contains the frequencies that were desired, e.g., specified via crate::limit::FrequencyLimit when crate::samples_fft_to_spectrum was called.

This means, the spectrum can cover all data from the DC component (0Hz) to the Nyquist frequency.

All results are related to the sampling rate provided to the library function which creates objects of this struct!

This struct can be shared across thread boundaries.

Implementations

impl FrequencySpectrum

pub fn new( data: Vec<(Frequency, FrequencyValue)>, frequency_resolution: f32, samples_len: u32, working_buffer: &mut [(Frequency, FrequencyValue)] ) -> Self

Creates a new object. Calculates several metrics from the data in the given vector.

Parameters

• data Vector with all (Frequency, FrequencyValue)-tuples
• frequency_resolution Resolution in Hertz. This equals to data[1].0 - data[0].0.
• samples_len Number of samples. Might be bigger than data.len() if the spectrum is obtained with a frequency limit.
• working_buffer Mutable buffer with the same length as data required to calculate certain metrics.

pub fn apply_scaling_fn( &mut self, scaling_fn: &SpectrumScalingFunction, working_buffer: &mut [(Frequency, FrequencyValue)] ) -> 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 crate::scaling::SpectrumScalingFunction.

pub const fn average(&self) -> FrequencyValue

Returns the average frequency value of the spectrum.

pub const fn median(&self) -> FrequencyValue

Returns the median 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] - [FrequencySpectrum::min().1], i.e. the range of the frequency values (not the frequencies itself, but their amplitudes/values).

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

Returns the underlying data.

pub const fn frequency_resolution(&self) -> f32

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.

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) -> FrequencyValue

Returns the value of the given frequency from the spectrum either exactly or approximated. 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.

Panics

If parameter search_fr (frequency) is below the lowest or the maximum frequency, this function panics! This is because the user provide the min/max frequency when the spectrum is created and knows about it. This is similar to an intended “out of bounds”-access.

Parameters

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

Return

Either exact value of approximated value, determined by Self::frequency_resolution.

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

Returns the frequency closest to parameter search_fr in the spectrum. 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).

Panics

If parameter search_fre (frequency) is below the lowest or the maximum frequency, this function panics!

Parameters

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

Return

Closest matching point in spectrum, determined by Self::frequency_resolution.

pub fn mel_val(&self, mel_val: f32) -> FrequencyValue

Wrapper around Self::freq_val_exact that consumes mel.

pub fn to_map(&self) -> BTreeMap<u32, f32>

Returns a BTreeMap with all value pairs. The key is of type u32 because f32 is not Ord.

pub fn to_mel_map(&self) -> BTreeMap<u32, f32>

Like Self::to_map but converts the frequency (x-axis) to mels. The resulting map contains more results in a higher density the higher the mel value gets. This comes from the logarithmic transformation from hertz to mels.

Trait Implementations

impl Debug for FrequencySpectrum

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

Formats the value using the given formatter.

impl Default for FrequencySpectrum

fn default() -> FrequencySpectrum

Returns the “default value” for a type.