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

better_rtplot-0.4.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.1
+Name: better-rtplot
+Version: 0.4.0
+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.0/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.0}/pyproject.toml

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

{better_rtplot-0.3.0 → better_rtplot-0.4.0}/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,172 @@ 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
+    height: Optional[float] = None
+
+    def to_dict(self):
+        return _drop_none({
+            "type": "button", "id": self.id, "label": self.label,
+            "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
+    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, "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
+    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, "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 +432,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 +451,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