kaxe 1.8.1.dev0__tar.gz → 1.8.1.dev4__tar.gz

{kaxe-1.8.1.dev0/src/kaxe.egg-info → kaxe-1.8.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaxe
-Version: 1.8.1.dev0
+Version: 1.8.1.dev4
 Summary: A small graphing tool for functions, points, equations and more
 Author-email: Valter Yde Daugberg <valteryde@hotmail.com>
 Project-URL: Homepage, https://github.com/valteryde/kaxe
@@ -27,6 +27,8 @@ Requires-Dist: psutil; extra == "3d"
 Provides-Extra: pdf
 Requires-Dist: reportlab>=4.0; extra == "pdf"
 Requires-Dist: fonttools>=4.0; extra == "pdf"
+Provides-Extra: viewer
+Requires-Dist: pyglet>=2.0; extra == "viewer"
 Dynamic: license-file
 
 
@@ -42,9 +44,9 @@ Documentation: [kaxe.readthedocs.io](https://kaxe.readthedocs.io/en/latest/)
 
 ```bash
 pip install kaxe          # 2D plotting (default)
-pip install kaxe[3d]        # add 3D plotting (OpenGL)
-pip install kaxe[pdf]       # add PDF export
-pip install kaxe[3d,pdf]    # 3D + PDF
+pip install kaxe[viewer]  # add interactive desktop viewer (pyglet)
+pip install kaxe[3d]      # add 3D plotting (OpenGL)
+pip install kaxe[pdf]     # add PDF export
 ```
 
 ## Quick example
@@ -57,10 +59,45 @@ plt.add(kaxe.Function2D(lambda x: x**2 - 4))
 plt.add(kaxe.Points2D([1, 2, 3], [1, 4, 9]))
 plt.theme(kaxe.Themes.A4Medium)
 plt.title("$x^2 - 4$")
+plt.show()                # streams to viewer if open, or opens system viewer
 plt.save("figure.png")
 plt.save("figure.svg")
 ```
 
+## Interactive Plot Viewer (Infinite Canvas)
+
+Kaxe includes a dedicated, lightweight OpenGL workspace powered by [pyglet](https://pyglet.org) so you can arrange, inspect, and compare multiple plots on an infinite canvas without cluttering your desktop with preview windows.
+
+1. **Start the viewer** in a terminal:
+   ```bash
+   kaxe viewer
+   ```
+2. **Tag and show your plots**:
+   ```python
+   # Tag plots with an ID to manage them on the board:
+   plt1 = kaxe.Plot().id("loss").title("Training Loss")
+   plt1.show()
+
+   plt2 = kaxe.Plot().id("accuracy").title("Validation Accuracy")
+   plt2.show()
+   ```
+
+When the viewer is open, `.show()` instantly streams plots to cards on your canvas. If you re-run code with the same ID, the card updates in-place and preserves previous runs as versions (`v1`, `v2`, etc.). If the viewer is closed, `.show()` automatically falls back to your operating system's default viewer.
+
+**Canvas & Card Controls:**
+* **Click & Drag on a Card**: Move that card freely across the canvas
+* **Click & Drag on Empty Space**: Pan the camera across the workspace
+* **Mouse Scroll**: Smooth zoom anchored to cursor
+* **`[A]`**: Auto-arrange all cards in a neat row
+* **`[Space]` or `[R]`**: Fit all cards on the canvas into view
+* **`[1]`**: View canvas at 100% native pixel scale
+* **`[←]` / `[→]`**: Cycle through versions (`v1`, `v2`, ...) of the selected card
+* **`[Backspace]` / `[Delete]`**: Remove the selected card from the board
+* **`[C]`** *(or Cmd/Ctrl+C)*: Copy selected plot to system clipboard
+* **`[S]`** *(or Cmd/Ctrl+S)*: Save selected plot to timestamped PNG
+* **`[H]`**: Toggle status & shortcuts HUD
+
+
 See the [getting started guide](https://kaxe.readthedocs.io/en/latest/pages/start.html), [recipes](https://kaxe.readthedocs.io/en/latest/pages/recipes.html), [styling guide](https://kaxe.readthedocs.io/en/latest/pages/styling.html), and [export guide](https://kaxe.readthedocs.io/en/latest/pages/export.html) for the full API.
 
 ## Goals

kaxe-1.8.1.dev4/README.md

@@ -0,0 +1,88 @@
+
+# Kaxe
+
+![BoxPlot](logo.png)
+
+Kaxe is a lightweight, pure-Python plotting library for publication-quality figures in LaTeX documents. Create plots and charts with a simple object-oriented API, style them for A4 pages, and export to PNG or SVG.
+
+Documentation: [kaxe.readthedocs.io](https://kaxe.readthedocs.io/en/latest/)
+
+## Installation
+
+```bash
+pip install kaxe          # 2D plotting (default)
+pip install kaxe[viewer]  # add interactive desktop viewer (pyglet)
+pip install kaxe[3d]      # add 3D plotting (OpenGL)
+pip install kaxe[pdf]     # add PDF export
+```
+
+## Quick example
+
+```python
+import kaxe
+
+plt = kaxe.Plot([-5, 5, -5, 5])
+plt.add(kaxe.Function2D(lambda x: x**2 - 4))
+plt.add(kaxe.Points2D([1, 2, 3], [1, 4, 9]))
+plt.theme(kaxe.Themes.A4Medium)
+plt.title("$x^2 - 4$")
+plt.show()                # streams to viewer if open, or opens system viewer
+plt.save("figure.png")
+plt.save("figure.svg")
+```
+
+## Interactive Plot Viewer (Infinite Canvas)
+
+Kaxe includes a dedicated, lightweight OpenGL workspace powered by [pyglet](https://pyglet.org) so you can arrange, inspect, and compare multiple plots on an infinite canvas without cluttering your desktop with preview windows.
+
+1. **Start the viewer** in a terminal:
+   ```bash
+   kaxe viewer
+   ```
+2. **Tag and show your plots**:
+   ```python
+   # Tag plots with an ID to manage them on the board:
+   plt1 = kaxe.Plot().id("loss").title("Training Loss")
+   plt1.show()
+
+   plt2 = kaxe.Plot().id("accuracy").title("Validation Accuracy")
+   plt2.show()
+   ```
+
+When the viewer is open, `.show()` instantly streams plots to cards on your canvas. If you re-run code with the same ID, the card updates in-place and preserves previous runs as versions (`v1`, `v2`, etc.). If the viewer is closed, `.show()` automatically falls back to your operating system's default viewer.
+
+**Canvas & Card Controls:**
+* **Click & Drag on a Card**: Move that card freely across the canvas
+* **Click & Drag on Empty Space**: Pan the camera across the workspace
+* **Mouse Scroll**: Smooth zoom anchored to cursor
+* **`[A]`**: Auto-arrange all cards in a neat row
+* **`[Space]` or `[R]`**: Fit all cards on the canvas into view
+* **`[1]`**: View canvas at 100% native pixel scale
+* **`[←]` / `[→]`**: Cycle through versions (`v1`, `v2`, ...) of the selected card
+* **`[Backspace]` / `[Delete]`**: Remove the selected card from the board
+* **`[C]`** *(or Cmd/Ctrl+C)*: Copy selected plot to system clipboard
+* **`[S]`** *(or Cmd/Ctrl+S)*: Save selected plot to timestamped PNG
+* **`[H]`**: Toggle status & shortcuts HUD
+
+
+See the [getting started guide](https://kaxe.readthedocs.io/en/latest/pages/start.html), [recipes](https://kaxe.readthedocs.io/en/latest/pages/recipes.html), [styling guide](https://kaxe.readthedocs.io/en/latest/pages/styling.html), and [export guide](https://kaxe.readthedocs.io/en/latest/pages/export.html) for the full API.
+
+## Goals
+
+Kaxe was made to create simple, aesthetic graphs for articles, reports, and other academic work in LaTeX:
+
+* Plots that fit the look of LaTeX documents (Computer Modern math via [fondi](https://github.com/valteryde/fondi))
+* A straightforward object-oriented interface: create a window, add objects, style, save
+
+## Examples of plots
+
+![BoxPlot](tests/images/boxed.png)
+![Polar plot](tests/images/polar.png)
+![PrettyPlot3D2](tests/images/3d-function-pretty-2.png)
+![Contour grid](tests/images/contourgrid.png)
+![Contour same](tests/images/contour3d.png)
+![AllLegends](tests/images/vectorimagearrow3d.png)
+![Functions](tests/images/function.png)
+![Points](tests/images/labels.png)
+![Equations](tests/images/equation.png)
+![Globallight](tests/images/lightfunction3d.png)

{kaxe-1.8.1.dev0 → kaxe-1.8.1.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kaxe"
-version = "1.8.1.dev0"
+version = "1.8.1.dev4"
 authors = [
   { name="Valter Yde Daugberg", email="valteryde@hotmail.com" },
 ]
@@ -31,6 +31,10 @@ core = []
   "psutil",
 ]
 pdf = ["reportlab>=4.0", "fonttools>=4.0"]
+viewer = ["pyglet>=2.0"]
+
+[project.scripts]
+kaxe = "kaxe.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/valteryde/kaxe"

kaxe-1.8.1.dev4/src/kaxe/__main__.py

@@ -0,0 +1,6 @@
+"""Support running `python -m kaxe viewer`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

kaxe-1.8.1.dev4/src/kaxe/_require_viewer.py

@@ -0,0 +1,8 @@
+_MSG = "Viewer features require optional dependencies. Install with: pip install kaxe[viewer]"
+
+
+def require_viewer():
+    try:
+        import pyglet  # noqa: F401
+    except ImportError as exc:
+        raise ImportError(_MSG) from exc

kaxe-1.8.1.dev4/src/kaxe/cli.py

@@ -0,0 +1,8 @@
+"""Top-level CLI module for Kaxe."""
+
+from .viewer.cli import main
+
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    main()

{kaxe-1.8.1.dev0 → kaxe-1.8.1.dev4}/src/kaxe/core/window.py

@@ -11,6 +11,7 @@ from .svg import SvgDocument, infer_format, is_file_path
 from .progress import make_progress_bar
 from .ipython_display import display_png_bytes, is_notebook, to_png_bytes
 from .styles import assign_series_color, _palette_color_at
+from ..viewer.client import try_show_in_viewer
 from PIL import Image
 
 
@@ -646,23 +647,54 @@ class Window(AttrObject):
             logging.info('Total time to save {}s'.format(str(round(time.time() - totStartTime, 4))))
     
     
-    def show(self):
+    def id(self, plot_id: str):
+        """Assign a persistent identifier to this plot for the Kaxe Viewer."""
+        self.plot_id = str(plot_id)
+        return self
+
+    def show(self, id: Optional[str] = None):
         """
-        Show the current image using `Pillow.Image.Show`
+        Show the current image using `Pillow.Image.Show` or the Kaxe Viewer.
         
         If a cached image is available, it will be used to save the file.
         Otherwise, the image will be generated and then saved.
 
+        Parameters
+        ----------
+        id : str, optional
+            Identifier for this plot when sent to the Kaxe Viewer canvas.
+
         Examples
         --------
-        >>> plt.show( )
+        >>> plt.show()
+        >>> plt.show(id="my_graph_1")
         """
+        if id is not None:
+            self.plot_id = str(id)
+
         data = to_png_bytes(self)
         if is_notebook():
             display_png_bytes(data)
+        elif try_show_in_viewer(
+            data,
+            title=getattr(self, "titleText", ""),
+            plot_id=getattr(self, "plot_id", None),
+        ):
+            return
         else:
             Image.open(BytesIO(data)).show()
 
+    def open(self, id: Optional[str] = None):
+        """
+        Show the current image or stream to viewer (alias for show()).
+
+        Examples
+        --------
+        >>> plt.open()
+        >>> plt.open(id="my_graph_1")
+        """
+        return self.show(id=id)
+
     def _repr_png_(self):
         if not is_notebook():
             return None

{kaxe-1.8.1.dev0 → kaxe-1.8.1.dev4}/src/kaxe/plot/d3/plot3d.py

@@ -547,6 +547,10 @@ class Plot3D(Plot3DAxesMixin, Window):
         else:
             self.save(None).show()
 
+    def open(self, gui=True):
+        """Show the current plot (alias for show())."""
+        return self.show(gui=gui)
+
     def title(self, firstAxis=None, secondAxis=None, thirdAxis=None):
         """
         Adds title to the plot.

{kaxe-1.8.1.dev0 → kaxe-1.8.1.dev4}/src/kaxe/plot/grid.py

@@ -4,6 +4,7 @@ from typing import Optional, Union
 from ..core.styles import AttrObject, AttrMap
 from ..core.window import *
 from ..core.ipython_display import display_png_bytes, is_notebook, to_png_bytes
+from ..viewer.client import try_show_in_viewer
 from ..core.legend import LegendBox
 from ..core.svg import (
     SvgDocument,
@@ -489,23 +490,54 @@ class Grid(AttrObject):
             img.save(fname, format="png")
 
 
-    def show(self):
+    def id(self, plot_id: str):
+        """Assign a persistent identifier to this grid for the Kaxe Viewer."""
+        self.plot_id = str(plot_id)
+        return self
+
+    def show(self, id: Optional[str] = None):
         """
-        Show the current image using `Pillow.Image.Show`
+        Show the current image using `Pillow.Image.Show` or the Kaxe Viewer.
         
         If a cached image is available, it will be used to save the file.
         Otherwise, the image will be generated and then saved.
 
+        Parameters
+        ----------
+        id : str, optional
+            Identifier for this grid when sent to the Kaxe Viewer canvas.
+
         Examples
         --------
-        >>> plt.show( )
+        >>> grid.show()
+        >>> grid.show(id="my_grid_1")
         """
+        if id is not None:
+            self.plot_id = str(id)
+
         data = to_png_bytes(self)
         if is_notebook():
             display_png_bytes(data)
+        elif try_show_in_viewer(
+            data,
+            title="Grid",
+            plot_id=getattr(self, "plot_id", None),
+        ):
+            return
         else:
             Image.open(BytesIO(data)).show()
 
+    def open(self, id: Optional[str] = None):
+        """
+        Show the current grid or stream to viewer (alias for show()).
+
+        Examples
+        --------
+        >>> grid.open()
+        >>> grid.open(id="my_grid_1")
+        """
+        return self.show(id=id)
+
     def _repr_png_(self):
         if not is_notebook():
             return None

kaxe-1.8.1.dev4/src/kaxe/viewer/__init__.py

@@ -0,0 +1,11 @@
+"""Kaxe Viewer package."""
+
+from .client import DEFAULT_PORT, get_viewer_port, is_viewer_active, send_to_viewer, try_show_in_viewer
+
+__all__ = [
+    "DEFAULT_PORT",
+    "get_viewer_port",
+    "is_viewer_active",
+    "send_to_viewer",
+    "try_show_in_viewer",
+]

kaxe-1.8.1.dev4/src/kaxe/viewer/cli.py

@@ -0,0 +1,89 @@
+"""Command line interface for launching Kaxe Viewer."""
+
+import argparse
+import queue
+import sys
+
+from .client import get_viewer_port, is_viewer_active
+from .server import start_server_thread
+
+
+def run_viewer(port: int = 41783):
+    """Launch the Kaxe Viewer Pyglet window and HTTP server."""
+    # Ensure optional dependency is installed
+    from .._require_viewer import require_viewer
+
+    try:
+        require_viewer()
+    except ImportError as e:
+        print(f"\n[Kaxe] {e}\n", file=sys.stderr)
+        sys.exit(1)
+
+    import pyglet
+    from .window import KaxeViewerWindow
+
+    # Check if a viewer is already running on this port
+    if is_viewer_active(port):
+        print(f"\n[Kaxe Viewer] Port {port} is already in use.", file=sys.stderr)
+        print("A Kaxe Viewer instance is likely already open.\n", file=sys.stderr)
+        sys.exit(1)
+
+    plot_queue = queue.Queue()
+
+    # Start HTTP server on background thread
+    server, thread = start_server_thread(port, plot_queue)
+
+    print("=" * 64)
+    print(f"  Kaxe Viewer running on http://127.0.0.1:{port}")
+    print("  Keep this terminal open while working.")
+    print("  In another terminal, run your scripts calling .show()!")
+    print()
+    print("  Controls:")
+    print("    • Mouse Wheel     : Zoom (centered at cursor)")
+    print("    • Left Click Drag : Pan image")
+    print("    • [R] or [Space]  : Fit plot to window")
+    print("    • [1]             : 100% native resolution")
+    print("    • [←] / [→]       : Cycle through previous plots")
+    print("    • [C]             : Copy image to clipboard")
+    print("    • [S]             : Save image to file")
+    print("    • [H]             : Toggle HUD overlay")
+    print("=" * 64)
+
+    # Create Pyglet window and run Cocoa / OpenGL event loop on main thread
+    window = KaxeViewerWindow(plot_queue)
+    pyglet.app.run()
+
+
+def main(argv=None):
+    """Entrypoint for the `kaxe` CLI command."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="kaxe",
+        description="Kaxe graphing & plotting toolkit CLI",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands")
+
+    # `kaxe viewer` command
+    viewer_parser = subparsers.add_parser(
+        "viewer",
+        help="Start the standalone Kaxe interactive plot viewer",
+    )
+    viewer_parser.add_argument(
+        "--port",
+        type=int,
+        default=get_viewer_port(),
+        help=f"Port to listen on (default: {get_viewer_port()})",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.subcommand == "viewer":
+        run_viewer(port=args.port)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

kaxe-1.8.1.dev4/src/kaxe/viewer/client.py

@@ -0,0 +1,91 @@
+"""Client-side probe and transmitter for Kaxe Viewer.
+
+This module intentionally uses ONLY Python standard library modules
+(socket, urllib, os) so that calling `plt.show()` never requires
+pyglet or any other viewer dependency.
+"""
+
+import os
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Optional
+
+DEFAULT_PORT = 41783
+
+
+def get_viewer_port() -> int:
+    """Return the configured viewer port from environment or the default."""
+    env_port = os.getenv("KAXE_VIEWER_PORT")
+    if env_port:
+        try:
+            return int(env_port)
+        except ValueError:
+            pass
+    return DEFAULT_PORT
+
+
+def is_viewer_active(port: Optional[int] = None, timeout: float = 0.03) -> bool:
+    """Check if the Kaxe Viewer is currently listening on localhost.
+
+    Uses a fast socket connection test with a short timeout (~30ms).
+    When no viewer is running, the OS kernel rejects the connection
+    virtually instantaneously (<1ms).
+    """
+    if port is None:
+        port = get_viewer_port()
+
+    try:
+        with socket.create_connection(("127.0.0.1", port), timeout=timeout):
+            return True
+    except (OSError, ConnectionRefusedError):
+        return False
+
+
+def send_to_viewer(
+    data: bytes,
+    title: str = "",
+    plot_id: Optional[str] = None,
+    port: Optional[int] = None,
+    timeout: float = 2.0,
+) -> bool:
+    """Send image PNG bytes to the active Kaxe Viewer over HTTP POST.
+
+    Returns True if successfully received, False otherwise.
+    """
+    if port is None:
+        port = get_viewer_port()
+
+    url = f"http://127.0.0.1:{port}/show"
+    safe_title = urllib.parse.quote(title or "")
+    safe_id = urllib.parse.quote(plot_id or "")
+    headers = {
+        "Content-Type": "image/png",
+        "X-Kaxe-Title": safe_title,
+        "X-Kaxe-Id": safe_id,
+    }
+
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            return response.status == 200
+    except (urllib.error.URLError, OSError):
+        return False
+
+
+def try_show_in_viewer(
+    data: bytes,
+    title: str = "",
+    plot_id: Optional[str] = None,
+) -> bool:
+    """Convenience helper: probe port and send image if viewer is alive.
+
+    Returns True if sent to viewer, False if fallback is needed.
+    """
+    port = get_viewer_port()
+    if is_viewer_active(port):
+        if send_to_viewer(data, title=title, plot_id=plot_id, port=port):
+            print("[Kaxe] Plot streamed to viewer", flush=True)
+            return True
+    return False

kaxe-1.8.1.dev4/src/kaxe/viewer/server.py

@@ -0,0 +1,79 @@
+"""Lightweight HTTP server embedded inside Kaxe Viewer.
+
+Uses Python standard library `http.server.ThreadingHTTPServer` to receive
+plot images and metadata from client scripts without external web frameworks.
+"""
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import queue
+import threading
+import urllib.parse
+from typing import Any, Dict
+
+
+class PlotRequestHandler(BaseHTTPRequestHandler):
+    """Handles incoming /show POST requests and /ping health checks."""
+
+    # Reference to the shared Queue injected by start_server
+    plot_queue: queue.Queue = queue.Queue()
+
+    def do_GET(self):
+        if self.path in ("/ping", "/health"):
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain")
+            self.end_headers()
+            self.wfile.write(b"OK")
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def do_POST(self):
+        if self.path == "/show":
+            content_length = int(self.headers.get("Content-Length", 0))
+            if content_length <= 0:
+                self.send_response(400)
+                self.end_headers()
+                self.wfile.write(b"Empty body")
+                return
+
+            img_bytes = self.rfile.read(content_length)
+            raw_title = self.headers.get("X-Kaxe-Title", "")
+            title = urllib.parse.unquote(raw_title) if raw_title else ""
+
+            raw_id = self.headers.get("X-Kaxe-Id", "")
+            plot_id = urllib.parse.unquote(raw_id) if raw_id else ""
+
+            item: Dict[str, Any] = {
+                "data": img_bytes,
+                "title": title,
+                "plot_id": plot_id,
+            }
+            self.plot_queue.put(item)
+
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain")
+            self.end_headers()
+            self.wfile.write(b"OK")
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def log_message(self, format: str, *args):
+        # Format messages cleanly in terminal
+        first_arg = args[0] if args else ""
+        if "POST /show" in str(first_arg):
+            print(f"[Kaxe Viewer] New plot received ({format % args})")
+        # Suppress noisy health checks in console
+
+
+def start_server_thread(
+    port: int,
+    plot_queue: queue.Queue,
+    host: str = "127.0.0.1",
+) -> tuple[ThreadingHTTPServer, threading.Thread]:
+    """Start the HTTP server on a daemon background thread."""
+    PlotRequestHandler.plot_queue = plot_queue
+    server = ThreadingHTTPServer((host, port), PlotRequestHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    return server, thread