Envelope input, canvas overlays, configurable cursor/fps, and controls hooks

[cboulay]

Seven commits, all of the same kind: things a consumer was doing by reaching into phosphor's internals, which phosphor should own. Found while generalising a downstream viewer that had reimplemented all of them, and refined against a live 256-channel stream.

Envelope input

SweepBuffer(envelope=True) accepts (n_samples, n_channels, 2) — an already-reduced (min, max) pair per sample — instead of raw values. That is what a min/max decimator upstream produces, and accepting it is what lets the reduction happen once near the source rather than shipping a full-rate signal across a process boundary only to discard most of it.

Column reduction takes min-of-mins and max-of-maxes, so the drawn result is identical to what the raw signal would have drawn, provided the upstream bins are finer than a display column. A test asserts exactly that equivalence — if it does not hold, moving decimation upstream changes what the user sees, which was the whole premise.

Measured downstream at 256 channels on a 5 s window: 15× less data across the boundary, and the frame rate roughly doubles at 2 ms bins. Coarser than about one display column (~2.5 ms there) and adjacent columns share a pair, which shows up as a visible zig-zag — worth knowing when choosing a bin size.

Two traps, both documented and tested:

• srate describes the stream being pushed, so in envelope mode it is the bin rate. Sizing from the pre-decimation rate makes the ring factor times longer than the data filling it, and the sweep sits mostly empty.
• Mismatched ranks raise. An (n, ch, 2) array read as raw plots 2*ch channels of interleaved bounds — plausible-looking and wrong.

Canvas overlays

ChannelLabelOverlay (per-trace identifiers) and ScaleBarOverlay (amplitude calibration bar) move in as phosphor.overlays. Base visual elements of a multichannel plot, not application furniture.

Qt painters rather than GPU graphics because text is the point: crisp glyphs at arbitrary sizes, hinted by the platform, no vertex churn as the view scrolls.

The substantive part is who drives them. Outside phosphor a consumer has to poll — sync geometry, re-measure the camera, push the view every tick — because it cannot see the render loop. Here they update from _animation_callback, so they track scroll, paging and zoom by construction. The world→screen projection is measured from the real camera via map_world_to_screen and cached against the inputs that can change it; when the probe fails it falls back to reconstructing the layout analytically, because in a paint path losing precise label placement beats losing the frame.

Label font is capped at 14 px and the labels are toggleable. Both from running it: at a low channel count rows are hundreds of pixels tall, and a label that scaled with them painted a large opaque chip over the signal it was naming. Even capped, the chips cover trace on a dense plot, so there is a "Labels" button.

The scale bar sits in the lower-right, anchored at its foot — centred it sat in the middle of the traces, and anchoring at the foot means the bottom edge stays put as the amplitude scale changes.

set_scale_bar_text() takes the label from the caller rather than formatting it: what a row-height means depends on the signal's units, which a plotting widget does not know. phosphor sizes the bar; the caller says what it represents.

Autoscale toggle removed

The A key and the Auto button switched off the only thing that ever moves the camera — _init_rendering disables the pan/zoom controller, so turning autoscale off did not hand control to the user, it stranded the view.

On the sweep that was a concrete bug: _time_zoom changes buf.display_dur and the axis label but never touches the camera, relying on _apply_auto_scale next frame. With autoscale off, zooming in halved the data's extent while the camera stayed at the old width, so the trace filled the left half of the window and appeared to advance at half the rate the axis claimed.

Nothing else used it — SpectrumWidget and ScatterWidget do not override _apply_auto_scale and also run with no controller, so their off state was equally inert. _apply_auto_scale now runs unconditionally, which is what it always effectively was. _zoom_amplitude's fallback no longer disables autoscale as a side effect — the same trap in miniature, reachable without ever pressing A.

Smaller API gaps

• DEFAULT_MAX_FPS was defined in constants.py and referenced nowhere. Now the default for SweepConfig.max_fps, applied through ChannelPlotWidget.set_max_fps() so every plot type gets it. A caller wanting a render cap had to reach through _figure.canvas.set_update_mode.
• Cursor thickness and colour are SweepConfig fields. The geometry-derived width is in time-world units and collapses to about a pixel, so a consumer wanting a visible cursor was re-styling the fastplotlib graphic on a timer, because the graphic is recreated on version bumps.
• set_channel_labels() — labels usually arrive after the plot is built, and without a setter the only option was assigning _channel_labels and hoping the overlay noticed, which it would not (it caches on identity).
• add_controls() / insert_after(slot, widget) on ChannelPlotControlsWidget, backed by named slots. Extending this toolbar previously meant scanning the layout for a QLabel with matching text and counting widgets past it.

Tests

Adds tests/ — phosphor had none. 27 tests, all headless: SweepBuffer is pure numpy, and the overlays run on Qt's offscreen platform, so the reduction and geometry logic is covered without a rendering backend.

Not covered

The SweepConfig plumbing, set_max_fps, and cursor styling are import-checked and lint-clean but not rendered — there is no GUI harness here and I did not add one. The envelope reduction and overlay geometry are well covered; the widget wiring around them is not. Everything has, however, been exercised by hand against a live 256-channel stream.

Deliberately out of scope: exposing the amplitude scale in physical units, which needs the unit vocabulary (A/D counts, µV, dB, z-units) settled first.