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 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
sourceimpl FrequencySpectrum
impl FrequencySpectrum
sourcepub fn new(
data: Vec<(Frequency, FrequencyValue)>,
frequency_resolution: f32,
samples_len: u32
) -> Self
pub fn new(
data: Vec<(Frequency, FrequencyValue)>,
frequency_resolution: f32,
samples_len: u32
) -> 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.
sourcepub fn apply_scaling_fn(
&self,
scaling_fn: SpectrumScalingFunction<'_>
) -> Result<(), SpectrumAnalyzerError>
pub fn apply_scaling_fn(
&self,
scaling_fn: SpectrumScalingFunction<'_>
) -> Result<(), SpectrumAnalyzerError>
Applies the function scaling_fn
to each element and updates
min
, max
, etc. afterwards accordingly. It ensures that no value
is NaN
or Infinity
afterwards (regarding IEEE-754).
Parameters
scaling_fn
Seecrate::scaling::SpectrumScalingFunction
.
sourcepub fn average(&self) -> FrequencyValue
pub fn average(&self) -> FrequencyValue
Returns the average frequency value of the spectrum.
sourcepub fn median(&self) -> FrequencyValue
pub fn median(&self) -> FrequencyValue
Returns the median frequency value of the spectrum.
sourcepub fn max(&self) -> (Frequency, FrequencyValue)
pub fn max(&self) -> (Frequency, FrequencyValue)
Returns the maximum (frequency, frequency value)-pair of the spectrum (regarding the frequency value).
sourcepub fn min(&self) -> (Frequency, FrequencyValue)
pub 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 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 to_map(
&self,
scale_fn: Option<&dyn Fn(f32) -> u32>
) -> BTreeMap<u32, f32>
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
sourceimpl Debug for FrequencySpectrum
impl Debug for FrequencySpectrum
sourceimpl Default for FrequencySpectrum
impl Default for FrequencySpectrum
sourcefn default() -> FrequencySpectrum
fn default() -> FrequencySpectrum
Returns the “default value” for a type. Read more
Auto Trait Implementations
impl !RefUnwindSafe for FrequencySpectrum
impl Send for FrequencySpectrum
impl !Sync for FrequencySpectrum
impl Unpin for FrequencySpectrum
impl UnwindSafe for FrequencySpectrum
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more