figrecipe 0.6.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

figrecipe/_editor/__init__.py

@@ -26,10 +26,14 @@ from ._flask_app import FigureEditor
 
 
 def edit(
-    source: Union[RecordingFigure, str, Path],
+    source: Optional[Union[RecordingFigure, str, Path]] = None,
     style: Optional[Union[str, Dict[str, Any]]] = None,
     port: int = 5050,
+    host: str = "127.0.0.1",
     open_browser: bool = True,
+    hot_reload: bool = False,
+    working_dir: Optional[Union[str, Path]] = None,
+    desktop: bool = False,
 ) -> Dict[str, Any]:
     """
     Launch interactive GUI editor for figure styling.
@@ -39,8 +43,14 @@ def edit(
 
     Parameters
     ----------
-    source : RecordingFigure, str, or Path
-        Either a live RecordingFigure object or path to a .yaml recipe file.
+    source : RecordingFigure, str, Path, or None
+        Figure source. Supports multiple formats:
+        - RecordingFigure: Live figure object
+        - .yaml/.yml: Direct recipe file
+        - .png/.jpg/etc: Image with associated .yaml
+        - Directory: Bundle containing recipe.yaml
+        - .zip: ZIP archive containing recipe.yaml
+        - None: Create new blank figure
     style : str or dict, optional
         Style preset name (e.g., 'SCITEX', 'SCITEX_DARK') or style dict.
         If None, uses the currently loaded global style.
@@ -48,6 +58,15 @@ def edit(
         Flask server port (default: 5050). Auto-finds available port if occupied.
     open_browser : bool, optional
         Whether to open browser automatically (default: True).
+    hot_reload : bool, optional
+        Enable hot reload - server restarts when source files change (default: False).
+        Like Django's development server. Browser auto-refreshes on reconnect.
+    working_dir : str or Path, optional
+        Working directory for file switching feature (default: current directory).
+        The file switcher will list recipe files from this directory.
+    desktop : bool, optional
+        Launch as native desktop window using pywebview (default: False).
+        Requires: pip install figrecipe[desktop]
 
     Returns
     -------
@@ -109,34 +128,65 @@ def edit(
     hitmap, color_map = generate_hitmap(fig)
     hitmap_base64 = hitmap_to_base64(hitmap)
 
+    # Resolve working directory
+    resolved_working_dir = Path(working_dir) if working_dir else Path.cwd()
+
     # Create and run editor with pre-rendered static PNG
     editor = FigureEditor(
         fig=fig,
         recipe_path=recipe_path,
         style=style_dict,
         port=port,
+        host=host,
         static_png_path=static_png_path,
         hitmap_base64=hitmap_base64,
         color_map=color_map,
+        hot_reload=hot_reload,
+        working_dir=resolved_working_dir,
+        desktop=desktop,
     )
 
     return editor.run(open_browser=open_browser)
 
 
-def _resolve_source(source: Union[RecordingFigure, str, Path]):
+def _check_figure_has_content(fig: RecordingFigure) -> bool:
+    """Check if figure has any plot content."""
+    for ax_row in fig._axes:
+        for ax in ax_row:
+            # Check for lines, patches, images, collections
+            if ax.lines or ax.patches or ax.images or ax.collections or ax.texts:
+                return True
+    return False
+
+
+def _resolve_source(source: Optional[Union[RecordingFigure, str, Path]]):
     """
     Resolve source to figure and optional recipe path.
 
     Parameters
     ----------
-    source : RecordingFigure, str, or Path
-        Input source.
+    source : RecordingFigure, str, Path, or None
+        Input source. Supports:
+        - None: Creates new blank figure
+        - RecordingFigure: Uses directly
+        - .yaml/.yml: Direct recipe file
+        - .png/.jpg/etc: Image with associated YAML
+        - Directory: Bundle containing recipe.yaml
+        - .zip: ZIP archive containing recipe.yaml
 
     Returns
     -------
     tuple
