visualizer: display several values of a statistic on one figure, and the IEEE 802.11 per-peer rate visualizer

[adamgeorge309]

Lets a statistic visualizer display several values of one statistic at once, on a bar chart above the network node, and adds an 802.11 per-peer data rate visualizer configured from it.

Why. A statistic visualizer could show one number per signal source. For a quantity that exists per peer, per source or per flow, that forces a choice between an aggregate that hides the distribution and one visualizer instance per value with no visual relationship between them — while the recording side already handles this with demux(), visible only after the run.

Three names for three things. An earlier version of this branch called all of it a "series". That word was doing three jobs at once, and one parameter fused two independent decisions:

• split — one signal source's values become several statistics
• group — several statistics are displayed together on one figure
• item — one of the several things a figure displays

splitBy determines whether the values a signal source emits are split into several statistics, and what identifies each:

• "none" — the source emits the values of a single statistic
• "details" — one statistic per distinct details object emitted with the value; the live counterpart of the demux() result filter
• "flow" — one statistic per packet flow of the source (statisticExpression contains demuxFlow())

groupBy determines which statistics are displayed together as the items of a single figure:

• "none" — each statistic gets a figure of its own
• "source" — the statistics of one signal source, i.e. the ones splitBy split its values into
• "networkNode" — the matching signal sources of one network node, one item per source, each labelled with its path relative to the node (wlan[0].mac), which is unique where the bare module name is not

Only the combinations the visualizations are keyed for are accepted, and the error names all three rules it enforces. Fully decoupling them — so splitBy = "details" with groupBy = "none" gives one text instrument per peer — is a follow-up that will not change this NED contract.

The figure is given as the attributes of an @figure property, either in a figure template along the module path (propertyName, which already existed) or in a new figure object parameter, which unlike the template can be set from an ini file and can refer to module parameters:

*.visualizer.*.statisticVisualizer.figure = {type: "barChart", maxValue: 1, valueFormat: "%.2f", barColor: "gold"}
*.visualizer.*.statisticVisualizer.figure = {type: "gauge", size: [60, 60], maxValue: 100, tickSize: 20}

Both funnel into cCanvas::createFigure() + cFigure::parse(), so there is one attribute vocabulary, one set of allowed keys, and no second dialect.

BarChartFigure (Register_Figure("barChart")) is the first indicator figure whose item count is not fixed. It follows PlotFigure: the interface carries the getter, the figure carries the setters — setNumItems(n) sizes the chart and setItemLabel(i, label) names each bar, as setNumSeries(3) and setLineColor(0…2) do for a plot. Bars are drawn in index order. The visualizer owns the label to index mapping: it holds the items in a std::map keyed by label, so an item's index is its position in label order, and the figure is only ever given a count, labels and values. A figure that cannot display labelled items is rejected with a message that says so.

IIndicatorFigure is renamed, series to item: getNumItems(), and setValue(int index, …). "Series" only fits PlotFigure, where an item really is a sequence of values over time. getNumSeries() stays for one release as a deprecated method that getNumItems() forwards to, so a figure implemented outside INET keeps working. Note that overriding a deprecated method is not a use of its name, so the compiler does not warn at the override — the deprecation is visible in the header and at call sites, and WHATSNEW says so rather than promising a warning that does not happen.

Ieee80211RateCanvasVisualizer shows the data rate a node is using towards each of its peers. It is a NED configuration of the generic visualizer, not new visualizer code, and being a StatisticCanvasVisualizer it needs no submodule of its own:

*.visualizer.*.statisticVisualizer.typename = "Ieee80211RateCanvasVisualizer"
*.visualizer.*.statisticVisualizer.displayRates = true

Also here: a bounds-check fix in FigureRecorder (a figure index equal to the item count was accepted and then wrote one past the end; a negative index passed too), and lifetime handling the per-frame refresh makes necessary — a result recorder is deleted with its source module, and a network node visualization is a figure group deleted with its node that takes the statistic figure with it, so an item whose source is gone and a visualization whose module is gone are both dropped before anything reads them, and the node visualization is looked up rather than remembered. That last part also repairs a pre-existing crash on this path.

