echomap::SignalFactory Class Reference

Provides various convenience functions for constructing Signal objects in exotic ways. More...

#include <SignalFactory.hpp>

Public Member Functions
	SignalFactory ()
	Begin constructing a new Signal.
bool	operator== (const SignalFactory &other) const
bool	operator< (const SignalFactory &other) const
std::unique_ptr< Signal >	take_signal () noexcept
const Signal &	observe_signal () const noexcept
void	emplace_sample (Signal::Sample::AmplitudeT amplitude) const
void	emplace_sample (const Signal::Sample &sample) const
void	emplace_sample (Signal::Sample::TimeT time, Signal::Sample::AmplitudeT amplitude) const
void	emplace_sample_from_source (Signal::Sample::AmplitudeT amplitude) const
void	emplace_sample_from_source (const Signal::Sample &sample) const
void	emplace_sample_from_source (Signal::Sample::TimeT time, Signal::Sample::AmplitudeT amplitude) const
void	set_signal_name (std::string_view name) const
void	set_time_offset (Signal::Sample::TimeT time_offset) const noexcept
void	set_sample_rate (std::size_t sample_rate) const noexcept
void	set_source (const std::filesystem::path &path, std::size_t channel) const

Static Public Member Functions
static std::vector< std::unique_ptr< Signal > >	load_wave_file (const char *file_path)
	Loads a WAV file from the file system.
static void	load_wave_file (const char *file_path, const std::span< SignalFactory *const > channel_factories)
	Loads a WAV file from the file system.
static std::unique_ptr< Signal >	downsample (const Signal &source, float downsample_factor, std::string_view name={})
	Downsamples an existing Signal instance across all channels to the given number of samples.

Static Private Member Functions
static void	load_wave_file_into_channels (drwav &drwav_info, std::string_view file_path, std::span< Signal *const > signal_ptrs)
	Loads the time-series sampled data into the given Signal objects.
static std::unique_ptr< Signal >	lttb_downsample (const Signal &source, size_t threshold, std::string_view name)
	Create a new Signal by downsampling the data points of an existing Signal to the given threshold.

Private Attributes
std::unique_ptr< Signal >	target
	The Signal being built by the factory.

Detailed Description

Provides various convenience functions for constructing Signal objects in exotic ways.

The SignalFactory is the unique source of a Signal: they may not be constructed in any other way.

Definition at line 29 of file SignalFactory.hpp.

Constructor & Destructor Documentation

SignalFactory()

echomap::SignalFactory::SignalFactory

(

)

Begin constructing a new Signal.

Definition at line 25 of file SignalFactory.cpp.

                             :
    // Cannot use make_unique here since Signal c'tor is private, and SignalFactory is "just a friend".
    target(std::unique_ptr<Signal>(new Signal()))
{
}

Member Function Documentation

downsample()

std::unique_ptr< Signal > echomap::SignalFactory::downsample ( const Signal & source, float downsample_factor, std::string_view name = {} )

staticnodiscard

Downsamples an existing Signal instance across all channels to the given number of samples.

Parameters

source	The existing Signal to downsample.
downsample_factor	The factor by which the number of samples should be reduced during downsampling.
name	Optional display name. If omitted, a sensible default based on the source signal and downsampling factor will be used.

Definition at line 140 of file SignalFactory.cpp.

{
    auto sample_count = static_cast<std::uint64_t>(static_cast<float>(source.get_sample_count()) / downsample_factor);
    if (static_cast<float>(sample_count) < downsample_factor)
        sample_count = static_cast<std::uint64_t>(downsample_factor);
 
    auto downsampled = name.empty() ? lttb_downsample(
                                              source,
                                              sample_count,
                                              std::format("{} ({}x downsampled)", source.get_name(), downsample_factor)
                                      )
                                    : lttb_downsample(source, sample_count, name);
 
    LOG_F_DEBUG(
            "Created {} as {}x-LTTB variant of {} with {} samples.",
            downsampled->get_name(),
            downsample_factor,
            source.get_name(),
            downsampled->get_sample_count()
    );
 
    return downsampled;
}

emplace_sample() [1/3]

void echomap::SignalFactory::emplace_sample

(

const Signal::Sample &

sample

)

const

