Concepts
Architecture
Acquisition, decision and rendering are independent concerns. Sources feed ring buffers on acquisition threads. The predict thread computes decisions, and the main thread renders widgets. Actuation is a fourth concern. A Target drives a device from a sanitized control frame. Targets or user code can send values through paced outputs.
Data flow
A typical tick of the system:
- Acquisition thread for stream
"emg"reads a chunk fromLSLSource, appends to the ring buffer, and appends to its Zarr array while a session is attached to that stream.ctx.sessionalso holds the most recent stopped take, so it is not the recording flag. It never copies the growing history. - Predict thread, once per
1/predict_hz, pulls a window via the channels-firstStream.get_window(), forwards it to@pipeline.extract, then to@pipeline.predict(model, features). The returneddict[str, Any]is stored inpipeline.predictions. - The main render thread draws widgets from
ctx.SignalViewerasks for only its visible tail and builds a plot-width-sized min/max envelope. The pose-output filter (PostProcessor) renders its panel. - Output thread for
LSLOutletreads its atomic latest-value slot every1/hzand sends it every tick, even if unchanged. Each write replaces the latest value. Delivery is latest-wins; values are never queued.
On desktop, acquisition, prediction and output loops use daemon threads; rendering stays on the main thread. Context, Pipeline and the stream buffers hold shared state, with locks around buffer and session access. In the browser playground, acquisition and prediction run as scheduled steps on the GUI frame loop.
Module map
| Module | Responsibility |
|---|---|
myogestic.core |
App, Context, lifecycle hooks, run loops |
myogestic.stream |
Stream, ring buffer, acquisition thread, display snapshots |
myogestic.sources |
LSLSource, ReplaySource, SerialSource |
myogestic.outputs |
Outlet base + LSLOutlet, the output-side filters |
myogestic.controls |
Target, ControlBus, Capability for driving devices |
myogestic.session |
Recording, label tracks, .mg.zip, window iterators |
myogestic.ml |
Pipeline, train/predict lifecycle, ML widgets |
myogestic.recipes |
CatBoost / scikit-learn constructor recipes |
myogestic.widgets |
Construct-once ImGui widget classes and rendering helpers |
myogestic.outputs.filters |
OneEuro / Gaussian / Identity output smoothers |
myogestic.bridges |
Subprocess pattern for heavy-data sources such as webcams and ultrasound |
Public API boundary
Keep these import paths stable. The internal modules myogestic.core and myogestic.stream are subject to change; user code should import from the package root or named subpackages:
from myogestic import App, Grid, Stream, TrainingDatafrom myogestic.sources import LSLSource, ReplaySourcefrom myogestic.outputs import LSLOutletfrom myogestic.ml import Pipelinefrom myogestic.session import open_session_store, iter_labeled_windowsfrom myogestic.widgets import SignalViewer, RecordingControls, SessionManagerSee Public API cheatsheet for the full surface.