Test

Builds at every one of the eight commits (release).

Four module tests — inet_run_module_tests -m release -f StatisticVisualizerItems, all PASS:

test	asserts
_1	three sink applications become three bar chart items; the bar count and labels in index order, read from the figure through a BarChartProbe
_2	a gauge fed several items is rejected, with the message
_3	deleting a signal source removes its bar; the survivors keep their own labels
_4	deleting a whole network node leaves nothing and does not crash

The visualizer is GUI-only (initialize() returns early on !hasGUI()), so all four run under Cmdenv's fake GUI, which makes hasGUI() true and drives refreshDisplay(). That matters for what the assertions are worth: the visualizer records nothing to a result file, so asserting on received packet counts would pass with the visualizer switched off — checked, it does. Test _1 therefore reads the figure, and _2's rejection is what proves the path executed at all. Test _4 was written for the lifetime handling and found a segfault at teardown in the first version of it.

Fingerprints. examples/visualizer/statisticbars (new) has rows in tests/fingerprint/store.json for Packets, Flow and Gauge — Flow being the only splitBy = "flow" coverage and Gauge the only non-bar-chart figure. All three pass through inet_run_fingerprint_tests. The tyf ingredient runs under fake GUI and hashes canvas figure geometry, so these are genuine visualizer coverage: Gauge shares its tplx/~tNl/~tND values with Packets (identical traffic) but differs on tyf.

Runs. All seven example configs run clean under fake GUI with the visualizer live.

Deliberately not in this PR

The OSG visualizer accepts splitBy/groupBy and renders nothing, and still has the pre-existing form of the lifetime defect fixed here on the canvas side. @statistic(record=figure) cannot target a barChart, because nothing pre-sizes its bars from a property. No test covers splitBy = "details" or Ieee80211RateCanvasVisualizer itself. BarChartFigure relayouts once per setValue, and its autoscale moves only the maximum. The display-unit conversion differs between the unsplit path (walks the unit list) and the split path (uses the first unit only, and none when statisticUnit is unset).

[devin-ai-integration]

Devin Review found 3 potential issues.

View 2 additional findings in Devin Review.

[devin-ai-integration]

🔴 Charts with a not-yet-measured bar can read past the end of the color list and crash

A bar whose value is still unknown is fed into the color picker (getBarColor() at src/inet/visualizer/base/StatisticVisualizerBase.cc:344-349) without any check for the "no value yet" case, so the color index becomes garbage and the program can read outside the color list and crash.
Impact: Simulations using the bar chart display can crash or draw corrupt charts as soon as a bar exists before its first measurement.

NaN propagation into the gradient index and into figure geometry

In sources mode every newly registered bar is initialized with values[label] = NaN (src/inet/visualizer/base/StatisticVisualizerBase.cc:378), and refreshGroupedBarValues() keeps NaN until the recorder produces a value; refreshFlowBarValues() and processBarValue() can also store NaN.

In getBarColor(), with value = NaN: fraction = (NaN - minValue)/range = NaN; both clamps if (fraction < 0) and if (fraction > 1) are false for NaN, so pos = NaN, and int index = (int)std::floor(NaN) is undefined behaviour (typically INT_MIN). index >= (int)barColors.size() - 1 is then false, so barColors[index] / barColors[index + 1] index the vector far out of range.

The same NaN also reaches StatisticCanvasVisualizer::refreshChart() (src/inet/visualizer/canvas/common/StatisticCanvasVisualizer.cc:242-248), producing h = NaN and a cRectangleFigure with NaN bounds.

Both places need an explicit NaN check (e.g. skip drawing the bar, or draw a zero-height bar in a neutral color), like the text mode does in DirectiveResolver::resolveDirective which renders "-" for NaN.