Definition at line 187 of file SignalFactory.cpp.

{
    target->emplace_sample(sample);
}

emplace_sample() [2/3]

void echomap::SignalFactory::emplace_sample

(

Signal::Sample::AmplitudeT

amplitude

)

const

Definition at line 180 of file SignalFactory.cpp.

{
    target->emplace_sample(amplitude);
}

emplace_sample() [3/3]

void echomap::SignalFactory::emplace_sample	(	Signal::Sample::TimeT	time,
		Signal::Sample::AmplitudeT	amplitude ) const

Definition at line 194 of file SignalFactory.cpp.

{
    target->emplace_sample(time, amplitude);
}

emplace_sample_from_source() [1/3]

void echomap::SignalFactory::emplace_sample_from_source

(

const Signal::Sample &

sample

)

const

Definition at line 209 of file SignalFactory.cpp.

{
    target->emplace_sample_from_source(sample);
}

emplace_sample_from_source() [2/3]

void echomap::SignalFactory::emplace_sample_from_source

(

Signal::Sample::AmplitudeT

amplitude

)

const

Definition at line 202 of file SignalFactory.cpp.

{
    target->emplace_sample_from_source(amplitude);
}

emplace_sample_from_source() [3/3]

void echomap::SignalFactory::emplace_sample_from_source	(	Signal::Sample::TimeT	time,
		Signal::Sample::AmplitudeT	amplitude ) const

Definition at line 216 of file SignalFactory.cpp.

{
    target->emplace_sample_from_source(time, amplitude);
}

load_wave_file() [1/2]

std::vector< std::unique_ptr< Signal > > echomap::SignalFactory::load_wave_file ( const char * file_path )

staticnodiscard

Loads a WAV file from the file system.

The Signal objects are constructed by this function, with default names, in the order of the channels in the wave file. That is, the first Signal will represent the first channel in the file, etc.

Parameters

file_path

The location of the WAV on the local file system.

Exceptions

ConfigurationError

The WAV file could not be loaded.

Returns

Series of owned Signal objects, one for each channel.

Definition at line 63 of file SignalFactory.cpp.

{
    drwav drwav_info;
    if (drwav_init_file(&drwav_info, file_path, nullptr) == 0u)
        throw ConfigurationError("Cannot open WAV file at " + std::string(file_path));
 
    const auto typed_path = std::filesystem::path(file_path);
    std::vector<std::unique_ptr<Signal>> signals;
    signals.resize(drwav_info.channels);
 
    std::size_t channel_num = 1;
    for (auto& channel : signals) {
        const auto formatted_name = std::format("{}#{}", typed_path.stem().c_str(), channel_num);
        channel = std::unique_ptr<Signal>(new Signal(formatted_name, Signal::Source(typed_path, channel_num)));
        ++channel_num;
    }
 
    try {
        std::vector<Signal*> signal_ptrs;
        signal_ptrs.reserve(signals.size());
        std::ranges::transform(
                signals,
                std::back_inserter(signal_ptrs),
                [](const std::unique_ptr<Signal>& signal) -> Signal* {
                    return signal.get();
                }
        );
 
        load_wave_file_into_channels(drwav_info, file_path, signal_ptrs);
    } catch (const std::runtime_error&) {
        drwav_uninit(&drwav_info);
        throw;
    }
 
    drwav_uninit(&drwav_info);
    return signals;
}

load_wave_file() [2/2]

void echomap::SignalFactory::load_wave_file ( const char * file_path, const std::span< SignalFactory *const > channel_factories )

static

Loads a WAV file from the file system.

The Signal objects are not directly constructed by this function. As many constructed SignalFactory objects as there are channels in the wave file must be provided through the SignalFactory spanning range.

Parameters

file_path

The location of the WAV on the local file system.

channel_factories

Destination factories of the Signal channels. In particular, a list of pointers to SignalFactory, each of which is constructing the Signal to receive the channel at the corresponding index. For each entry at index idx: If channels[idx] == nullptr, the wave file channel idx is ignored; or If channels[idx] != nullptr, the wave file channel idx is written to the Signal being constructed by the SignalFactory channels[idx].

Exceptions

ConfigurationError

The WAV file could not be loaded.

Precondition

