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

figrecipe/_api/_style_manager.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Style management API for figrecipe.
+
+Provides style loading, unloading, and application functions.
+"""
+
+__all__ = [
+    "load_style",
+    "unload_style",
+    "list_presets",
+    "apply_style",
+    "STYLE",
+]
+
+
+def load_style(style="SCITEX", dark=False):
+    """Load style configuration and apply it globally.
+
+    After calling this function, subsequent `subplots()` calls will
+    automatically use the loaded style (fonts, colors, theme, etc.).
+
+    Parameters
+    ----------
+    style : str, Path, bool, or None
+        One of:
+        - "SCITEX" / "FIGRECIPE": Scientific publication style (default)
+        - "MATPLOTLIB": Vanilla matplotlib defaults
+        - Path to custom YAML file: "/path/to/my_style.yaml"
+        - None or False: Unload style (reset to matplotlib defaults)
+    dark : bool, optional
+        If True, apply dark theme transformation (default: False).
+        Equivalent to appending "_DARK" to preset name.
+
+    Returns
+    -------
+    DotDict or None
+        Style configuration with dot-notation access.
+        Returns None if style is unloaded.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+
+    >>> # Load scientific style (default)
+    >>> fr.load_style()
+    >>> fr.load_style("SCITEX")  # explicit
+
+    >>> # Load dark theme
+    >>> fr.load_style("SCITEX_DARK")
+    >>> fr.load_style("SCITEX", dark=True)  # equivalent
+
+    >>> # Reset to vanilla matplotlib
+    >>> fr.load_style(None)    # unload
+    >>> fr.load_style(False)   # unload
+    >>> fr.load_style("MATPLOTLIB")  # explicit vanilla
+
+    >>> # Access style values
+    >>> style = fr.load_style("SCITEX")
+    >>> style.axes.width_mm
+    40
+    """
+    from ..styles import load_style as _load_style
+
+    return _load_style(style, dark=dark)
+
+
+def unload_style():
+    """Unload the current style and reset to matplotlib defaults.
+
+    After calling this, subsequent `subplots()` calls will use vanilla
+    matplotlib behavior without FigRecipe styling.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fr.load_style("SCITEX")  # Apply scientific style
+    >>> fig, ax = fr.subplots()  # Styled
+    >>> fr.unload_style()        # Reset to matplotlib defaults
+    >>> fig, ax = fr.subplots()  # Vanilla matplotlib
+    """
+    from ..styles import unload_style as _unload_style
+
+    _unload_style()
+
+
+def list_presets():
+    """List available style presets.
+
+    Returns
+    -------
+    list of str
+        Names of available presets.
+
+    Examples
+    --------
+    >>> import figrecipe as ps
+    >>> ps.list_presets()
+    ['MINIMAL', 'PRESENTATION', 'SCIENTIFIC']
+    """
+    from ..styles import list_presets as _list_presets
+
+    return _list_presets()
+
+
+def apply_style(ax, style=None):
+    """Apply mm-based styling to an axes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes to apply styling to.
+    style : dict or DotDict, optional
+        Style configuration. If None, uses default FIGRECIPE_STYLE.
+
+    Returns
+    -------
+    float
+        Trace line width in points.
+
+    Examples
+    --------
+    >>> import figrecipe as ps
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> trace_lw = ps.apply_style(ax)
+    >>> ax.plot(x, y, lw=trace_lw)
+    """
+    from ..styles import apply_style_mm, get_style, to_subplots_kwargs
+
+    if style is None:
+        style = to_subplots_kwargs(get_style())
+    elif hasattr(style, "to_subplots_kwargs"):
+        style = style.to_subplots_kwargs()
+    return apply_style_mm(ax, style)
+
+
+class _StyleProxy:
+    """Proxy object for lazy style loading."""
+
+    def __getattr__(self, name):
+        from ..styles import STYLE
+
+        return getattr(STYLE, name)
+
+    def to_subplots_kwargs(self):
+        from ..styles import to_subplots_kwargs
+
+        return to_subplots_kwargs()
+
+
+# Create style proxy
+STYLE = _StyleProxy()

figrecipe/_api/_subplots.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Subplots helper implementation for the public API."""
+
+from typing import Any, Dict, Optional, Tuple, Union
+
+from numpy.typing import NDArray
+
+from .._utils._units import mm_to_inch
+from .._wrappers import RecordingAxes, RecordingFigure
+
+
+def _get_mm_value(explicit, global_style, style_path, default):
+    """Get mm value with priority: explicit > global style > default."""
+    if explicit is not None:
+        return explicit
+    if global_style is not None:
+        try:
+            val = global_style
+            for key in style_path:
+                val = val.get(key) if isinstance(val, dict) else getattr(val, key, None)
+                if val is None:
+                    break
+            if val is not None:
+                return val
+        except (KeyError, AttributeError):
+            pass
+    return default
+
+
+def _check_mm_layout(
+    axes_width_mm,
+    axes_height_mm,
+    margin_left_mm,
+    margin_right_mm,
+    margin_bottom_mm,
+    margin_top_mm,
+    space_w_mm,
+    space_h_mm,
+    global_style,
+):
+    """Check if mm-based layout is requested."""
+    has_explicit_mm = any(
+        [
+            axes_width_mm is not None,
+            axes_height_mm is not None,
+            margin_left_mm is not None,
+            margin_right_mm is not None,
+            margin_bottom_mm is not None,
+            margin_top_mm is not None,
+            space_w_mm is not None,
+            space_h_mm is not None,
+        ]
+    )
+
+    has_style_mm = False
+    if global_style is not None:
+        try:
+            has_style_mm = (
+                global_style.get("axes", {}).get("width_mm") is not None
+                or getattr(getattr(global_style, "axes", None), "width_mm", None)
+                is not None
+            )
+        except (KeyError, AttributeError):
+            pass
+
+    return has_explicit_mm or has_style_mm
+
+
+def _calculate_mm_layout(
+    nrows: int,
+    ncols: int,
+    axes_width_mm: Optional[float],
+    axes_height_mm: Optional[float],
+    margin_left_mm: Optional[float],
+    margin_right_mm: Optional[float],
+    margin_bottom_mm: Optional[float],
+    margin_top_mm: Optional[float],
+    space_w_mm: Optional[float],
+    space_h_mm: Optional[float],
+    global_style,
+    kwargs: Dict[str, Any],
+) -> Tuple[Optional[Dict[str, float]], Dict[str, Any]]:
+    """Calculate mm-based layout and update kwargs with figsize."""
+    aw = _get_mm_value(axes_width_mm, global_style, ["axes", "width_mm"], 40)
+    ah = _get_mm_value(axes_height_mm, global_style, ["axes", "height_mm"], 28)
+    ml = _get_mm_value(margin_left_mm, global_style, ["margins", "left_mm"], 15)
+    mr = _get_mm_value(margin_right_mm, global_style, ["margins", "right_mm"], 5)
+    mb = _get_mm_value(margin_bottom_mm, global_style, ["margins", "bottom_mm"], 12)
+    mt = _get_mm_value(margin_top_mm, global_style, ["margins", "top_mm"], 8)
+    sw = _get_mm_value(space_w_mm, global_style, ["spacing", "horizontal_mm"], 8)
+    sh = _get_mm_value(space_h_mm, global_style, ["spacing", "vertical_mm"], 10)
+
+    # Calculate total figure size
+    total_width_mm = ml + (ncols * aw) + ((ncols - 1) * sw) + mr
+    total_height_mm = mb + (nrows * ah) + ((nrows - 1) * sh) + mt
+
+    # Convert to inches and set figsize
+    kwargs["figsize"] = (mm_to_inch(total_width_mm), mm_to_inch(total_height_mm))
+
+    mm_layout = {
+        "axes_width_mm": aw,
+        "axes_height_mm": ah,
+        "margin_left_mm": ml,
+        "margin_right_mm": mr,
+        "margin_bottom_mm": mb,
+        "margin_top_mm": mt,
+        "space_w_mm": sw,
+        "space_h_mm": sh,
+    }
+
+    return mm_layout, kwargs
+
+
+def _apply_mm_layout_to_figure(
+    fig: RecordingFigure,
+    mm_layout: Dict[str, float],
+    nrows: int,
+    ncols: int,
+):
+    """Apply mm-based layout adjustments to figure."""
+    ml = mm_layout["margin_left_mm"]
+    mr = mm_layout["margin_right_mm"]
+    mb = mm_layout["margin_bottom_mm"]
+    mt = mm_layout["margin_top_mm"]
+    aw = mm_layout["axes_width_mm"]
+    ah = mm_layout["axes_height_mm"]
+    sw = mm_layout["space_w_mm"]
+    sh = mm_layout["space_h_mm"]
+
+    total_width_mm = ml + (ncols * aw) + ((ncols - 1) * sw) + mr
+    total_height_mm = mb + (nrows * ah) + ((nrows - 1) * sh) + mt
+
+    # Calculate relative positions (0-1 range)
+    left = ml / total_width_mm
+    right = 1 - (mr / total_width_mm)
+    bottom = mb / total_height_mm
+    top = 1 - (mt / total_height_mm)
+
+    # Calculate spacing as fraction of figure size
+    wspace = sw / aw if ncols > 1 else 0
+    hspace = sh / ah if nrows > 1 else 0
+
+    fig.fig.subplots_adjust(
+        left=left,
+        right=right,
+        bottom=bottom,
+        top=top,
+        wspace=wspace,
+        hspace=hspace,
+    )
+
+    # Record layout in figure record for reproduction
+    fig.record.layout = {
+        "left": left,
+        "right": right,
+        "bottom": bottom,
+        "top": top,
+        "wspace": wspace,
+        "hspace": hspace,
+    }
+
+
+def _apply_style_to_axes(
+    fig: RecordingFigure,
+    axes: Union[RecordingAxes, NDArray],
+    nrows: int,
+    ncols: int,
+    style: Optional[Dict[str, Any]],
+    apply_style_mm: bool,
+    global_style,
+) -> Optional[Dict[str, Any]]:
+    """Apply style to axes and return style dict if applied."""
+    import numpy as np
+
+    from ..styles import apply_style_mm as _apply_style
+    from ..styles import to_subplots_kwargs
+
+    style_dict = None
+    should_apply_style = False
+
+    if style is not None:
+        should_apply_style = True
+        style_dict = (
+            style.to_subplots_kwargs()
+            if hasattr(style, "to_subplots_kwargs")
+            else style
+        )
+    elif apply_style_mm and global_style is not None:
+        style_dict = to_subplots_kwargs(global_style)
+        if style_dict and style_dict.get("axes_thickness_mm") is not None:
+            should_apply_style = True
+
+    if should_apply_style and style_dict:
+        if nrows == 1 and ncols == 1:
+            _apply_style(axes._ax, style_dict)
+        else:
+            axes_array = np.array(axes)
+            for ax in axes_array.flat:
+                _apply_style(ax._ax if hasattr(ax, "_ax") else ax, style_dict)
+
+        fig.record.style = style_dict
+
+    return style_dict
+
+
+def create_subplots(
+    nrows: int = 1,
+    ncols: int = 1,
+    axes_width_mm: Optional[float] = None,
+    axes_height_mm: Optional[float] = None,
+    margin_left_mm: Optional[float] = None,
+    margin_right_mm: Optional[float] = None,
+    margin_bottom_mm: Optional[float] = None,
+    margin_top_mm: Optional[float] = None,
+    space_w_mm: Optional[float] = None,
+    space_h_mm: Optional[float] = None,
+    style: Optional[Dict[str, Any]] = None,
+    apply_style_mm: bool = True,
+    panel_labels: Optional[bool] = None,
+    **kwargs,
+) -> Tuple[RecordingFigure, Union[RecordingAxes, NDArray]]:
+    """Core subplots implementation."""
+    from .._wrappers._figure import create_recording_subplots
+    from ..styles._style_loader import _STYLE_CACHE, to_subplots_kwargs
+
+    global_style = _STYLE_CACHE
+
+    # Check if mm-based layout is requested
+    use_mm_layout = _check_mm_layout(
+        axes_width_mm,
+        axes_height_mm,
+        margin_left_mm,
+        margin_right_mm,
+        margin_bottom_mm,
+        margin_top_mm,
+        space_w_mm,
+        space_h_mm,
+        global_style,
+    )
+
+    if use_mm_layout and "figsize" not in kwargs:
+        mm_layout, kwargs = _calculate_mm_layout(
+            nrows,
+            ncols,
+            axes_width_mm,
+            axes_height_mm,
+            margin_left_mm,
+            margin_right_mm,
+            margin_bottom_mm,
+            margin_top_mm,
+            space_w_mm,
+            space_h_mm,
+            global_style,
+            kwargs,
+        )
+    else:
+        mm_layout = None
+
+    # Apply DPI from global style if not explicitly provided
+    if "dpi" not in kwargs and global_style is not None:
+        style_dpi = None
+        try:
+            if hasattr(global_style, "figure") and hasattr(global_style.figure, "dpi"):
+                style_dpi = global_style.figure.dpi
+            elif hasattr(global_style, "output") and hasattr(
+                global_style.output, "dpi"
+            ):
+                style_dpi = global_style.output.dpi
+        except (KeyError, AttributeError):
+            pass
+        if style_dpi is not None:
+            kwargs["dpi"] = style_dpi
+
+    # Handle style parameter
+    if style is not None:
+        if hasattr(style, "to_subplots_kwargs"):
+            style_kwargs = style.to_subplots_kwargs()
+            for key, value in style_kwargs.items():
+                if key not in kwargs:
+                    kwargs[key] = value
+
+    # Check if style specifies constrained_layout
+    style_constrained = False
+    if global_style is not None:
+        style_dict_check = to_subplots_kwargs(global_style)
+        style_constrained = style_dict_check.get("constrained_layout", False)
+
+    # Use constrained_layout if: style specifies it, or non-mm layout
+    if "constrained_layout" not in kwargs:
+        if style_constrained:
+            kwargs["constrained_layout"] = True
+        elif not use_mm_layout:
+            kwargs["constrained_layout"] = True
+
+    # Create the recording subplots
+    fig, axes = create_recording_subplots(nrows, ncols, **kwargs)
+
+    # Record constrained_layout setting for reproduction
+    fig.record.constrained_layout = kwargs.get("constrained_layout", False)
+
+    # Store mm_layout metadata on figure for serialization
+    use_constrained = kwargs.get("constrained_layout", False)
+    if mm_layout is not None and not use_constrained:
+        fig._mm_layout = mm_layout
+        _apply_mm_layout_to_figure(fig, mm_layout, nrows, ncols)
+
+    # Apply styling using helper
+    _apply_style_to_axes(fig, axes, nrows, ncols, style, apply_style_mm, global_style)
+
+    # Determine panel_labels setting
+    use_panel_labels = panel_labels
+    if use_panel_labels is None and global_style is not None:
+        behavior = global_style.get("behavior", {})
+        use_panel_labels = behavior.get("panel_labels", False)
+
+    # Add panel labels if enabled (for multi-panel figures)
+    if use_panel_labels and (nrows > 1 or ncols > 1):
+        fig.add_panel_labels()
+
+    return fig, axes
+
+
+__all__ = [
+    "_get_mm_value",
+    "_check_mm_layout",
+    "_calculate_mm_layout",
+    "_apply_mm_layout_to_figure",
+    "_apply_style_to_axes",
+    "create_subplots",
+]
+
+# EOF

