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

figrecipe/_editor/_overrides.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Style override management with separation of base and manual styles.
+
+This module handles the layered style system:
+1. Base style (from preset like SCITEX)
+2. Programmatic style (from code, e.g., fr.load_style())
+3. Manual overrides (from GUI editor)
+
+Manual overrides are stored separately with timestamps, allowing:
+- Restoration to original (programmatic) style
+- Tracking when manual edits were made
+- Comparison between original and edited versions
+"""
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class StyleOverrides:
+    """
+    Manages layered style overrides with timestamp tracking.
+
+    Attributes
+    ----------
+    base_style : dict
+        Original style from preset (e.g., SCITEX values).
+    programmatic_style : dict
+        Style set programmatically via code.
+    manual_overrides : dict
+        Overrides from GUI editor.
+    call_overrides : dict
+        Call parameter overrides {call_id: {param: value}}.
+    base_timestamp : str
+        When base style was set (ISO format).
+    manual_timestamp : str
+        When manual overrides were last modified.
+    """
+
+    base_style: Dict[str, Any] = field(default_factory=dict)
+    programmatic_style: Dict[str, Any] = field(default_factory=dict)
+    manual_overrides: Dict[str, Any] = field(default_factory=dict)
+    call_overrides: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    base_timestamp: Optional[str] = None
+    manual_timestamp: Optional[str] = None
+
+    def get_effective_style(self) -> Dict[str, Any]:
+        """
+        Get the final effective style by merging all layers.
+
+        Priority: base < programmatic < manual
+
+        Returns
+        -------
+        dict
+            Merged style dictionary.
+        """
+        result = {}
+        result.update(self.base_style)
+        result.update(self.programmatic_style)
+        result.update(self.manual_overrides)
+        return result
+
+    def get_original_style(self) -> Dict[str, Any]:
+        """
+        Get style without manual overrides (for "Restore" function).
+
+        Returns
+        -------
+        dict
+            Style with only base + programmatic layers.
+        """
+        result = {}
+        result.update(self.base_style)
+        result.update(self.programmatic_style)
+        return result
+
+    def set_manual_override(self, key: str, value: Any) -> None:
+        """
+        Set a single manual override.
+
+        Parameters
+        ----------
+        key : str
+            Style property key (e.g., 'axes_width_mm').
+        value : Any
+            Property value.
+        """
+        self.manual_overrides[key] = value
+        self.manual_timestamp = datetime.now().isoformat()
+
+    def update_manual_overrides(self, overrides: Dict[str, Any]) -> None:
+        """
+        Update multiple manual overrides at once.
+
+        Parameters
+        ----------
+        overrides : dict
+            Dictionary of overrides to apply.
+        """
+        self.manual_overrides.update(overrides)
+        self.manual_timestamp = datetime.now().isoformat()
+
+    def clear_manual_overrides(self, clear_call_overrides: bool = True) -> None:
+        """Clear all manual overrides (restore to original).
+
+        Parameters
+        ----------
+        clear_call_overrides : bool
+            Also clear call parameter overrides (default True).
+        """
+        self.manual_overrides = {}
+        if clear_call_overrides:
+            self.call_overrides = {}
+        self.manual_timestamp = None
+
+    def has_manual_overrides(self) -> bool:
+        """Check if any manual overrides exist."""
+        return len(self.manual_overrides) > 0
+
+    def get_diff(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Get differences between original and manual overrides.
+
+        Returns
+        -------
+        dict
+            Dictionary showing changes: {key: {'original': val, 'manual': val}}
+        """
+        original = self.get_original_style()
+        diff = {}
+
+        for key, manual_val in self.manual_overrides.items():
+            original_val = original.get(key)
+            if original_val != manual_val:
+                diff[key] = {
+                    "original": original_val,
+                    "manual": manual_val,
+                }
+
+        return diff
+
+    def set_call_override(self, call_id: str, param: str, value: Any) -> None:
+        """
+        Set a call parameter override.
+
+        Parameters
+        ----------
+        call_id : str
+            ID of the call (e.g., 'bp1', 'vp1').
+        param : str
+            Parameter name.
+        value : Any
+            Parameter value.
+        """
+        if call_id not in self.call_overrides:
+            self.call_overrides[call_id] = {}
+        self.call_overrides[call_id][param] = value
+        self.manual_timestamp = datetime.now().isoformat()
+
+    def get_call_overrides(self, call_id: str) -> Dict[str, Any]:
+        """Get all overrides for a specific call."""
+        return self.call_overrides.get(call_id, {})
+
+    def has_call_overrides(self) -> bool:
+        """Check if any call overrides exist."""
+        return len(self.call_overrides) > 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "base_style": self.base_style,
+            "programmatic_style": self.programmatic_style,
+            "manual_overrides": self.manual_overrides,
+            "call_overrides": self.call_overrides,
+            "base_timestamp": self.base_timestamp,
+            "manual_timestamp": self.manual_timestamp,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "StyleOverrides":
+        """Create from dictionary."""
+        return cls(
+            base_style=data.get("base_style", {}),
+            programmatic_style=data.get("programmatic_style", {}),
+            manual_overrides=data.get("manual_overrides", {}),
+            call_overrides=data.get("call_overrides", {}),
+            base_timestamp=data.get("base_timestamp"),
+            manual_timestamp=data.get("manual_timestamp"),
+        )
+
+
+def get_overrides_path(recipe_path: Path) -> Path:
+    """
+    Get the path for storing overrides alongside a recipe.
+
+    Parameters
+    ----------
+    recipe_path : Path
+        Path to the recipe file.
+
+    Returns
+    -------
+    Path
+        Path to the overrides file.
+
+    Examples
+    --------
+    >>> get_overrides_path(Path('figure.yaml'))
+    Path('figure.overrides.json')
+    """
+    return recipe_path.with_suffix(".overrides.json")
+
+
+def save_overrides(
+    overrides: StyleOverrides,
+    path: Path,
+) -> Path:
+    """
+    Save style overrides to JSON file.
+
+    Parameters
+    ----------
+    overrides : StyleOverrides
+        Overrides to save.
+    path : Path
+        Path to save to (or recipe path to derive from).
+
+    Returns
+    -------
+    Path
+        Path where overrides were saved.
+    """
+    # If path is a recipe, derive overrides path
+    if path.suffix in (".yaml", ".yml"):
+        path = get_overrides_path(path)
+
+    data = overrides.to_dict()
+    data["_version"] = "1.0"
+    data["_saved_at"] = datetime.now().isoformat()
+
+    with open(path, "w") as f:
+        json.dump(data, f, indent=2)
+
+    return path
+
+
+def load_overrides(path: Path) -> Optional[StyleOverrides]:
+    """
+    Load style overrides from JSON file.
+
+    Parameters
+    ----------
+    path : Path
+        Path to overrides file or recipe file.
+
+    Returns
+    -------
+    StyleOverrides or None
+        Loaded overrides, or None if file doesn't exist.
+    """
+    # If path is a recipe, derive overrides path
+    if path.suffix in (".yaml", ".yml"):
+        path = get_overrides_path(path)
+
+    if not path.exists():
+        return None
+
+    with open(path) as f:
+        data = json.load(f)
+
+    # Remove metadata
+    data.pop("_version", None)
+    data.pop("_saved_at", None)
+
+    return StyleOverrides.from_dict(data)
+
+
+def create_overrides_from_style(
+    base_style: Optional[Dict[str, Any]] = None,
+    programmatic_style: Optional[Dict[str, Any]] = None,
+) -> StyleOverrides:
+    """
+    Create StyleOverrides from existing style configuration.
+
+    Parameters
+    ----------
+    base_style : dict, optional
+        Base style from preset.
+    programmatic_style : dict, optional
+        Style set via code.
+
+    Returns
+    -------
+    StyleOverrides
+        New overrides object.
+    """
+    return StyleOverrides(
+        base_style=base_style or {},
+        programmatic_style=programmatic_style or {},
+        manual_overrides={},
+        base_timestamp=datetime.now().isoformat(),
+        manual_timestamp=None,
+    )
+
+
+__all__ = [
+    "StyleOverrides",
+    "get_overrides_path",
+    "save_overrides",
+    "load_overrides",
+    "create_overrides_from_style",
+]

