Skip to content
GitHub · 2.7.0

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

Python
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:

Python
hello = HelloWidget()
viewer = SignalViewer("emg")
@app.ui
def 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:

Python
import numpy as np
from 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:

Python
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:

Text
myogestic/widgets/signals/viewer.py # public class SignalViewer - calls into the privates
myogestic/widgets/signals/_state.py # per-stream state dataclass
myogestic/widgets/signals/_controls.py # control panel rendering
myogestic/widgets/signals/_plot.py # plot rendering

The 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:

Python
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():

Python
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-read ctx.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 ctx or your own object for .ui() to read.
  • Calling imgui.set_next_window_size(...) inside a Grid cell. The grid manages sizes; per-window calls fight it. If you need a non-grid window, render outside the grid and use popout_panel or imgui.begin/end directly.
  • Using mutable defaults in the constructor. def __init__(self, names=[]) shares the default list across instances. Use names: list[str] | None = None and if names is None: names = [] inside.