There are sufficient SignalFactory objects in the destination range to store channels in the wave file.

Definition at line 103 of file SignalFactory.cpp.

{
    drwav drwav_info;
    if (drwav_init_file(&drwav_info, file_path, nullptr) == 0u)
        throw ConfigurationError("Cannot open WAV file at " + std::string(file_path));
 
    assert(drwav_info.channels >= channel_factories.size());
 
    try {
        /*
         * For convenience of callers, this function takes a span of factories responsible for constructing the signals
         * for each of the channel slots, rather than the signals themselves. But for portability and simplicity, our
         * internal functions need the signals directly. Hence, we cheaply construct a span-compliant collection of the
         * mutating signal pointers, accessible to us as private member variables.
         */
        std::vector<Signal*> channels;
        channels.resize(drwav_info.channels, nullptr);
 
        std::size_t channel_idx = 0;
        for (const auto* const factory : channel_factories) {
            if (factory != nullptr && factory->target != nullptr)
                channels[channel_idx] = factory->target.get();
            ++channel_idx;
        }
 
        load_wave_file_into_channels(drwav_info, file_path, channels);
    } catch (const std::runtime_error&) {
        drwav_uninit(&drwav_info);
        throw;
    }
 
    drwav_uninit(&drwav_info);
}

load_wave_file_into_channels()

void echomap::SignalFactory::load_wave_file_into_channels ( drwav & drwav_info, std::string_view file_path, std::span< Signal *const > signal_ptrs )

staticprivate

Loads the time-series sampled data into the given Signal objects.

Parameters

drwav_info	The initialised and loaded dr_wav control structure.
file_path	The location of the WAV on the local file system.
signal_ptrs	Destination of the Signal channels.

Precondition

There are sufficient Signal objects in the destination range to store channels in the wave file.

See also

load_wave_file(const char*, mutable_signal_range auto&&) for semantics of the destination channels parameter.

Definition at line 253 of file SignalFactory.cpp.

{
    assert(drwav_info.channels <= std::ranges::size(signal_ptrs));
 
    for (auto* const channel : signal_ptrs)
        if (channel != nullptr) {
            channel->reserve_samples(drwav_info.totalPCMFrameCount);
            channel->set_sample_rate(drwav_info.sampleRate);
        }
 
    /*
     * Dr_WAV provides audio data as amplitudes uniformly interleaved across the channels. That is, for a stereo signal,
     * data is provided in the pattern L0, R0, L1, R1, ..., L(N-1), R(N-1). We receive the interleaved data in chunks of
     * a fixed size and iteratively de-interleave it into our AudioPoint channels until all frames from the source file
     * have been consumed.
     */
    constexpr drwav_uint64 chunk_frame_count = 8192;
    std::vector<float> interleaved(chunk_frame_count * drwav_info.channels);
    drwav_uint64 remaining_frames = drwav_info.totalPCMFrameCount;
 
    while (remaining_frames > 0) {
        const auto frame_count = std::min(remaining_frames, chunk_frame_count);
        if (drwav_read_pcm_frames_f32(&drwav_info, frame_count, interleaved.data()) != frame_count)
            // We couldn't read the expected number of frames. drwav_init_file must've provided the wrong count.
            throw ConfigurationError("Cannot read WAV file at " + std::string(file_path) + ". Is it corrupted?");
 
        for (drwav_uint64 frame_idx = 0; frame_idx < frame_count; ++frame_idx)
            for (drwav_uint16 channel_idx = 0; channel_idx < drwav_info.channels; ++channel_idx) {
                if (auto* const destination = std::ranges::begin(signal_ptrs)[channel_idx]; destination != nullptr)
                    /*
                     * The audio data is uniformly spaced, so we can infer the time values by taking the current frame
                     * offset for the chunk (total frames - remaining frames) and adding the current frame index.
                     */
                    destination->emplace_sample_from_source(interleaved[frame_idx * drwav_info.channels + channel_idx]);
            }
 
        remaining_frames -= frame_count;
    }
 
    if (remaining_frames != 0)
        throw ConfigurationError("Cannot read entire WAV file at " + std::string(file_path) + ". Is it corrupted?");
 
    for (auto* const channel : signal_ptrs | std::views::filter([](auto ptr) { return ptr; })) {
        // Assert that any signal being constructed by these means should have an extant FS source.
        assert(channel->fs_source.has_value());
        channel->fs_source->is_loaded = true;
        LOG_F_DEBUG(
                "Loaded signal \"{}\" with {} samples at {} Hz, starting at {} s.",
                channel->get_name(),
                channel->get_sample_count(),
                channel->get_sample_rate(),
                channel->get_time_offset()
        );
    }
}

