plotlive 0.1.0__py3-none-any.whl

plotlive/events.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+import time
+
+
+ZOOM_IN  = 0.85
+ZOOM_OUT = 1.0 / 0.85
+_DBL_CLICK = 0.35  # seconds
+
+_HELP_LINES = [
+    ('?  /  H',      'Show / hide this help panel'),
+    ('Space',        'Play / pause animation'),
+    ('-> Right arrow', 'Step forward one frame  (while paused)'),
+    ('<- Left arrow',  'Step back one frame     (while paused)'),
+    ('Scroll up',    'Zoom in  (centered on cursor)'),
+    ('Scroll down',  'Zoom out (centered on cursor)'),
+    ('Drag',         'Pan the view'),
+    ('Double-click', 'Focus subplot  (multi-plot)  /  Reset zoom (single plot)'),
+    ('Esc',          'Exit focus mode'),
+    ('R',            'Reset zoom / pan  +  restart animation'),
+    ('S',            'Save current frame as frame_NNNN.png'),
+    ('?  /  H  /  Esc', 'Close this panel'),
+]
+
+
+class InteractionState:
+    """Tracks interactive input. Mutates Axes.transform on pan/zoom events."""
+
+    def __init__(self, figure):
+        self.figure = figure
+        self._pan_active: bool = False
+        self._pan_last_pos: tuple[int, int] | None = None
+        self._active_ax = None
+        self._hover_pos: tuple[int, int] | None = None
+        self._last_click_time: float = 0.0
+        self.show_help: bool = False
+
+    def _find_ax_at(self, sx: int, sy: int):
+        # In focus mode all interaction targets the focused subplot
+        if self.figure._focused_ax is not None:
+            return self.figure._focused_ax
+        for ax in self.figure.axes:
+            if ax.transform.contains_screen_point(sx, sy):
+                return ax
+        return None
+
+    def handle_event(self, event, screen=None) -> bool:
+        """
+        Process one pygame event. Returns True if a redraw is needed.
+        screen is the pygame display surface, used for saving frames.
+        """
+        import pygame
+        dirty = False
+        anim = self.figure._animation
+
+        # While help is open, only allow keys that close it
+        if self.show_help:
+            if event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_h,
+                                 pygame.K_SLASH, pygame.K_QUESTION):
+                    self.show_help = False
+                    dirty = True
+            return dirty
+
+        if event.type == pygame.MOUSEBUTTONDOWN and event.button == 1:
+            ax = self._find_ax_at(*event.pos)
+            if ax:
+                self._active_ax = ax
+                self._pan_active = True
+                self._pan_last_pos = event.pos
+                now = time.monotonic()
+                if now - self._last_click_time < _DBL_CLICK:
+                    if self.figure._focused_ax is not None:
+                        # Exit focus mode
+                        self.figure._focused_ax = None
+                        dirty = True
+                    elif len(self.figure.axes) > 1:
+                        # Enter focus mode on the clicked subplot
+                        self.figure._focused_ax = ax
+                        dirty = True
+                    else:
+                        # Single-axes figure: keep the original reset-to-home
+                        ax.transform.reset_to_home()
+                        dirty = True
+                self._last_click_time = now
+
+        elif event.type == pygame.MOUSEBUTTONUP and event.button == 1:
+            self._pan_active = False
+            self._pan_last_pos = None
+
+        elif event.type == pygame.MOUSEMOTION:
+            self._hover_pos = event.pos
+            if self._pan_active and self._pan_last_pos and self._active_ax:
+                dx = event.pos[0] - self._pan_last_pos[0]
+                dy = event.pos[1] - self._pan_last_pos[1]
+                self._active_ax.transform.pan(dx, dy)
+                self._pan_last_pos = event.pos
+                dirty = True
+            dirty = True
+
+        elif event.type == pygame.MOUSEWHEEL:
+            ax = self._find_ax_at(*pygame.mouse.get_pos())
+            if ax:
+                factor = ZOOM_IN if event.y > 0 else ZOOM_OUT
+                mx, my = pygame.mouse.get_pos()
+                ax.transform.zoom(mx, my, factor)
+                dirty = True
+
+        elif event.type == pygame.KEYDOWN:
+            key = event.key
+
+            # Exit focus mode
+            if key == pygame.K_ESCAPE and self.figure._focused_ax is not None:
+                self.figure._focused_ax = None
+                dirty = True
+
+            # Help panel
+            elif key in (pygame.K_h, pygame.K_SLASH, pygame.K_QUESTION):
+                self.show_help = True
+                dirty = True
+
+            # View reset + animation restart
+            elif key == pygame.K_r:
+                ax = self.figure._focused_ax or self._active_ax or (self.figure.axes[0] if self.figure.axes else None)
+                if ax:
+                    ax.transform.reset_to_home()
+                    dirty = True
+                if anim:
+                    anim.pause()
+                    anim._finished = False
+                    anim._next_frame = 0
+                    dirty |= anim._show_frame(0)
+
+            # Animation: play/pause toggle
+            elif key == pygame.K_SPACE:
+                if anim:
+                    anim.toggle()
+                    dirty = True
+
+            # Animation: step forward one frame
+            elif key == pygame.K_RIGHT:
+                if anim and not anim._playing:
+                    dirty = anim.step_forward()
+
+            # Animation: step back one frame
+            elif key == pygame.K_LEFT:
+                if anim and not anim._playing:
+                    dirty = anim.step_back()
+
+            # Save current frame as PNG
+            elif key == pygame.K_s:
+                if screen is not None:
+                    _save_frame(screen, anim)
+
+        return dirty
+
+    def get_hover_hits(self) -> list[dict]:
+        if not self._hover_pos:
+            return []
+        ax = self._find_ax_at(*self._hover_pos)
+        if not ax:
+            return []
+        return ax.hit_test(*self._hover_pos)
+
+
+def draw_help_overlay(surface) -> None:
+    """Draw a centred help panel over the current surface."""
+    import pygame
+    from .fonts import get_font
+
+    sw, sh = surface.get_size()
+    font_key  = get_font('label')
+    font_title = get_font('title')
+
+    pad   = 20
+    row_h = font_key.get_height() + 6
+    col_gap = 24
+
+    # Measure columns
+    key_w = max(font_key.size(k)[0] for k, _ in _HELP_LINES)
+    val_w = max(font_key.size(v)[0] for _, v in _HELP_LINES)
+    title_surf = font_title.render('Keyboard shortcuts', True, (255, 255, 255))
+
+    box_w = pad + key_w + col_gap + val_w + pad
+    box_h = pad + title_surf.get_height() + 10 + len(_HELP_LINES) * row_h + pad
+
+    bx = (sw - box_w) // 2
+    by = (sh - box_h) // 2
+
+    # Dim background
+    dim = pygame.Surface((sw, sh), pygame.SRCALPHA)
+    dim.fill((0, 0, 0, 160))
+    surface.blit(dim, (0, 0))
+
+    # Panel background
+    panel = pygame.Surface((box_w, box_h), pygame.SRCALPHA)
+    panel.fill((30, 30, 30, 230))
+    pygame.draw.rect(panel, (100, 100, 100), (0, 0, box_w, box_h), 1)
+    surface.blit(panel, (bx, by))
+
+    # Title
+    surface.blit(title_surf, (bx + (box_w - title_surf.get_width()) // 2, by + pad))
+    ty = by + pad + title_surf.get_height() + 10
+
+    # Separator line
+    pygame.draw.line(surface, (80, 80, 80),
+                     (bx + pad, ty - 4), (bx + box_w - pad, ty - 4))
+
+    # Rows
+    for key_text, val_text in _HELP_LINES:
+        ks = font_key.render(key_text, True, (255, 200, 60))
+        vs = font_key.render(val_text, True, (200, 200, 200))
+        surface.blit(ks, (bx + pad, ty))
+        surface.blit(vs, (bx + pad + key_w + col_gap, ty))
+        ty += row_h
+
+    # Dismiss hint
+    hint = get_font('tooltip').render('Press  ?  H  or  Esc  to close', True, (130, 130, 130))
+    surface.blit(hint, (bx + (box_w - hint.get_width()) // 2, ty + 6))
+
+
+def _save_frame(screen, anim) -> None:
+    import pygame
+    frame_num = anim._displayed_frame if anim and anim._displayed_frame >= 0 else 0
+    filename = f'frame_{frame_num:04d}.png'
+    pygame.image.save(screen, filename)
+    print(f'Saved {filename}')

plotlive/figure.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+import numpy as np
+from .axes import Axes
+
+if TYPE_CHECKING:
+    from .animation import FuncAnimation
+
+_DPI = 100
+_DEFAULT_LEFT   = 0.125
+_DEFAULT_RIGHT  = 0.900
+_DEFAULT_BOTTOM = 0.110
+_DEFAULT_TOP    = 0.880
+_DEFAULT_WSPACE = 0.200
+_DEFAULT_HSPACE = 0.200
+
+
+class Figure:
+    """Top-level container. Owns all Axes and the pygame surface."""
+
+    def __init__(self, figsize: tuple[float, float] = (6.4, 4.8),
+                 facecolor='white', **kwargs):
+        self.figsize = figsize
+        self.pixel_size = (int(figsize[0] * _DPI), int(figsize[1] * _DPI))
+        self.facecolor = facecolor
+        self.axes: list[Axes] = []
+        self._suptitle: str = ''
+        self._animation: FuncAnimation | None = None
+        self._focused_ax = None   # Axes | None — which subplot is in focus mode
+        self._dirty: bool = True
+
+    def add_axes(self, rect: tuple[float, float, float, float], **kwargs) -> Axes:
+        """Add axes at rect=(left, bottom, width, height) in normalized [0,1] coords."""
+        ax = Axes(self, rect_norm=rect)
+        self.axes.append(ax)
+        return ax
+
+    def add_subplot(self, nrows: int, ncols: int, index: int, **kwargs) -> Axes:
+        """Add subplot at 1-based index in nrows×ncols grid."""
+        rect = self._compute_subplot_rect(nrows, ncols, index)
+        ax = Axes(self, rect_norm=rect)
+        self.axes.append(ax)
+        return ax
+
+    def _compute_subplot_rect(
+        self, nrows: int, ncols: int, index: int,
+        wspace: float = _DEFAULT_WSPACE,
+        hspace: float = _DEFAULT_HSPACE,
+    ) -> tuple[float, float, float, float]:
+        row = (index - 1) // ncols
+        col = (index - 1) % ncols
+        total_w = _DEFAULT_RIGHT - _DEFAULT_LEFT
+        total_h = _DEFAULT_TOP - _DEFAULT_BOTTOM
+        # wspace/hspace are fractions of subplot size (matplotlib convention)
+        subplot_w = total_w / (ncols + (ncols - 1) * wspace)
+        subplot_h = total_h / (nrows + (nrows - 1) * hspace)
+        left   = _DEFAULT_LEFT + col * subplot_w * (1 + wspace)
+        bottom = _DEFAULT_BOTTOM + (nrows - 1 - row) * subplot_h * (1 + hspace)
+        return (left, bottom, subplot_w, subplot_h)
+
+    def subplots(
+        self, nrows: int = 1, ncols: int = 1, squeeze: bool = True, **kwargs
+    ) -> tuple['Figure', np.ndarray | Axes]:
+        axs = np.empty((nrows, ncols), dtype=object)
+        for r in range(nrows):
+            for c in range(ncols):
+                idx = r * ncols + c + 1
+                axs[r, c] = self.add_subplot(nrows, ncols, idx, **kwargs)
+        if squeeze:
+            axs = axs.squeeze()
+            if axs.ndim == 0:
+                return self, axs.item()
+        return self, axs
+
+    def set_size_inches(self, w: float, h: float) -> None:
+        self.figsize = (w, h)
+        self.pixel_size = (int(w * _DPI), int(h * _DPI))
+
+    def suptitle(self, t: str, **kwargs) -> None:
+        self._suptitle = t
+
+    def tight_layout(self, **kwargs) -> None:
+        pass  # MVP: no-op; generous default margins handle most cases
+
+    def savefig(self, fname: str, dpi: int = 100, **kwargs) -> None:
+        import pygame
+        if not pygame.get_init():
+            pygame.init()
+        surface = self._render_to_surface()
+        pygame.image.save(surface, fname)
+
+    def _render_to_surface(self):
+        from .renderer import FigureRenderer
+        return FigureRenderer(self).render()

plotlive/fonts.py

@@ -0,0 +1,73 @@
+"""
+Font loading with a three-level fallback:
+  1. Bundled FreeSansBold.ttf (copied from pygame-ce, Apache 2.0)
+  2. pygame SysFont (OS-level)
+  3. pygame built-in default (None path)
+"""
+from __future__ import annotations
+import functools
+from pathlib import Path
+
+_DATA_DIR = Path(__file__).parent / 'data'
+_BUNDLED_BOLD = str(_DATA_DIR / 'FreeSansBold.ttf')
+
+_ROLE_SIZES: dict[str, tuple[str | None, int]] = {
+    'tick':     (_BUNDLED_BOLD, 11),
+    'label':    (_BUNDLED_BOLD, 13),
+    'title':    (_BUNDLED_BOLD, 14),
+    'legend':   (_BUNDLED_BOLD, 11),
+    'tooltip':  (_BUNDLED_BOLD, 10),
+    'suptitle': (_BUNDLED_BOLD, 16),
+}
+
+
+def _ensure_init():
+    import pygame
+    if not pygame.font.get_init():
+        pygame.font.init()
+
+
+def _make_font(path: str | None, size: int):
+    """Create a pygame Font with fallback to default."""
+    import pygame
+    _ensure_init()
+    if path and Path(path).exists():
+        try:
+            f = pygame.font.Font(path, size)
+            # Validate by doing a test render
+            f.render('a', True, (0, 0, 0))
+            return f
+        except Exception:
+            pass
+    # Fallback to SysFont
+    for name in ('freesans', 'arial', 'helvetica', 'sans'):
+        try:
+            f = pygame.font.SysFont(name, size)
+            f.render('a', True, (0, 0, 0))
+            return f
+        except Exception:
+            continue
+    # Final fallback: pygame built-in
+    return pygame.font.Font(None, size)
+
+
+@functools.lru_cache(maxsize=64)
+def get_font(role: str = 'tick', size_override: int | None = None):
+    """Return a cached font for the given role."""
+    path, size = _ROLE_SIZES.get(role, _ROLE_SIZES['tick'])
+    if size_override is not None:
+        size = size_override
+    return _make_font(path, size)
+
+
+def render_text(text: str, role: str, color: tuple):
+    """Render text to a pygame Surface."""
+    font = get_font(role)
+    return font.render(text, True, color[:3])
+
+
+def render_text_rotated(text: str, role: str, color: tuple, angle: float = 90.0):
+    """Render text rotated by angle degrees."""
+    import pygame
+    surf = render_text(text, role, color)
+    return pygame.transform.rotate(surf, angle)