Struct spectrum_analyzer::FrequencySpectrum

pub struct FrequencySpectrum { /* fields omitted */ }

Convenient wrapper around the processed FFT result which describes each frequency and its value/amplitude in the analyzed slice of samples. It only consists of the frequencies which 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!

Implementations

impl FrequencySpectrum

pub fn new(
    data: Vec<(Frequency, FrequencyValue)>,
    frequency_resolution: f32
) -> Self

Creates a new object. Calculates several metrics on top of the passed vector.

Parameters

• data Vector with all (Frequency, FrequencyValue)-tuples
• frequency_resolution Resolution in Hertz. This equals to data[1].0 - data[0].0.

pub fn apply_complex_scaling_fn(
    &self,
    total_scaling_fn: ComplexSpectrumScalingFunction
)

Applies the function generated by total_scaling_fn to each element and updates min, max, etc. afterwards accordingly.

Parameters

• total_scaling_fn See [crate::spectrum::SpectrumTotalScaleFunctionFactory].

pub fn average(&self) -> FrequencyValue

Getter for FrequencySpectrum::average.

pub fn median(&self) -> FrequencyValue

Getter for FrequencySpectrum::median.

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

Getter for FrequencySpectrum::max.

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

Getter for FrequencySpectrum::min.

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 amplitude/value).

pub fn data(&self) -> Ref<'_, Vec<(Frequency, FrequencyValue)>>

Getter for FrequencySpectrum::data.

pub fn frequency_resolution(&self) -> f32

Getter for FrequencySpectrum::frequency_resolution.

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.

pub fn min_fr(&self) -> Frequency

Getter for the highest frequency that is captured inside this spectrum. Shortcut for spectrum.data()[0].0.

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 using [calculate_point_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 to_map(
    &self,
    scale_fn: Option<&dyn Fn(f32) -> u32>
) -> BTreeMap<u32, f32>

Returns a BTreeMap. The key is of type u32. (f32 is not Ord, hence we can’t use it as key.) You can optionally specify a scale function, e.g. multiply all frequencies with 1000 for better accuracy when represented as unsigned integer.

Parameters

• scale_fn optional scale function, e.g. multiply all frequencies with 1000 for better accuracy when represented as unsigned integer.

Return

New BTreeMap from frequency to frequency value.

Trait Implementations

impl Debug for FrequencySpectrum

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

Formats the value using the given formatter.