figrecipe 0.5.0__py3-none-any.whl

figrecipe/_serializer.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Serialization for recipe files (YAML + data files)."""
+
+from pathlib import Path
+from typing import Any, Dict, Literal, Optional, Union
+
+import numpy as np
+from ruamel.yaml import YAML
+
+from ._recorder import FigureRecord
+from ._utils._numpy_io import save_array, load_array, DataFormat
+
+
+def _convert_numpy_types(obj: Any) -> Any:
+    """Recursively convert numpy types to Python native types.
+
+    Parameters
+    ----------
+    obj : Any
+        Object to convert.
+
+    Returns
+    -------
+    Any
+        Object with numpy types converted to native Python types.
+    """
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    elif isinstance(obj, np.integer):
+        return int(obj)
+    elif isinstance(obj, np.floating):
+        return float(obj)
+    elif isinstance(obj, np.bool_):
+        return bool(obj)
+    elif isinstance(obj, dict):
+        return {k: _convert_numpy_types(v) for k, v in obj.items()}
+    elif isinstance(obj, (list, tuple)):
+        converted = [_convert_numpy_types(item) for item in obj]
+        return type(obj)(converted) if isinstance(obj, tuple) else converted
+    else:
+        return obj
+
+
+def save_recipe(
+    record: FigureRecord,
+    path: Union[str, Path],
+    include_data: bool = True,
+    data_format: DataFormat = "csv",
+) -> Path:
+    """Save a figure record to YAML file.
+
+    Parameters
+    ----------
+    record : FigureRecord
+        The figure record to save.
+    path : str or Path
+        Output path (.yaml).
+    include_data : bool
+        If True, save large arrays to separate files.
+    data_format : str
+        Format for data files: 'csv' (default), 'npz', or 'inline'.
+        - 'csv': Human-readable CSV files with dtype header
+        - 'npz': Compressed numpy binary format
+        - 'inline': Store all data directly in YAML (may be large)
+
+    Returns
+    -------
+    Path
+        Path to saved YAML file.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Create data directory for large arrays
+    data_dir = path.parent / f"{path.stem}_data"
+
+    # Convert record to dict
+    data = record.to_dict()
+
+    # Process arrays: save large ones to files, update references
+    if include_data and data_format != "inline":
+        data = _process_arrays_for_save(data, data_dir, record.id, data_format)
+
+    # Convert numpy types to native Python types
+    data = _convert_numpy_types(data)
+
+    # Save YAML
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    yaml.indent(mapping=2, sequence=4, offset=2)
+
+    with open(path, "w") as f:
+        yaml.dump(data, f)
+
+    return path
+
+
+def _process_arrays_for_save(
+    data: Dict[str, Any],
+    data_dir: Path,
+    fig_id: str,
+    data_format: DataFormat = "csv",
+) -> Dict[str, Any]:
+    """Process arrays in data dict, saving large ones to files.
+
+    Parameters
+    ----------
+    data : dict
+        Data dictionary to process.
+    data_dir : Path
+        Directory for array files.
+    fig_id : str
+        Figure ID for naming files.
+    data_format : str
+        Format for data files: 'csv', 'npz', or 'inline'.
+
+    Returns
+    -------
+    dict
+        Processed data with file references.
+    """
+    data_dir_created = False
+
+    for ax_key, ax_data in data.get("axes", {}).items():
+        for call_list in [ax_data.get("calls", []), ax_data.get("decorations", [])]:
+            for call in call_list:
+                call_id = call.get("id", "unknown")
+
+                # Process args
+                for i, arg in enumerate(call.get("args", [])):
+                    if "_array" in arg:
+                        # Large array - save to file
+                        if not data_dir_created:
+                            data_dir.mkdir(parents=True, exist_ok=True)
+                            data_dir_created = True
+
+                        arr = arg.pop("_array")
+                        filename = f"{call_id}_{arg.get('name', f'arg{i}')}"
+                        file_path = save_array(arr, data_dir / filename, data_format)
+                        arg["data"] = str(file_path.relative_to(data_dir.parent))
+
+    return data
+
+
+def load_recipe(path: Union[str, Path]) -> FigureRecord:
+    """Load a figure record from YAML file.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .yaml recipe file.
+
+    Returns
+    -------
+    FigureRecord
+        Loaded figure record.
+    """
+    path = Path(path)
+
+    yaml = YAML()
+    with open(path) as f:
+        data = yaml.load(f)
+
+    # Resolve data file references
+    data = _resolve_data_references(data, path.parent)
+
+    return FigureRecord.from_dict(data)
+
+
+def _resolve_data_references(
+    data: Dict[str, Any],
+    base_dir: Path,
+) -> Dict[str, Any]:
+    """Resolve file references to actual array data.
+
+    Parameters
+    ----------
+    data : dict
+        Data dictionary with file references.
+    base_dir : Path
+        Base directory for resolving relative paths.
+
+    Returns
+    -------
+    dict
+        Data with arrays loaded.
+    """
+    for ax_key, ax_data in data.get("axes", {}).items():
+        for call_list in [ax_data.get("calls", []), ax_data.get("decorations", [])]:
+            for call in call_list:
+                for arg in call.get("args", []):
+                    data_ref = arg.get("data")
+
+                    # Check if it's a file reference
+                    if isinstance(data_ref, str) and (
+                        data_ref.endswith(".npy")
+                        or data_ref.endswith(".npz")
+                        or data_ref.endswith(".csv")
+                    ):
+                        file_path = base_dir / data_ref
+                        if file_path.exists():
+                            arr = load_array(file_path)
+                            arg["data"] = arr.tolist()
+                            arg["_loaded_array"] = arr
+
+    return data
+
+
+def recipe_to_dict(path: Union[str, Path]) -> Dict[str, Any]:
+    """Load recipe as raw dictionary (for inspection).
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .yaml recipe file.
+
+    Returns
+    -------
+    dict
+        Raw recipe data.
+    """
+    path = Path(path)
+
+    yaml = YAML()
+    with open(path) as f:
+        return dict(yaml.load(f))

