echomap::SignalWaveformPanel Class Reference

The SignalWaveformPanel provides a preview of downsampled time-series waveforms of each Signal in the active Project. More...

#include <SignalWaveformPanel.hpp>

Inheritance diagram for echomap::SignalWaveformPanel:

Classes
struct	CallbackData

Public Member Functions
	SignalWaveformPanel (Worker *parent_worker, WorkerResultDespatcher &despatcher, const Project *initial_project=nullptr)
	Create a new SignalWaveformPanel to display downsampled Signal waveforms in the time domain.
	SignalWaveformPanel (const SignalWaveformPanel &)=delete
SignalWaveformPanel &	operator= (const SignalWaveformPanel &)=delete
	SignalWaveformPanel (SignalWaveformPanel &&) noexcept
SignalWaveformPanel &	operator= (SignalWaveformPanel &&) noexcept=delete
const char *	get_imgui_name () const noexcept override
	Retrieves the name of the IPanel for Dear ImGui API functions.
void	draw () noexcept override
	Draw the panel to the active rendering context.
void	change_active_project (const Project *new_project) override
	Updates the active Project being described by the IPanel.
Public Member Functions inherited from echomap::IPanel
virtual void	update_gpu (const wgpu::CommandEncoder &command_encoder)
	Delegate work to the GPU via the WebGPU platform.

Static Public Member Functions
static const char *	get_imgui_stable_name () noexcept

Private Member Functions
void	handle_downsampled_result (DownsampleResult &&result)
void	update_bounding_box (const Signal &signal) noexcept
void	update_bounding_box () noexcept
const Signal *	get_downsampled_signal (std::shared_ptr< Signal > signal)
	Retrieves a downsampled Signal from the cache.

Static Private Member Functions
static ImPlotPoint	get_indexed_signal_point (int index, void *user_data) noexcept

Private Attributes
std::unordered_map< id_type, std::unique_ptr< Signal > >	downsample_cache
	The duplicated Signal objects, downsampled for visualisation.
ImPlotRect	bounding_box
	The maximum bounding box of an LTTB-downsampled wave form plot.
std::string	panel_name
ImPlotSpec	plotting_spec_2d
Worker *	parent_worker
const Project *	active_project = nullptr
std::vector< sigc::scoped_connection >	connections

Static Private Attributes
static constexpr float	default_downsample_factor = 50.0f

Additional Inherited Members
Static Protected Attributes inherited from echomap::IPanel
static constexpr ImVec2	button_size {80.0f, 20.0f}
static constexpr auto	table_flags

Detailed Description

The SignalWaveformPanel provides a preview of downsampled time-series waveforms of each Signal in the active Project.

Additionally, the panel owns the downsampled time series in a cache used exclusively for visualisation.

Definition at line 32 of file SignalWaveformPanel.hpp.

Constructor & Destructor Documentation

SignalWaveformPanel()

echomap::SignalWaveformPanel::SignalWaveformPanel ( Worker * parent_worker, WorkerResultDespatcher & despatcher, const Project * initial_project = nullptr )

explicit

Create a new SignalWaveformPanel to display downsampled Signal waveforms in the time domain.

The SignalWaveformPanel consumes the DownsampleResult message.

Parameters

parent_worker	The Worker to receive ITask commands over the command bus.
despatcher	The despatcher to expose the result buses.
initial_project	An optional initial Project for the IPanel to display.

Definition at line 23 of file SignalWaveformPanel.cpp.

  :
    bounding_box{
            std::numeric_limits<double>::max(),
            std::numeric_limits<double>::lowest(),
            Signal::normalised_range.first,
            Signal::normalised_range.second
    },
    panel_name(std::string("Signal Waveform Preview") + get_imgui_stable_name()),
    parent_worker(parent_worker),
    active_project(initial_project)
{
    connections.emplace_back(despatcher.downsample_finished_channel.nominate_consumer(
            sigc::mem_fun(*this, &SignalWaveformPanel::handle_downsampled_result)
    ));
}

Member Function Documentation

change_active_project()

void echomap::SignalWaveformPanel::change_active_project ( const Project * new_project )

overridevirtual

Updates the active Project being described by the IPanel.

Parameters

new_project

An observing pointer to the new active Project.

Implements echomap::IProjectPanel.