figrecipe/_editor/_renderer.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Preview rendering with style overrides.
+
+This module renders figure previews with user-specified style overrides
+applied, enabling real-time preview updates in the GUI editor.
+"""
+
+import io
+from typing import Any, Dict, Optional, Tuple
+
+from matplotlib.figure import Figure
+
+from .._wrappers import RecordingFigure
+from ._bbox import extract_bboxes
+
+
+def render_preview(
+    fig: RecordingFigure,
+    overrides: Optional[Dict[str, Any]] = None,
+    dpi: int = 150,
+    dark_mode: bool = False,
+) -> Tuple[bytes, Dict[str, Any], Tuple[int, int]]:
+    """
+    Render figure preview with style overrides applied.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        Figure to render.
+    overrides : dict, optional
+        Style overrides to apply.
+    dpi : int, optional
+        Render resolution (default: 150).
+    dark_mode : bool, optional
+        Whether to render in dark mode (default: False).
+
+    Returns
+    -------
+    png_bytes : bytes
+        PNG image data.
+    bboxes : dict
+        Element bounding boxes.
+    img_size : tuple
+        (width, height) in pixels.
+    """
+    # Get underlying matplotlib figure
+    mpl_fig = fig.fig if hasattr(fig, "fig") else fig
+
+    # Apply style overrides
+    if overrides:
+        _apply_overrides(mpl_fig, overrides)
+
+    # Apply dark mode if requested
+    if dark_mode:
+        _apply_dark_mode(mpl_fig)
+
+    # Render to buffer first
+    buf = io.BytesIO()
+    mpl_fig.savefig(buf, format="png", dpi=dpi, bbox_inches="tight")
+    buf.seek(0)
+    png_bytes = buf.read()
+
+    # Get image dimensions
+    from PIL import Image
+
+    buf.seek(0)
+    img = Image.open(buf)
+    img_width, img_height = img.size
+
+    # Set figure DPI to match render DPI and force canvas redraw for accurate bbox extraction
+    original_dpi = mpl_fig.dpi
+    mpl_fig.set_dpi(dpi)
+    mpl_fig.canvas.draw()
+
+    # Extract bounding boxes (with figure DPI matching render DPI)
+    bboxes = extract_bboxes(mpl_fig, img_width, img_height)
+
+    # Restore original DPI
+    mpl_fig.set_dpi(original_dpi)
+
+    return png_bytes, bboxes, (img_width, img_height)
+
+
+def render_to_base64(
+    fig: RecordingFigure,
+    overrides: Optional[Dict[str, Any]] = None,
+    dpi: int = 150,
+    dark_mode: bool = False,
+) -> Tuple[str, Dict[str, Any], Tuple[int, int]]:
+    """
+    Render figure preview as base64 string.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        Figure to render.
+    overrides : dict, optional
+        Style overrides to apply.
+    dpi : int, optional
+        Render resolution (default: 150).
+    dark_mode : bool, optional
+        Whether to render in dark mode (default: False).
+
+    Returns
+    -------
+    base64_str : str
+        Base64-encoded PNG image.
+    bboxes : dict
+        Element bounding boxes.
+    img_size : tuple
+        (width, height) in pixels.
+    """
+    import base64
+
+    png_bytes, bboxes, img_size = render_preview(fig, overrides, dpi, dark_mode)
+    base64_str = base64.b64encode(png_bytes).decode("utf-8")
+
+    return base64_str, bboxes, img_size
+
+
+def _apply_overrides(fig: Figure, overrides: Dict[str, Any]) -> None:
+    """
+    Apply style overrides to figure.
+
+    Parameters
+    ----------
+    fig : Figure
+        Matplotlib figure.
+    overrides : dict
+        Style overrides with keys like:
+        - axes_width_mm, axes_height_mm
+        - fonts_axis_label_pt, fonts_tick_label_pt
+        - lines_trace_mm
+        - etc.
+    """
+    from ..styles._style_applier import apply_style_mm
+
+    axes_list = fig.get_axes()
+
+    for ax in axes_list:
+        # Apply mm-based styling
+        apply_style_mm(ax, overrides)
+
+        # Apply specific overrides that aren't handled by apply_style_mm
+        # YAML-compatible keys are canonical, legacy keys supported for backwards compatibility
+
+        # Font sizes (YAML: fonts_axis_label_pt, legacy: axis_font_size_pt)
+        axis_fs = overrides.get(
+            "fonts_axis_label_pt", overrides.get("axis_font_size_pt")
+        )
+        if axis_fs is not None:
+            ax.xaxis.label.set_fontsize(axis_fs)
+            ax.yaxis.label.set_fontsize(axis_fs)
+
+        tick_fs = overrides.get(
+            "fonts_tick_label_pt", overrides.get("tick_font_size_pt")
+        )
+        if tick_fs is not None:
+            ax.tick_params(labelsize=tick_fs)
+
+        title_fs = overrides.get("fonts_title_pt", overrides.get("title_font_size_pt"))
+        if title_fs is not None:
+            ax.title.set_fontsize(title_fs)
+
+        family = overrides.get("fonts_family", overrides.get("font_family"))
+        if family is not None:
+            ax.xaxis.label.set_fontfamily(family)
+            ax.yaxis.label.set_fontfamily(family)
+            ax.title.set_fontfamily(family)
+            for label in ax.get_xticklabels() + ax.get_yticklabels():
+                label.set_fontfamily(family)
+
+        # Ticks (YAML: ticks_direction, legacy: tick_direction)
+        tick_dir = overrides.get("ticks_direction", overrides.get("tick_direction"))
+        if tick_dir is not None and tick_dir in ("in", "out", "inout"):
+            ax.tick_params(direction=tick_dir)
+
+        tick_len = overrides.get("ticks_length_mm", overrides.get("tick_length_mm"))
+        if tick_len is not None:
+            from .._utils._units import mm_to_pt
+
+            length = mm_to_pt(tick_len)
+            ax.tick_params(length=length)
+
+        # Grid (YAML: behavior_grid, legacy: grid)
+        grid_value = overrides.get("behavior_grid", overrides.get("grid"))
+        if grid_value is not None:
+            if grid_value:
+                ax.grid(True, alpha=0.3)
+            else:
+                ax.grid(False)
+
+        # Spines (YAML: behavior_hide_top_spine, legacy: hide_top_spine)
+        hide_top = overrides.get(
+            "behavior_hide_top_spine", overrides.get("hide_top_spine")
+        )
+        if hide_top is not None:
+            ax.spines["top"].set_visible(not hide_top)
+
+        hide_right = overrides.get(
+            "behavior_hide_right_spine", overrides.get("hide_right_spine")
+        )
+        if hide_right is not None:
+            ax.spines["right"].set_visible(not hide_right)
+
+        # Legend
+        legend = ax.get_legend()
+        if legend is not None:
+            if "legend_frameon" in overrides:
+                legend.set_frame_on(overrides["legend_frameon"])
+
+            if "legend_alpha" in overrides:
+                frame = legend.get_frame()
+                fc = frame.get_facecolor()
+                frame.set_facecolor((*fc[:3], overrides["legend_alpha"]))
+
+        # Line widths (YAML: lines_trace_mm, legacy: trace_thickness_mm)
+        trace_mm = overrides.get("lines_trace_mm", overrides.get("trace_thickness_mm"))
+        if trace_mm is not None:
+            from .._utils._units import mm_to_pt
+
+            lw = mm_to_pt(trace_mm)
+            for line in ax.get_lines():
+                line.set_linewidth(lw)
+
+        # Marker sizes (YAML: markers_scatter_mm, legacy: marker_size_mm)
+        # Only apply to PathCollection (scatter), not PolyCollection (violin/fill)
+        scatter_mm = overrides.get(
+            "markers_scatter_mm",
+            overrides.get("markers_size_mm", overrides.get("marker_size_mm")),
+        )
+        if scatter_mm is not None:
+            from matplotlib.collections import PathCollection
+
+            from .._utils._units import mm_to_scatter_size
+
+            size = mm_to_scatter_size(scatter_mm)
+            for coll in ax.collections:
+                # Only apply to scatter plots (PathCollection), not violin/fill (PolyCollection)
+                if isinstance(coll, PathCollection):
+                    try:
+                        coll.set_sizes([size])
+                    except Exception:
+                        pass
+
+
+def _apply_dark_mode(fig: Figure) -> None:
+    """
+    Apply dark mode colors to figure.
+
+    Parameters
+    ----------
+    fig : Figure
+        Matplotlib figure.
+    """
+    # Dark theme colors
+    bg_color = "#1a1a1a"
+    text_color = "#e8e8e8"
+
+    # Figure background
+    fig.patch.set_facecolor(bg_color)
+
+    # Figure-level text elements (suptitle, supxlabel, supylabel)
+    if hasattr(fig, "_suptitle") and fig._suptitle is not None:
+        fig._suptitle.set_color(text_color)
+    if hasattr(fig, "_supxlabel") and fig._supxlabel is not None:
+        fig._supxlabel.set_color(text_color)
+    if hasattr(fig, "_supylabel") and fig._supylabel is not None:
+        fig._supylabel.set_color(text_color)
+
+    for ax in fig.get_axes():
+        # Axes background
+        ax.set_facecolor(bg_color)
+
+        # Text colors
+        ax.xaxis.label.set_color(text_color)
+        ax.yaxis.label.set_color(text_color)
+        ax.title.set_color(text_color)
+
+        # Tick labels
+        ax.tick_params(colors=text_color)
+
+        # Spines
+        for spine in ax.spines.values():
+            spine.set_color(text_color)
+
+        # Grid
+        ax.tick_params(color=text_color)
+
+        # Legend
+        legend = ax.get_legend()
+        if legend is not None:
+            frame = legend.get_frame()
+            frame.set_facecolor(bg_color)
+            frame.set_edgecolor(text_color)
+            for text in legend.get_texts():
+                text.set_color(text_color)
+
+
+def render_download(
+    fig: RecordingFigure,
+    fmt: str = "png",
+    dpi: int = 300,
+    overrides: Optional[Dict[str, Any]] = None,
+    dark_mode: bool = False,
+) -> bytes:
+    """
+    Render figure for download in specified format.
+
+    Parameters
+    ----------
+    fig : RecordingFigure
+        Figure to render.
+    fmt : str
+        Output format: 'png', 'svg', 'pdf' (default: 'png').
+    dpi : int
+        Resolution for raster formats (default: 300).
+    overrides : dict, optional
+        Style overrides to apply.
+    dark_mode : bool, optional
+        Whether to render in dark mode.
+
+    Returns
+    -------
+    bytes
+        File content.
+    """
+    mpl_fig = fig.fig if hasattr(fig, "fig") else fig
+
+    if overrides:
+        _apply_overrides(mpl_fig, overrides)
+
+    if dark_mode:
+        _apply_dark_mode(mpl_fig)
+
+    buf = io.BytesIO()
+    mpl_fig.savefig(buf, format=fmt, dpi=dpi, bbox_inches="tight")
+    buf.seek(0)
+
+    return buf.read()
+
+
+__all__ = [
+    "render_preview",
+    "render_to_base64",
+    "render_download",
+]