echomap::FrequencySpectrumFactory Class Reference

Provides a static helper to perform discrete Fourier transforms on Signal objects to produce frequency spectra. More...

#include <FrequencySpectrumFactory.hpp>

Static Public Member Functions
static std::unique_ptr< FrequencySpectrum >	create_frequency_spectrum (const Signal &signal, WindowFunctions::AllFunctions window_function, std::size_t transform_size)
	Construct a FrequencySpectrum of the given uniformly sampled Signal.

Static Private Member Functions
static float	prepare_input (const FFTWBuffers &buffers, WindowFunctions::AllFunctions window_function, std::span< const Signal::Sample::AmplitudeT > input)
	Copies and prepare the input amplitude time-series for FFT with the given window function preference.
static Signal::Sample::AmplitudeT	amplitude_to_dbfs (Signal::Sample::AmplitudeT amplitude) noexcept
	Convert an amplitude to a dBfs (decibels relative to full-scale) quantity.

Detailed Description

Provides a static helper to perform discrete Fourier transforms on Signal objects to produce frequency spectra.

Definition at line 27 of file FrequencySpectrumFactory.hpp.

Member Function Documentation

amplitude_to_dbfs()

Signal::Sample::AmplitudeT echomap::FrequencySpectrumFactory::amplitude_to_dbfs ( Signal::Sample::AmplitudeT amplitude )

staticnodiscardprivatenoexcept

Convert an amplitude to a dBfs (decibels relative to full-scale) quantity.

Parameters

amplitude

The linear amplitude.

Returns

The dBfs quantisation of the linear amplitude.

Definition at line 107 of file FrequencySpectrumFactory.cpp.

{
#if defined(__EMSCRIPTEN__) || defined(__DOXYGEN__)
    constexpr auto full = std::max(web::abs(Signal::normalised_range.first), web::abs(Signal::normalised_range.second));
#else
    constexpr auto full = std::max(std::abs(Signal::normalised_range.first), std::abs(Signal::normalised_range.second));
#endif
    assert(full > 0.0f);
 
    constexpr auto maximum_ratio = 1.0e-6f; // 20log_{10}(1e-6) = -120dB.
    return 20.0f * std::log10(std::max(std::abs(amplitude) / full, maximum_ratio));
}

create_frequency_spectrum()

std::unique_ptr< FrequencySpectrum > echomap::FrequencySpectrumFactory::create_frequency_spectrum ( const Signal & signal, WindowFunctions::AllFunctions window_function, std::size_t transform_size )

staticnodiscard

Construct a FrequencySpectrum of the given uniformly sampled Signal.

Parameters

signal	The uniformly sampled Signal of which to take the DFT.
window_function	The window function to apply onto the input time-series.
transform_size	The number of samples in the transform window.

Returns

An owning container of the created FrequencySpectrum.

Exceptions

std::runtime_error	The given Signal was not uniformly sampled; hence, a DFT is not applicable.
std::runtime_error	FFTW failed to initialise.

Definition at line 27 of file FrequencySpectrumFactory.cpp.

{
    if (!signal.is_uniformly_sampled())
        throw std::runtime_error(std::format("Attempted to transform variably sampled {}.", signal.get_name()));
 
    const auto display_name = std::format(
            "{} ({} DFT @ {})",
            signal.get_name(),
            WindowFunctions::get_window_name<WindowFunctions::Constant>(),
            transform_size
    );
 
    if (transform_size == 0)
        return std::unique_ptr<FrequencySpectrum>(new FrequencySpectrum(window_function, display_name));
 
    // Create FFTW buffers, making a separate input buffer if and only if we're using a non-constant input transform.
    const FFTWBuffers context(
            transform_size,
            std::holds_alternative<WindowFunctions::Constant>(window_function) ? std::make_optional(signal.amplitudes())
                                                                               : std::nullopt
    );
 
    // Pre-process input as advised by the window function.
    const auto scale_divisor = prepare_input(context, window_function, signal.amplitudes());
 
    // Create a plan, do the FFT, and clean up. (Buffers are RAII scoped to this function.)
    const fftwf_plan plan = // NOLINT(*-misplaced-const) - Declaration is correct.
            fftwf_plan_dft_r2c_1d(static_cast<int>(transform_size), context.input, context.coefficients, FFTW_ESTIMATE);
 
    if (plan == nullptr)
        throw std::runtime_error("Failed to create an FFTW plan.");
 
    fftwf_execute(plan);
    fftwf_destroy_plan(plan);
 
    // Construct the FrequencySpectrum from the coefficients.
    const auto bin_count = transform_size / 2 + 1;
    auto spectrum = std::unique_ptr<FrequencySpectrum>(new FrequencySpectrum(window_function, display_name));
    spectrum->reserve_bins(bin_count);
 
    for (std::size_t bin_idx = 0; bin_idx < bin_count; ++bin_idx) {
        const auto is_dc = bin_idx == 0;
        const auto is_nyquist = transform_size % 2 == 0 && bin_idx == transform_size / 2;
        const auto scale = (is_dc || is_nyquist ? 1.0f : 2.0f) / scale_divisor;
 
        const auto real = context.coefficients[bin_idx][0];
        const auto imag = context.coefficients[bin_idx][1];
        const auto linear_amplitude = std::sqrt(real * real + imag * imag) * scale;
 
        spectrum->emplace_bin(
                static_cast<float>(bin_idx) * static_cast<float>(signal.get_sample_rate()) /
                        static_cast<float>(transform_size),
                amplitude_to_dbfs(linear_amplitude),
                std::atan2(imag, real)
        );
    }
 
    return spectrum;
}

prepare_input()

float echomap::FrequencySpectrumFactory::prepare_input ( const FFTWBuffers & buffers, WindowFunctions::AllFunctions window_function, std::span< const Signal::Sample::AmplitudeT > input )

staticprivate

Copies and prepare the input amplitude time-series for FFT with the given window function preference.

Parameters

buffers	Initialised FFTWBuffers for the input.
window_function	Selector for the window function to use.
input	The amplitude series.

Returns

The scaling divisor constant used for computing the magnitude.

Precondition

The size of the given input range is at least the transform size specified by the FFTWBuffers object.

Definition at line 91 of file FrequencySpectrumFactory.cpp.

{
    assert(input.size() >= buffers.input_size);
 
    return std::visit(
            [&buffers, &input]<WindowFunction WindowT>(WindowT) {
                return WindowFunctions::apply_window<WindowT>(buffers, input);
            },
            window_function
    );
}

---

The documentation for this class was generated from the following files:

• src/objects/factories/FrequencySpectrumFactory.hpp
• src/objects/factories/FrequencySpectrumFactory.cpp