figrecipe/_api/_validate.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Standalone validation implementation."""
+
+import tempfile
+from pathlib import Path
+from typing import Union
+
+import numpy as np
+
+from .._reproducer import reproduce
+from .._utils._image_diff import compare_images
+from .._validator import ValidationResult
+
+
+def validate_recipe(
+    path: Union[str, Path],
+    mse_threshold: float = 100.0,
+) -> ValidationResult:
+    """Validate that a saved recipe can reproduce its original figure.
+
+    For standalone validation, we reproduce twice and compare
+    (This validates the recipe is self-consistent).
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .yaml recipe file.
+    mse_threshold : float
+        Maximum acceptable MSE for validation to pass (default: 100).
+
+    Returns
+    -------
+    ValidationResult
+        Detailed comparison results.
+    """
+    path = Path(path)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+
+        # Reproduce twice
+        fig1, _ = reproduce(path)
+        img1_path = tmpdir / "render1.png"
+        fig1.savefig(img1_path, dpi=150)
+
+        fig2, _ = reproduce(path)
+        img2_path = tmpdir / "render2.png"
+        fig2.savefig(img2_path, dpi=150)
+
+        # Compare
+        diff = compare_images(img1_path, img2_path)
+
+        mse = diff["mse"]
+        if np.isnan(mse):
+            valid = False
+            message = f"Image dimensions differ: {diff['size1']} vs {diff['size2']}"
+        elif mse > mse_threshold:
+            valid = False
+            message = f"MSE ({mse:.2f}) exceeds threshold ({mse_threshold})"
+        else:
+            valid = True
+            message = "Recipe produces consistent output"
+
+        return ValidationResult(
+            valid=valid,
+            mse=mse if not np.isnan(mse) else float("inf"),
+            psnr=diff["psnr"],
+            max_diff=diff["max_diff"]
+            if not np.isnan(diff["max_diff"])
+            else float("inf"),
+            size_original=diff["size1"],
+            size_reproduced=diff["size2"],
+            same_size=diff["same_size"],
+            file_size_diff=diff["file_size2"] - diff["file_size1"],
+            message=message,
+        )
+
+
+__all__ = ["validate_recipe"]
+
+# EOF

figrecipe/_cli/__init__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""figrecipe CLI - Command-line interface for figrecipe."""
+
+from ._main import main
+
+__all__ = ["main"]