-        (RecordingFigure or None, Path or None)
+        (RecordingFigure, Path or None)
     """
+    # Handle None - create new blank figure
+    if source is None:
+        from .. import subplots
+
+        fig, ax = subplots()
+        ax.set_title("New Figure")
+        return fig, None
+
     if isinstance(source, RecordingFigure):
         return source, None
 
@@ -157,13 +207,11 @@ def _resolve_source(source: Union[RecordingFigure, str, Path]):
         )
         return wrapped_fig, None
 
-    # Assume it's a path
-    path = Path(source)
-    if not path.exists():
-        raise FileNotFoundError(f"Recipe file not found: {path}")
+    # Assume it's a path - use bundle resolution (handles dir, zip, yaml, png)
+    from .._utils._bundle import resolve_recipe_path
 
-    if path.suffix.lower() not in (".yaml", ".yml"):
-        raise ValueError(f"Expected .yaml or .yml file, got: {path.suffix}")
+    path, _temp_dir = resolve_recipe_path(source)
+    # Note: temp_dir cleanup handled by reproduce() if ZIP was extracted
 
     # Load recipe and reproduce figure
     from .._reproducer import reproduce

figrecipe/_editor/_bbox/__init__.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Modular bbox extraction for figure elements.
+
+This package provides functions for extracting bounding boxes from
+matplotlib figure elements for hit detection in the GUI editor.
+
+The main function `extract_bboxes` is re-exported from _bbox_main.py
+for backward compatibility.
+
+Modules:
+- _transforms: Coordinate transformation utilities
+- _elements: General element, text, and tick bbox extraction
+- _lines: Line and quiver bbox extraction
+- _collections: Collection (scatter, fill) and patch bbox extraction
+"""
+
+# Re-export main function from _extract.py
+# Import modular helpers
+from ._collections import get_collection_bbox, get_patch_bbox
+from ._elements import get_element_bbox, get_text_bbox, get_tick_labels_bbox
+from ._extract import extract_bboxes
+from ._lines import get_line_bbox, get_quiver_bbox
+from ._transforms import display_to_image, transform_bbox
+
+__all__ = [
+    # Main function
+    "extract_bboxes",
+    # Transforms
+    "transform_bbox",
+    "display_to_image",
+    # Elements
+    "get_element_bbox",
+    "get_text_bbox",
+    "get_tick_labels_bbox",
+    # Lines
+    "get_line_bbox",
+    "get_quiver_bbox",
+    # Collections
+    "get_collection_bbox",
+    "get_patch_bbox",
+]

figrecipe/_editor/_bbox/_collections.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Collection bbox extraction for scatter, fill, and patch elements.
+
+This module handles bbox extraction for matplotlib collections
+(scatter plots, fills, bars, etc.).
+"""
+
+import math
+from typing import Any, Dict, Optional
+
+from matplotlib.axes import Axes
+from matplotlib.collections import PathCollection
+from matplotlib.figure import Figure
+from matplotlib.transforms import Bbox
+
+from ._elements import get_element_bbox
+from ._transforms import display_to_image, transform_bbox
+
+
+def get_collection_bbox(
+    coll,
+    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 collection (scatter, fill)."""
+    try:
+        bbox = None
+
+        # For scatter plots, get_window_extent() can fail or return empty
+        # So we calculate bbox from data points as fallback
+        if isinstance(coll, PathCollection):
+            offsets = coll.get_offsets()
+            if len(offsets) > 0:
+                transform = ax.transData
+                points = []
+
+                # Limit to reasonable number of points
+                max_points = 200
+                step = max(1, len(offsets) // max_points)
+
+                for i in range(0, len(offsets), step):
+                    try:
+                        offset = offsets[i]
+                        display_coords = transform.transform(offset)
+                        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
+
+                # Calculate bbox from points
+                if points:
+                    xs = [p[0] for p in points]
+                    ys = [p[1] for p in points]
+                    # Add padding around scatter points for easier clicking
+                    padding = 10  # pixels
+                    bbox = {
+                        "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),
+                        "points": points,
+                    }
+                    return bbox
+
+        # Fallback: try standard window extent
+        window_extent = coll.get_window_extent(renderer)
+        if window_extent is None:
+            # Use axes extent as fallback
+            return get_element_bbox(
+                ax,
+                fig,
+                renderer,
+                tight_bbox,
+                img_width,
+                img_height,
+                scale_x,
+                scale_y,
+                pad_inches,
+                saved_height_inches,
+            )
+
+        # Check if window_extent is valid (not inf)
+        if (
+            math.isinf(window_extent.x0)
+            or math.isinf(window_extent.y0)
+            or math.isinf(window_extent.x1)
+            or math.isinf(window_extent.y1)
+        ):
+            # Invalid extent - use axes extent as fallback
+            return get_element_bbox(
+                ax,
+                fig,
+                renderer,
+                tight_bbox,
+                img_width,
+                img_height,
+                scale_x,
+                scale_y,
+                pad_inches,
+                saved_height_inches,
+            )
+
+        bbox = transform_bbox(
+            window_extent,
+            fig,
+            tight_bbox,
+            img_width,
+            img_height,
+            scale_x,
+            scale_y,
+            pad_inches,
+            saved_height_inches,
+        )
+
+        return bbox
+
+    except Exception:
+        return None
+
+
+def get_patch_bbox(
+    patch,
+    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, float]]:
+    """Get bbox for a patch (bar, rectangle)."""
+    try:
+        window_extent = patch.get_window_extent(renderer)
+        if window_extent is None:
+            return None
+        return transform_bbox(
+            window_extent,
+            fig,
+            tight_bbox,
+            img_width,
+            img_height,
+            scale_x,
+            scale_y,
+            pad_inches,
+            saved_height_inches,
+        )
+    except Exception:
+        return None
+
+
+__all__ = ["get_collection_bbox", "get_patch_bbox"]