lttb_downsample()

std::unique_ptr< Signal > echomap::SignalFactory::lttb_downsample ( const Signal & source, size_t threshold, std::string_view name )

staticnodiscardprivate

Create a new Signal by downsampling the data points of an existing Signal to the given threshold.

This helper uses the well-known Largest-Triangle Three-Buckets (LTTB) downsampling algorithm, described in detail by the Master's Thesis Downsampling Time Series for Visual Representation, Sveinn Steinarsson (2013).

In addition to the thesis, reference implementations in all major languages are available online. This function uses a specialised implementation for the AudioPoint structure: https://github.com/sveinn-steinarsson/flot-downsample.

Parameters

source	The original Signal to be downsampled.
threshold	The number of samples in the downsampled data.
name	Name of the downsampled Signal.

Returns

The downsampled Signal, detained in an owning container.

Postcondition

The number of samples in the returned signal matches the threshold parameter.

Definition at line 313 of file SignalFactory.cpp.

{
    const auto source_size = source.get_sample_count();
 
    // We don't need to assert for the post-condition on these trivial cases.
 
    if (threshold == 0 || source_size == 0)
        // Base case: the user requested zero samples (empty signal), or there were no samples available in the source.
        return std::unique_ptr<Signal>(new Signal(name));
 
    if (threshold >= source_size)
        // Base case: the destination wants more samples than are available. Just copy the source signal.
        return std::make_unique<Signal>(source, name);
 
    auto downsampled = std::unique_ptr<Signal>(new Signal(name));
    downsampled->reserve_samples(threshold);
 
    if (threshold == 1) {
        // Base case: the user only wants one sample. We choose the first by convention.
        downsampled->emplace_sample(source.get_time_at_index(0), source[0]);
        return downsampled;
    }
 
    if (threshold == 2) {
        // Base case: the user only wants two samples. We choose the first and last by necessity.
        downsampled->emplace_sample(source.get_time_at_index(0), source[0]);
        downsampled->emplace_sample(source.get_time_at_index(source_size - 1), source[source_size - 1]);
        return downsampled;
    }
 
    const auto bucket_size =
            static_cast<unsigned int>(static_cast<double>(source_size - 2) / static_cast<double>(threshold - 2));
    std::size_t fixed_point_idx = 0;
 
    // Always add the first point.
    downsampled->emplace_sample(source.get_time_at_index(0), source[0]);
 
    for (std::size_t dst_point_idx = 0; dst_point_idx < threshold - 2; ++dst_point_idx) {
        Signal::Sample::TimeT average_time = 0.0f;
        Signal::Sample::AmplitudeT average_amplitude = 0.0f;
 
        // Calculate the point-average for the next bucket, containing our fixed point.
 
        const auto average_range_start = static_cast<std::size_t>(std::floor((dst_point_idx + 1) * bucket_size)) + 1;
        const auto average_range_end =
                std::min(static_cast<std::uint64_t>(std::floor((dst_point_idx + 2) * bucket_size)) + 1, source_size);
        const auto average_range_length = average_range_end - average_range_start;
 
        for (auto range_idx = average_range_start; range_idx < average_range_end; ++range_idx) {
            average_time += source.get_time_at_index(range_idx);
            average_amplitude += source[range_idx];
        }
 
        average_time /= static_cast<Signal::Sample::TimeT>(average_range_length);
        average_amplitude /= static_cast<Signal::Sample::AmplitudeT>(average_range_length);
 
        // Store the sample data at the fixed point.
        const auto fp_time = source.get_time_at_index(fixed_point_idx);
        const auto fp_amplitude = source[fixed_point_idx];
 
        // Get the range for the current bucket and compute triangle areas over the three buckets.
        const auto range_lower = static_cast<std::size_t>(std::floor(dst_point_idx * bucket_size)) + 1;
        const auto range_upper = std::min(
                static_cast<std::uint64_t>(std::floor((dst_point_idx + 1) * bucket_size)) + 1,
                source_size - 1
        );
 
        // (C++ note: we need to combine Sample::TimeT and Sample::AmplitudeT here, so float seems like a safe choice.)
        auto max_area = std::numeric_limits<float>::lowest();
        auto next_fixed_point_idx = range_lower;
 
        // Calculate triangle area formed by the vertices in the adjacent buckets, tracking the maximum.
        for (auto range_idx = range_lower; range_idx < range_upper; ++range_idx) {
            const float area = std::abs(
                    (fp_time - average_time) * (source[range_idx] - fp_amplitude) -
                    (fp_time - source.get_time_at_index(range_idx)) * (average_amplitude - fp_amplitude)
            );
 
            if (area > max_area) {
                max_area = area;
                next_fixed_point_idx = range_idx;
            }
        }
 
        /*
         * Pick the point from the bucket to include in the downsampled data, and set the index as our next starting
         * point.
         */
        downsampled->emplace_sample(source.get_time_at_index(next_fixed_point_idx), source[next_fixed_point_idx]);
 
        fixed_point_idx = next_fixed_point_idx;
    }
 
    // Always add the last point.
    downsampled->emplace_sample(source.get_time_at_index(source_size - 1), source[source_size - 1]);
 
    assert(downsampled->get_sample_count() == threshold);
    return downsampled;
}

