spectra-plot 0.2.6__tar.gz → 0.3.0__tar.gz

{spectra_plot-0.2.6/spectra_plot.egg-info → spectra_plot-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectra-plot
-Version: 0.2.6
+Version: 0.3.0
 Summary: GPU-accelerated scientific plotting via IPC
 License: MIT
 Classifier: Development Status :: 3 - Alpha
@@ -15,8 +15,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+Requires-Dist: flatbuffers>=2.0
 Provides-Extra: numpy
 Requires-Dist: numpy>=1.20; extra == "numpy"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: numpy>=1.20; extra == "dev"
+Requires-Dist: flatbuffers>=2.0; extra == "dev"

spectra_plot-0.3.0/VERSION

@@ -0,0 +1 @@
+0.3.0

{spectra_plot-0.2.6 → spectra_plot-0.3.0}/pyproject.toml

@@ -9,6 +9,9 @@ description = "GPU-accelerated scientific plotting via IPC"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.9"
+dependencies = [
+    "flatbuffers>=2.0",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
@@ -24,7 +27,7 @@ classifiers = [
 
 [project.optional-dependencies]
 numpy = ["numpy>=1.20"]
-dev = ["pytest>=7.0", "numpy>=1.20"]
+dev = ["pytest>=7.0", "numpy>=1.20", "flatbuffers>=2.0"]
 
 [project.scripts]
 spectra-backend = "spectra._cli:backend_main"

{spectra_plot-0.2.6 → spectra_plot-0.3.0}/spectra/__init__.py

@@ -8,6 +8,8 @@ Usage::
 
     sp.plot([1, 4, 9, 16])                    # that's it. window opens.
     sp.plot(x, y, color="red", label="data")   # with style
+    sp.hline(0)                                # horizontal reference line
+    sp.fplot(lambda x: x**2, -2, 2)            # plot a function
     sp.scatter(x, y)                           # scatter plot
     sp.hist(data, bins=50)                     # histogram
     sp.plot3(x, y, z)                          # 3D line
@@ -52,6 +54,10 @@ from ._easy import (
     violin_plot,
     hline,
     vline,
+    fplot,
+    ihline,
+    ivline,
+    ifplot,
     plot3,
     scatter3,
     surf,
@@ -105,6 +111,10 @@ __all__ = [
     "violin_plot",
     "hline",
     "vline",
+    "fplot",
+    "ihline",
+    "ivline",
+    "ifplot",
     "plot3",
     "scatter3",
     "surf",

{spectra_plot-0.2.6 → spectra_plot-0.3.0}/spectra/_codec.py

@@ -1,10 +1,8 @@
-"""TLV (Tag-Length-Value) codec mirroring src/ipc/codec.hpp.
+"""IPC payload codec mirroring src/ipc/codec.hpp.
 
-Wire format per field: [tag: u8] [len: u32 LE] [data: len bytes]
-
-FlatBuffers payloads are prefixed with 0x01; legacy TLV payloads start with
-a raw tag byte (never 0x00 or 0x01 in practice, but 0x00 is reserved).
-Decode functions auto-detect the format and delegate to _codec_fb when needed.
+All encode_* functions emit FlatBuffers (0x01 prefix) via _codec_fb.
+PayloadEncoder remains for a few legacy write paths (chunked set-data, anim).
+Decode functions auto-detect FlatBuffers vs legacy TLV and delegate to _codec_fb.
 """
 
 import struct
@@ -306,17 +304,25 @@ def encode_req_remove_series(figure_id: int, series_index: int) -> bytes:
 def encode_req_close_figure(figure_id: int) -> bytes:
     return fb_codec.encode_fb_req_close_figure(figure_id=figure_id)
 
+def decode_req_update_batch(data: bytes) -> list:
+    """Decode REQ_UPDATE_BATCH. Returns a list of update dicts."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_req_update_batch(data)
+    updates = []
+    dec = PayloadDecoder(data)
+    while dec.next():
+        if dec.tag == P.TAG_BATCH_ITEM:
+            updates.append(decode_req_update_property(dec.as_blob()))
+    return updates
+
+
 def encode_req_update_batch(updates: list) -> bytes:
     """Encode REQ_UPDATE_BATCH — multiple property updates in one message.
 
     Each item in `updates` is a dict with keys matching encode_req_update_property kwargs:
         figure_id, axes_index, series_index, prop, f1..f4, bool_val, str_val
     """
-    enc = PayloadEncoder()
-    for upd in updates:
-        item_bytes = encode_req_update_property(**upd)
-        enc.put_blob(P.TAG_BATCH_ITEM, item_bytes)
-    return enc.take()
+    return fb_codec.encode_fb_req_update_batch(updates)
 
 
 def encode_req_reconnect(session_id: int, session_token: str = "") -> bytes:

{spectra_plot-0.2.6 → spectra_plot-0.3.0}/spectra/_codec_fb.py

@@ -217,6 +217,38 @@ def encode_fb_req_update_property(
     return _finalize(builder)
 
 
+def encode_fb_req_update_batch(updates: List[dict]) -> bytes:
+    """Encode REQ_UPDATE_BATCH with nested property updates."""
+    builder = flatbuffers.Builder(1024)
+    offsets = []
+    for upd in updates:
+        prop_off = builder.CreateString(upd.get("prop", ""))
+        str_val = upd.get("str_val", "")
+        str_off = builder.CreateString(str_val) if str_val else None
+        FBReqUpdProp.Start(builder)
+        FBReqUpdProp.AddFigureId(builder, upd.get("figure_id", 0))
+        FBReqUpdProp.AddAxesIndex(builder, upd.get("axes_index", 0))
+        FBReqUpdProp.AddSeriesIndex(builder, upd.get("series_index", 0))
+        FBReqUpdProp.AddProperty(builder, prop_off)
+        FBReqUpdProp.AddF1(builder, upd.get("f1", 0.0))
+        FBReqUpdProp.AddF2(builder, upd.get("f2", 0.0))
+        FBReqUpdProp.AddF3(builder, upd.get("f3", 0.0))
+        FBReqUpdProp.AddF4(builder, upd.get("f4", 0.0))
+        FBReqUpdProp.AddBoolVal(builder, upd.get("bool_val", False))
+        if str_off is not None:
+            FBReqUpdProp.AddStrVal(builder, str_off)
+        offsets.append(FBReqUpdProp.End(builder))
+    FBReqUpdBatch.StartUpdatesVector(builder, len(offsets))
+    for off in reversed(offsets):
+        builder.PrependUOffsetTRelative(off)
+    upds_off = builder.EndVector()
+    FBReqUpdBatch.Start(builder)
+    FBReqUpdBatch.AddUpdates(builder, upds_off)
+    root = builder.EndObject()
+    builder.Finish(root)
+    return _finalize(builder)
+
+
 def encode_fb_req_show(figure_id: int, window_id: int = 0) -> bytes:
     builder = flatbuffers.Builder(64)
     FBReqShow.Start(builder)
@@ -330,6 +362,30 @@ def decode_fb_evt_window_closed(data: bytes) -> Tuple[int, int, str]:
     )
 
 
+def decode_fb_req_update_batch(data: bytes) -> List[dict]:
+    buf = _strip(data) if _is_fb(data) else data
+    fb = FBReqUpdBatch.ReqUpdateBatchPayload.GetRootAs(buf, 0)
+    updates = []
+    if fb.UpdatesLength():
+        for i in range(fb.UpdatesLength()):
+            upd = fb.Updates(i)
+            updates.append(
+                {
+                    "figure_id": upd.FigureId(),
+                    "axes_index": upd.AxesIndex(),
+                    "series_index": upd.SeriesIndex(),
+                    "prop": (upd.Property() or b"").decode("utf-8", errors="replace"),
+                    "f1": upd.F1(),
+                    "f2": upd.F2(),
+                    "f3": upd.F3(),
+                    "f4": upd.F4(),
+                    "bool_val": upd.BoolVal(),
+                    "str_val": (upd.StrVal() or b"").decode("utf-8", errors="replace"),
+                }
+            )
+    return updates
+
+
 def decode_fb_evt_figure_destroyed(data: bytes) -> Tuple[int, str]:
     buf = _strip(data) if _is_fb(data) else data
     fb = FBEvtFigDestroyed.EvtFigureDestroyedPayload.GetRootAs(buf, 0)
@@ -504,3 +560,21 @@ def decode_fb_req_update_property(data: bytes) -> dict:
         "str_val": str_val_raw.decode("utf-8") if str_val_raw else "",
     }
 
+
+def decode_fb_snapshot_knobs(data: bytes) -> dict:
+    """Extract knob name → value from a STATE_SNAPSHOT / RESP_SNAPSHOT payload."""
+    from ._fb_generated.spectra.ipc.fb.StateSnapshotPayload import StateSnapshotPayload
+
+    raw = _strip(data)
+    snap = StateSnapshotPayload.GetRootAs(bytearray(raw), 0)
+    out: dict = {}
+    n = snap.KnobsLength()
+    for i in range(n):
+        k = snap.Knobs(i)
+        if k is None:
+            continue
+        name = k.Name()
+        if name:
+            out[name.decode("utf-8")] = float(k.Value())
+    return out
+

{spectra_plot-0.2.6 → spectra_plot-0.3.0}/spectra/_easy.py

@@ -137,6 +137,10 @@ class _EasyState:
         self._shutting_down = False
         self._axes_bounds: dict = {}  # id(axes) -> [xmin, xmax, ymin, ymax]
         self._subplot_cache: dict = {}  # (figure_id, rows, cols, index) -> Axes
+        self._pending_knobs: List[dict] = []
+        self._interactive_bindings: List = []
+        self._interactive_started = False
+        self._knob_values: dict = {}
 
     def _ensure_session(self):
         """Lazily create the backend session."""
@@ -160,8 +164,10 @@ class _EasyState:
         """Show the current figure if it hasn't been shown yet."""
         fig = self._current_fig
         if fig is not None and id(fig) in self._pending_show:
+            self._flush_pending_knobs()
             self._pending_show.discard(id(fig))
             fig.show()
+            _ensure_interactive_loop()
 
     def _ensure_axes(self):
         """Lazily create axes on the current figure."""
@@ -178,6 +184,32 @@ class _EasyState:
             self._current_axes3d = fig.subplot3d(1, 1, 1)
         return self._current_axes3d
 
+    def _flush_pending_knobs(self) -> None:
+        """Push queued knob definitions to the backend before the window opens."""
+        if not self._pending_knobs:
+            return
+        from . import _protocol as P
+        from . import _codec as codec
+
+        session = self._ensure_session()
+        for spec in self._pending_knobs:
+            payload = codec.encode_req_update_property(
+                figure_id=spec["figure_id"],
+                axes_index=0,
+                series_index=0,
+                prop="add_knob",
+                f1=spec["value"],
+                f2=spec["min"],
+                f3=spec["max"],
+                str_val=spec["name"],
+            )
+            try:
+                session._request(P.REQ_UPDATE_PROPERTY, payload)
+            except Exception:
+                pass
+            self._knob_values[spec["name"]] = spec["value"]
+        self._pending_knobs.clear()
+
     def shutdown(self):
         """Clean shutdown — stop live threads, close session."""
         self._shutting_down = True
@@ -187,6 +219,10 @@ class _EasyState:
             t.join(timeout=2.0)
         self._live_threads.clear()
         self._live_stop_events.clear()
+        self._pending_knobs.clear()
+        self._interactive_bindings.clear()
+        self._interactive_started = False
+        self._knob_values.clear()
         if self._session is not None:
             try:
                 self._session.close()
@@ -686,8 +722,22 @@ def violin_plot(
     return series
 
 
-def hline(y: float, color: Union[str, Tuple, List, None] = "gray", label: str = ""):
-    """Draw a horizontal line across the plot."""
+def hline(
+    y: float,
+    color: Union[str, Tuple, List, None] = "gray",
+    label: str = "",
+    *,
+    interactive: bool = False,
+    ymin: float = -10.0,
+    ymax: float = 10.0,
+    knob_name: str = "Y line",
+):
+    """Draw a horizontal reference line at y (e.g. ``hline(0)`` for the x-axis).
+
+    Set ``interactive=True`` (or use ``ihline``) to drag a slider that moves the line.
+    """
+    if interactive:
+        return ihline(y, ymin, ymax, color=color, label=label, knob_name=knob_name)
     ax = _state._ensure_axes()
     series = ax.line([-1e12, 1e12], [y, y], label=label)
     c = _parse_color(color)
@@ -697,8 +747,22 @@ def hline(y: float, color: Union[str, Tuple, List, None] = "gray", label: str =
     return series
 
 
-def vline(x: float, color: Union[str, Tuple, List, None] = "gray", label: str = ""):
-    """Draw a vertical line across the plot."""
+def vline(
+    x: float,
+    color: Union[str, Tuple, List, None] = "gray",
+    label: str = "",
+    *,
+    interactive: bool = False,
+    xmin: float = -10.0,
+    xmax: float = 10.0,
+    knob_name: str = "X line",
+):
+    """Draw a vertical reference line at x (e.g. ``vline(0)`` for the y-axis).
+
+    Set ``interactive=True`` (or use ``ivline``) to drag a slider that moves the line.
+    """
+    if interactive:
+        return ivline(x, xmin, xmax, color=color, label=label, knob_name=knob_name)
     ax = _state._ensure_axes()
     series = ax.line([x, x], [-1e12, 1e12], label=label)
     c = _parse_color(color)
@@ -708,6 +772,283 @@ def vline(x: float, color: Union[str, Tuple, List, None] = "gray", label: str =
     return series
 
 
+def fplot(
+    func,
+    xmin: Optional[float] = None,
+    xmax: Optional[float] = None,
+    n: int = 200,
+    color: Union[str, Tuple, List, None] = None,
+    width: Optional[float] = None,
+    label: str = "",
+    *,
+    interactive: bool = False,
+    params: Optional[List[Tuple[str, float, float, float]]] = None,
+    **kwargs,
+):
+    """Plot y = func(x) over an x range.
+
+    Usage::
+
+        sp.fplot(lambda x: x ** 2, -2, 2)
+        sp.fplot(math.sin)                    # uses current axes x-range or [-1, 1]
+        sp.fplot(lambda x: x ** 2, color="red", label="parabola")
+        sp.ifplot(lambda x, a, b: a * x * x + b, -3, 3, params=[("a", 0.2, -1, 1)])
+
+  If *xmin* / *xmax* are omitted, uses accumulated axes bounds from prior plots
+  on the same axes, otherwise ``[-1, 1]``.
+
+  Set ``interactive=True`` with *params* ``[(name, value, min, max), ...]`` to
+  expose sliders for each coefficient (or use ``ifplot``).
+    """
+    if interactive:
+        return ifplot(func, xmin, xmax, n=n, color=color, width=width, label=label,
+                      params=params or [], **kwargs)
+
+    ax = _state._ensure_axes()
+
+    if xmin is None or xmax is None:
+        ax_key = (ax._figure_id, ax._index)
+        if ax_key in _state._axes_bounds:
+            bounds = _state._axes_bounds[ax_key]
+            if xmin is None:
+                xmin = bounds[0]
+            if xmax is None:
+                xmax = bounds[1]
+        else:
+            if xmin is None:
+                xmin = -1.0
+            if xmax is None:
+                xmax = 1.0
+
+    if xmin == xmax:
+        xmax = xmin + 1.0
+
+    n = max(int(n), 2)
+    step = (xmax - xmin) / (n - 1)
+    xs = [xmin + i * step for i in range(n)]
+    ys = [float(func(x)) for x in xs]
+
+    series = ax.line(xs, ys, label=label)
+    _apply_series_style(series, color=color, width=width, **kwargs)
+    _auto_fit_axes(ax, xs, ys)
+    _state._show_if_pending()
+    return series
+
+
+# ─── Interactive reference lines & function plots ─────────────────────────────
+
+_REF_SPAN = 1e12
+
+
+class _InteractiveHLine:
+    __slots__ = ("series", "knob_name")
+
+    def __init__(self, series, knob_name: str) -> None:
+        self.series = series
+        self.knob_name = knob_name
+
+    def apply(self, knobs: dict) -> None:
+        if self.knob_name not in knobs:
+            return
+        y = float(knobs[self.knob_name])
+        self.series.set_data([-_REF_SPAN, _REF_SPAN], [y, y])
+
+
+class _InteractiveVLine:
+    __slots__ = ("series", "knob_name")
+
+    def __init__(self, series, knob_name: str) -> None:
+        self.series = series
+        self.knob_name = knob_name
+
+    def apply(self, knobs: dict) -> None:
+        if self.knob_name not in knobs:
+            return
+        x = float(knobs[self.knob_name])
+        self.series.set_data([x, x], [-_REF_SPAN, _REF_SPAN])
+
+
+class _InteractiveFplot:
+    __slots__ = ("series", "func", "xs", "param_names")
+
+    def __init__(self, series, func, xs: List[float], param_names: List[str]) -> None:
+        self.series = series
+        self.func = func
+        self.xs = xs
+        self.param_names = param_names
+
+    def apply(self, knobs: dict) -> None:
+        pvals = [float(knobs.get(n, 0.0)) for n in self.param_names]
+        ys = [float(self.func(x, *pvals)) for x in self.xs]
+        self.series.set_data(self.xs, ys)
+
+
+def _queue_knob(ax, name: str, value: float, vmin: float, vmax: float) -> None:
+    spec = {
+        "figure_id": ax._figure_id,
+        "name": name,
+        "value": float(value),
+        "min": float(vmin),
+        "max": float(vmax),
+    }
+    _state._knob_values[name] = float(value)
+    fig = _state._current_fig
+    if fig is not None and id(fig) not in _state._pending_show:
+        from . import _protocol as P
+        from . import _codec as codec
+
+        session = _state._ensure_session()
+        payload = codec.encode_req_update_property(
+            figure_id=spec["figure_id"],
+            axes_index=0,
+            series_index=0,
+            prop="add_knob",
+            f1=spec["value"],
+            f2=spec["min"],
+            f3=spec["max"],
+            str_val=spec["name"],
+        )
+        try:
+            session._request(P.REQ_UPDATE_PROPERTY, payload)
+        except Exception:
+            _state._pending_knobs.append(spec)
+    else:
+        _state._pending_knobs.append(spec)
+
+
+def _poll_knob_values(session) -> dict:
+    from . import _protocol as P
+    from . import _codec as codec
+
+    try:
+        resp = session._request(P.REQ_GET_SNAPSHOT, b"")
+        payload = resp["payload"]
+        if payload and payload[0] == P.PAYLOAD_FORMAT_FLATBUFFERS:
+            from . import _codec_fb as fb_codec
+            return fb_codec.decode_fb_snapshot_knobs(payload)
+    except Exception:
+        pass
+    return dict(_state._knob_values)
+
+
+def _ensure_interactive_loop() -> None:
+    if _state._interactive_started or not _state._interactive_bindings:
+        return
+    _state._interactive_started = True
+    from ._animation import ipc_sleep
+    from ._log import log
+
+    stop_event = threading.Event()
+    _state._live_stop_events.append(stop_event)
+
+    def _loop() -> None:
+        session = _state._ensure_session()
+        session._live_thread_count += 1
+        try:
+            while not stop_event.is_set():
+                ipc_sleep(0.05, session)
+                knobs = _poll_knob_values(session)
+                _state._knob_values.update(knobs)
+                for binding in _state._interactive_bindings:
+                    try:
+                        binding.apply(knobs)
+                    except Exception as e:
+                        log.warning("interactive update error: %s", e)
+        finally:
+            session._live_thread_count -= 1
+
+    thread = threading.Thread(target=_loop, daemon=True, name="spectra-interactive")
+    thread.start()
+    _state._live_threads.append(thread)
+
+
+def ihline(
+    y: float,
+    ymin: float = -10.0,
+    ymax: float = 10.0,
+    color: Union[str, Tuple, List, None] = "gray",
+    label: str = "",
+    knob_name: str = "Y line",
+):
+    """Interactive horizontal line — drag the PARAMETERS slider to move y."""
+    series = hline(y, color=color, label=label)
+    ax = _state._ensure_axes()
+    _queue_knob(ax, knob_name, y, ymin, ymax)
+    _state._interactive_bindings.append(_InteractiveHLine(series, knob_name))
+    _state._show_if_pending()
+    return series
+
+
+def ivline(
+    x: float,
+    xmin: float = -10.0,
+    xmax: float = 10.0,
+    color: Union[str, Tuple, List, None] = "gray",
+    label: str = "",
+    knob_name: str = "X line",
+):
+    """Interactive vertical line — drag the PARAMETERS slider to move x."""
+    series = vline(x, color=color, label=label)
+    ax = _state._ensure_axes()
+    _queue_knob(ax, knob_name, x, xmin, xmax)
+    _state._interactive_bindings.append(_InteractiveVLine(series, knob_name))
+    _state._show_if_pending()
+    return series
+
+
+def ifplot(
+    func,
+    xmin: Optional[float] = None,
+    xmax: Optional[float] = None,
+    n: int = 200,
+    color: Union[str, Tuple, List, None] = None,
+    width: Optional[float] = None,
+    label: str = "",
+    params: Optional[List[Tuple[str, float, float, float]]] = None,
+    **kwargs,
+):
+    """Interactive function plot — sliders retune each entry in *params*.
+
+    *func* signature: ``func(x, *param_values)`` matching *params* order::
+
+        sp.ifplot(lambda x, a, b: a * x * x + b, -3, 3,
+                  params=[("a", 0.2, -1, 1), ("b", 0, -2, 2)])
+    """
+    param_specs = params or []
+    ax = _state._ensure_axes()
+
+    if xmin is None or xmax is None:
+        ax_key = (ax._figure_id, ax._index)
+        if ax_key in _state._axes_bounds:
+            bounds = _state._axes_bounds[ax_key]
+            xmin = xmin if xmin is not None else bounds[0]
+            xmax = xmax if xmax is not None else bounds[1]
+        else:
+            xmin = xmin if xmin is not None else -1.0
+            xmax = xmax if xmax is not None else 1.0
+    if xmin == xmax:
+        xmax = xmin + 1.0
+
+    n = max(int(n), 2)
+    step = (xmax - xmin) / (n - 1)
+    xs = [xmin + i * step for i in range(n)]
+    pvals = [p[1] for p in param_specs]
+    ys = [float(func(x, *pvals)) for x in xs]
+
+    series = ax.line(xs, ys, label=label)
+    _apply_series_style(series, color=color, width=width, **kwargs)
+    _auto_fit_axes(ax, xs, ys)
+
+    param_names: List[str] = []
+    for name, value, vmin, vmax in param_specs:
+        _queue_knob(ax, name, value, vmin, vmax)
+        param_names.append(name)
+
+    _state._interactive_bindings.append(_InteractiveFplot(series, func, xs, param_names))
+    _state._show_if_pending()
+    return series
+
+
 # ─── Auto-fit helper ─────────────────────────────────────────────────────────
 
 def _auto_fit_axes(ax, x: List[float], y: List[float]) -> None: