martino/udpscope
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

measure: the split's own means are back as above/below/between

Browse Source 
`top`, `bottom` and `amplitude` became the *flat levels* in e83ad86 -- the level the
signal dwells at, read from the density of the window's buckets -- and that change kept
the split's own two means as its internal fallback for a window the pyramid cannot
summarize. Those means are now three types of their own, so the two different questions
about one split can be asked side by side: `above %` and `below %` are the plain mean of
the samples on one side of a share -- the reading the old `top`/`bottom` gave -- and
`between % %` is the mean of the band between two shares, which no single split can
answer, because a band's two edges are two thresholds.

Nothing about the arithmetic is new, and nothing is a new pass. `Above`/`Below` are the
`sum[]`/`count[]` split `measure_accumulate()` already folds -- the very figures
`Top`/`Bottom` fall back to -- and `Between` is the **difference of two levels' upper
sides**, both of which come out of one pass two over one window. It rides the bucket
fast path unchanged: a bucket wholly inside the band is strictly above the lower level
and strictly below the upper one, so both accumulators fold it whole, and only the
buckets that straddle either edge are opened. `measure_level_pcts()` is the one place the
shares are read, and it clamps both and puts `between`'s pair **in order**, so "between
80 % and 20 %" is the band between 20 % and 80 % -- normalized rather than refused,
because the shares name two edges rather than a direction. Nothing to measure reads `--`,
as for every other type: a share at 100 % has no sample above it, and a band can hold
none at all.

Measured, `[bandavg-probe]`, fast mock at a 2 s window (`--rate 1300000 --batch 1000
--freq 1`):

  sine   `above 50` 0.636620 (2/pi), `below 50` -0.636620, `between 50 75` 0.255873
  square `above 50` 0.986496 (30 harmonics) / 1.000000 (--square-harmonics 0),
         `between 50 75` 0.302744 / --
  ramp   `between 50 75` 0.250000 and `above 50` 0.500000, `above 100` --

