Guides
Add a custom widget
A widget is a class with a .ui() method. Construct it once, then call .ui(...) inside @app.ui each frame.
There is no registration list, base class or decorator.
The simplest widget
from imgui_bundle import imgui
class HelloWidget: def ui(self, ctx) -> None: imgui.text("Hello, MyoGestic!") if imgui.button("Reset"): ctx.status_message = "reset clicked"Build it once and render it each frame:
hello = HelloWidget()viewer = SignalViewer("emg")
@app.uidef ui(ctx): hello.ui(ctx) viewer.ui(ctx)A widget that reads streams
Pass the stream name to __init__ and the live ctx to .ui() each frame:
import numpy as npfrom imgui_bundle import imgui
class ChannelRmsBar: """Bar chart of per-channel RMS over the current window."""
def __init__(self, stream: str = "emg") -> None: self._stream = stream
def ui(self, ctx) -> None: s = ctx.streams.get(self._stream) if s is None: imgui.text_disabled(f"stream '{self._stream}' not found") return data, _ = s.get_window() # (n_channels, n_samples) if data.size == 0: imgui.text_disabled("buffer empty") return rms = np.sqrt(np.mean(data**2, axis=1)) rms_norm = rms / (rms.max() + 1e-9) for ch, val in enumerate(rms_norm): imgui.text(f"ch {ch:2d}") imgui.same_line() imgui.progress_bar(float(val), imgui.ImVec2(120, 0), f"{rms[ch]:.3f}")bar = ChannelRmsBar("emg") once, then bar.ui(ctx) inside @app.ui, and you have a live RMS bar chart.
Persistent state
Store persistent UI state as instance attributes. Keeping the widget instance preserves selected channels, scroll offset and popup state across frames:
class ChannelPicker: def __init__(self, stream: str = "emg") -> None: self._stream = stream self._visible: set[int] = set() # persists across frames
def ui(self, ctx) -> None: s = ctx.streams.get(self._stream) if s is None or s.info is None: return for ch in range(s.info.n_channels): on = ch in self._visible changed, on = imgui.checkbox(f"ch {ch}", on) if changed: self._visible = self._visible | {ch} if on else self._visible - {ch}ChannelPicker("emg") and ChannelPicker("imu") keep separate state.
Splitting a widget across files
If a widget grows past ~200 LOC, split it. Use the SignalViewer layout as a template:
myogestic/widgets/signals/viewer.py # public class SignalViewer - calls into the privatesmyogestic/widgets/signals/_state.py # per-stream state dataclassmyogestic/widgets/signals/_controls.py # control panel renderingmyogestic/widgets/signals/_plot.py # plot renderingThe public class lives in one file. Private modules are explicitly underscore-prefixed and not exported from myogestic.widgets.__init__. User code never imports them.
Exporting your widget
Edit myogestic/widgets/__init__.py:
from myogestic.widgets.my_widget import MyWidget
__all__ = [..., "MyWidget"]from myogestic.widgets import MyWidget imports the widget.
Reading from Pipeline predictions
For widgets that visualize model output, store the stable pipeline object in the constructor and read its live predictions in .ui():
class SimplePrediction: def __init__(self, pipeline) -> None: self._pipeline = pipeline
def ui(self) -> None: if self._pipeline.model is None: imgui.text_disabled("not trained") return pred = self._pipeline.predictions # dict[str, Any] - what predict() last returned if not pred: imgui.text_disabled("no prediction yet") return imgui.text(f"Class: {pred.get('class')}")Read scalar fields directly. Use dict(self._pipeline.predictions) for a coherent snapshot of multiple fields.
Common mistakes
See Troubleshooting for errors by symptom.
- Constructing the widget inside
@app.ui.MyWidget().ui(ctx)in the frame loop rebuilds it every frame and resets its state. Build it once, outside the render function. - Holding a removed
Stream. Apps can add or remove streams while running. Re-readctx.streams.get(name)each frame in.ui(ctx)if your widget must follow those changes. - Computing in the widget. Run FFT, convolution and model evaluation on the predict thread. Cache results on
ctxor your own object for.ui()to read. - Calling
imgui.set_next_window_size(...)inside aGridcell. The grid manages sizes; per-window calls fight it. If you need a non-grid window, render outside the grid and usepopout_panelorimgui.begin/enddirectly. - Using mutable defaults in the constructor.
def __init__(self, names=[])shares the default list across instances. Usenames: list[str] | None = Noneandif names is None: names = []inside.