Suggested change

	double range = maxForScale - minValue;
	double fraction = range > 0 ? (value - minValue) / range : 0;
	if (fraction < 0) fraction = 0;
	if (fraction > 1) fraction = 1;
	double pos = fraction * (barColors.size() - 1);
	int index = (int)std::floor(pos);
	double fraction = range > 0 ? (value - minValue) / range : 0;
	if (std::isnan(fraction)) fraction = 0;
	if (fraction < 0) fraction = 0;
	if (fraction > 1) fraction = 1;
	double pos = fraction * (barColors.size() - 1);
	int index = (int)std::floor(pos);
	if (index >= (int)barColors.size() - 1)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[adamgeorge309]

Handled by the rework this review predates: the gradient moved into BarChartFigure, whose getBarColor() returns the first color for NaN, and whose layout() maps a NaN value to zero height and hides the bar. No NaN reaches the color index or the figure bounds.

[devin-ai-integration]

🔴 Statistic collectors pile up without limit when a display cannot draw bar charts

A new hidden statistic collector is attached to the same module on every single signal (addResultRecorder() at src/inet/visualizer/base/StatisticVisualizerBase.cc:366) before it is known whether the chart can actually be created, so when charts are unsupported the collectors grow without bound.
Impact: With a display that does not support bar charts, memory use and per-signal processing cost grow continuously until the run slows to a crawl or runs out of memory.

Early return skips the registration bookkeeping

processGroupedBarSource() first checks groupedBarSourceIds and the source filter, then calls addResultRecorder(source, signal). If createBarSetVisualization() returns nullptr (the base-class default, i.e. any visualizer that does not implement bar charts, e.g. StatisticOsgVisualizer), it returns at src/inet/visualizer/base/StatisticVisualizerBase.cc:373 before groupedBarSourceIds.insert(module->getId()) at line 379. Consequently the guard at line 361 never fires, and each subsequent emission of the signal appends yet another recorder chain to the source module.

processFlowBarSource() has exactly the same ordering problem: addResultRecorder() at line 404, early return at line 409, groupedBarSourceIds.insert() at line 412.

A fix is to determine whether a bar set can be created (or mark the source as handled / disable bar mode) before attaching the recorder.

Prompt for agents

In StatisticVisualizerBase::processGroupedBarSource() and processFlowBarSource() (src/inet/visualizer/base/StatisticVisualizerBase.cc), addResultRecorder() is called before the code checks whether createBarSetVisualization() succeeds. When the concrete visualizer does not support bar charts (base implementation returns nullptr), the function returns early without inserting the module id into groupedBarSourceIds, so the duplicate-registration guard never trips and a new recorder chain is attached to the source module on every signal emission, growing memory and per-signal cost without bound. Reorder so the bar set is obtained/created (or the unsupported case detected and permanently remembered, e.g. by disabling bar handling or still inserting into groupedBarSourceIds) before any recorder is attached.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[adamgeorge309]

Handled by the rework this review predates: registerSeriesSource() now inserts into seriesSourceIds before it tries to create the visualization, and calls addResultRecorder() only after the nullptr check, so a visualizer that cannot display series registers each source once and attaches nothing.

[devin-ai-integration]

🟡 Bars for same-named modules in one node overwrite each other

Each bar is labelled only with the short module name (module->getFullName() at src/inet/visualizer/base/StatisticVisualizerBase.cc:376), so two identically named modules inside the same node share one bar and only one of them is shown.
Impact: In nodes with several same-named submodules (for example multiple wireless interfaces), some sources silently disappear from the chart.

Label collision in the per-node bar map

In sources mode the bar set is keyed by the network node id, and each bar is keyed by module->getFullName(). For a source filter matching e.g. **.wlan[*].mac, both wlan[0].mac and wlan[1].mac have full name mac, so barSetVisualization->recorders[label] and values[label] (lines 377-378) overwrite the earlier entry; the first module's recorder is dropped from the map and its value never displayed, while the count of bars is lower than the number of matching sources.