figrecipe/_signatures/__init__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Matplotlib function signatures for validation and defaults."""
+
+from ._loader import get_signature, get_defaults, validate_kwargs
+
+__all__ = ["get_signature", "get_defaults", "validate_kwargs"]

figrecipe/_signatures/_loader.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Load and query matplotlib function signatures."""
+
+import inspect
+from typing import Any, Dict, List, Optional, Set
+
+import matplotlib.pyplot as plt
+
+
+# Cache for signatures
+_SIGNATURE_CACHE: Dict[str, Dict[str, Any]] = {}
+
+
+def get_signature(method_name: str) -> Dict[str, Any]:
+    """Get signature for a matplotlib Axes method.
+
+    Parameters
+    ----------
+    method_name : str
+        Name of the method (e.g., 'plot', 'scatter').
+
+    Returns
+    -------
+    dict
+        Signature information with 'args' and 'kwargs' keys.
+    """
+    if method_name in _SIGNATURE_CACHE:
+        return _SIGNATURE_CACHE[method_name]
+
+    # Create a temporary axes to introspect
+    fig, ax = plt.subplots()
+    plt.close(fig)
+
+    method = getattr(ax, method_name, None)
+    if method is None:
+        return {"args": [], "kwargs": {}}
+
+    try:
+        sig = inspect.signature(method)
+    except (ValueError, TypeError):
+        return {"args": [], "kwargs": {}}
+
+    args = []
+    kwargs = {}
+
+    for name, param in sig.parameters.items():
+        if name == "self":
+            continue
+
+        if param.kind == inspect.Parameter.VAR_POSITIONAL:
+            args.append({"name": f"*{name}", "type": "*args"})
+        elif param.kind == inspect.Parameter.VAR_KEYWORD:
+            kwargs["**kwargs"] = {"type": "**kwargs"}
+        elif param.default is inspect.Parameter.empty:
+            # Positional argument
+            args.append({
+                "name": name,
+                "type": _get_type_str(param.annotation),
+            })
+        else:
+            # Keyword argument with default
+            kwargs[name] = {
+                "type": _get_type_str(param.annotation),
+                "default": _serialize_default(param.default),
+            }
+
+    result = {"args": args, "kwargs": kwargs}
+    _SIGNATURE_CACHE[method_name] = result
+    return result
+
+
+def _get_type_str(annotation) -> Optional[str]:
+    """Convert annotation to string."""
+    if annotation is inspect.Parameter.empty:
+        return None
+    if hasattr(annotation, "__name__"):
+        return annotation.__name__
+    return str(annotation)
+
+
+def _serialize_default(default) -> Any:
+    """Serialize default value."""
+    if default is inspect.Parameter.empty:
+        return None
+    if callable(default):
+        return f"<{type(default).__name__}>"
+    try:
+        import json
+        json.dumps(default)
+        return default
+    except (TypeError, ValueError):
+        return repr(default)
+
+
+def get_defaults(method_name: str) -> Dict[str, Any]:
+    """Get default values for a method's kwargs.
+
+    Parameters
+    ----------
+    method_name : str
+        Name of the method.
+
+    Returns
+    -------
+    dict
+        Mapping of kwarg names to default values.
+    """
+    sig = get_signature(method_name)
+    defaults = {}
+
+    for name, info in sig.get("kwargs", {}).items():
+        if name != "**kwargs" and "default" in info:
+            defaults[name] = info["default"]
+
+    return defaults
+
+
+def validate_kwargs(
+    method_name: str,
+    kwargs: Dict[str, Any],
+) -> Dict[str, List[str]]:
+    """Validate kwargs against method signature.
+
+    Parameters
+    ----------
+    method_name : str
+        Name of the method.
+    kwargs : dict
+        Kwargs to validate.
+
+    Returns
+    -------
+    dict
+        Validation result with 'valid', 'unknown', and 'missing' keys.
+    """
+    sig = get_signature(method_name)
+    known_kwargs = set(sig.get("kwargs", {}).keys()) - {"**kwargs"}
+
+    # If method accepts **kwargs, all are valid
+    if "**kwargs" in sig.get("kwargs", {}):
+        return {
+            "valid": list(kwargs.keys()),
+            "unknown": [],
+            "missing": [],
+        }
+
+    valid = []
+    unknown = []
+
+    for key in kwargs:
+        if key in known_kwargs:
+            valid.append(key)
+        else:
+            unknown.append(key)
+
+    return {
+        "valid": valid,
+        "unknown": unknown,
+        "missing": [],  # Not checking required kwargs for now
+    }
+
+
+def list_plotting_methods() -> List[str]:
+    """List all available plotting methods.
+
+    Returns
+    -------
+    list
+        Names of plotting methods.
+    """
+    fig, ax = plt.subplots()
+    plt.close(fig)
+
+    # Common plotting methods
+    methods = [
+        "plot", "scatter", "bar", "barh", "hist", "hist2d",
+        "boxplot", "violinplot", "pie", "errorbar", "fill",
+        "fill_between", "fill_betweenx", "stackplot", "stem",
+        "step", "imshow", "pcolor", "pcolormesh", "contour",
+        "contourf", "quiver", "barbs", "streamplot", "hexbin",
+        "eventplot", "stairs", "ecdf",
+    ]
+
+    # Filter to only those that exist
+    return [m for m in methods if hasattr(ax, m)]