Definition at line 96 of file SignalWaveformPanel.cpp.

{
    active_project = new_project;
    downsample_cache.clear();
    update_bounding_box();
}

draw()

void echomap::SignalWaveformPanel::draw ( )

overridevirtualnoexcept

Draw the panel to the active rendering context.

Implements echomap::IPanel.

Definition at line 52 of file SignalWaveformPanel.cpp.

{
    if (ImGui::Begin(panel_name.c_str())) {
        if (active_project == nullptr)
            ImGui::Text("No project is loaded.");
        else if (ImPlot::BeginAlignedPlots("##WaveformAlignedGroup")) {
            ImPlot::PushStyleColor(ImPlotCol_FrameBg, ImVec4(0.0f, 0.0f, 0.0f, 0.0f));
            bool drawn_any = false;
 
            for (const auto& signal : active_project->share_signals()) {
                drawn_any = true;
 
                if (const auto* const downsampled = get_downsampled_signal(signal); downsampled == nullptr)
                    ImGui::Text("Loading downsampled variant of %s...", signal->get_imgui_name());
                else if (ImPlot::BeginPlot(downsampled->get_imgui_name())) {
 
                    ImPlot::SetupAxes("Time (seconds)", "Amplitude");
                    ImPlot::SetupAxisLinks(ImAxis_X1, &bounding_box.X.Min, &bounding_box.X.Max);
                    ImPlot::SetupAxisLinks(ImAxis_Y1, &bounding_box.Y.Min, &bounding_box.Y.Max);
 
                    CallbackData callback_data = {.signal = downsampled};
                    ImPlot::PlotLineG(
                            "",
                            &SignalWaveformPanel::get_indexed_signal_point,
                            &callback_data,
                            static_cast<int>(downsampled->get_sample_count()),
                            plotting_spec_2d
                    );
 
                    ImPlot::EndPlot();
                }
            }
 
            ImPlot::EndAlignedPlots();
            ImPlot::PopStyleColor();
 
            if (!drawn_any)
                ImGui::Text("No signals are available.");
        }
    }
 
    ImGui::End();
}

get_downsampled_signal()

const Signal * echomap::SignalWaveformPanel::get_downsampled_signal ( std::shared_ptr< Signal > signal )

private

Retrieves a downsampled Signal from the cache.

If the downsampled variant is not present, it is computed and cached.

Parameters

signal

The original Signal to downsample.

Returns

A stable observing pointer to the downsampled Signal, or null if it could not be produced at this time.

Precondition

The given Signal container must detain a valid Signal object.

Definition at line 163 of file SignalWaveformPanel.cpp.

{
    assert(signal != nullptr);
    const auto downsampled_it = downsample_cache.find(signal->get_id());
 
    if (downsampled_it == downsample_cache.end()) {
        /*
         * If the source signal hasn't already been downsampled and cached, submit a job to do it ASAP.
         *
         * The result won't be picked up on this render cycle, so return nullptr to indicate the "Loading" state, but it
         * should come through shortly. We emplace a nullptr in the slot to indicate that the work has been requested,
         * but not yet completed.
         */
 
        downsample_cache.emplace(signal->get_id(), nullptr);
        parent_worker->submit(std::make_unique<DownsampleTask>(std::move(signal)));
        return nullptr;
    }
 
    return downsampled_it->second.get();
}

get_imgui_name()

const char * echomap::SignalWaveformPanel::get_imgui_name ( ) const

nodiscardoverridevirtualnoexcept

Retrieves the name of the IPanel for Dear ImGui API functions.

Returns

The human-readable name of the window as a NULL-terminated C string.

Implements echomap::IPanel.

Definition at line 47 of file SignalWaveformPanel.cpp.

{
    return panel_name.c_str();
}

get_imgui_stable_name()

const char * echomap::SignalWaveformPanel::get_imgui_stable_name ( )

staticnoexcept

Definition at line 105 of file SignalWaveformPanel.cpp.

{
    return "###SignalWaveformPanel";
}

get_indexed_signal_point()

ImPlotPoint echomap::SignalWaveformPanel::get_indexed_signal_point ( int index, void * user_data )

staticprivatenoexcept

Definition at line 135 of file SignalWaveformPanel.cpp.

