Struct spectrum_analyzer::FrequencySpectrum
source · pub struct FrequencySpectrum { /* private fields */ }
Expand description
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§
source§impl FrequencySpectrum
impl FrequencySpectrum
sourcepub fn new(
data: Vec<(Frequency, FrequencyValue)>,
frequency_resolution: f32,
samples_len: u32,
working_buffer: &mut [(Frequency, FrequencyValue)]
) -> Self
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
)-tuplesfrequency_resolution
Resolution in Hertz. This equals todata[1].0 - data[0].0
.samples_len
Number of samples. Might be bigger thandata.len()
if the spectrum is obtained with a frequency limit.working_buffer
Mutable buffer with the same length asdata
required to calculate certain metrics.
sourcepub fn apply_scaling_fn(
&mut self,
scaling_fn: &SpectrumScalingFunction,
working_buffer: &mut [(Frequency, FrequencyValue)]
) -> Result<(), SpectrumAnalyzerError>
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
Seecrate::scaling::SpectrumScalingFunction
.
sourcepub const fn average(&self) -> FrequencyValue
pub const fn average(&self) -> FrequencyValue
Returns the average frequency value of the spectrum.
sourcepub const fn median(&self) -> FrequencyValue
pub const fn median(&self) -> FrequencyValue
Returns the median frequency value of the spectrum.
sourcepub const fn max(&self) -> (Frequency, FrequencyValue)
pub const fn max(&self) -> (Frequency, FrequencyValue)
Returns the maximum (frequency, frequency value)-pair of the spectrum regarding the frequency value.
sourcepub const fn min(&self) -> (Frequency, FrequencyValue)
pub const fn min(&self) -> (Frequency, FrequencyValue)
Returns the minimum (frequency, frequency value)-pair of the spectrum regarding the frequency value.
sourcepub fn range(&self) -> FrequencyValue
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).
sourcepub fn data(&self) -> &[(Frequency, FrequencyValue)]
pub fn data(&self) -> &[(Frequency, FrequencyValue)]
Returns the underlying data.
sourcepub const fn frequency_resolution(&self) -> f32
pub const fn frequency_resolution(&self) -> f32
Returns the frequency resolution of this spectrum.
sourcepub const fn samples_len(&self) -> u32
pub const fn samples_len(&self) -> u32
Returns the number of samples used to obtain this spectrum.
sourcepub fn max_fr(&self) -> Frequency
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.
sourcepub fn min_fr(&self) -> Frequency
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
.
sourcepub fn dc_component(&self) -> Option<FrequencyValue>
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.
sourcepub fn freq_val_exact(&self, search_fr: f32) -> FrequencyValue
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
.
sourcepub fn freq_val_closest(&self, search_fr: f32) -> (Frequency, FrequencyValue)
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
.
sourcepub fn mel_val(&self, mel_val: f32) -> FrequencyValue
pub fn mel_val(&self, mel_val: f32) -> FrequencyValue
Wrapper around Self::freq_val_exact
that consumes mel.
sourcepub fn to_mel_map(&self) -> BTreeMap<u32, f32>
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.