figrecipe/_cli/_compose.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""compose command - Combine multiple figures."""
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+import click
+
+
+@click.command()
+@click.argument("sources", nargs=-1, type=click.Path(exists=True), required=True)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(),
+    required=True,
+    help="Output path for composed figure.",
+)
+@click.option(
+    "--layout",
+    type=click.Choice(["horizontal", "vertical", "grid"]),
+    default="horizontal",
+    help="Layout arrangement (default: horizontal).",
+)
+@click.option(
+    "--cols",
+    type=int,
+    help="Number of columns for grid layout.",
+)
+@click.option(
+    "--dpi",
+    type=int,
+    default=300,
+    help="DPI for output (default: 300).",
+)
+def compose(
+    sources: Tuple[str, ...],
+    output: str,
+    layout: str,
+    cols: Optional[int],
+    dpi: int,
+) -> None:
+    """Compose multiple figures into one.
+
+    SOURCES are paths to .yaml recipe files or bundle directories.
+    """
+    from .. import compose as fr_compose
+    from .. import reproduce, save
+
+    if len(sources) < 2:
+        raise click.ClickException("At least 2 source figures required.")
+
+    source_paths = [Path(s) for s in sources]
+    output_path = Path(output)
+
+    # Determine grid dimensions
+    n = len(sources)
+    if layout == "horizontal":
+        nrows, ncols = 1, n
+    elif layout == "vertical":
+        nrows, ncols = n, 1
+    else:  # grid
+        if cols:
+            ncols = cols
+            nrows = (n + cols - 1) // cols
+        else:
+            # Auto-determine roughly square grid
+            import math
+
+            ncols = math.ceil(math.sqrt(n))
+            nrows = math.ceil(n / ncols)
+
+    # Reproduce and compose figures
+    try:
+        figures = []
+        for src in source_paths:
+            fig, _ = reproduce(src)
+            figures.append(fig)
+
+        composed = fr_compose(*figures, nrows=nrows, ncols=ncols)
+        save(composed, output_path, dpi=dpi)
+
+        click.echo(f"Composed {len(figures)} figures: {output_path}")
+
+    except Exception as e:
+        raise click.ClickException(f"Composition failed: {e}") from e