figrecipe/_utils/__init__.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Utility modules for figrecipe."""
+
+from ._numpy_io import load_array, save_array
+from ._diff import get_non_default_kwargs, is_default_value
+from ._units import mm_to_inch, inch_to_mm, mm_to_pt, pt_to_mm
+
+__all__ = [
+    "save_array",
+    "load_array",
+    "get_non_default_kwargs",
+    "is_default_value",
+    "mm_to_inch",
+    "inch_to_mm",
+    "mm_to_pt",
+    "pt_to_mm",
+]
+
+# Optional: image comparison (requires PIL)
+try:
+    from ._image_diff import compare_images, create_comparison_figure
+    __all__.extend(["compare_images", "create_comparison_figure"])
+except ImportError:
+    pass
+
+# Optional: crop utility (requires PIL)
+try:
+    from ._crop import crop, find_content_area
+    __all__.extend(["crop", "find_content_area"])
+except ImportError:
+    pass

figrecipe/_utils/_crop.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Auto-crop figures to content area with optional margin.
+
+This utility automatically detects the content area of saved figures
+and crops them, removing excess whitespace while preserving a specified margin.
+"""
+
+__all__ = ["crop", "find_content_area", "mm_to_pixels"]
+
+import os
+from pathlib import Path
+from typing import Optional, Tuple, Union
+
+import numpy as np
+
+
+def find_content_area(image_path: Union[str, Path]) -> Tuple[int, int, int, int]:
+    """Find the bounding box of the content area in an image.
+
+    Parameters
+    ----------
+    image_path : str or Path
+        Path to the image file
+
+    Returns
+    -------
+    tuple
+        (left, upper, right, lower) bounding box coordinates
+
+    Raises
+    ------
+    FileNotFoundError
+        If the image cannot be read
+    """
+    from PIL import Image
+
+    img = Image.open(image_path)
+    img_array = np.array(img)
+
+    # Check if image has alpha channel (RGBA)
+    if len(img_array.shape) == 3 and img_array.shape[2] == 4:
+        # Use alpha channel to find content (non-transparent pixels)
+        alpha = img_array[:, :, 3]
+        rows = np.any(alpha > 0, axis=1)
+        cols = np.any(alpha > 0, axis=0)
+    else:
+        # For RGB images, detect background color from corners
+        if len(img_array.shape) == 3:
+            h, w = img_array.shape[:2]
+            corners = [
+                img_array[0, 0],
+                img_array[0, w - 1],
+                img_array[h - 1, 0],
+                img_array[h - 1, w - 1],
+            ]
+            bg_color = np.median(corners, axis=0).astype(np.uint8)
+            diff = np.abs(img_array.astype(np.int16) - bg_color.astype(np.int16))
+            is_content = np.any(diff > 10, axis=2)
+        else:
+            # Grayscale
+            h, w = img_array.shape
+            corners = [
+                img_array[0, 0],
+                img_array[0, w - 1],
+                img_array[h - 1, 0],
+                img_array[h - 1, w - 1],
+            ]
+            bg_value = np.median(corners)
+            is_content = np.abs(img_array.astype(np.int16) - bg_value) > 10
+
+        rows = np.any(is_content, axis=1)
+        cols = np.any(is_content, axis=0)
+
+    if np.any(rows) and np.any(cols):
+        y_min, y_max = np.where(rows)[0][[0, -1]]
+        x_min, x_max = np.where(cols)[0][[0, -1]]
+        return x_min, y_min, x_max + 1, y_max + 1
+    else:
+        return 0, 0, img.width, img.height
+
+
+def mm_to_pixels(mm: float, dpi: int = 300) -> int:
+    """Convert millimeters to pixels at given DPI.
+
+    Parameters
+    ----------
+    mm : float
+        Size in millimeters
+    dpi : int
+        Resolution in dots per inch (default: 300)
+
+    Returns
+    -------
+    int
+        Size in pixels (rounded)
+    """
+    return round(mm * dpi / 25.4)
+
+
+def crop(
+    input_path: Union[str, Path],
+    output_path: Optional[Union[str, Path]] = None,
+    margin_mm: float = 1.0,
+    margin_px: Optional[int] = None,
+    overwrite: bool = False,
+    verbose: bool = False,
+    return_offset: bool = False,
+    crop_box: Optional[Tuple[int, int, int, int]] = None,
+) -> Union[Path, Tuple[Path, dict]]:
+    """Crop a figure image to its content area with a specified margin.
+
+    Automatically detects background color (from corners) and crops to
+    content, leaving only the specified margin around it.
+
+    Parameters
+    ----------
+    input_path : str or Path
+        Path to the input image (PNG, JPEG, etc.)
+    output_path : str or Path, optional
+        Path to save the cropped image. If None and overwrite=True,
+        overwrites the input. If None and overwrite=False, adds '_cropped' suffix.
+    margin_mm : float, optional
+        Margin in millimeters to keep around content (default: 1.0mm).
+        Converted to pixels using image DPI (or 300 DPI if not available).
+    margin_px : int, optional
+        Margin in pixels (overrides margin_mm if provided).
+    overwrite : bool, optional
+        Whether to overwrite the input file (default: False)
+    verbose : bool, optional
+        Whether to print detailed information (default: False)
+    return_offset : bool, optional
+        If True, also return the crop offset for metadata adjustment.
+    crop_box : tuple, optional
+        Explicit crop coordinates (left, upper, right, lower). If provided,
+        skips auto-detection and uses these exact coordinates.
+
+    Returns
+    -------
+    Path or tuple
+        Path to the saved cropped image. If return_offset=True, returns
+        (path, offset_dict) with crop boundaries.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fig, ax = fr.subplots(axes_width_mm=60, axes_height_mm=40)
+    >>> ax.plot([1, 2, 3], [1, 2, 3], id='line')
+    >>> fig.savefig("figure.png", dpi=300)
+    >>> fr.crop("figure.png", overwrite=True)  # 1mm margin
+    >>> fr.crop("figure.png", margin_mm=2.0)   # 2mm margin
+    >>> fr.crop("figure.png", margin_px=24)    # explicit 24 pixels
+    """
+    from PIL import Image
+
+    input_path = Path(input_path)
+
+    # Determine output path
+    if output_path is None:
+        if overwrite:
+            output_path = input_path
+        else:
+            output_path = input_path.with_stem(f"{input_path.stem}_cropped")
+    else:
+        output_path = Path(output_path)
+
+    img = Image.open(input_path)
+    original_width, original_height = img.size
+
+    # Get DPI from image metadata (default to 300 if not available)
+    dpi = 300
+    if "dpi" in img.info:
+        dpi_info = img.info["dpi"]
+        if isinstance(dpi_info, tuple):
+            dpi = int(dpi_info[0])  # Use horizontal DPI
+        else:
+            dpi = int(dpi_info)
+
+    # Calculate margin in pixels
+    if margin_px is not None:
+        margin = margin_px
+    else:
+        margin = mm_to_pixels(margin_mm, dpi)
+
+    if verbose:
+        print(f"Original: {original_width}x{original_height}")
+        print(f"DPI: {dpi}")
+        print(f"Margin: {margin_mm}mm = {margin}px")
+
+    # Use explicit crop_box or auto-detect
+    if crop_box is not None:
+        left, upper, right, lower = crop_box
+        if verbose:
+            print(f"Using explicit crop_box: {crop_box}")
+    else:
+        left, upper, right, lower = find_content_area(input_path)
+        if verbose:
+            print(f"Content area: left={left}, upper={upper}, right={right}, lower={lower}")
+
+        # Add margin, clamping to image boundaries
+        left = max(left - margin, 0)
+        upper = max(upper - margin, 0)
+        right = min(right + margin, img.width)
+        lower = min(lower + margin, img.height)
+
+    if verbose:
+        print(f"Cropping to: {left},{upper} -> {right},{lower}")
+        print(f"New size: {right - left}x{lower - upper}")
+
+    # Crop the image
+    cropped_img = img.crop((left, upper, right, lower))
+
+    # Preserve metadata
+    save_kwargs = {}
+    if "dpi" in img.info:
+        save_kwargs["dpi"] = img.info["dpi"]
+
+    ext = output_path.suffix.lower()
+    if ext == ".png":
+        save_kwargs["compress_level"] = 0
+        save_kwargs["optimize"] = False
+
+        # Preserve PNG text chunks
+        from PIL import PngImagePlugin
+        pnginfo = PngImagePlugin.PngInfo()
+        for key, value in img.info.items():
+            if isinstance(value, (str, bytes)):
+                try:
+                    pnginfo.add_text(key, str(value) if isinstance(value, bytes) else value)
+                except Exception:
+                    pass
+        save_kwargs["pnginfo"] = pnginfo
+
+    elif ext in [".jpg", ".jpeg"]:
+        save_kwargs["quality"] = 100
+        save_kwargs["subsampling"] = 0
+        save_kwargs["optimize"] = False
+
+    cropped_img.save(output_path, **save_kwargs)
+
+    final_width, final_height = cropped_img.size
+    if verbose:
+        area_reduction = 1 - ((final_width * final_height) / (original_width * original_height))
+        print(f"Saved {area_reduction * 100:.1f}% of original area")
+        if output_path != input_path:
+            print(f"Saved to: {output_path}")
+
+    if return_offset:
+        offset = {
+            "left": left,
+            "upper": upper,
+            "right": right,
+            "lower": lower,
+            "original_width": original_width,
+            "original_height": original_height,
+            "new_width": final_width,
+            "new_height": final_height,
+        }
+        return output_path, offset
+
+    return output_path