better-rtplot 0.2.0__tar.gz → 0.2.1__tar.gz

better_rtplot-0.2.1/PKG-INFO

@@ -0,0 +1,446 @@
+Metadata-Version: 2.1
+Name: better-rtplot
+Version: 0.2.1
+Summary: 
+License: GPL V3.0
+Author: jmontp
+Author-email: jmontp@umich.edu
+Requires-Python: >=3.9,<3.13
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: browser
+Provides-Extra: server
+Requires-Dist: aiohttp (>=3.9.0) ; extra == "browser"
+Requires-Dist: numpy (>=1.23.5)
+Requires-Dist: pandas (>=1.5.3) ; extra == "server" or extra == "browser"
+Requires-Dist: pyarrow (>=11.0.0) ; extra == "server" or extra == "browser"
+Requires-Dist: pyqtgraph (>=0.13.0) ; extra == "server"
+Requires-Dist: pyside6 (>6.4.0) ; extra == "server"
+Requires-Dist: pyzmq (>=25.0.0)
+Description-Content-Type: text/markdown
+
+![Logo of the project](https://github.com/jmontp/rtplot/blob/master/.images/signature-stationery.png)
+
+# rtplot — real-time plotting over ZMQ
+
+**rtplot** lets a Python script push live data to a plot window — locally, or
+across the network — with a few lines of code on the sender side. The plot
+window can be a traditional Qt application or a modern browser UI, and it
+also supports interactive controls (buttons, sliders, dials, text and
+numeric displays) that feed values back into the sending script in real time.
+
+Typical use: a robot or data-acquisition script runs on a Raspberry Pi or
+microcontroller host, and you watch live signals and tweak gains from a
+laptop on the same network.
+
+---
+
+## Table of contents
+
+- [Highlights](#highlights)
+- [Install](#install)
+- [60-second quickstart](#60-second-quickstart)
+- [Choosing a server: browser vs. Qt](#choosing-a-server-browser-vs-qt)
+- [Interactive controls](#interactive-controls)
+  - [Reading controls from Python](#reading-controls-from-python)
+  - [Pushing values into displays](#pushing-values-into-displays)
+  - [Element reference](#element-reference)
+- [Plot configuration](#plot-configuration)
+- [Sending data](#sending-data)
+- [Saving data](#saving-data)
+- [Networking modes](#networking-modes)
+- [Performance tuning](#performance-tuning)
+- [CLI reference](#cli-reference)
+- [Examples](#examples)
+
+---
+
+## Highlights
+
+- **Fast.** 500+ fps on a single trace on a modern laptop. Binary WebSocket
+  deltas on the browser server; raw Qt rendering on the desktop server.
+- **Two frontends.** A new browser-based server (aiohttp + uPlot) and the
+  original pyqtgraph desktop server. Both speak the same ZMQ protocol, so
+  client code is identical.
+- **Remote-friendly.** Either the sender or the plot host can bind — pick
+  whichever fits your network. Works across LAN, WSL, and SSH tunnels.
+- **Plot config lives with the data.** The sender declares the plot layout,
+  so a Pi running your experiment owns the look of its own dashboards.
+- **Interactive controls** *(browser server only)*. Declare buttons,
+  sliders, dials, numeric/text displays in the same `initialize_plots`
+  call. Poll from your tight loop; no threads, no callbacks.
+- **Save to Parquet** with a single button click or `client.save_plot()`
+  call.
+
+---
+
+## Install
+
+Minimum install — just the client (send data only):
+
+```bash
+pip install better-rtplot
+```
+
+Add the browser server (recommended):
+
+```bash
+pip install "better-rtplot[browser]"
+```
+
+Add the Qt/pyqtgraph server instead:
+
+```bash
+pip install "better-rtplot[server]"
+```
+
+The `browser` extra pulls `aiohttp` + `pandas` + `pyarrow`; the `server`
+extra pulls `pyqtgraph` + `PySide6` + `pandas` + `pyarrow`. If you only
+`pip install better-rtplot` and try to launch a server, rtplot will print
+a friendly message telling you which extra to add.
+
+WSL users: the browser server works out of the box — open the URL it
+prints in your Windows browser. The Qt server needs an X server such as
+[VcXsrv](https://sourceforge.net/projects/vcxsrv/).
+
+---
+
+## 60-second quickstart
+
+**Terminal 1 — start a plot window:**
+
+```bash
+python -m rtplot.server_browser        # browser UI at http://localhost:8050
+# or
+python -m rtplot.server                 # desktop Qt window
+```
+
+**Terminal 2 — send data:**
+
+```python
+from rtplot import client
+import numpy as np, time
+
+client.local_plot()                     # send to the server on 127.0.0.1
+client.initialize_plots(["sin", "cos"]) # one plot with two named traces
+
+for i in range(10000):
+    t = i * 0.01
+    client.send_array([np.sin(t), np.cos(t)])
+    time.sleep(0.01)
+```
+
+That's it. Open http://localhost:8050 if you used the browser server; the
+Qt server will pop up its own window.
+
+---
+
+## Choosing a server: browser vs. Qt
+
+| | **Browser server** (`rtplot.server_browser`) | **Qt server** (`rtplot.server`) |
+|---|---|---|
+| Frontend | aiohttp + uPlot in any modern browser | pyqtgraph + PySide6 desktop window |
+| Extra | `[browser]` | `[server]` |
+| Works over SSH | Yes (just forward the HTTP port) | No (needs X forwarding) |
+| Interactive controls | **Yes** — buttons, sliders, dials, displays | No |
+| Typical frame rate | 60 Hz render, 1000 Hz data push cap | 500+ fps |
+| Saves to Parquet | Yes | Yes |
+
+If you're on WSL, running remotely, or you want interactive controls,
+**use the browser server**. The Qt server is still available for local
+desktop use and for legacy setups.
+
+---
+
+## Interactive controls
+
+*Browser server only.* Declare a control row inline in your plot layout:
+
+```python
+from rtplot import client
+import numpy as np, time
+
+client.local_plot()
+client.initialize_plots([
+    {"names": ["signal"], "yrange": [-6, 6]},
+    {"controls": [
+        {"type": "button", "id": "reset", "label": "Reset"},
+        {"type": "button", "id": "pause", "label": "Pause"},
+        {"type": "slider", "id": "gain",  "label": "Gain",
+         "min": 0, "max": 5, "value": 1.0, "step": 0.1, "format": "{:.2f}"},
+    ]},
+    {"controls": [
+        {"type": "dial",    "id": "freq", "label": "Freq (Hz)",
+         "min": 0.1, "max": 5.0, "value": 1.0, "step": 0.05,
+         "sensitivity": 0.5, "format": "{:.2f}"},
+        {"type": "display", "id": "t",    "label": "t (s)", "format": "{:.2f}"},
+        {"type": "text",    "id": "msg",  "label": "Status",
+         "value": "running"},
+    ]},
+])
+
+running = True
+t0 = time.time()
+while True:
+    ctrl = client.poll_controls()
+    for btn in ctrl.buttons:
+        if btn == "reset": t0 = time.time()
+        if btn == "pause": running = not running
+
+    gain = ctrl.values.get("gain", 1.0)
+    freq = ctrl.values.get("freq", 1.0)
+    t = time.time() - t0
+    amp = gain * np.sin(2 * np.pi * freq * t) if running else 0.0
+
+    client.set_display("t", t)
+    client.set_display("msg", "paused" if not running else "running")
+    client.send_array(amp)
+    time.sleep(0.01)
+```
+
+### Reading controls from Python
+
+```python
+ctrl = client.poll_controls()           # non-blocking, cheap to call every loop
+gain = ctrl.values.get("gain", 1.0)     # latest slider/dial value
+for btn_id in ctrl.buttons:             # list of buttons fired since last poll
+    handle(btn_id)
+```
+
+`poll_controls()` returns a `ControlState(values, buttons)` namedtuple:
+
+- `values` — a `dict` of `{element_id: float}` for every slider and dial
+  the server has told the client about. Defaults declared in
+  `initialize_plots` are pre-seeded so the **first** call already sees
+  them.
+- `buttons` — a `list` of button ids fired since the previous poll, in
+  order. The list is cleared on return, so each event is delivered
+  exactly once.
+
+Call it from your tight loop before computing the next sample. No
+threads, no callbacks, no missed events.
+
+### Pushing values into displays
+
+```python
+client.set_display("t", 12.34)       # numeric display box
+client.set_display("msg", "running") # text field
+```
+
+`set_display()` accepts either a number (for `type: "display"` elements)
+or a string (for `type: "text"` elements). Updates are coalesced on the
+server and rebroadcast to every connected browser at ~30 Hz.
+
+### Element reference
+
+| Type | Purpose | Notable fields |
+|---|---|---|
+| `button` | Fires a discrete event when clicked | `id`, `label` |
+| `slider` | Scalar input via horizontal range | `id`, `label`, `min`, `max`, `value`, `step`, `format` |
+| `dial` | Scalar input via rotational drag | same as slider, plus `sensitivity` (full turns per range sweep; default `1.0`) |
+| `display` | Read-only numeric readout | `id`, `label`, `format` |
+| `text` | Read-only text field (prompts, status) | `id`, `label`, `value` |
+
+Slider and dial widgets both render as **`[widget] [−] [number input] [+]`**,
+so you can drag, type a value directly, or nudge by `step`. The dial
+accepts "round and round" circular drag — each full rotation walks the
+value through `(max − min) × sensitivity`, so `sensitivity: 0.25` gives
+you four rotations per sweep for fine control.
+
+The `format` field accepts Python-style `{:.Nf}` strings (e.g. `"{:.2f}"`).
+
+---
+
+## Plot configuration
+
+Each entry in `initialize_plots` is one of:
+
+- an **integer** — `client.initialize_plots(3)` → one plot with 3 anonymous
+  traces
+- a **string** — `client.initialize_plots("torque")` → one plot with one
+  named trace
+- a **list of strings** — one plot, one trace per name
+- a **list of lists of strings** — one plot per sublist
+- a **dict** — one plot, with full styling options (below)
+- a **list of dicts** — multiple plots with full styling
+
+A styled plot dict accepts any of:
+
+| Key | Meaning |
+|---|---|
+| `names` | **Required.** List of trace names. |
+| `colors` | List of per-trace colors. Single letter (`r g b c m y k w`) or any CSS color string. |
+| `line_style` | `"-"` for dashed, `""` (or anything else) for solid, per trace. |
+| `line_width` | Per-trace line width in pixels. |
+| `title` | Plot title. |
+| `xlabel` / `ylabel` | Axis labels. |
+| `yrange` | `[ymin, ymax]` — pins the Y axis and significantly speeds up rendering. |
+| `xrange` | Integer number of samples visible at once (default 200). |
+
+Special row entries (not plots themselves):
+
+- `{"controls": [...]}` — a row of interactive controls (browser server only)
+- `{"non_plot_labels": ["name1", "name2"]}` — extra scalar names that ride
+  along with `send_array` and get saved into the output Parquet file, but
+  aren't rendered as traces
+
+---
+
+## Sending data
+
+```python
+client.send_array(scalar)           # float
+client.send_array([a, b, c])        # 1-D list: one sample per trace
+client.send_array(np.array([...]))  # 1-D numpy array: one sample per trace
+client.send_array(np.array([[...]]))# 2-D (num_traces, N): N samples at once
+```
+
+Passing a 2-D array with `N > 1` lets you push a batch of samples per
+`send_array` call, which is the fastest way to get many samples through
+without dropping frames.
+
+---
+
+## Saving data
+
+The server saves every sample it has received since the latest
+`initialize_plots` call to a Parquet file, including any
+`non_plot_labels` data that rode along with your normal data.
+
+Trigger a save from either side:
+
+- **Browser UI:** click the **Save Plot** button.
+- **Python:** `client.save_plot("my_run")`
+
+Control where things get written:
+
+```bash
+python -m rtplot.server_browser -sd ./saved_plots -sn experiment1
+```
+
+- `-sd` / `--save-dir` — target directory
+- `-sn` / `--save-name` — filename prefix (a timestamp is always appended)
+
+### Save non-plot signals alongside the plotted ones
+
+```python
+client.initialize_plots([
+    {"names": ["hip_angle", "knee_angle"]},
+    {"non_plot_labels": ["battery", "cpu_temp", "loop_latency"]},
+])
+```
+
+Send `battery`, `cpu_temp` and `loop_latency` as extra rows after the
+plotted traces in each `send_array` call; they won't be drawn but they
+will land in the Parquet file.
+
+---
+
+## Networking modes
+
+rtplot uses ZMQ, so either the sender or the plot host can be the one
+that *binds* a socket. Pick whichever works for your network and
+firewalls.
+
+**Mode A — plot host binds, sender connects** *(typical for lab laptops)*
+
+```bash
+# on the plot host (e.g. your laptop)
+python -m rtplot.server_browser
+```
+
+```python
+# on the sender (e.g. the Pi)
+from rtplot import client
+client.configure_ip("192.168.1.42")   # the laptop's LAN IP
+```
+
+**Mode B — sender binds, plot host connects** *(typical when the sender
+has a static IP and the viewer roams around)*
+
+```bash
+# on the plot host
+python -m rtplot.server_browser -p 192.168.1.50   # the sender's IP
+```
+
+```python
+# on the sender
+from rtplot import client
+# no configure_ip call needed — the default behavior binds
+```
+
+If you pass `-p host:port` to the server, rtplot also derives the control
+return-channel endpoint from that same host/port (it uses `port+1`). This
+means sliders, buttons, and dials work transparently in both modes with
+no extra config.
+
+---
+
+## Performance tuning
+
+If you start running out of frames, try these, in roughly this order:
+
+1. **Pin the Y range.** `{"yrange": [-2, 2]}` on each plot lets the
+   renderer skip autoscaling work and gives the single biggest win.
+2. **Batch your samples.** Pass a 2-D numpy array to `send_array` so N
+   samples ship per call.
+3. **Shrink the window.** Fewer pixels to redraw per frame.
+4. **Reduce `line_width`.** Thicker lines cost more to rasterize.
+5. **Use the `-s N` / `--skip N` server flag** to push every Nth sample
+   batch to the browser instead of every one. Add `-a` / `--adaptable`
+   to let the server tune `N` to your data rate automatically.
+6. **Increase `xrange`.** Counterintuitively, a longer visible history
+   can be cheaper than a short one because the browser ring-buffers the
+   data and only replaces the tail on each push.
+
+---
+
+## CLI reference
+
+**Browser server** (`python -m rtplot.server_browser`):
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `-p HOST[:PORT]` | (bind) | Connect to a sender at this address instead of binding |
+| `--host HOST` | `0.0.0.0` | HTTP bind interface |
+| `--port N` | `8050` | HTTP port |
+| `--no-browser` | off | Don't try to open a browser on startup |
+| `--rate N` | `1000` | Max WebSocket push rate (Hz) |
+| `-n N` / `--skip N` | `1` | Push every Nth sample batch |
+| `-a` / `--adaptable` | off | Auto-tune skip rate to data rate |
+| `-c` / `--column` | row | Lay plots out in columns instead of rows |
+| `-d` / `--debug` | off | Extra debug logging |
+| `-sd DIR` / `--save-dir DIR` | cwd | Where to write `.parquet` saves |
+| `-sn NAME` / `--save-name NAME` | — | Prefix for saved filenames |
+
+**Qt server** (`python -m rtplot.server`): same `-p`, `-n`, `-a`, `-c`,
+`-d`, `-sd`, `-sn` flags as above, plus:
+
+| Flag | Meaning |
+|---|---|
+| `-b` / `--bigscreen` | Pre-configure for the neurobionics lab big-screen display |
+| `-t FILE` / `--plot_config FILE` | Load a plot configuration from a file on startup |
+
+---
+
+## Examples
+
+- [`rtplot/example_code.py`](rtplot/example_code.py) — a walk through
+  every `initialize_plots` signature, plus a controls demo at the bottom.
+- [`rtplot/interactive_test.py`](rtplot/interactive_test.py) — a guided
+  end-to-end test that walks you through clicking buttons, dragging
+  sliders, typing into the number input, using the ± nudge arrows, and
+  spinning the dial. Good for smoke-testing a fresh install.
+
+  ```bash
+  python -m rtplot.server_browser &
+  python -m rtplot.interactive_test
+  ```
+
+![Qt server example 1](https://github.com/jmontp/rtplot/blob/master/.images/rtplot_example1.png)
+![Qt server example 2](https://github.com/jmontp/rtplot/blob/master/.images/rtplot_example2.png)
+