The first three are the figures the old `top`/`bottom` documented; the ramp's are what a
uniform density predicts (a band's mean is its own centre); the ideal square's empty band
is the nothing-to-measure rule. The pane offers the types and edits their percentages
through the dialog's second share -- which only `between` shows -- and a measurement's
pair survives add/edit/delete and the session file (`threshold2`), where a file written
before it existed loads at the default.

No raw pass: with the measurements probe adding one of every type at a 2 s window, `raw`
went from 113966 of 240719031 covered (0.0%) to 134978 of 255372033 (0.1%), 0.8 -> 1.1
ns a covered sample.

Docs: the band-average invariant (and the two assertions the flat-level change moved),
the probe readings for the new probe, the verification recipe, the manual's measurements
page and the README.
This commit is contained in:
Martino Ferrari committed 2026-10-15 07:56:37 +02:00
1 parent e83ad86b8f
commit 22e7a8efcc
14 files changed
+769 -98
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/layout_store.cpp
+9
View File
@@ -612,6 +612,14 @@ bool load_layout(const std::string& path, LayoutState& out) {
m.options.threshold_pct = std::stod(value);
} catch (...) {
}
} else if (key == "threshold2") {
// The band's other edge. A file written before `Between` existed has no such key, and the
// struct's own default is what such a measurement then reads -- which is the same value the
// dialog offers a new one.
try {
m.options.threshold_pct2 = std::stod(value);
} catch (...) {
}
} else if (key == "noise") {
try {
m.options.noise_pct = std::stod(value);
@@ -752,6 +760,7 @@ bool save_layout(const std::string& path, const LayoutState& state) {
}
o << "\n[[measure]]\nsignal = " << toml_escape(m.signal) << "\ntype = " << kind
<< "\nthreshold = " << m.options.threshold_pct
<< "\nthreshold2 = " << m.options.threshold_pct2
<< "\nabove = " << (m.options.above ? "true" : "false") << "\nshow = "
<< (m.options.show_on_plot ? "true" : "false") << "\nnoise = " << m.options.noise_pct
<< "\nhf = " << m.options.hf_fc << "\n";
src/measure.cpp
+92 -28
View File
@@ -342,21 +342,36 @@ MeasureFlatLevels measure_flat_levels(const MeasureStats& b, double pct) {
return out;
}
bool measure_level_pct(MeasureType type, const MeasureOptions& options, double& pct) {
int measure_level_pcts(MeasureType type, const MeasureOptions& options, double pct[2]) {
const auto share = [](double v) { return std::clamp(v, 0.0, 100.0) / 100.0; };
switch (type) {
case MeasureType::Top:
case MeasureType::Bottom:
pct = std::clamp(options.threshold_pct, 0.0, 100.0) / 100.0;
return true;
case MeasureType::Above:
case MeasureType::Below:
pct[0] = share(options.threshold_pct);
return 1;
case MeasureType::Between: {
// The band's two edges, clamped and *ordered*: the shares name a lower and an upper edge, so
// "between 80 % and 20 %" is the band between 20 % and 80 %. Normalizing rather than refusing
// is the honest reading of a band -- the set of samples does not depend on which edge the user
// typed first -- and the two accumulators the pair is answered from are keyed on these ordered
// values, so the same band is one walk however it was written.
const double a = share(options.threshold_pct);
const double b = share(options.threshold_pct2);
pct[0] = std::min(a, b);
pct[1] = std::max(a, b);
return 2;
}
case MeasureType::PulseDuration:
case MeasureType::Period:
case MeasureType::Frequency:
// The *mid* level, for all three. No option here on purpose: a period is the spacing of
// one crossing per cycle, and a threshold near either extreme counts noise as crossings.
pct = 0.5;
return true;
pct[0] = 0.5;
return 1;
default:
return false;
return 0;
}
}
@@ -373,11 +388,14 @@ const char* measure_type_name(MeasureType type) {
case MeasureType::PulseDuration: return "pulse duration";
case MeasureType::Period: return "period";
case MeasureType::Frequency: return "frequency";
case MeasureType::Above: return "above";
case MeasureType::Below: return "below";
case MeasureType::Between: return "between";
}
return "?";
}
int measure_type_count() { return 10; }
int measure_type_count() { return 13; }
MeasureType measure_type_at(int index) {
switch (index) {
@@ -390,15 +408,24 @@ MeasureType measure_type_at(int index) {
case 6: return MeasureType::Amplitude;
case 7: return MeasureType::PulseDuration;
case 8: return MeasureType::Frequency;
default: return MeasureType::Period;
case 9: return MeasureType::Period;
// Appended rather than filed beside `Top`/`Bottom`, where they read best in the dropdown:
// `layout_store` writes *this* index into the session file, so renumbering would turn a saved
// `max` into an `above` on the next start -- silently, and only for users who had one.
case 10: return MeasureType::Above;
case 11: return MeasureType::Below;
default: return MeasureType::Between;
}
}
bool measure_uses_threshold(MeasureType type) {
return type == MeasureType::Top || type == MeasureType::Bottom ||
type == MeasureType::PulseDuration;
type == MeasureType::PulseDuration || type == MeasureType::Above ||
type == MeasureType::Below || type == MeasureType::Between;
}
bool measure_uses_band(MeasureType type) { return type == MeasureType::Between; }
bool measure_uses_side(MeasureType type) { return type == MeasureType::PulseDuration; }
bool measure_uses_noise(MeasureType type) {
@@ -408,8 +435,8 @@ bool measure_uses_noise(MeasureType type) {
bool measure_can_show_on_plot(MeasureType) { return true; }
MeasureResult compute_measure(const MeasureStats& b, const MeasureLevel* level, MeasureType type,
const MeasureOptions& options) {
MeasureResult compute_measure(const MeasureStats& b, const MeasureLevel* const levels[2],
MeasureType type, const MeasureOptions& options) {
MeasureResult out;
if (!b.valid) return out;
@@ -475,10 +502,10 @@ MeasureResult compute_measure(const MeasureStats& b, const MeasureLevel* level,
// is the value. The band is a *value* band, so the reading does not follow the window's
// alignment, and it excludes both a plateau's ripple and an edge's overshoot -- which is the
// whole point, because those are exactly what a mean over a side reports instead.
double pct = 0.0;
if (!measure_level_pct(type, options, pct)) return out;
double pct[2] = {0.0, 0.0};
if (measure_level_pcts(type, options, pct) == 0) return out;
const bool want_top = type == MeasureType::Top;
const MeasureFlatLevels flat = measure_flat_levels(b, pct);
const MeasureFlatLevels flat = measure_flat_levels(b, pct[0]);
if (want_top ? flat.top_ok : flat.bottom_ok) {
out.primary = want_top ? flat.top : flat.bottom;
out.marks.push_back({true, out.primary});
@@ -487,11 +514,47 @@ MeasureResult compute_measure(const MeasureStats& b, const MeasureLevel* level,
}
// No histogram: the mean of one side of the level, straight out of the second pass' running
// sums. A window the pyramid cannot summarize is one bucket or two of a zoomed-in view, or
// an HF-rejected walk, and on those the split's own means are the honest reading.
if (level == nullptr) return out;
// an HF-rejected walk, and on those the split's own means are the honest reading -- and they
// are what `Above`/`Below` report on *every* window.
const MeasureLevel* lv = levels != nullptr ? levels[0] : nullptr;
const std::size_t s = want_top ? 1 : 0;
if (level->count[s] == 0) return out;
out.primary = level->sum[s] / static_cast<double>(level->count[s]);
if (lv == nullptr || lv->count[s] == 0) return out;
out.primary = lv->sum[s] / static_cast<double>(lv->count[s]);
out.marks.push_back({true, out.primary});
out.valid = true;
return out;
}
case MeasureType::Above:
case MeasureType::Below: {
// The plain mean of the samples on one side of the share -- what `Top`/`Bottom` reported
// before they became flat levels, and a different question from them: a mean over a side
// carries the ripple and the edge's overshoot (0.986496 on the rippled square where the
// plateau is 1), which is exactly why the flat-level types exist beside these.
const MeasureLevel* lv = levels != nullptr ? levels[0] : nullptr;
const std::size_t s = type == MeasureType::Above ? 1 : 0;
if (lv == nullptr || lv->count[s] == 0) return out;
out.primary = lv->sum[s] / static_cast<double>(lv->count[s]);
out.marks.push_back({true, out.primary});
out.valid = true;
return out;
}
case MeasureType::Between: {
// The band's interior: what lies above the lower edge and *not* above the upper one. Both
// accumulators split the same samples the same way -- pass two walks one bucket list and one
// filter for the whole window -- so the band is the *difference* of the two upper sides, and
// it is exact rather than approximate. It needs no third walk of its own, and the bucket
// fast path serves it unchanged: a bucket wholly inside the band is strictly above the lower
// level and strictly below the upper, so both accumulators fold it whole.
const MeasureLevel* lower = levels != nullptr ? levels[0] : nullptr;
const MeasureLevel* upper = levels != nullptr ? levels[1] : nullptr;
if (lower == nullptr || upper == nullptr) return out;
// Equal counts mean an empty interior: nothing lies in the band, so there is nothing to
// average -- the pane reads `--`, as it does for any other type with no samples on the side
// it was asked about. `lower` may not count *fewer*, which would say the two accumulators
// saw different samples.
if (lower->count[1] <= upper->count[1]) return out;
out.primary = (lower->sum[1] - upper->sum[1]) /
static_cast<double>(lower->count[1] - upper->count[1]);
out.marks.push_back({true, out.primary});
out.valid = true;
return out;
@@ -499,18 +562,19 @@ MeasureResult compute_measure(const MeasureStats& b, const MeasureLevel* level,
case MeasureType::PulseDuration:
case MeasureType::Period:
case MeasureType::Frequency: {
if (level == nullptr) return out;
if (levels == nullptr || levels[0] == nullptr) return out;
const MeasureLevel& level = *levels[0];
// The pulse is one side of the mid level: its widths run from the edge that enters it to
// the edge that leaves it, and a period is the spacing of the edges that *enter* it -- one
// per cycle, whatever else the waveform does in between.
const std::size_t s = options.above ? 1 : 0;
const double enter_span = level->last_enter[s] - level->first_enter[s];
const double enter_period = level->enters[s] >= 2
? enter_span / static_cast<double>(level->enters[s] - 1)
const double enter_span = level.last_enter[s] - level.first_enter[s];
const double enter_period = level.enters[s] >= 2
? enter_span / static_cast<double>(level.enters[s] - 1)
: 0.0;
if (type == MeasureType::PulseDuration) {
if (level->widths[s] == 0) return out;
out.primary = level->width_sum[s] / static_cast<double>(level->widths[s]);
if (level.widths[s] == 0) return out;
out.primary = level.width_sum[s] / static_cast<double>(level.widths[s]);
// Duty as width/period, not as pulse-time over the window: a window that starts or
// ends mid-pulse holds partial cycles, and counting only the complete ones against
// the whole span would report a duty that depends on where the window happened to
@@ -518,15 +582,15 @@ MeasureResult compute_measure(const MeasureStats& b, const MeasureLevel* level,
// them -- a window holding one pulse reports the width alone.
out.secondary = enter_period > 0.0 ? out.primary / enter_period : 0.0;
out.has_secondary = enter_period > 0.0;
out.marks.push_back({false, level->first_enter[s]});
out.marks.push_back({false, level->first_enter[s] + out.primary});
out.marks.push_back({false, level.first_enter[s]});
out.marks.push_back({false, level.first_enter[s] + out.primary});
out.valid = true;
return out;
}
if (!(enter_period > 0.0)) return out;
out.primary = type == MeasureType::Period ? enter_period : 1.0 / enter_period;
out.marks.push_back({false, level->first_enter[s]});
out.marks.push_back({false, level->first_enter[s] + enter_period});
out.marks.push_back({false, level.first_enter[s]});
out.marks.push_back({false, level.first_enter[s] + enter_period});
out.valid = true;
return out;
}
src/measure.hpp
+51 -18
View File
@@ -38,16 +38,37 @@ enum class MeasureType {
PulseDuration, ///< how long the signal spends on one side of the threshold
Period, ///< the time between two successive crossings of the threshold
Frequency, ///< 1 / period
/// The mean of the samples **above** `threshold_pct` -- the split's own upper mean, which is
/// what `Top` reported before a flat level replaced it. `Top`/`Bottom` are the level the signal
/// *dwells at* (a density question, so a ringing edge does not drag them); these two are the
/// plain mean of the samples on one side of the share, ripple and overshoot included, which is
/// a *different* question about the same split and the reason the two coexist: on a unit sine
/// this reads `0.636620` (2/pi) where `Top` reads `0.957988`, and on the mock's band-limited
/// square `0.986496` where its plateau is 1.
Above,
/// The same from the split's lower side.
Below,
/// The mean of the samples **between** `threshold_pct` and `threshold_pct2`: the band's
/// interior, which neither of the two means above can answer (one of them gives the two sides
/// and the other the whole window, because the band's two edges are not one split).
Between,
};
/// Type-specific behaviour. Every field is meaningful only for the types named below; the
/// others ignore it (an option that does nothing for a type is left out of the dialog
/// rather than stored and ignored).
struct MeasureOptions {
/// `Top`/`Bottom`/`PulseDuration`/`Period`/`Frequency`: where the split is, as a share of
/// `Top`/`Bottom`/`PulseDuration`/`Above`/`Below`/`Between`: where the split is, as a share of
/// the window's own min..max. The middle by default, which is what a symmetric waveform
/// wants; a 3.3 V logic signal with ringing wants it nearer the top.
/// wants; a 3.3 V logic signal with ringing wants it nearer the top. For `Above`/`Below` it is
/// the level the mean is taken on one side of; for `Between` it is the band's *lower* edge.
double threshold_pct = 50.0;
/// `Between`: the band's other edge, the same unit. The two are read through
/// `measure_level_pcts()`, which clamps both and puts the pair in order, so the band between
/// 80 % and 20 % is the band between 20 % and 80 % -- the shares name two *edges* and the order
/// they were typed in carries no meaning, which is why a reversed pair is normalized rather
/// than refused.
double threshold_pct2 = 75.0;
/// `PulseDuration`: which side of the threshold is "the pulse". `Period`/`Frequency`
/// use it as the edge direction, so one cycle is counted once.
bool above = true;
@@ -268,11 +289,13 @@ struct MeasureLevel {
/// fact rather than a threshold decision. `measure_set_level()` is what sizes it; zero reduces
/// the walk exactly to a single level.
double hysteresis = 0.0;
/// The samples either side of `level`, exactly: `Top`/`Bottom`'s reading on a window with no
/// bucket histogram to read a flat level from (shorter than one bucket, or an HF-rejected
/// walk). They are folded on every window -- pass two walks it for the crossing types anyway
/// -- but a window that has a histogram is read from that instead, because a mean over a side
/// reports the ripple and the overshoot rather than the level the signal dwells at.
/// The samples either side of `level`, exactly: the reading of `Above`/`Below` is one of these
/// two means, `Between`'s is the difference of two *levels'* upper sides, and `Top`/`Bottom` fall
/// back to them on a window with no bucket histogram to read a flat level from (shorter than one
/// bucket, or an HF-rejected walk). They are folded on every window -- pass two walks it for the
/// crossing types anyway -- but a window that has a histogram is read from that instead, because
/// a mean over a side reports the ripple and the overshoot rather than the level the signal
/// dwells at.
/// Index 0 is the side below the level (a sample exactly *at* it counts here), index 1 the
/// side above it.
double sum[2] = {0.0, 0.0};
@@ -326,13 +349,18 @@ bool measure_accumulate_bucket(const MeasureBucket& bucket,
const std::function<double(std::size_t)>& time_of,
MeasureLevel& level);
/// The level a type reads, as a share of the window's own min..max, or false when it reads none
/// (the pure statistics, answered from `MeasureStats` alone). `Top`/`Bottom` read the
/// measurement's own threshold; the crossing types read the mid level, deliberately -- see
/// `measure_uses_threshold()`. `Amplitude` reads no level either: its value is the delta between
/// the two flat levels, which the histogram answers, and the split's two means are only a
/// fallback it takes from the window's own extremes -- see `compute_measure()`.
bool measure_level_pct(MeasureType type, const MeasureOptions& options, double& pct);
/// The levels a type reads, as shares of the window's own min..max, **lower first**, or 0 when it
/// reads none (the pure statistics, answered from `MeasureStats` alone). `pct` must hold two: a
/// level type fills `pct[0]` and answers 1, `Between` fills both and answers 2.
///
/// `Top`/`Bottom`/`Above`/`Below` read the measurement's own threshold; the crossing types read the
/// mid level, deliberately -- see `measure_uses_threshold()`. `Amplitude` reads no level either: its
/// value is the delta between the two flat levels, which the histogram answers, and the split's two
/// means are only a fallback it takes from the window's own extremes -- see `compute_measure()`.
///
/// This is the one place `Between`'s pair is clamped and ordered, so the pane's dedup key, the
/// engine's two accumulators and the dialog all describe the same band whatever was typed.
int measure_level_pcts(MeasureType type, const MeasureOptions& options, double pct[2]);
/// The window's two flat levels, from the bucket histogram in `stats.flat`. `top` is the densest
/// band of the bins *above* `lo + pct * (hi - lo)`, `bottom` the same below it -- for a
@@ -352,10 +380,11 @@ struct MeasureFlatLevels {
};
MeasureFlatLevels measure_flat_levels(const MeasureStats& stats, double pct);
/// The engine: one measurement's answer, O(1), from the two passes' results. `level` is the
/// accumulator for `measure_level_pct(type, options)` and may be null for the types that read
/// none. The function reads nothing else, which is what keeps the answer independent of the plot.
MeasureResult compute_measure(const MeasureStats& stats, const MeasureLevel* level,
/// The engine: one measurement's answer, O(1), from the two passes' results. `levels` is the
/// accumulators `measure_level_pcts(type, options)` asked for, in the same order -- `nullptr` for
/// the types that read none, and either entry may be null when the caller could not resolve it.
/// The function reads nothing else, which is what keeps the answer independent of the plot.
MeasureResult compute_measure(const MeasureStats& stats, const MeasureLevel* const levels[2],
MeasureType type, const MeasureOptions& options);
/// A measurement type's name, as the pane's row and the dialog's dropdown spell it.
@@ -368,6 +397,10 @@ MeasureType measure_type_at(int index);
/// spacing of the crossings of the *mid* level, one rising edge per cycle, and offering a
/// threshold there only invites a setting that makes the count wrong.
bool measure_uses_threshold(MeasureType type);
/// Whether a type reads a *pair* of shares, so the dialog shows its second share only then: the
/// two edges of a band are one measurement's two parameters, and one field of the two is a
/// measurement of a different band than the user asked for.
bool measure_uses_band(MeasureType type);
/// Whether a type uses the `above` side (only `PulseDuration`, where it says which half of
/// the waveform is the pulse).
bool measure_uses_side(MeasureType type);
src/ui.cpp
+24 -8
View File
@@ -1374,12 +1374,8 @@ GtkWidget* measures_row(App& app, std::size_t index, const Measure& m) {
gtk_widget_set_halign(kind, GTK_ALIGN_START);
gtk_widget_set_hexpand(kind, true);
gtk_label_set_ellipsize(GTK_LABEL(kind), PANGO_ELLIPSIZE_END);
char tip[160];
std::snprintf(tip, sizeof(tip), "%s\n%s", m.signal.c_str(),
measure_uses_threshold(m.type)
? (m.options.above ? "the above-threshold side" : "the below-threshold side")
: "");
gtk_widget_set_tooltip_text(kind, tip);
const std::string tip = m.signal + "\n" + measure_row_summary(m);
gtk_widget_set_tooltip_text(kind, tip.c_str());
gtk_box_append(GTK_BOX(box), kind);
GtkWidget* value = gtk_label_new("--");
gtk_widget_set_halign(value, GTK_ALIGN_END);
@@ -1684,6 +1680,17 @@ void open_measure_dialog(App& app, int edit_index) {
GtkWidget* threshold_row = labelled_row("threshold %", threshold, &threshold_label);
gtk_box_append(GTK_BOX(box), threshold_row);
// `Between`'s second share: the dialog offers it only for the one type that reads two (see
// `measure_uses_band()`), and the label is retitled per type with the field above it. The 75 is
// `MeasureOptions::threshold_pct2`'s default -- a default the *reader* sees, so it is seeded here
// as well as in the struct.
GtkWidget* band = spin(0.0, 100.0, 1.0, 1, 75.0);
gtk_widget_set_tooltip_text(band,
"the band's other edge, the same share of the visible range");
GtkWidget* band_label = nullptr;
GtkWidget* band_row = labelled_row("to %", band, &band_label);
gtk_box_append(GTK_BOX(box), band_row);
GtkWidget* above = gtk_switch_new();
gtk_widget_set_halign(above, GTK_ALIGN_START);
gtk_widget_set_tooltip_text(above, "which half of the waveform is the pulse");
@@ -1714,8 +1721,9 @@ void open_measure_dialog(App& app, int edit_index) {
gtk_box_append(GTK_BOX(box), show);
auto* d = new MeasureDialog{&app, edit_index, signal_drop, type_drop,
threshold, above, show, window,
threshold_row, threshold_label, side_row, side_label,
threshold, band, above, show,
window, threshold_row, threshold_label, band_row,
band_label, side_row, side_label,
noise, noise_row, hf, hf_row,
sig_names};
app.measure_dialog = window;
@@ -1739,12 +1747,14 @@ void open_measure_dialog(App& app, int edit_index) {
}
}
gtk_spin_button_set_value(GTK_SPIN_BUTTON(threshold), editing->options.threshold_pct);
gtk_spin_button_set_value(GTK_SPIN_BUTTON(band), editing->options.threshold_pct2);
gtk_spin_button_set_value(GTK_SPIN_BUTTON(noise), editing->options.noise_pct);
gtk_spin_button_set_value(GTK_SPIN_BUTTON(hf), editing->options.hf_fc);
gtk_switch_set_active(GTK_SWITCH(above), editing->options.above);
gtk_check_button_set_active(GTK_CHECK_BUTTON(show), editing->options.show_on_plot);
} else {
gtk_spin_button_set_value(GTK_SPIN_BUTTON(threshold), 50.0);
gtk_spin_button_set_value(GTK_SPIN_BUTTON(band), MeasureOptions{}.threshold_pct2);
gtk_switch_set_active(GTK_SWITCH(above), true);
}
g_signal_connect(type_drop, "notify::selected", G_CALLBACK(on_measure_type_changed), d);
@@ -5769,6 +5779,9 @@ int run_ui(int argc, char** argv, const Config& cfg, ScopeModel& model, Acquisit
if (const char* env = g_getenv("UDPSCOPE_PROBE_MEASURES_MS")) {
g_timeout_add(static_cast<guint>(std::atoi(env)), measures_probe_step, &app);
}
if (const char* env = g_getenv("UDPSCOPE_PROBE_BANDAVG_MS")) {
g_timeout_add(static_cast<guint>(std::atoi(env)), bandavg_probe_step, &app);
}
if (const char* env = g_getenv("UDPSCOPE_PROBE_FIT_MS")) {
g_timeout_add(static_cast<guint>(std::atoi(env)), fit_probe_step, &app);
}
@@ -6379,6 +6392,9 @@ int run_ui(int argc, char** argv, const Config& cfg, ScopeModel& model, Acquisit
i, m.signal.c_str(), measure_type_name(m.type), m.options.threshold_pct,
m.options.above ? 1 : 0, m.options.show_on_plot ? 1 : 0,
r.valid ? "ok" : "invalid", r.valid ? r.primary : 0.0);
// The band's other edge, only for the type that reads two shares: the reading of a `between`
// is a function of the pair, so a line that printed one of them could not say what it is.
if (measure_uses_band(m.type)) std::printf(" thr2=%.1f%%", m.options.threshold_pct2);
// What the row *reads*: the formatted string with its unit (so `frequency` showing Hz
// is asserted here, not inferred), and the row's chip count (two: the measurement's
// colour and the signal's).
src/ui_app.hpp
+17
View File
@@ -584,6 +584,10 @@ struct App {
/// it is a window of its own, so the main window's widget tree does not reach its buttons.
GtkWidget* measure_dialog = nullptr;
int dbg_measure_step = 0;
/// The band-average probe's own step counter. Its own rather than the measurement pane's: the two
/// probes add measurements, so they must not be scheduled in one run (see verification.md), and a
/// shared counter would make that a silent mis-step rather than a documented prohibition.
int dbg_bandavg_step = 0;
int cursors_pane_mode = -1;
int cursors_pane_rows = -1;
unsigned cursors_pane_generation = ~0u;
@@ -1174,6 +1178,9 @@ struct MeasureDialog {
GtkWidget* signal_drop = nullptr;
GtkWidget* type_drop = nullptr;
GtkWidget* threshold = nullptr;
/// `Between`'s *other* edge: the same unit as `threshold`, shown only for the one type that reads
/// two shares (see `measure_uses_band()`).
GtkWidget* band = nullptr;
GtkWidget* above = nullptr;
GtkWidget* show = nullptr;
GtkWidget* window = nullptr;
@@ -1182,6 +1189,8 @@ struct MeasureDialog {
/// and the difference has to be in words, not just in visibility.
GtkWidget* threshold_row = nullptr;
GtkWidget* threshold_label = nullptr;
GtkWidget* band_row = nullptr;
GtkWidget* band_label = nullptr;
GtkWidget* side_row = nullptr;
GtkWidget* side_label = nullptr;
/// The two noise-rejection rows. `noise` is a percentage of the window's peak-to-peak, `hf` a corner in
@@ -1502,6 +1511,10 @@ void on_layout_drag_update(GtkGestureDrag* gesture, double offset_x, double offs
void on_layout_drag_end(GtkGestureDrag* gesture, double offset_x, double offset_y, gpointer user);
void on_trigger_toggled(GtkToggleButton* button, gpointer user);
plot::u32 measure_color(std::size_t index);
/// One line naming what a measurement's type is measuring, with the shares it reads them at: the
/// pane's row tooltip. The row's own label is the type alone (as for every type), so this is where
/// a user sees the share an `above`/`below`/`between` row is averaging over.
std::string measure_row_summary(const Measure& m);
bool visible_samples(App& app, std::size_t channel, std::vector<double>& time, std::vector<double>& value);
int measure_channel(App& app, const std::string& signal);
int measure_row(App& app, const std::string& signal);
@@ -1731,6 +1744,10 @@ void measure_dialog_click(App& a, const char* label);
void measure_dialog_report(App& a, const char* what);
void measures_probe_next(App& a, int step, guint delay_ms);
gboolean measures_probe_step(gpointer user);
void bandavg_probe_next(App& a, int step, guint delay_ms);
void bandavg_report(App& a, const char* what);
int bandavg_index(App& a, MeasureType type, const char* signal);
gboolean bandavg_probe_step(gpointer user);
gboolean zoomkeys_probe(gpointer user);
void menus_probe_next(App& a, int step, guint delay_ms);
void menu_row_labels(GtkWidget* box, GtkWidget** label, GtkWidget** accel);
src/ui_measure.cpp
+88 -14
View File
@@ -7,6 +7,7 @@
#include <gtk/gtk.h>
#include <cstdio>
#include <string>
namespace udpscope {
@@ -21,6 +22,35 @@ plot::u32 measure_color(std::size_t index) {
return kPalette[index % (sizeof(kPalette) / sizeof(kPalette[0]))];
}
/// One line naming what a measurement's type measures, with the shares it reads them at. The pane's
/// row shows the type alone, as it does for every type, so this is the only place a reader sees
/// *which* side of *which* split an `above`/`below` is averaging over, or how wide a `between`
/// band is -- and the reading of those three is entirely a function of those two numbers.
std::string measure_row_summary(const Measure& m) {
const auto pct_text = [](double v) {
char text[32];
std::snprintf(text, sizeof(text), "%g%% of the range", v);
return std::string(text);
};
switch (m.type) {
case MeasureType::Above:
return "the mean of the samples above " + pct_text(m.options.threshold_pct);
case MeasureType::Below:
return "the mean of the samples below " + pct_text(m.options.threshold_pct);
case MeasureType::Between:
return "the mean of the samples between " + pct_text(m.options.threshold_pct) + " and " +
pct_text(m.options.threshold_pct2);
case MeasureType::Top:
case MeasureType::Bottom:
return "the flat level on one side of the split at " + pct_text(m.options.threshold_pct);
case MeasureType::PulseDuration:
return std::string(m.options.above ? "the pulse above " : "the pulse below ") +
pct_text(m.options.threshold_pct);
default:
return std::string("the ") + measure_type_name(m.type) + " of this window";
}
}
/// The channel a measurement's signal resolved to, or -1 while the stream does not carry it.
int measure_channel(App& app, const std::string& signal) {
std::lock_guard<std::mutex> lock(app.model->mutex());
@@ -94,6 +124,8 @@ void measure_dialog_sync(MeasureDialog* d) {
const bool side = measure_uses_side(type);
gtk_widget_set_visible(d->threshold_row, threshold);
gtk_widget_set_visible(d->side_row, side);
// The band's second share: a `Between` is the one type whose two edges are *both* parameters.
gtk_widget_set_visible(d->band_row, measure_uses_band(type));
// The band moves the edge decision, so it is shown for exactly the crossing types. The HF reject sits
// before both walks, so it is shown for all of them.
gtk_widget_set_visible(d->noise_row, measure_uses_noise(type));
@@ -138,6 +170,24 @@ void measure_dialog_sync(MeasureDialog* d) {
gtk_label_set_text(GTK_LABEL(d->threshold_label), "split % of the range (picks the side)");
gtk_check_button_set_label(GTK_CHECK_BUTTON(d->show), "show on plot (ruler at the level)");
break;
case MeasureType::Above:
case MeasureType::Below: {
// These *are* a mean over one side of the split -- the reading the old `top`/`bottom` gave --
// so the words have to say which side of which share, and they have to say it beside the
// field rather than only in the docs: the same spin means a different side for each type.
const bool above = type == MeasureType::Above;
gtk_label_set_text(GTK_LABEL(d->threshold_label), above ? "above % of the range"
: "below % of the range");
gtk_check_button_set_label(GTK_CHECK_BUTTON(d->show), "show on plot (ruler at the mean)");
break;
}
case MeasureType::Between:
// Two shares, so two rows: the band's edges, lower first (the engine orders a reversed pair
// rather than refusing it, so either order the user types reads the same band).
gtk_label_set_text(GTK_LABEL(d->threshold_label), "from % of the range");
gtk_label_set_text(GTK_LABEL(d->band_label), "to % of the range");
gtk_check_button_set_label(GTK_CHECK_BUTTON(d->show), "show on plot (ruler at the mean)");
break;
case MeasureType::PulseDuration:
gtk_label_set_text(GTK_LABEL(d->threshold_label), "split % of the range");
gtk_label_set_text(GTK_LABEL(d->side_label), "pulse above the level");
@@ -177,6 +227,7 @@ void on_measure_dialog_apply(GtkButton*, gpointer user) {
m.signal = d->signals[sig];
m.type = measure_type_at(gtk_drop_down_get_selected(GTK_DROP_DOWN(d->type_drop)));
m.options.threshold_pct = gtk_spin_button_get_value(GTK_SPIN_BUTTON(d->threshold));
m.options.threshold_pct2 = gtk_spin_button_get_value(GTK_SPIN_BUTTON(d->band));
m.options.above = gtk_switch_get_active(GTK_SWITCH(d->above));
m.options.show_on_plot = gtk_check_button_get_active(GTK_CHECK_BUTTON(d->show));
m.options.noise_pct = gtk_spin_button_get_value(GTK_SPIN_BUTTON(d->noise));
@@ -308,6 +359,10 @@ void update_measures(App& app, bool force, bool accumulate) {
std::vector<int> chan(app.measures.size(), -1);
std::vector<int> want_window(app.measures.size(), -1);
std::vector<int> want_level(app.measures.size(), -1);
// `Between` reads two levels, and they are two ordinary entries of the same list: one walk answers
// every level in the pane, so a band costs the same pass two as any other measurement plus one
// more accumulator in it.
std::vector<int> want_level2(app.measures.size(), -1);
for (std::size_t i = 0; i < app.measures.size(); ++i) {
const Measure& m = app.measures[i];
const int channel = measure_channel(app, m.signal);
@@ -335,20 +390,26 @@ void update_measures(App& app, bool force, bool accumulate) {
m.type == MeasureType::Amplitude) {
w.flat_wanted = true;
}
double pct = 0.0;
if (!measure_level_pct(m.type, m.options, pct)) continue;
double pct[2] = {0.0, 0.0};
const int level_count = measure_level_pcts(m.type, m.options, pct);
// A type that does not read the band must not split the accumulator over it: its sums split at the bare
// level, so a `Top` is the same walk whatever the band is. Grouping those at the default is what keeps
// the common pane at exactly one level.
const double noise =
measure_uses_noise(m.type) ? m.options.noise_pct : MeasureOptions{}.noise_pct;
std::size_t k = 0;
while (k < w.pct.size() && (w.pct[k] != pct || w.noise[k] != noise)) ++k;
if (k == w.pct.size()) {
w.pct.push_back(pct);
w.noise.push_back(noise);
for (int j = 0; j < level_count; ++j) {
std::size_t k = 0;
while (k < w.pct.size() && (w.pct[k] != pct[j] || w.noise[k] != noise)) ++k;
if (k == w.pct.size()) {
w.pct.push_back(pct[j]);
w.noise.push_back(noise);
}
if (j == 0) {
want_level[i] = static_cast<int>(k);
} else {
want_level2[i] = static_cast<int>(k);
}
}
want_level[i] = static_cast<int>(k);
}
// The data work: two walks per channel, whatever the pane holds. The first fixes the window's
@@ -483,11 +544,15 @@ void update_measures(App& app, bool force, bool accumulate) {
continue;
}
const App::MeasureWindow& w = *wp;
const MeasureLevel* level =
want_level[i] >= 0 && static_cast<std::size_t>(want_level[i]) < w.level.size()
? &w.level[static_cast<std::size_t>(want_level[i])]
: nullptr;
const MeasureResult r = compute_measure(w.stats, level, m.type, m.options);
// In the order `measure_level_pcts()` asked for them: the band's lower edge first.
const MeasureLevel* levels[2] = {nullptr, nullptr};
const int want[2] = {want_level[i], want_level2[i]};
for (int j = 0; j < 2; ++j) {
if (want[j] >= 0 && static_cast<std::size_t>(want[j]) < w.level.size()) {
levels[j] = &w.level[static_cast<std::size_t>(want[j])];
}
}
const MeasureResult r = compute_measure(w.stats, levels, m.type, m.options);
app.measure_results[i] = r;
if (r.valid) app.measure_last_valid[i] = r;
// Time-valued types carry seconds and a frequency carries hertz whatever the signal's
@@ -646,11 +711,20 @@ void measure_dialog_report(App& a, const char* what) {
if (dd != nullptr) {
// What the dialog is offering for the type on screen: the option rows' visibility and
// the words on them, which is the per-type behaviour a user sees.
std::snprintf(options, sizeof(options), "type=%d thr=%d side=%d show=%d '%s'",
std::snprintf(options, sizeof(options), "type=%d thr=%d band=%d side=%d show=%d "
"shares=%.1f/%.1f '%s'",
static_cast<int>(gtk_drop_down_get_selected(GTK_DROP_DOWN(dd->type_drop))),
dd->threshold_row != nullptr && gtk_widget_get_visible(dd->threshold_row) ? 1 : 0,
dd->band_row != nullptr && gtk_widget_get_visible(dd->band_row) ? 1 : 0,
dd->side_row != nullptr && gtk_widget_get_visible(dd->side_row) ? 1 : 0,
dd->show != nullptr && gtk_widget_get_visible(dd->show) ? 1 : 0,
// What the two share fields are *showing*: the pair a `between` reads, read back
// out of the widgets, so a field that is built but not seeded or not read back is
// visible in the line rather than only in the number it produces.
dd->threshold != nullptr
? gtk_spin_button_get_value(GTK_SPIN_BUTTON(dd->threshold))
: 0.0,
dd->band != nullptr ? gtk_spin_button_get_value(GTK_SPIN_BUTTON(dd->band)) : 0.0,
dd->show != nullptr && gtk_check_button_get_child(GTK_CHECK_BUTTON(dd->show)) !=
nullptr
? gtk_label_get_text(GTK_LABEL(gtk_check_button_get_child(
src/ui_probe.cpp
+219
View File
@@ -2842,6 +2842,225 @@ gboolean measures_probe_step(gpointer user) {
return G_SOURCE_REMOVE;
}
/// The band-average readings, on the shapes whose band means can be computed by hand.
///
/// `above`, `below` and `between` are plain means of the samples on one side of a share -- what
/// `top`/`bottom` reported before a flat level replaced them -- and a mean over a side is a
/// *different number* from the level the signal dwells at, so each reading is asserted where the
/// shape predicts it. Seven measurements are added on the mock's three scalar signals at once,
/// because the trio's point is that a *pair* of levels answers a band no single split can:
/// * the 1 Hz unit sine: `above 50` = 2/pi = 0.636620 and `below 50` = -2/pi, the figures the old
/// `top`/`bottom` documented (and *not* `top`/`bottom`'s 0.957988, the level a sine dwells at
/// near its peak), and `between 50 75` = 3(2-sqrt 3)/pi = 0.255873 -- the mean of the samples in
/// the band (0, 0.5], which is neither 0 (the whole window's mean) nor 0.5 (the band's edge);
/// * the mock's band-limited `square` (30 harmonics, its default): `above 50` = 0.986496, the
/// reading the commit that made `top` a flat level recorded as the *old* `top` -- the edges'
/// ring is inside this mean, and the plateau the signal dwells at is not;
/// * the mock's `ramp`, whose density is uniform: every band's mean is that band's own centre, so
/// `above 50` = 0.5 and `between 50 75` = 0.25 of the range -- a pair of figures no other
/// measurement type on this shape reports (`average` is 0 there, `top`/`bottom` its edges).
/// The dialog leg then edits the sine's band through the real widgets -- the second share is the
/// one field only `between` offers -- and re-reads the value, so a share that is built but not
/// seeded or not read back shows up as a reading that did not move.
gboolean bandavg_probe_step(gpointer user) {
App* a = static_cast<App*>(user);
if (a->window == nullptr) return G_SOURCE_REMOVE;
switch (a->dbg_bandavg_step) {
case 0: {
// The three shapes are enabled *here* rather than assumed: `enable_all_probe` switches a
// signal off two seconds after it runs, and a probe that read another probe's leftovers
// would measure whatever was left. `set_signals_enabled()` is one structural change and a
// no-op when the state already holds, so the usual case costs nothing and the ring keeps
// its history; when it does rebuild, the report below is far enough out for a full window.
std::vector<std::size_t> wanted;
{
std::lock_guard<std::mutex> lock(a->model->mutex());
const std::vector<SignalInfo>& signals = a->model->signals();
for (std::size_t s = 0; s < signals.size(); ++s) {
if (signals[s].name == "sine" || signals[s].name == "square" ||
signals[s].name == "ramp") {
wanted.push_back(s);
}
}
}
a->model->set_signals_enabled(wanted, true);
struct Leg {
const char* signal;
MeasureType type;
double lo;
double hi;
};
const Leg legs[] = {
{"sine", MeasureType::Above, 50.0, 0.0},
{"sine", MeasureType::Below, 50.0, 0.0},
{"sine", MeasureType::Between, 50.0, 75.0},
{"square", MeasureType::Above, 50.0, 0.0},
// The same band on the square: on the band-limited one it holds the two edges' transitions
// -- a real interior whose mean is ~0, because a transition is odd about its own midpoint --
// and on the ideal `--square-harmonics 0` step it holds *nothing at all*, because every
// sample is exactly +/-1. That pair is the empty-interior rule from both sides.
{"square", MeasureType::Between, 50.0, 75.0},
{"ramp", MeasureType::Between, 50.0, 75.0},
// A share at the top of the range has no sample above it, so this one must read what any
// other measurement with nothing to measure reads -- `invalid`/`--`, never 0. The empty
// *interior* is the same rule from the other side, and the ideal square below is where it
// shows: its samples are all exactly +/-1, so the band (0, 0.5] holds none of them.
{"ramp", MeasureType::Above, 100.0, 0.0},
};
for (const Leg& leg : legs) {
Measure m;
m.signal = leg.signal;
m.type = leg.type;
m.options.threshold_pct = leg.lo;
if (leg.hi > 0.0) m.options.threshold_pct2 = leg.hi;
// The marks are part of the reading for these types too: one ruler at the mean.
m.options.show_on_plot = measure_can_show_on_plot(m.type);
a->measures.push_back(std::move(m));
}
select_side_tab(*a, "measure");
rebuild_measures_pane(*a);
g_timeout_add(250, measure_trace, a);
bandavg_probe_next(*a, 1, 1500);
break;
}
case 1: {
// A *full* window before any reading. The window is what the pane last described -- two seconds
// on the documented run -- and the mock delivers about 0.5 MS/s of the 1.3 MS/s it declares, so
// a ring the probe has just re-enabled needs seconds of wall clock to hold a whole one. A short
// ring reads a *partial* window, which is a different number and keeps moving while it fills,
// and the ring is capacity-bound as well, so the wait is read off the store rather than guessed:
// `stored_slots` is how much history there is and `window / dt` is what the pane is measuring.
double slot_dt = 0.0;
{
std::lock_guard<std::mutex> lock(a->model->mutex());
slot_dt = a->model->partition().slot_dt();
}
const double window_s = a->measure_window_valid
? a->measure_window.max - a->measure_window.min
: 0.0;
const std::uint64_t want =
slot_dt > 0.0 && window_s > 0.0 ? static_cast<std::uint64_t>(window_s / slot_dt) : 0;
const std::uint64_t have = a->model->stored_slots();
if (have < want) {
std::fprintf(stderr, "[bandavg-probe] %-15s stored=%llu of %llu slots for a %.3f s window\n",
"waiting", static_cast<unsigned long long>(have),
static_cast<unsigned long long>(want), window_s);
std::fflush(stderr);
bandavg_probe_next(*a, 1, 500);
break;
}
bandavg_report(*a, "readings");
bandavg_probe_next(*a, 2, 400);
break;
}
case 2: {
// The `between` on the sine, through the ordinary edit path: its dialog is the one that
// offers the second share, and this is where the field is read back out of the widgets.
const int at = bandavg_index(*a, MeasureType::Between, "sine");
if (at < 0) {
std::fprintf(stderr, "[bandavg-probe] no sine/between measurement to edit\n");
std::fflush(stderr);
break;
}
open_measure_dialog(*a, at);
bandavg_probe_next(*a, 3, 400);
break;
}
case 3: {
bandavg_report(*a, "edit opened");
auto* d = static_cast<MeasureDialog*>(
g_object_get_data(G_OBJECT(a->measure_dialog), "udpscope-measure-ctx"));
if (d != nullptr) {
// The two fields as the *stored* parameters came back into them, and the band row's
// visibility: a share that is stored but not seeded, or offered for a type that does not
// read it, is a field the user cannot edit back to what the pane is showing.
std::fprintf(stderr,
"[bandavg-probe] %-15s band_row=%d shares=%.1f/%.1f (as stored)\n",
"edit opened", gtk_widget_get_visible(d->band_row) ? 1 : 0,
gtk_spin_button_get_value(GTK_SPIN_BUTTON(d->threshold)),
gtk_spin_button_get_value(GTK_SPIN_BUTTON(d->band)));
// From the mid split to 90 %: a band whose mean neither of its sides reports (the readings
// above 50 and below 90 are 0.636620 and 0.431362), so the value after the save can only
// come from the pair the two fields now hold.
gtk_spin_button_set_value(GTK_SPIN_BUTTON(d->threshold), 50.0);
gtk_spin_button_set_value(GTK_SPIN_BUTTON(d->band), 90.0);
}
measure_dialog_click(*a, "Save");
bandavg_probe_next(*a, 4, 500);
break;
}
case 4:
bandavg_report(*a, "after band edit");
bandavg_probe_next(*a, 5, 300);
break;
case 5: {
// The delete half of the cycle, through the dialog's own button: a measurement that carries
// two shares is shown to survive add, edit and delete like the ones that carry none.
const int at = bandavg_index(*a, MeasureType::Between, "sine");
if (at >= 0) open_measure_dialog(*a, at);
bandavg_probe_next(*a, 6, 400);
break;
}
default: {
const std::size_t before = a->measures.size();
// `measure_dialog_click()` falls through to the emit when it cannot find its button, so the
// dialog being there is this side's to check, not the helper's.
if (a->measure_dialog != nullptr) measure_dialog_click(*a, "Delete");
std::fprintf(stderr, "[bandavg-probe] %-15s measures=%zu -> %zu (want one fewer)\n",
"after delete", before, a->measures.size());
std::fflush(stderr);
break;
}
}
return G_SOURCE_REMOVE;
}
void bandavg_probe_next(App& a, int step, guint delay_ms) {
a.dbg_bandavg_step = step;
g_timeout_add(delay_ms, bandavg_probe_step, &a);
}
/// The index of one of the probe's measurements, by the pair that names it: a `between` on the sine
/// and a `between` on the ramp are two measurements of one type.
int bandavg_index(App& a, MeasureType type, const char* signal) {
for (std::size_t i = 0; i < a.measures.size(); ++i) {
if (a.measures[i].type == type && a.measures[i].signal == signal) return static_cast<int>(i);
}
return -1;
}
/// Reads the pane out: one line per measurement the probe added, with the shares it was given and
/// the two readings a user could compare (the value and the row's own formatted text). The numbers
/// come from a *forced* recompute over the window on screen now, so they are what the pane says at
/// this instant rather than whatever the last moving frame left behind.
void bandavg_report(App& a, const char* what) {
update_measures(a, /*force=*/true, /*accumulate=*/false);
// The window each reading was taken over, beside it: a mean over a share of a *partial* window is
// a different number from the same share of a full one, and nothing in the value says which it
// was. `samples` against the ring's span is what a short ring looks like from here.
for (const App::MeasureWindow& w : a.measure_samples) {
std::fprintf(stderr,
"[bandavg-probe] %-15s window channel=%d lo=%.6f hi=%.6f samples=%zu levels=%zu\n",
what, w.channel, w.stats.lo, w.stats.hi, w.stats.count, w.level.size());
}
for (std::size_t i = 0; i < a.measures.size(); ++i) {
const Measure& m = a.measures[i];
const MeasureResult& r = i < a.measure_results.size() ? a.measure_results[i] : MeasureResult{};
char shares[64];
if (measure_uses_band(m.type)) {
std::snprintf(shares, sizeof(shares), "%.0f/%.0f%%", m.options.threshold_pct,
m.options.threshold_pct2);
} else {
std::snprintf(shares, sizeof(shares), "%.0f%%", m.options.threshold_pct);
}
std::fprintf(stderr, "[bandavg-probe] %-15s %-7s '%s' shares=%-9s -> %-8s %.9g text=[%s]\n",
what, measure_type_name(m.type), m.signal.c_str(), shares,
r.valid ? "ok" : "invalid", r.valid ? r.primary : 0.0,
i < a.measure_text.size() ? a.measure_text[i].c_str() : "");
}
std::fflush(stderr);
}
gboolean zoomkeys_probe(gpointer user) {
App* a = static_cast<App*>(user);
if (a->rows->row_count() == 0 || a->rows->row(0).plot == nullptr) return G_SOURCE_REMOVE;