better-rtplot 0.3.0__tar.gz → 0.4.1__tar.gz

better_rtplot-0.4.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.1
+Name: better-rtplot
+Version: 0.4.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: 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
+
+# rtplot — real-time plotting over ZMQ
+
+**rtplot** pushes live data from a Python script to a browser plot —
+locally or across a network — in a few lines of code. The plot page
+also hosts interactive widgets (buttons, sliders, dials, numeric / text
+displays) that feed values back to the sender in real time.
+
+Typical use: a robot or data-acquisition script runs on a Raspberry Pi,
+and you watch signals and tweak gains from a laptop on the same Wi-Fi.
+
+---
+
+## How it works
+
+Two processes talking over ZMQ, plus a browser viewer:
+
+```mermaid
+flowchart TD
+    script["Your Python script<br/>send_array() · poll_controls()"]
+    subgraph server["rtplot-server"]
+        browser["browser tab<br/>localhost:8050"]
+    end
+    script -- "data :5555" --> server
+    server -- "controls :5556" --> script
+```
+
+Sender and server don't have to be on the same machine — see the
+[networking guide](docs/networking.md).
+
+---
+
+## Install
+
+**Server** — grab the prebuilt binary from the
+[Releases page](https://github.com/jmontp/rtplot/releases):
+
+| Platform | Asset |
+|---|---|
+| Windows | `rtplot-server-<version>-windows-x64.exe` |
+| Linux | `rtplot-server-<version>-linux-x86_64.tar.gz` |
+| macOS (Apple Silicon) | `rtplot-server-<version>-macos-arm64.tar.gz` |
+
+No Python needed on the viewing machine. On Windows the binary opens
+a small Tk status window showing the listening URL.
+
+**Client** — pip install in the env that runs your script:
+
+```bash
+pip install better-rtplot
+```
+
+(If you'd rather run the server from Python too, use
+`pip install "better-rtplot[browser]"` — see the
+[API reference](docs/api.md#install-detail).)
+
+---
+
+## Your first plot
+
+```mermaid
+flowchart TD
+    t1["terminal 1: start the server"]
+    t2["terminal 2: run your script"]
+    br["browser: open localhost:8050"]
+    t1 --> t2 --> br
+```
+
+**Terminal 1 — start the server.** Run the prebuilt `rtplot-server`
+binary you downloaded above. Open `http://localhost:8050` in a
+browser — the page is blank until data arrives.
+
+**Terminal 2 — run your sender script.** Save as `my_plot.py`:
+
+```python
+from rtplot import client
+import time
+
+client.local_plot()
+client.initialize_plots(["my signal"])
+
+for i in range(1000):
+    client.send_array(i * 0.01)
+    time.sleep(0.01)
+```
+
+```bash
+python my_plot.py
+```
+
+A rising line now draws itself in the browser tab.
+
+---
+
+## Highlights
+
+- **Fast.** Binary WebSocket deltas up to 1 kHz; the browser coalesces
+  samples into one repaint per `requestAnimationFrame`, so rendering
+  tracks your monitor refresh rate regardless of sample rate.
+- **Browser-based.** aiohttp + uPlot, no desktop GUI toolkit, works
+  over SSH port forwarding.
+- **Remote-friendly.** Sender or plot host can bind. Live Bind /
+  Connect buttons retarget without restart.
+- **Config lives with the data.** The sender declares plot layout.
+- **Interactive controls.** Buttons, sliders, dials, displays — polled
+  from your loop, no threads, no callbacks.
+- **Static HTML snapshots.** `save_snapshot("out.html")` writes a
+  self-contained ~65 KB file with the current trace embedded.
+
+---
+
+## Where to go next
+
+- **[API reference](docs/api.md)** — every `rtplot.client` function,
+  the plot-layout schema, interactive controls, snapshots, browser UI,
+  and `rtplot-server` CLI flags.
+- **[Networking guide](docs/networking.md)** — Mode A vs. Mode B,
+  viewing from a phone or second laptop, the WSL2 wrinkle, Cloudflare
+  Tunnel, Tailscale.
+- **[Examples](examples/README.md)** — runnable scripts with embedded
+  HTML snapshots you can open offline.
+
+---
+
+Issues and feature requests:
+[github.com/jmontp/rtplot/issues](https://github.com/jmontp/rtplot/issues).
+

better_rtplot-0.4.1/README.md

@@ -0,0 +1,125 @@
+# rtplot — real-time plotting over ZMQ
+
+**rtplot** pushes live data from a Python script to a browser plot —
+locally or across a network — in a few lines of code. The plot page
+also hosts interactive widgets (buttons, sliders, dials, numeric / text
+displays) that feed values back to the sender in real time.
+
+Typical use: a robot or data-acquisition script runs on a Raspberry Pi,
+and you watch signals and tweak gains from a laptop on the same Wi-Fi.
+
+---
+
+## How it works
+
+Two processes talking over ZMQ, plus a browser viewer:
+
+```mermaid
+flowchart TD
+    script["Your Python script<br/>send_array() · poll_controls()"]
+    subgraph server["rtplot-server"]
+        browser["browser tab<br/>localhost:8050"]
+    end
+    script -- "data :5555" --> server
+    server -- "controls :5556" --> script
+```
+
+Sender and server don't have to be on the same machine — see the
+[networking guide](docs/networking.md).
+
+---
+
+## Install
+
+**Server** — grab the prebuilt binary from the
+[Releases page](https://github.com/jmontp/rtplot/releases):
+
+| Platform | Asset |
+|---|---|
+| Windows | `rtplot-server-<version>-windows-x64.exe` |
+| Linux | `rtplot-server-<version>-linux-x86_64.tar.gz` |
+| macOS (Apple Silicon) | `rtplot-server-<version>-macos-arm64.tar.gz` |
+
+No Python needed on the viewing machine. On Windows the binary opens
+a small Tk status window showing the listening URL.
+
+**Client** — pip install in the env that runs your script:
+
+```bash
+pip install better-rtplot
+```
+
+(If you'd rather run the server from Python too, use
+`pip install "better-rtplot[browser]"` — see the
+[API reference](docs/api.md#install-detail).)
+
+---
+
+## Your first plot
+
+```mermaid
+flowchart TD
+    t1["terminal 1: start the server"]
+    t2["terminal 2: run your script"]
+    br["browser: open localhost:8050"]
+    t1 --> t2 --> br
+```
+
+**Terminal 1 — start the server.** Run the prebuilt `rtplot-server`
+binary you downloaded above. Open `http://localhost:8050` in a
+browser — the page is blank until data arrives.
+
+**Terminal 2 — run your sender script.** Save as `my_plot.py`:
+
+```python
+from rtplot import client
+import time
+
+client.local_plot()
+client.initialize_plots(["my signal"])
+
+for i in range(1000):
+    client.send_array(i * 0.01)
+    time.sleep(0.01)
+```
+
+```bash
+python my_plot.py
+```
+
+A rising line now draws itself in the browser tab.
+
+---
+
+## Highlights
+
+- **Fast.** Binary WebSocket deltas up to 1 kHz; the browser coalesces
+  samples into one repaint per `requestAnimationFrame`, so rendering
+  tracks your monitor refresh rate regardless of sample rate.
+- **Browser-based.** aiohttp + uPlot, no desktop GUI toolkit, works
+  over SSH port forwarding.
+- **Remote-friendly.** Sender or plot host can bind. Live Bind /
+  Connect buttons retarget without restart.
+- **Config lives with the data.** The sender declares plot layout.
+- **Interactive controls.** Buttons, sliders, dials, displays — polled
+  from your loop, no threads, no callbacks.
+- **Static HTML snapshots.** `save_snapshot("out.html")` writes a
+  self-contained ~65 KB file with the current trace embedded.
+
+---
+
+## Where to go next
+
+- **[API reference](docs/api.md)** — every `rtplot.client` function,
+  the plot-layout schema, interactive controls, snapshots, browser UI,
+  and `rtplot-server` CLI flags.
+- **[Networking guide](docs/networking.md)** — Mode A vs. Mode B,
+  viewing from a phone or second laptop, the WSL2 wrinkle, Cloudflare
+  Tunnel, Tailscale.
+- **[Examples](examples/README.md)** — runnable scripts with embedded
+  HTML snapshots you can open offline.
+
+---
+
+Issues and feature requests:
+[github.com/jmontp/rtplot/issues](https://github.com/jmontp/rtplot/issues).

{better_rtplot-0.3.0 → better_rtplot-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "better-rtplot"
-version = "0.3.0"
+version = "0.4.1"
 description = ""
 authors = ["jmontp <jmontp@umich.edu>"]
 license = "GPL V3.0"

{better_rtplot-0.3.0 → better_rtplot-0.4.1}/rtplot/client.py

@@ -2,6 +2,8 @@ import zmq
 import numpy as np
 import time
 from collections import OrderedDict, namedtuple
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple, Union
 
 ###################
 # ZMQ Networking #
@@ -85,19 +87,177 @@ SENDING_DISPLAY = "4"
 #Lightweight result type returned by poll_controls()
 ControlState = namedtuple("ControlState", ["values", "buttons"])
 
+
+##########################################
+# Typed plot / controls configuration API #
+##########################################
+#
+# These dataclasses are an alternative to the dict-based configuration
+# accepted by initialize_plots(). Both APIs coexist — the typed form
+# serializes to the exact same on-the-wire dict, so the server is
+# unaware of which one the caller used.
+#
+#   client.initialize_plots([
+#       client.Plot(names=["signal"], yrange=(-6, 6), title="demo"),
+#       client.ControlsRow([client.Button("reset", "Reset")]),
+#   ])
+#
+# is equivalent to the classic:
+#
+#   client.initialize_plots([
+#       {"names": ["signal"], "yrange": [-6, 6], "title": "demo"},
+#       {"controls": [{"type": "button", "id": "reset", "label": "Reset"}]},
+#   ])
+
+
+def _drop_none(d):
+    # Wire format treats missing keys as "use default"; None would
+    # JSON-serialize to null which the server wouldn't handle.
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _range_to_list(r):
+    # yrange/xrange go over the wire as JSON lists.
+    return list(r) if r is not None else None
+
+
+@dataclass
+class Plot:
+    """A single plot with optional styling.
+
+    All fields beyond ``names`` are optional and mirror the styled-plot
+    dict keys documented in ``docs/api.md``.
+    """
+    names: List[str]
+    colors: Optional[List[str]] = None
+    line_style: Optional[List[str]] = None
+    line_width: Optional[float] = None
+    title: Optional[str] = None
+    xlabel: Optional[str] = None
+    ylabel: Optional[str] = None
+    yrange: Optional[Tuple[float, float]] = None
+    xrange: Optional[int] = None
+    height: Optional[float] = None
+
+    def to_dict(self):
+        return _drop_none({
+            "names": list(self.names),
+            "colors": list(self.colors) if self.colors is not None else None,
+            "line_style": list(self.line_style) if self.line_style is not None else None,
+            "line_width": self.line_width,
+            "title": self.title,
+            "xlabel": self.xlabel,
+            "ylabel": self.ylabel,
+            "yrange": _range_to_list(self.yrange),
+            "xrange": self.xrange,
+            "height": self.height,
+        })
+
+
+@dataclass
+class Button:
+    id: str
+    label: str
+    color: Optional[str] = None
+    height: Optional[float] = None
+
+    def to_dict(self):
+        return _drop_none({
+            "type": "button", "id": self.id, "label": self.label,
+            "color": self.color, "height": self.height,
+        })
+
+
+@dataclass
+class Slider:
+    id: str
+    label: str
+    min: float
+    max: float
+    value: float = 0.0
+    step: Optional[float] = None
+    format: Optional[str] = None
+    color: Optional[str] = None
+    height: Optional[float] = None
+
+    def to_dict(self):
+        return _drop_none({
+            "type": "slider", "id": self.id, "label": self.label,
+            "min": self.min, "max": self.max, "value": self.value,
+            "step": self.step, "format": self.format,
+            "color": self.color, "height": self.height,
+        })
+
+
+@dataclass
+class Dial:
+    id: str
+    label: str
+    min: float
+    max: float
+    value: float = 0.0
+    step: Optional[float] = None
+    sensitivity: Optional[float] = None
+    format: Optional[str] = None
+    color: Optional[str] = None
+    height: Optional[float] = None
+
+    def to_dict(self):
+        return _drop_none({
+            "type": "dial", "id": self.id, "label": self.label,
+            "min": self.min, "max": self.max, "value": self.value,
+            "step": self.step, "sensitivity": self.sensitivity,
+            "format": self.format, "color": self.color,
+            "height": self.height,
+        })
+
+
+@dataclass
+class Display:
+    id: str
+    label: str
+    format: Optional[str] = None
+    height: Optional[float] = None
+
+    def to_dict(self):
+        return _drop_none({
+            "type": "display", "id": self.id, "label": self.label,
+            "format": self.format, "height": self.height,
+        })
+
+
+@dataclass
+class Text:
+    id: str
+    label: str
+    value: str = ""
+    height: Optional[float] = None
+
+    def to_dict(self):
+        return _drop_none({
+            "type": "text", "id": self.id, "label": self.label,
+            "value": self.value, "height": self.height,
+        })
+
+
+@dataclass
+class ControlsRow:
+    """A row of control widgets, rendered in place of a plot."""
+    controls: List[Union[Button, Slider, Dial, Display, Text, dict]] = field(default_factory=list)
+
+    def to_dict(self):
+        return {"controls": [
+            c.to_dict() if hasattr(c, "to_dict") else c
+            for c in self.controls
+        ]}
+
+
 def local_plot():
     """Send data to a plot in the same computer"""
 
     local_address = "tcp://127.0.0.1:5555"
     configure_ip(ip = local_address)
 
-def plot_to_neurobionics_tv():
-    """Send data to a plot in the same computer"""
-
-    tv_computer_address = "tcp://141.212.77.23:5555"
-    configure_ip(ip = tv_computer_address)
-    
-
 def configure_port(new_port:int):
     """Rebind the local publisher on ``new_port`` (bind mode only).
 
@@ -277,6 +437,11 @@ def initialize_plots(plot_descriptions=1):
         plot_desc_dict = OrderedDict()
         plot_desc_dict["plot0"] = plot_descriptions
 
+    #Process typed inputs (Plot / ControlsRow) passed alone
+    elif hasattr(plot_descriptions, "to_dict"):
+        plot_desc_dict = OrderedDict()
+        plot_desc_dict["plot0"] = plot_descriptions.to_dict()
+
     #Process lists of things
     elif isinstance(plot_descriptions, list):
 
@@ -291,10 +456,14 @@ def initialize_plots(plot_descriptions=1):
             for i,plot_desc in enumerate(plot_descriptions):
                 plot_desc_dict["plot{}".format(i)] = {"names":plot_desc}
 
-        #Process list of dics
-        elif isinstance(plot_descriptions[0],dict):
+        #Process list of dicts or typed objects (Plot / ControlsRow),
+        # including mixed lists — anything exposing .to_dict() is normalized
+        # to the wire dict form.
+        elif isinstance(plot_descriptions[0],dict) or hasattr(plot_descriptions[0], "to_dict"):
             plot_desc_dict = OrderedDict()
             for i,plot_desc in enumerate(plot_descriptions):
+                if hasattr(plot_desc, "to_dict"):
+                    plot_desc = plot_desc.to_dict()
                 plot_desc_dict["plot{}".format(i)] = plot_desc
 
     #Throw error

{better_rtplot-0.3.0 → better_rtplot-0.4.1}/rtplot/server_browser.py

@@ -787,6 +787,8 @@ INDEX_HTML = """<!doctype html>
   .ctrl-item-tall > .ctrl-val { align-self: center; }
   .ctrl-btn:hover { background: #f0f0f0; }
   .ctrl-btn:active { background: #e2e2e2; }
+  .ctrl-btn-colored:hover { filter: brightness(0.93); }
+  .ctrl-btn-colored:active { filter: brightness(0.85); }
   .ctrl-slider .ctrl-rangeinput { flex: 1; min-width: 120px; }
   .ctrl-numinput { width: 72px; font-family: monospace; font-size: calc(13px * var(--ui-scale)); padding: 4px 6px; border: 1px solid #b8b8b8; border-radius: 3px; background: #fff; color: #222; text-align: right; -moz-appearance: textfield; }
   .ctrl-numinput::-webkit-outer-spin-button,
@@ -1093,6 +1095,7 @@ INDEX_HTML = """<!doctype html>
           min, max, step, initial: value,
           commit, applyLocal,
           sensitivity, hasMin, hasMax,
+          color: el.color,
         });
         if (widget && widget.node) item.appendChild(widget.node);
 
@@ -1127,7 +1130,7 @@ INDEX_HTML = """<!doctype html>
         return item;
       }
 
-      function buildSliderWidget({ min, max, step, initial, commit, applyLocal, hasMin, hasMax }) {
+      function buildSliderWidget({ min, max, step, initial, commit, applyLocal, hasMin, hasMax, color }) {
         // HTML range inputs can't represent unbounded values, so fall back
         // to sane defaults when the user omits min/max on a slider.
         const rangeMin = hasMin ? min : 0;
@@ -1137,6 +1140,7 @@ INDEX_HTML = """<!doctype html>
         range.className = 'ctrl-rangeinput';
         range.min = rangeMin;
         range.max = rangeMax;
+        if (color != null) range.style.accentColor = resolveColor(color);
         range.step = step;
         range.value = initial;
         // Live preview: update the number box (and any other mirrors) on every
@@ -1149,7 +1153,7 @@ INDEX_HTML = """<!doctype html>
         };
       }
 
-      function buildDialWidget({ min, max, initial, commit, applyLocal, sensitivity, hasMin, hasMax }) {
+      function buildDialWidget({ min, max, initial, commit, applyLocal, sensitivity, hasMin, hasMax, color }) {
         const svgNS = 'http://www.w3.org/2000/svg';
         const size = 100;
         const svg = document.createElementNS(svgNS, 'svg');
@@ -1185,6 +1189,7 @@ INDEX_HTML = """<!doctype html>
 
         const indicator = document.createElementNS(svgNS, 'line');
         indicator.classList.add('dial-indicator');
+        if (color != null) indicator.style.stroke = resolveColor(color);
         svg.appendChild(indicator);
 
         // Unified rotation math: the indicator advances by 2π radians for
@@ -1270,6 +1275,12 @@ INDEX_HTML = """<!doctype html>
           const b = document.createElement('button');
           b.className = 'ctrl-btn';
           b.textContent = el.label || el.id;
+          if (el.color != null) {
+            const c = resolveColor(el.color);
+            b.style.backgroundColor = c;
+            b.style.borderColor = c;
+            b.classList.add('ctrl-btn-colored');
+          }
           b.addEventListener('click', () => sendCtrl({ type: 'control_button', id: el.id }));
           item.appendChild(b);
         } else if (el.type === 'slider') {