figrecipe/_editor/_bbox/_elements.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Element bbox extraction for general elements, text, and ticks.
+
+This module handles bbox extraction for axes, text labels, and tick marks.
+"""
+
+from typing import Dict, Optional
+
+from matplotlib.figure import Figure
+from matplotlib.transforms import Bbox
+
+from ._transforms import transform_bbox
+
+
+def get_element_bbox(
+    element,
+    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, float]]:
+    """Get bbox for a general element."""
+    try:
+        window_extent = element.get_window_extent(renderer)
+        if window_extent is None:
+            return None
+        return transform_bbox(
+            window_extent,
+            fig,
+            tight_bbox,
+            img_width,
+            img_height,
+            scale_x,
+            scale_y,
+            pad_inches,
+            saved_height_inches,
+        )
+    except Exception:
+        return None
+
+
+def get_text_bbox(
+    text,
+    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, float]]:
+    """Get bbox for a text element."""
+    try:
+        window_extent = text.get_window_extent(renderer)
+        if window_extent is None:
+            return None
+        return transform_bbox(
+            window_extent,
+            fig,
+            tight_bbox,
+            img_width,
+            img_height,
+            scale_x,
+            scale_y,
+            pad_inches,
+            saved_height_inches,
+        )
+    except Exception:
+        return None
+
+
+def get_tick_labels_bbox(
+    axis,
+    axis_type: str,  # 'x' or 'y'
+    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, float]]:
+    """
+    Get bbox for tick labels, extended to span the full axis dimension.
+
+    For x-axis: tick labels bbox spans the full width of the plot area.
+    For y-axis: tick labels bbox spans the full height of the plot area.
+    """
+    try:
+        all_bboxes = []
+
+        # Get all tick label bboxes
+        for tick in axis.get_major_ticks():
+            tick_label = tick.label1 if hasattr(tick, "label1") else tick.label
+            if tick_label and tick_label.get_visible():
+                try:
+                    tick_extent = tick_label.get_window_extent(renderer)
+                    if tick_extent is not None and tick_extent.width > 0:
+                        all_bboxes.append(tick_extent)
+                except Exception:
+                    pass
+
+        if not all_bboxes:
+            return None
+
+        # Merge all tick label bboxes
+        merged = all_bboxes[0]
+        for bbox in all_bboxes[1:]:
+            merged = Bbox.union([merged, bbox])
+
+        # Get the axes extent to extend the tick labels region
+        ax = axis.axes
+        ax_bbox = ax.get_window_extent(renderer)
+
+        if axis_type == "x":
+            # For x-axis: extend width to match axes width, keep tick labels height
+            merged = Bbox.from_extents(
+                ax_bbox.x0,  # Align left with axes
+                merged.y0,  # Keep tick labels y position
+                ax_bbox.x1,  # Align right with axes
+                merged.y1,  # Keep tick labels height
+            )
+        else:  # y-axis
+            # For y-axis: extend height to match axes height, keep tick labels width
+            merged = Bbox.from_extents(
+                merged.x0,  # Keep tick labels x position
+                ax_bbox.y0,  # Align bottom with axes
+                merged.x1,  # Keep tick labels width
+                ax_bbox.y1,  # Align top with axes
+            )
+
+        return transform_bbox(
+            merged,
+            fig,
+            tight_bbox,
+            img_width,
+            img_height,
+            scale_x,
+            scale_y,
+            pad_inches,
+            saved_height_inches,
+        )
+
+    except Exception:
+        return None
+
+
+__all__ = ["get_element_bbox", "get_text_bbox", "get_tick_labels_bbox"]