{
    const auto* const signal = static_cast<CallbackData*>(user_data)->signal;
    return {signal->get_time_at_index(index), signal->begin()[index]};
}

handle_downsampled_result()

void echomap::SignalWaveformPanel::handle_downsampled_result ( DownsampleResult && result )

private

Definition at line 110 of file SignalWaveformPanel.cpp.

{
    auto ds_slot_it = downsample_cache.find(result.get_source_id());
    auto signal = std::move(result).take_downsampled();
 
    if (ds_slot_it == downsample_cache.end()) {
        LOG_F_WARN("Received an unexpected result for the downsampled Signal {}.", signal->get_name());
        const auto signal_name_view = signal->get_name();
        auto [it, success] = downsample_cache.emplace(result.get_source_id(), std::move(signal));
 
        if (!success) {
            LOG_F_ERROR("Could not store the downsampled Signal {} in the cache.", signal_name_view);
            return;
        }
 
        ds_slot_it = it;
    } else
        ds_slot_it->second = std::move(signal);
 
    // Update the bounding box for the signal graphical representation.
    update_bounding_box(*ds_slot_it->second);
}

update_bounding_box() [1/2]

void echomap::SignalWaveformPanel::update_bounding_box ( )

privatenoexcept

Definition at line 155 of file SignalWaveformPanel.cpp.

{
    bounding_box.X.Min = std::numeric_limits<double>::max();
    bounding_box.X.Max = std::numeric_limits<double>::lowest();
    bounding_box.Y.Min = Signal::normalised_range.first;
    bounding_box.Y.Max = Signal::normalised_range.second;
}

update_bounding_box() [2/2]

void echomap::SignalWaveformPanel::update_bounding_box ( const Signal & signal )

privatenoexcept

Definition at line 144 of file SignalWaveformPanel.cpp.

{
    if (signal.get_sample_count() > 0) {
        bounding_box.X.Min = std::min<double>(signal.get_time_at_index(0), bounding_box.X.Min);
        bounding_box.X.Max =
                std::max<double>(signal.get_time_at_index(signal.get_sample_count() - 1), bounding_box.X.Max);
    }
}

Member Data Documentation

active_project

const Project* echomap::SignalWaveformPanel::active_project = nullptr

private

Definition at line 122 of file SignalWaveformPanel.hpp.

bounding_box

ImPlotRect echomap::SignalWaveformPanel::bounding_box

private

The maximum bounding box of an LTTB-downsampled wave form plot.

The Y axis (amplitude) is fixed, since our PCM-normalised values, given as a constraint from the Signal samples, are within a fixed range. The X range is variable and should be updated as new Signal objects are received.

Definition at line 117 of file SignalWaveformPanel.hpp.

connections

std::vector<sigc::scoped_connection> echomap::SignalWaveformPanel::connections

private

Definition at line 123 of file SignalWaveformPanel.hpp.

default_downsample_factor

float echomap::SignalWaveformPanel::default_downsample_factor = 50.0f

staticconstexprprivate

Definition at line 67 of file SignalWaveformPanel.hpp.

downsample_cache

std::unordered_map<id_type, std::unique_ptr<Signal> > echomap::SignalWaveformPanel::downsample_cache

private

The duplicated Signal objects, downsampled for visualisation.

This map associates the IDs of the original Signal objects with owning containers of their downsampled counterparts.

It is typically undesirable for the panels to own any non-trivial state. In this case, however, the data is generated exclusively for the purposes of visualisation on this panel, and the elements' construction and destruction is at the whim of the renderer such that downsampled time series are only created ad-hoc when they need to be visualised. Therefore, the SignalWaveformPanel seems to be the natural owner.

Definition at line 109 of file SignalWaveformPanel.hpp.

panel_name

std::string echomap::SignalWaveformPanel::panel_name

private

Definition at line 119 of file SignalWaveformPanel.hpp.

parent_worker

Worker* echomap::SignalWaveformPanel::parent_worker

private

Definition at line 121 of file SignalWaveformPanel.hpp.

plotting_spec_2d

ImPlotSpec echomap::SignalWaveformPanel::plotting_spec_2d

private

Definition at line 120 of file SignalWaveformPanel.hpp.

---

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

• src/panels/SignalWaveformPanel.hpp
• src/panels/SignalWaveformPanel.cpp