observe_signal()

const Signal & echomap::SignalFactory::observe_signal ( ) const

nodiscardnoexcept

Definition at line 175 of file SignalFactory.cpp.

{
    return *target;
}

operator<()

bool echomap::SignalFactory::operator< ( const SignalFactory & other ) const

nodiscard

Definition at line 48 of file SignalFactory.cpp.

{
    if (target == nullptr || other.target == nullptr || !target->observe_source().has_value() ||
        !other.target->observe_source().has_value())
        return false;
 
    // Safe to deference; attempt to compare by channel and then path.
    const auto& us = *target->observe_source(); // NOLINT(*-identifier-length)
    const auto& them = *target->observe_source();
 
    return us < them;
}

operator==()

bool echomap::SignalFactory::operator== ( const SignalFactory & other ) const

nodiscard

Definition at line 31 of file SignalFactory.cpp.

{
    if (target.get() == other.target.get())
        return true;
 
    if (target == nullptr)
        return false; // We're null; the other isn't.
 
    if (other.target == nullptr)
        return false; // The other is null; we're not.
 
    // Safe to dereference; compare by IDs.
    return *target == *other.target;
}

set_sample_rate()

void echomap::SignalFactory::set_sample_rate ( std::size_t sample_rate ) const

noexcept

Definition at line 238 of file SignalFactory.cpp.

{
    target->set_sample_rate(sample_rate);
}

set_signal_name()

void echomap::SignalFactory::set_signal_name

(

std::string_view

name

)

const

Definition at line 224 of file SignalFactory.cpp.

{
    target->set_name(name);
}

set_source()

void echomap::SignalFactory::set_source	(	const std::filesystem::path &	path,
		std::size_t	channel ) const

Definition at line 245 of file SignalFactory.cpp.

{
    target->set_source(path, channel);
}

set_time_offset()

void echomap::SignalFactory::set_time_offset ( Signal::Sample::TimeT time_offset ) const

noexcept

Definition at line 231 of file SignalFactory.cpp.

{
    target->set_time_offset(time_offset);
}

take_signal()

std::unique_ptr< Signal > echomap::SignalFactory::take_signal ( )

nodiscardnoexcept

Definition at line 168 of file SignalFactory.cpp.

{
    auto signal = std::move(target);
    target = std::unique_ptr<Signal>(new Signal()); // NOLINT(*-unhandled-exception-at-new)
    return signal;
}

Member Data Documentation

target

std::unique_ptr<Signal> echomap::SignalFactory::target

private

The Signal being built by the factory.

Invariant

The target container always contains a valid Signal object, such that dereferencing is safe.

Definition at line 165 of file SignalFactory.hpp.

---

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

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