A label that is unique within the node (e.g. the path relative to the network node) would avoid the collision.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[adamgeorge309]

Real, fixed in 1afadc8. The label is now the path of the source relative to the network node, so pointing sourceFilter at *.switch.eth[*].mac in examples/visualizer/statisticbars gives eth[0].mac and eth[1].mac instead of a single mac bar. Direct submodules such as app[0] keep their label, so the existing configs render the same.

[levy]

The statistic visualizer should be capable of visualizing the value using any instrument figure. Each kind of instrument figure comes with its own set of parameters. We can't let all those parameters go into the statistic visualizer module.

For example, we can have bar chart/line chart/histogram chart/gauge/text instruments, each have their own set parameters.

Options:

• add a @figure template to the derived statistic visualizer module which can have its figure type fixed and have its own parameters. Cons: doesn't really combine well with using a different figure.
• add an object parameter to the statistic visualizer to control the appearance of figures

[adamgeorge309]

Reworked along these lines — thanks, the objection was right, and it turned out the mechanism was already in the codebase and this PR was simply bypassing it.

StatisticCanvasVisualizer already had propertyName/propertyIndex: it looks up a figure template property along the module path, instantiates the class named by its type= key, and calls figure->parse(property), so every figure-specific parameter lives in the property. @statistic(record=figure; targetFigure=...) + @figure does the same thing for the canvas of a module. The 17 bar-specific parameters on the statistic visualizer were exactly what that mechanism exists to prevent, and displayMode was redundant with it — the figure type is the display mode.

So the two options are not alternatives: both are front ends for the same thing, and both now funnel into cCanvas::createFigure() + cFigure::parse(), i.e. one attribute vocabulary, one construction path, no second dialect to document.

• The @figure template (option 1). The con named above is weaker than it sounds: the type is in the template's type=, propertyName/propertyIndex are ordinary string parameters, and the lookup walks the module path — so a derived visualizer only sets defaults and the user can put their own template on the network and select it from the ini. The real limit is different: NED property values are static strings, so a single attribute cannot be overridden from an ini file and cannot refer to a module parameter.
• An object parameter (option 2) has neither limit, which matters immediately here: Ieee80211RateVisualizer forwards its maxRate parameter into the figure as {... maxValue: this.maxRate / 1Mbps ...}, which a static template cannot do.

Since the template is the only one of the two that can replace a figure a derived visualizer already defaults to, it takes precedence over the parameter.

What was actually missing was on the figure side, not the parameter side: IIndicatorFigure had a fixed series count and integer-indexed series, so a chart fed by a live demux had nowhere to go — which is why the bar chart ended up inside the visualizer. It now has getSeriesIndex(label, createIfMissing) (default implementation maps the empty label to series 0, so existing figures are unaffected), and BarChartFigure is a normal registered figure owning its own parameters. The visualizer keeps only the data-side question — seriesBy = "none"|"details"|"sources"|"flow" — which is a demultiplexing policy, not appearance.

The new examples/visualizer/statisticbars shows the same visualizer and the same series driving a bar chart or a gauge, by one ini line.

[adamgeorge309]

Pushed 1afadc8 for the third Devin finding, which was real: in seriesBy = "sources" a series was labelled with the name of its source module alone, so same-named sources in one node - the MACs of several network interfaces, say - collapsed into a single series and all but the last one silently vanished from the chart. The label is now the path of the source relative to the network node; direct submodules such as app[0] are unaffected, so the existing example configs render unchanged.

The other two findings were made against the pre-rework commit and no longer apply: the NaN handling now sits in BarChartFigure (getBarColor() and layout() both special-case it), and registerSeriesSource() registers the source before attaching any recorder, so nothing accumulates when series are unsupported.

[levy]

The word series makes me so confused. Is it not grouping statistics instead? Groups have members, some figures are capable of displaying a group of statistics. Grouped by flow name for example. A series is just a sequence of data points, so I don't quite understand why is this word used.