figrecipe 0.5.0__py3-none-any.whl → 0.7.4__py3-none-any.whl

figrecipe/_editor/_bbox/_lines.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Line bbox extraction for line plots.
+
+This module handles bbox extraction for line elements,
+including data point sampling for hit detection.
+"""
+
+from typing import Any, Dict, Optional
+
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from matplotlib.transforms import Bbox
+
+from ._transforms import display_to_image, transform_bbox
+
+
+def get_line_bbox(
+    line,
+    ax: Axes,
+    fig: Figure,
+    renderer,
+    tight_bbox: Bbox,
+    img_width: int,
+    img_height: int,
+    scale_x: float,
+    scale_y: float,
+    pad_inches: float,
+    saved_height_inches: float,
+    include_points: bool = True,
+) -> Optional[Dict[str, Any]]:
+    """Get bbox and points for a line."""
+    try:
+        # Get window extent
+        window_extent = line.get_window_extent(renderer)
+        if window_extent is None:
+            return None
+
+        bbox = transform_bbox(
+            window_extent,
+            fig,
+            tight_bbox,
+            img_width,
+            img_height,
+            scale_x,
+            scale_y,
+            pad_inches,
+            saved_height_inches,
+        )
+        if bbox is None:
+            return None
+
+        # Add path points for proximity detection
+        if include_points:
+            xdata = line.get_xdata()
+            ydata = line.get_ydata()
+
+            if len(xdata) > 0 and len(ydata) > 0:
+                # Transform data coords to image pixels
+                transform = ax.transData
+                points = []
+
+                # Downsample if too many points
+                max_points = 100
+                step = max(1, len(xdata) // max_points)
+
+                for i in range(0, len(xdata), step):
+                    try:
+                        display_coords = transform.transform((xdata[i], ydata[i]))
+                        img_coords = display_to_image(
+                            display_coords[0],
+                            display_coords[1],
+                            fig,
+                            tight_bbox,
+                            img_width,
+                            img_height,
+                            scale_x,
+                            scale_y,
+                            pad_inches,
+                            saved_height_inches,
+                        )
+                        if img_coords:
+                            points.append(img_coords)
+                    except Exception:
+                        continue
+
+                if points:
+                    bbox["points"] = points
+
+        return bbox
+
+    except Exception:
+        return None
+
+
+def get_quiver_bbox(
+    quiver,
+    ax: Axes,
+    fig: Figure,
+    renderer,
+    tight_bbox: Bbox,
+    img_width: int,
+    img_height: int,
+    scale_x: float,
+    scale_y: float,
+    pad_inches: float,
+    saved_height_inches: float,
+) -> Optional[Dict[str, Any]]:
+    """Get bbox for a quiver plot from its data points."""
+    try:
+        # Get X, Y positions from quiver
+        # Quiver stores positions in X, Y arrays
+        X = quiver.X
+        Y = quiver.Y
+
+        if X is None or Y is None or len(X) == 0:
+            return None
+
+        # Flatten if needed
+        import numpy as np
+
+        X_flat = np.asarray(X).flatten()
+        Y_flat = np.asarray(Y).flatten()
+
+        if len(X_flat) == 0 or len(Y_flat) == 0:
+            return None
+
+        transform = ax.transData
+        points = []
+
+        # Limit to reasonable number of points
+        max_points = 100
+        step = max(1, len(X_flat) // max_points)
+
+        for i in range(0, len(X_flat), step):
+            try:
+                display_coords = transform.transform((X_flat[i], Y_flat[i]))
+                img_coords = display_to_image(
+                    display_coords[0],
+                    display_coords[1],
+                    fig,
+                    tight_bbox,
+                    img_width,
+                    img_height,
+                    scale_x,
+                    scale_y,
+                    pad_inches,
+                    saved_height_inches,
+                )
+                if img_coords:
+                    points.append(img_coords)
+            except Exception:
+                continue
+
+        if not points:
+            return None
+
+        # Calculate bbox from points
+        xs = [p[0] for p in points]
+        ys = [p[1] for p in points]
+        padding = 15  # pixels - slightly larger for quiver arrows
+        return {
+            "x": float(min(xs) - padding),
+            "y": float(min(ys) - padding),
+            "width": float(max(xs) - min(xs) + 2 * padding),
+            "height": float(max(ys) - min(ys) + 2 * padding),
+        }
+    except Exception:
+        return None
+
+
+__all__ = ["get_line_bbox", "get_quiver_bbox"]

figrecipe/_editor/_bbox/_transforms.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Coordinate transformation utilities for bbox extraction.
+
+This module handles the transformation from matplotlib display coordinates
+to image pixel coordinates for hit detection.
+"""
+
+from typing import Dict, List, Optional
+
+from matplotlib.figure import Figure
+from matplotlib.transforms import Bbox
+
+
+def transform_bbox(
+    window_extent: Bbox,
+    fig: Figure,
+    tight_bbox: Bbox,
+    img_width: int,
+    img_height: int,
+    scale_x: float,
+    scale_y: float,
+    pad_inches: float,
+    saved_height_inches: float,
+) -> Optional[Dict[str, float]]:
+    """
+    Transform matplotlib window extent to image pixel coordinates.
+
+    Parameters
+    ----------
+    window_extent : Bbox
+        Bbox in display coordinates (points).
+    fig : Figure
+        Matplotlib figure.
+    tight_bbox : Bbox
+        Tight bbox of figure in inches.
+    img_width, img_height : int
+        Output image dimensions.
+    scale_x, scale_y : float
+        Scale factors from inches to pixels.
+    pad_inches : float
+        Padding added by bbox_inches='tight' (default 0.1).
+    saved_height_inches : float
+        Total saved image height including padding.
+
+    Returns
+    -------
+    dict or None
+        {x, y, width, height} in image pixels.
+    """
+    try:
+        dpi = fig.dpi
+
+        # Convert display coords to inches
+        x0_inches = window_extent.x0 / dpi
+        y0_inches = window_extent.y0 / dpi
+        x1_inches = window_extent.x1 / dpi
+        y1_inches = window_extent.y1 / dpi
+
+        # Transform to saved image coordinates
+        # Account for tight bbox origin and padding
+        x0_rel = x0_inches - tight_bbox.x0 + pad_inches
+        x1_rel = x1_inches - tight_bbox.x0 + pad_inches
+
+        # Y coordinate flip: matplotlib Y=0 at bottom, image Y=0 at top
+        y0_rel = saved_height_inches - (y1_inches - tight_bbox.y0 + pad_inches)
+        y1_rel = saved_height_inches - (y0_inches - tight_bbox.y0 + pad_inches)
+
+        # Scale to image pixels
+        x0_px = x0_rel * scale_x
+        y0_px = y0_rel * scale_y
+        x1_px = x1_rel * scale_x
+        y1_px = y1_rel * scale_y
+
+        # Clamp to bounds
+        x0_px = max(0, min(x0_px, img_width))
+        x1_px = max(0, min(x1_px, img_width))
+        y0_px = max(0, min(y0_px, img_height))
+        y1_px = max(0, min(y1_px, img_height))
+
+        width = x1_px - x0_px
+        height = y1_px - y0_px
+
+        if width <= 0 or height <= 0:
+            return None
+
+        return {
+            "x": float(x0_px),
+            "y": float(y0_px),
+            "width": float(width),
+            "height": float(height),
+        }
+
+    except Exception:
+        return None
+
+
+def display_to_image(
+    display_x: float,
+    display_y: float,
+    fig: Figure,
+    tight_bbox: Bbox,
+    img_width: int,
+    img_height: int,
+    scale_x: float,
+    scale_y: float,
+    pad_inches: float,
+    saved_height_inches: float,
+) -> Optional[List[float]]:
+    """
+    Transform display coordinates to image pixel coordinates.
+
+    Returns
+    -------
+    list or None
+        [x, y] in image pixels.
+    """
+    try:
+        dpi = fig.dpi
+
+        # Convert to inches
+        x_inches = display_x / dpi
+        y_inches = display_y / dpi
+
+        # Transform to saved image coordinates with padding
+        x_rel = x_inches - tight_bbox.x0 + pad_inches
+
+        # Y coordinate flip: matplotlib Y=0 at bottom, image Y=0 at top
+        y_rel = saved_height_inches - (y_inches - tight_bbox.y0 + pad_inches)
+
+        # Scale to image pixels
+        x_px = x_rel * scale_x
+        y_px = y_rel * scale_y
+
+        # Clamp
+        x_px = max(0, min(x_px, img_width))
+        y_px = max(0, min(y_px, img_height))
+
+        return [float(x_px), float(y_px)]
+
+    except Exception:
+        return None
+
+
+__all__ = ["transform_bbox", "display_to_image"]

