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

figrecipe/_editor/_hitmap/_detect.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Plot type detection utilities for hitmap generation."""
+
+from typing import Any, Dict
+
+
+def detect_plot_types(fig) -> Dict[int, Dict[str, Any]]:
+    """Detect plot types from recorded calls in figure.
+
+    Parameters
+    ----------
+    fig : Figure
+        The figure to analyze.
+
+    Returns
+    -------
+    dict
+        Mapping from ax_index to plot type info.
+    """
+    # Get figure record if available
+    if hasattr(fig, "record"):
+        record = fig.record
+    elif hasattr(fig, "fig") and hasattr(fig.fig, "_record"):
+        record = fig.fig._record
+    else:
+        return {}
+
+    result = {}
+
+    # Process each axes in the record
+    if hasattr(record, "axes"):
+        # First pass: collect all ax_keys to determine grid dimensions
+        ax_keys = list(record.axes.keys())
+        max_row, max_col = 0, 0
+        for ax_key in ax_keys:
+            try:
+                parts = ax_key.split("_")
+                row, col = int(parts[1]), int(parts[2])
+                max_row = max(max_row, row)
+                max_col = max(max_col, col)
+            except (ValueError, IndexError):
+                pass
+        ncols = max_col + 1
+
+        for ax_key, ax_record in record.axes.items():
+            # Extract ax_index from key (e.g., "ax_0_0" -> 0, "ax_2_2" -> 8 for 3x3)
+            try:
+                parts = ax_key.split("_")
+                row, col = int(parts[1]), int(parts[2])
+                ax_idx = row * ncols + col
+            except (ValueError, IndexError):
+                ax_idx = 0
+
+            if ax_idx not in result:
+                result[ax_idx] = {"types": set(), "call_ids": {}}
+
+            # Collect all call types and their IDs
+            if hasattr(ax_record, "calls"):
+                for call in ax_record.calls:
+                    func_name = call.function
+                    call_id = call.id
+
+                    result[ax_idx]["types"].add(func_name)
+
+                    if func_name not in result[ax_idx]["call_ids"]:
+                        result[ax_idx]["call_ids"][func_name] = []
+                    result[ax_idx]["call_ids"][func_name].append(call_id)
+
+    return result
+
+
+def is_boxplot_element(line, ax) -> bool:
+    """Check if a line element belongs to a boxplot.
+
+    Parameters
+    ----------
+    line : Line2D
+        The line to check.
+    ax : Axes
+        The axes containing the line.
+
+    Returns
+    -------
+    bool
+        True if line is a boxplot element.
+    """
+    label = line.get_label() or ""
+
+    # Boxplot whisker/median lines have specific patterns
+    if label.startswith("_line"):
+        return True
+
+    # Check if line is horizontal (median) or vertical (whisker)
+    xdata = line.get_xdata()
+    ydata = line.get_ydata()
+
+    if len(xdata) == 2 and len(ydata) == 2:
+        # Horizontal or vertical line segments
+        is_horizontal = ydata[0] == ydata[1]
+        is_vertical = xdata[0] == xdata[1]
+        if is_horizontal or is_vertical:
+            return True
+
+    return False
+
+
+def is_violin_element(coll, ax) -> bool:
+    """Check if a collection element belongs to a violin plot.
+
+    Parameters
+    ----------
+    coll : Collection
+        The collection to check.
+    ax : Axes
+        The axes containing the collection.
+
+    Returns
+    -------
+    bool
+        True if collection is a violin element.
+    """
+    from matplotlib.collections import PolyCollection
+
+    if isinstance(coll, PolyCollection):
+        # Violin bodies are PolyCollections
+        return True
+    return False
+
+
+__all__ = [
+    "detect_plot_types",
+    "is_boxplot_element",
+    "is_violin_element",
+]
+
+# EOF

figrecipe/_editor/_hitmap/_restore.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Property restoration for hitmap generation."""
+
+from typing import Any, Dict, List
+
+from matplotlib.collections import (
+    LineCollection,
+    PathCollection,
+    PolyCollection,
+)
+
+
+def restore_axes_properties(
+    axes_list: List,
+    original_props: Dict[str, Any],
+    include_text: bool = True,
+) -> None:
+    """Restore original properties to axes elements.
+
+    Parameters
+    ----------
+    axes_list : list
+        List of axes to restore.
+    original_props : dict
+        Dictionary of original properties keyed by element key.
+    include_text : bool
+        Whether text elements were modified.
+    """
+    for ax_idx, ax in enumerate(axes_list):
+        # Restore lines
+        for i, line in enumerate(ax.get_lines()):
+            key = f"ax{ax_idx}_line{i}"
+            if key in original_props:
+                props = original_props[key]
+                line.set_color(props["color"])
+                line.set_markerfacecolor(props["markerfacecolor"])
+                line.set_markeredgecolor(props["markeredgecolor"])
+
+        # Restore collections
+        for i, coll in enumerate(ax.collections):
+            if isinstance(coll, PathCollection):
+                key = f"ax{ax_idx}_scatter{i}"
+                if key in original_props:
+                    props = original_props[key]
+                    coll.set_facecolors(props["facecolors"])
+                    coll.set_edgecolors(props["edgecolors"])
+            elif isinstance(coll, PolyCollection):
+                key = f"ax{ax_idx}_fill{i}"
+                if key in original_props:
+                    props = original_props[key]
+                    coll.set_facecolors(props["facecolors"])
+                    coll.set_edgecolors(props["edgecolors"])
+            elif isinstance(coll, LineCollection):
+                key = f"ax{ax_idx}_linecoll{i}"
+                if key in original_props:
+                    props = original_props[key]
+                    if len(props["colors"]) > 0:
+                        coll.set_color(props["colors"])
+
+        # Restore patches
+        for i, patch in enumerate(ax.patches):
+            key = f"ax{ax_idx}_bar{i}"
+            if key in original_props:
+                props = original_props[key]
+                patch.set_facecolor(props["facecolor"])
+                patch.set_edgecolor(props["edgecolor"])
+
+        # Restore text
+        if include_text:
+            key = f"ax{ax_idx}_title"
+            if key in original_props:
+                ax.title.set_color(original_props[key]["color"])
+
+            key = f"ax{ax_idx}_xlabel"
+            if key in original_props:
+                ax.xaxis.label.set_color(original_props[key]["color"])
+
+            key = f"ax{ax_idx}_ylabel"
+            if key in original_props:
+                ax.yaxis.label.set_color(original_props[key]["color"])
+
+        # Restore legend
+        key = f"ax{ax_idx}_legend"
+        if key in original_props:
+            legend = ax.get_legend()
+            if legend:
+                frame = legend.get_frame()
+                props = original_props[key]
+                frame.set_facecolor(props["facecolor"])
+                frame.set_edgecolor(props["edgecolor"])
+
+        # Restore spines
+        for spine in ax.spines.values():
+            spine.set_color("black")
+
+        # Restore tick colors
+        ax.tick_params(colors="black")
+
+
+def restore_figure_text(
+    mpl_fig,
+    original_props: Dict[str, Any],
+    include_text: bool = True,
+) -> None:
+    """Restore figure-level text properties.
+
+    Parameters
+    ----------
+    mpl_fig : Figure
+        The matplotlib figure.
+    original_props : dict
+        Dictionary of original properties.
+    include_text : bool
+        Whether text elements were modified.
+    """
+    if not include_text:
+        return
+
+    key = "fig_suptitle"
+    if key in original_props and hasattr(mpl_fig, "_suptitle") and mpl_fig._suptitle:
+        mpl_fig._suptitle.set_color(original_props[key]["color"])
+
+    key = "fig_supxlabel"
+    if key in original_props and hasattr(mpl_fig, "_supxlabel") and mpl_fig._supxlabel:
+        mpl_fig._supxlabel.set_color(original_props[key]["color"])
+
+    key = "fig_supylabel"
+    if key in original_props and hasattr(mpl_fig, "_supylabel") and mpl_fig._supylabel:
+        mpl_fig._supylabel.set_color(original_props[key]["color"])
+
+
+def restore_backgrounds(fig, axes_list: List) -> None:
+    """Restore background colors.
+
+    Parameters
+    ----------
+    fig : Figure
+        The figure.
+    axes_list : list
+        List of axes.
+    """
+    fig.patch.set_facecolor("white")
+    for ax in axes_list:
+        ax.set_facecolor("white")
+
+
+__all__ = [
+    "restore_axes_properties",
+    "restore_figure_text",
+    "restore_backgrounds",
+]
+
+# EOF

