FastSense: add addSpan(t0, t1, ...) — vertical time-window highlight (the missing vertical dual of addBand)

[HanSur94]

Problem / motivation

The FastSense annotation family — addLine, addThreshold, addBand, addMarker, addShaded, addFill — can highlight a horizontal Y-band across the full X range (addBand(yLow, yHigh)), but has no vertical dual: there is no first-class way to highlight a time window [t0, t1] across the full plot height.

Highlighting a time interval on a recording — a test phase, a maneuver, a warm-up, a fault/downtime window, an event span — is one of the most common annotations a sensor/test engineer draws on a time-series plot. Today the only options are awkward:

• addShaded(x, y1, y2) can fake it, but forces the caller to hand-build x/y1/y2 vectors at the current Y extent — brittle, and it doesn't follow the axes.
• addVLine(x) (proposed in FastSense: add addVLine(x, ...) — vertical reference line at a time (the missing vertical partner of addThreshold) #357) is a single line, not a filled region, so it can't shade an interval.

So the single most common time-series annotation has no clean path.

Proposed feature

Add FastSense.addSpan(t0, t1, ...) — the vertical / time dual of addBand: a shaded patch spanning the full Y range between two X/time bounds.

fp.addSpan(t0, t1, 'FaceColor', [1 0.95 0.8], 'FaceAlpha', 0.25, 'Label', 'Run 3');

Same name-value options and lifecycle contract as addBand ('FaceColor', 'FaceAlpha', 'EdgeColor', 'Label'; must be called before render()).

Rough sketch

• Lib/class: libs/FastSense/FastSense.m
• Property: new Spans struct-array mirroring Bands (FastSense.m:106).
• Method: public addSpan(obj, t0, t1, varargin) mirroring addBand (:686) — same parseOpts/warnUnknownOpts_ defaults, same IsRendered guard.
• Render: a loop mirroring the band render (:1128-1145). Bands emit patchX = [xmin, xmax, xmax, xmin], patchY = [YLow, YLow, YHigh, YHigh]; spans emit the symmetric patchX = [t0, t1, t1, t0], patchY = [ymin, ymin, ymax, ymax] at the axes' Y extent, drawn on the back layer with HandleVisibility off and UserData tagged Type = 'span'.
• Public API shape: addSpan(t0, t1) and addSpan(t0, t1, 'FaceColor', ..., 'FaceAlpha', ..., 'EdgeColor', ..., 'Label', ...).

Value

Direct, one-call highlighting of a time window — the bread-and-butter annotation for test/sensor recordings. Pairs naturally with the existing event/threshold work: an event [tStart, tEnd] can be shaded in a single call.

Constraints check

• Toolbox-free: ✅ plain patch on the existing axes; no toolbox.
• Backward-compatible: ✅ Spans defaults empty → existing plots render byte-for-byte unchanged; no change to serialized dashboards.
• Pure MATLAB/Octave: ✅ mirrors the existing addBand patch path (already Octave-safe).
• Widget contract: ✅ no DashboardWidget/Tag base-contract change (a follow-on could forward it via FastSenseWidget, cf. FastSenseWidget: forward addBand/addMarker/addShaded/addFill annotations to the dashboard chart #216 — out of scope here).

Effort estimate

S — one file (FastSense.m): property + addSpan method + render loop, plus a FastSense test (addSpan before render → one patch at [t0,t1]×[ylim]; empty Spans → unchanged; FaceColor/Alpha/Label honored).

Product micro-decision to flag

Whether the span should track live YLim on zoom. For symmetry and simplicity, the recommended default is to fix the Y extent at render time — exactly as addBand fixes its X extent (bands don't track XLim either). Flagging it so the human decision is explicit.

---

AI-proposed via /feature-scout — needs a human product decision before implementation.