figrecipe/_editor/_flask_app.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Flask-based GUI editor for figure styling.
+
+This module provides a web-based interface for interactively adjusting
+figure styles with hitmap-based element selection.
+
+Style Override Architecture
+---------------------------
+Styles are managed in layers with separate storage:
+
+1. Base style (from preset like SCITEX)
+2. Programmatic style (from code)
+3. Manual overrides (from GUI editor)
+
+Manual overrides are stored separately in `.overrides.json` files,
+allowing restoration to original programmatic styles.
+"""
+
+# Force Agg backend before any pyplot import to avoid Tkinter threading issues
+import matplotlib
+
+matplotlib.use("Agg")
+
+import webbrowser
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .._wrappers import RecordingFigure
+from ._overrides import create_overrides_from_style, load_overrides
+
+
+class FigureEditor:
+    """
+    Browser-based figure style editor using Flask.
+
+    Features:
+    - Real-time figure preview with style overrides
+    - Hitmap-based element selection
+    - Full style property editing (dimensions, fonts, lines, colors, etc.)
+    - Dark/light theme toggle
+    - Download in PNG/SVG/PDF formats
+    - Separate storage of manual overrides (can restore to original)
+    - Hot reload: server restarts on source file changes (like Django)
+    """
+
+    def __init__(
+        self,
+        fig: RecordingFigure,
+        recipe_path: Optional[Path] = None,
+        style: Optional[Dict[str, Any]] = None,
+        port: int = 5050,
+        static_png_path: Optional[Path] = None,
+        hitmap_base64: Optional[str] = None,
+        color_map: Optional[Dict] = None,
+        hot_reload: bool = False,
+        working_dir: Optional[Path] = None,
+    ):
+        """
+        Initialize figure editor.
+
+        Parameters
+        ----------
+        fig : RecordingFigure
+            Figure to edit.
+        recipe_path : Path, optional
+            Path to recipe file (if loaded from file).
+        style : dict, optional
+            Initial style configuration (programmatic).
+        port : int
+            Flask server port.
+        static_png_path : Path, optional
+            Path to pre-rendered static PNG (source of truth for initial display).
+        hitmap_base64 : str, optional
+            Pre-generated hitmap as base64.
+        color_map : dict, optional
+            Pre-generated color map for hitmap.
+        hot_reload : bool, optional
+            Enable hot reload - server restarts on source file changes.
+        working_dir : Path, optional
+            Working directory for file switching (default: current directory).
+        """
+        self.fig = fig
+        self.recipe_path = Path(recipe_path) if recipe_path else None
+        self.port = port
+        self.hot_reload = hot_reload
+        self.working_dir = Path(working_dir) if working_dir else Path.cwd()
+
+        # Load user preferences
+        from ._preferences import load_preferences
+
+        prefs = load_preferences()
+        self.dark_mode = prefs.get("dark_mode", False)
+
+        # Pre-rendered static PNG (source of truth)
+        self._static_png_path = static_png_path
+        self._initial_base64 = None
+        if static_png_path and static_png_path.exists():
+            import base64
+
+            with open(static_png_path, "rb") as f:
+                self._initial_base64 = base64.b64encode(f.read()).decode("utf-8")
+
+        # Store original axes positions for restore functionality
+        self._initial_axes_positions = self._capture_axes_positions()
+
+        # Initialize style overrides system
+        self._init_style_overrides(style)
+
+        # Pre-generated hitmap and color_map
+        # Use empty dict as default to prevent JavaScript errors
+        # when page loads before hitmap is generated
+        self._hitmap_base64 = hitmap_base64
+        self._color_map = color_map if color_map is not None else {}
+
+    def _init_style_overrides(self, programmatic_style: Optional[Dict[str, Any]]):
+        """Initialize the layered style override system."""
+        # Try to load existing overrides
+        if self.recipe_path:
+            existing = load_overrides(self.recipe_path)
+            if existing:
+                self.style_overrides = existing
+                if programmatic_style:
+                    self.style_overrides.programmatic_style = programmatic_style
+                return
+
+        # Get base style from global preset
+        base_style = {}
+        style_name = "SCITEX"
+        try:
+            from ..styles._style_loader import (
+                _CURRENT_STYLE_NAME,
+                _STYLE_CACHE,
+                load_style,
+                to_subplots_kwargs,
+            )
+
+            if _STYLE_CACHE is None:
+                load_style("SCITEX")
+
+            from ..styles._style_loader import _STYLE_CACHE
+
+            if _STYLE_CACHE is not None:
+                base_style = to_subplots_kwargs(_STYLE_CACHE)
+                style_name = _CURRENT_STYLE_NAME or "SCITEX"
+        except Exception:
+            pass
+
+        self._style_name = style_name
+
+        self.style_overrides = create_overrides_from_style(
+            base_style=base_style,
+            programmatic_style=programmatic_style or {},
+        )
+
+    @property
+    def style(self) -> Dict[str, Any]:
+        """Get the original style (without manual overrides)."""
+        return self.style_overrides.get_original_style()
+
+    @property
+    def overrides(self) -> Dict[str, Any]:
+        """Get current manual overrides."""
+        return self.style_overrides.manual_overrides
+
+    @overrides.setter
+    def overrides(self, value: Dict[str, Any]):
+        """Set manual overrides."""
+        self.style_overrides.manual_overrides = value
+
+    def get_effective_style(self) -> Dict[str, Any]:
+        """Get the final merged style."""
+        return self.style_overrides.get_effective_style()
+
+    def _capture_axes_positions(self) -> Dict[int, list]:
+        """Capture current axes positions (matplotlib coords: [left, bottom, width, height])."""
+        mpl_fig = self.fig.fig if hasattr(self.fig, "fig") else self.fig
+        axes = mpl_fig.get_axes()
+        positions = {}
+        for i, ax in enumerate(axes):
+            bbox = ax.get_position()
+            positions[i] = [bbox.x0, bbox.y0, bbox.width, bbox.height]
+        return positions
+
+    def restore_axes_positions(self) -> None:
+        """Restore axes to their original positions."""
+        if not self._initial_axes_positions:
+            return
+        mpl_fig = self.fig.fig if hasattr(self.fig, "fig") else self.fig
+        axes = mpl_fig.get_axes()
+        for i, ax in enumerate(axes):
+            if i in self._initial_axes_positions:
+                pos = self._initial_axes_positions[i]
+                ax.set_position(pos)
+
+    def run(self, open_browser: bool = True) -> Dict[str, Any]:
+        """
+        Run the editor server.
+
+        Parameters
+        ----------
+        open_browser : bool
+            Whether to open browser automatically.
+
+        Returns
+        -------
+        dict
+            Final style overrides after editing session.
+        """
+        from flask import Flask
+
+        from ._routes_axis import register_axis_routes
+        from ._routes_core import register_core_routes
+        from ._routes_element import register_element_routes
+        from ._routes_style import register_style_routes
+
+        # Defer hitmap generation until first request (lazy loading)
+        self._hitmap_generated = self._hitmap_base64 is not None
+
+        # Create Flask app
+        app = Flask(__name__)
+
+        # Register all routes
+        register_core_routes(app, self)
+        register_style_routes(app, self)
+        register_axis_routes(app, self)
+        register_element_routes(app, self)
+
+        # Start server
+        url = f"http://127.0.0.1:{self.port}"
+        print(f"Figure Editor running at {url}")
+
+        if self.hot_reload:
+            print("Hot reload ENABLED - server will restart on source file changes")
+        print("Press Ctrl+C to stop and return overrides")
+
+        if open_browser:
+            webbrowser.open(url)
+
+        try:
+            # Use Flask's built-in reloader when hot_reload is enabled
+            # Note: debug and use_reloader are always False when working with
+            # multiple coding agents to avoid file watching conflicts
+            app.run(
+                host="127.0.0.1",
+                port=self.port,
+                debug=False,
+                use_reloader=False,
+                threaded=True,
+            )
+        except KeyboardInterrupt:
+            print("\nEditor closed")
+
+        return self.overrides
+
+
+__all__ = ["FigureEditor"]