figrecipe/_editor/_hitmap_main.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Hitmap generation for interactive element selection.
+
+This module generates color-coded images where each figure element
+(line, scatter, bar, text, etc.) is rendered with a unique RGB color.
+This enables precise pixel-based element detection when users click
+on the figure preview.
+
+The color encoding uses 24-bit RGB:
+- First 12 elements: hand-picked visually distinct colors
+- Elements 13+: HSV-based generation for deterministic uniqueness
+"""
+
+import io
+from typing import Any, Dict, Tuple
+
+from matplotlib.figure import Figure
+from PIL import Image
+
+
+def generate_hitmap(
+    fig: Figure,
+    dpi: int = 150,
+    include_text: bool = True,
+) -> Tuple[Image.Image, Dict[str, Any]]:
+    """
+    Generate hitmap with unique colors per element.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Figure to generate hitmap for.
+    dpi : int, optional
+        Resolution for hitmap rendering (default: 150).
+    include_text : bool, optional
+        Whether to include text elements like labels (default: True).
+
+    Returns
+    -------
+    hitmap : PIL.Image.Image
+        RGB image where each element has unique color.
+    color_map : dict
+        Mapping from element key to metadata:
+        {
+            'element_key': {
+                'id': int,
+                'type': str,  # 'line', 'scatter', 'bar', 'boxplot', 'violin', etc.
+                'label': str,
+                'ax_index': int,
+                'rgb': [r, g, b],
+            }
+        }
+    """
+    # Import from helper modules (inside function to avoid circular imports)
+    from ._hitmap._artists import (
+        process_collections,
+        process_figure_text,
+        process_images,
+        process_legend,
+        process_lines,
+        process_patches,
+        process_text,
+    )
+    from ._hitmap._colors import (
+        AXES_COLOR,
+        BACKGROUND_COLOR,
+        normalize_color,
+    )
+    from ._hitmap._detect import detect_plot_types
+    from ._hitmap._restore import (
+        restore_axes_properties,
+        restore_backgrounds,
+        restore_figure_text,
+    )
+
+    # Store original properties for restoration
+    original_props = {}
+    color_map = {}
+    element_id = 1
+
+    # Detect plot types from record
+    plot_types = detect_plot_types(fig)
+
+    # Get all axes (handle RecordingFigure wrapper)
+    if hasattr(fig, "fig"):
+        mpl_fig = fig.fig
+    else:
+        mpl_fig = fig
+    axes_list = mpl_fig.get_axes()
+
+    # Process all artists and assign colors
+    for ax_idx, ax in enumerate(axes_list):
+        ax_info = plot_types.get(ax_idx, {"types": set(), "call_ids": {}})
+
+        # Process lines
+        element_id = process_lines(
+            ax, ax_idx, element_id, original_props, color_map, ax_info
+        )
+
+        # Process collections (scatter, fills, etc.)
+        element_id = process_collections(
+            ax, ax_idx, element_id, original_props, color_map, ax_info
+        )
+
+        # Process patches (bars, wedges, polygons)
+        element_id = process_patches(
+            ax, ax_idx, element_id, original_props, color_map, ax_info
+        )
+
+        # Process images
+        element_id = process_images(ax, ax_idx, element_id, color_map, ax_info)
+
+        # Process text elements
+        if include_text:
+            element_id = process_text(ax, ax_idx, element_id, original_props, color_map)
+
+        # Process legend
+        element_id = process_legend(ax, ax_idx, element_id, original_props, color_map)
+
+    # Process figure-level text elements
+    if include_text:
+        element_id = process_figure_text(mpl_fig, element_id, original_props, color_map)
+
+    # Set non-selectable elements to axes color
+    for ax in axes_list:
+        for spine in ax.spines.values():
+            spine.set_color(normalize_color(AXES_COLOR))
+        ax.tick_params(colors=normalize_color(AXES_COLOR))
+
+    # Set figure background
+    fig.patch.set_facecolor(normalize_color(BACKGROUND_COLOR))
+    for ax in axes_list:
+        ax.set_facecolor(normalize_color(BACKGROUND_COLOR))
+
+    # Render to buffer
+    buf = io.BytesIO()
+    fig.savefig(
+        buf, format="png", dpi=dpi, facecolor=fig.get_facecolor(), bbox_inches="tight"
+    )
+    buf.seek(0)
+
+    # Load as PIL Image
+    hitmap = Image.open(buf).convert("RGB")
+
+    # Restore original properties
+    restore_axes_properties(axes_list, original_props, include_text)
+    restore_figure_text(mpl_fig, original_props, include_text)
+    restore_backgrounds(fig, axes_list)
+
+    return hitmap, color_map
+
+
+def hitmap_to_base64(hitmap: Image.Image) -> str:
+    """
+    Convert hitmap image to base64 string.
+
+    Parameters
+    ----------
+    hitmap : PIL.Image.Image
+        Hitmap image.
+
+    Returns
+    -------
+    str
+        Base64-encoded PNG string.
+    """
+    import base64
+
+    buf = io.BytesIO()
+    hitmap.save(buf, format="PNG")
+    buf.seek(0)
+    return base64.b64encode(buf.read()).decode("utf-8")
+
+
+__all__ = [
+    "generate_hitmap",
+    "hitmap_to_base64",
+]
+
+# EOF

figrecipe/_editor/_preferences.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""User preferences management for the figure editor.
+
+Preferences are stored in ~/.figrecipe/preferences.json and persist
+across sessions. This allows users to set defaults like dark mode.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+# Default preferences
+DEFAULT_PREFERENCES = {
+    "dark_mode": False,
+    "default_style": "SCITEX",
+    "auto_save": True,
+    "show_hit_regions": False,
+}
+
+# Preferences file location
+PREFERENCES_DIR = Path.home() / ".figrecipe"
+PREFERENCES_FILE = PREFERENCES_DIR / "preferences.json"
+
+
+def get_preferences_path() -> Path:
+    """Get the path to the preferences file."""
+    return PREFERENCES_FILE
+
+
+def load_preferences() -> Dict[str, Any]:
+    """Load user preferences from disk.
+
+    Returns
+    -------
+    dict
+        User preferences merged with defaults.
+    """
+    prefs = DEFAULT_PREFERENCES.copy()
+
+    if PREFERENCES_FILE.exists():
+        try:
+            with open(PREFERENCES_FILE, "r") as f:
+                saved = json.load(f)
+                prefs.update(saved)
+        except (json.JSONDecodeError, IOError):
+            # If file is corrupted, use defaults
+            pass
+
+    return prefs
+
+
+def save_preferences(prefs: Dict[str, Any]) -> bool:
+    """Save user preferences to disk.
+
+    Parameters
+    ----------
+    prefs : dict
+        Preferences to save.
+
+    Returns
+    -------
+    bool
+        True if save was successful.
+    """
+    try:
+        PREFERENCES_DIR.mkdir(parents=True, exist_ok=True)
+        with open(PREFERENCES_FILE, "w") as f:
+            json.dump(prefs, f, indent=2)
+        return True
+    except IOError:
+        return False
+
+
+def get_preference(key: str, default: Any = None) -> Any:
+    """Get a single preference value.
+
+    Parameters
+    ----------
+    key : str
+        Preference key.
+    default : Any, optional
+        Default value if key not found.
+
+    Returns
+    -------
+    Any
+        Preference value.
+    """
+    prefs = load_preferences()
+    return prefs.get(key, default)
+
+
+def set_preference(key: str, value: Any) -> bool:
+    """Set a single preference value.
+
+    Parameters
+    ----------
+    key : str
+        Preference key.
+    value : Any
+        Value to set.
+
+    Returns
+    -------
+    bool
+        True if save was successful.
+    """
+    prefs = load_preferences()
+    prefs[key] = value
+    return save_preferences(prefs)
+
+
+def reset_preferences() -> bool:
+    """Reset all preferences to defaults.
+
+    Returns
+    -------
+    bool
+        True if reset was successful.
+    """
+    return save_preferences(DEFAULT_PREFERENCES.copy())
+
+
+__all__ = [
+    "DEFAULT_PREFERENCES",
+    "get_preferences_path",
+    "load_preferences",
+    "save_preferences",
+    "get_preference",
+    "set_preference",
+    "reset_preferences",
+]
+
+# EOF