scitex 2.1.2__py3-none-any.whl → 2.4.2__py3-none-any.whl

scitex/plt/utils/_crop.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Time-stamp: "2025-11-19 15:30:00 (ywatanabe)"
+# File: ./src/scitex/plt/utils/_crop.py
+
+"""
+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 small margin.
+"""
+
+import os
+import numpy as np
+from typing import Optional, Tuple
+from PIL import Image
+
+
+def find_content_area(image_path: str) -> Tuple[int, int, int, int]:
+    """
+    Find the bounding box of the content area in an image.
+
+    Parameters
+    ----------
+    image_path : str
+        Path to the image file
+
+    Returns
+    -------
+    tuple
+        (left, upper, right, lower) bounding box coordinates
+
+    Raises
+    ------
+    FileNotFoundError
+        If the image cannot be read
+    """
+    # Read the image with PIL
+    img = Image.open(image_path)
+
+    # Convert to numpy array for processing
+    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]
+        # Find non-transparent pixels
+        rows = np.any(alpha > 0, axis=1)
+        cols = np.any(alpha > 0, axis=0)
+    else:
+        # For RGB images, detect background color from corners and find non-background pixels
+        if len(img_array.shape) == 3:
+            # Sample background color from corners (more robust than assuming white)
+            h, w = img_array.shape[:2]
+            corners = [
+                img_array[0, 0],           # top-left
+                img_array[0, w-1],         # top-right
+                img_array[h-1, 0],         # bottom-left
+                img_array[h-1, w-1],       # bottom-right
+            ]
+            # Use median of corners as background color (robust to one corner having content)
+            bg_color = np.median(corners, axis=0).astype(np.uint8)
+
+            # Find pixels that differ significantly from background (threshold: 10 per channel)
+            diff = np.abs(img_array.astype(np.int16) - bg_color.astype(np.int16))
+            is_content = np.any(diff > 10, axis=2)
+        else:
+            # Grayscale: detect background from corners
+            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)
+
+    # Find the bounding box
+    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:
+        # If no content found, return the whole image
+        return 0, 0, img.width, img.height
+
+
+def crop(
+    input_path: str,
+    output_path: Optional[str] = None,
+    margin: int = 12,
+    overwrite: bool = False,
+    verbose: bool = False,
+) -> str:
+    """
+    Crop a figure image to its content area with a specified margin.
+
+    This function is designed for publication-ready figures created with
+    large margins. It automatically detects the content and crops to it,
+    leaving a small margin around the content.
+
+    Parameters
+    ----------
+    input_path : str
+        Path to the input image (PNG, TIFF, etc.)
+    output_path : str, optional
+        Path to save the cropped image. If None and overwrite=True,
+        overwrites the input. If None and overwrite=False, adds '_cropped' suffix.
+    margin : int, optional
+        Margin in pixels to add around the content area (default: 12, ~1mm at 300 DPI)
+    overwrite : bool, optional
+        Whether to overwrite the input file (default: False)
+    verbose : bool, optional
+        Whether to print detailed information (default: False)
+
+    Returns
+    -------
+    str
+        Path to the saved cropped image
+
+    Raises
+    ------
+    FileNotFoundError
+        If the input image cannot be read
+
+    Examples
+    --------
+    >>> import scitex as stx
+    >>> fig, ax = stx.plt.subplots(**stx.plt.presets.SCITEX_STYLE)
+    >>> ax.plot([1, 2, 3], [1, 2, 3])
+    >>> stx.io.save(fig, "figure.png", dpi=300, transparent=True)
+    >>> stx.plt.crop("figure.png", "figure_cropped.png")  # 1mm margin (12px at 300 DPI)
+
+    >>> # Or crop in place
+    >>> stx.plt.crop("figure.png", overwrite=True)
+    """
+    # Determine output path
+    if output_path is None:
+        if overwrite:
+            output_path = input_path
+        else:
+            # Add '_cropped' suffix before extension
+            base, ext = os.path.splitext(input_path)
+            output_path = f"{base}_cropped{ext}"
+
+    # Read the image with PIL (preserves alpha channel and DPI metadata)
+    img = Image.open(input_path)
+
+    original_width, original_height = img.size
+
+    if verbose:
+        print(f"Original image dimensions: {original_width}x{original_height}")
+        if 'dpi' in img.info:
+            print(f"Original DPI: {img.info['dpi']}")
+
+    # Find the content area (returns left, upper, right, lower)
+    left, upper, right, lower = find_content_area(input_path)
+
+    if verbose:
+        print(f"Content area detected at: left={left}, upper={upper}, right={right}, lower={lower}")
+
+    # Calculate the coordinates with margin, clamping to the 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={left}, upper={upper}, right={right}, lower={lower}")
+        print(f"New dimensions: {right-left}x{lower-upper}")
+
+    # Crop the image using PIL (lossless operation)
+    cropped_img = img.crop((left, upper, right, lower))
+
+    # Preserve DPI metadata and save with maximum quality
+    save_kwargs = {}
+
+    # Preserve DPI if it exists
+    if 'dpi' in img.info:
+        save_kwargs['dpi'] = img.info['dpi']
+
+    ext = os.path.splitext(output_path)[1].lower()
+    if ext in ['.png']:
+        # PNG: lossless compression, preserve all metadata including text chunks
+        save_kwargs['compress_level'] = 0  # No compression for maximum quality and speed
+        save_kwargs['optimize'] = False
+
+        # Preserve PNG text chunks (tEXt, zTXt, iTXt) where scitex metadata is stored
+        from PIL import PngImagePlugin
+        pnginfo = PngImagePlugin.PngInfo()
+
+        # Copy all text chunks from original image
+        for key, value in img.info.items():
+            if isinstance(value, (str, bytes)):
+                try:
+                    pnginfo.add_text(key, value)
+                except Exception:
+                    pass  # Skip if can't add this chunk
+
+        save_kwargs['pnginfo'] = pnginfo
+    elif ext in ['.jpg', '.jpeg']:
+        # JPEG: maximum quality for daily use (quality=100, no compression artifacts)
+        save_kwargs['quality'] = 100
+        save_kwargs['subsampling'] = 0  # No chroma subsampling (best quality)
+        save_kwargs['optimize'] = False
+
+        # Preserve EXIF metadata where scitex metadata is stored
+        try:
+            import piexif
+
+            # Try to load existing EXIF data
+            if 'exif' in img.info:
+                # piexif.load() reads the EXIF bytes
+                exif_dict = piexif.load(img.info['exif'])
+                # Re-dump to bytes for saving
+                exif_bytes = piexif.dump(exif_dict)
+                save_kwargs['exif'] = exif_bytes
+        except ImportError:
+            # piexif not available, try PIL's built-in EXIF
+            if hasattr(img, 'getexif'):
+                exif = img.getexif()
+                if exif:
+                    save_kwargs['exif'] = exif
+        except Exception:
+            # If EXIF reading fails, continue without it
+            pass
+
+    # Save the cropped image
+    cropped_img.save(output_path, **save_kwargs)
+
+    # Calculate space saved
+    final_width, final_height = cropped_img.size
+    area_reduction = 1 - ((final_width * final_height) / (original_width * original_height))
+    area_reduction_pct = area_reduction * 100
+
+    if verbose:
+        print(f"Image processed: {input_path}")
+        print(f"Size changed from {original_width}x{original_height} to {final_width}x{final_height}")
+        print(f"Saved {area_reduction_pct:.1f}% of the original area")
+        if output_path != input_path:
+            print(f"Saved to: {output_path}")
+
+    return output_path
+
+
+# EOF

scitex/plt/utils/_dimension_viewer.py

@@ -0,0 +1,437 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-11-19 12:30:00 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/plt/utils/_dimension_viewer.py
+
+"""
+Visual dimension viewer/debugger for matplotlib figures.
+
+This tool helps you understand and debug the relationship between:
+- Millimeters (mm)
+- Inches
+- Pixels (px)
+- DPI (dots per inch)
+- Figure size vs Axes size
+
+Very useful when you're confused about dimensions!
+"""
+
+__FILE__ = __file__
+
+import matplotlib.patches as mpatches
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+def view_dimensions(
+    fig, ax, show_rulers=True, show_grid=True, output_path=None
+):
+    """
+    Create a visual representation of figure/axes dimensions.
+
+    This creates a separate diagnostic figure showing:
+    - The figure canvas (gray)
+    - The axes box (white with border)
+    - Dimension annotations
+    - Rulers with mm/pixel markings
+    - Grid overlay
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Figure to analyze
+    ax : matplotlib.axes.Axes
+        Axes to analyze
+    show_rulers : bool, optional
+        Show rulers with mm/pixel markings (default: True)
+    show_grid : bool, optional
+        Show grid overlay (default: True)
+    output_path : str, optional
+        If provided, save the diagnostic figure to this path
+
+    Returns
+    -------
+    fig_diag : matplotlib.figure.Figure
+        The diagnostic figure showing dimensions
+
+    Examples
+    --------
+    >>> from scitex.plt.utils import create_axes_with_size_mm, view_dimensions
+    >>> fig, ax = create_axes_with_size_mm(30, 21, mode='publication')
+    >>> ax.plot([0, 1], [0, 1])
+    >>> fig_diag = view_dimensions(fig, ax, output_path='/tmp/dimensions.png')
+    >>> plt.show()
+    """
+    from ._figure_from_axes_mm import get_dimension_info
+
+    # Get dimension info
+    info = get_dimension_info(fig, ax)
+
+    # Create diagnostic figure (larger for visibility)
+    fig_diag = plt.figure(figsize=(10, 8), facecolor="white")
+    ax_diag = fig_diag.add_subplot(111)
+
+    # Get dimensions
+    fig_w_mm, fig_h_mm = info["figure_size_mm"]
+    axes_w_mm, axes_h_mm = info["axes_size_mm"]
+    axes_pos = info["axes_position"]
+    dpi = info["dpi"]
+
+    # Calculate margins in mm
+    margin_left_mm = axes_pos[0] * fig_w_mm
+    margin_bottom_mm = axes_pos[1] * fig_h_mm
+    margin_right_mm = fig_w_mm - (margin_left_mm + axes_w_mm)
+    margin_top_mm = fig_h_mm - (margin_bottom_mm + axes_h_mm)
+
+    # Draw figure canvas (gray rectangle)
+    fig_rect = mpatches.Rectangle(
+        (0, 0),
+        fig_w_mm,
+        fig_h_mm,
+        linewidth=2,
+        edgecolor="black",
+        facecolor="lightgray",
+        alpha=0.3,
+        label="Figure canvas",
+    )
+    ax_diag.add_patch(fig_rect)
+
+    # Draw axes box (white rectangle)
+    axes_rect = mpatches.Rectangle(
+        (margin_left_mm, margin_bottom_mm),
+        axes_w_mm,
+        axes_h_mm,
+        linewidth=3,
+        edgecolor="blue",
+        facecolor="white",
+        alpha=0.8,
+        label="Axes box",
+    )
+    ax_diag.add_patch(axes_rect)
+
+    # Annotate dimensions
+    # Figure dimensions
+    ax_diag.annotate(
+        "",
+        xy=(fig_w_mm, -3),
+        xytext=(0, -3),
+        arrowprops=dict(arrowstyle="<->", color="black", lw=1.5),
+    )
+    ax_diag.text(
+        fig_w_mm / 2,
+        -5,
+        f"Figure: {fig_w_mm:.1f} mm\n({info['figure_size_px'][0]} px @ {dpi} DPI)",
+        ha="center",
+        va="top",
+        fontsize=10,
+        bbox=dict(boxstyle="round", facecolor="white", alpha=0.8),
+    )
+
+    ax_diag.annotate(
+        "",
+        xy=(-3, fig_h_mm),
+        xytext=(-3, 0),
+        arrowprops=dict(arrowstyle="<->", color="black", lw=1.5),
+    )
+    ax_diag.text(
+        -5,
+        fig_h_mm / 2,
+        f"Figure: {fig_h_mm:.1f} mm\n({info['figure_size_px'][1]} px)",
+        ha="right",
+        va="center",
+        fontsize=10,
+        rotation=90,
+        bbox=dict(boxstyle="round", facecolor="white", alpha=0.8),
+    )
+
+    # Axes dimensions
+    axes_center_x = margin_left_mm + axes_w_mm / 2
+    axes_center_y = margin_bottom_mm + axes_h_mm / 2
+
+    ax_diag.annotate(
+        "",
+        xy=(margin_left_mm + axes_w_mm, axes_center_y),
+        xytext=(margin_left_mm, axes_center_y),
+        arrowprops=dict(arrowstyle="<->", color="blue", lw=2),
+    )
+    ax_diag.text(
+        axes_center_x,
+        axes_center_y + 1,
+        f"Axes: {axes_w_mm:.1f} mm\n({info['axes_size_px'][0]} px)",
+        ha="center",
+        va="bottom",
+        fontsize=11,
+        fontweight="bold",
+        color="blue",
+        bbox=dict(boxstyle="round", facecolor="white", alpha=0.9),
+    )
+
+    ax_diag.annotate(
+        "",
+        xy=(axes_center_x, margin_bottom_mm + axes_h_mm),
+        xytext=(axes_center_x, margin_bottom_mm),
+        arrowprops=dict(arrowstyle="<->", color="blue", lw=2),
+    )
+    ax_diag.text(
+        axes_center_x + 1,
+        axes_center_y,
+        f"Axes: {axes_h_mm:.1f} mm\n({info['axes_size_px'][1]} px)",
+        ha="left",
+        va="center",
+        fontsize=11,
+        fontweight="bold",
+        color="blue",
+        rotation=90,
+        bbox=dict(boxstyle="round", facecolor="white", alpha=0.9),
+    )
+
+    # Margin annotations
+    # Left margin
+    if margin_left_mm > 1:
+        ax_diag.text(
+            margin_left_mm / 2,
+            margin_bottom_mm + axes_h_mm / 2,
+            f"L: {margin_left_mm:.1f}",
+            ha="center",
+            va="center",
+            fontsize=9,
+            color="gray",
+        )
+
+    # Right margin
+    if margin_right_mm > 1:
+        ax_diag.text(
+            margin_left_mm + axes_w_mm + margin_right_mm / 2,
+            margin_bottom_mm + axes_h_mm / 2,
+            f"R: {margin_right_mm:.1f}",
+            ha="center",
+            va="center",
+            fontsize=9,
+            color="gray",
+        )
+
+    # Bottom margin
+    if margin_bottom_mm > 1:
+        ax_diag.text(
+            margin_left_mm + axes_w_mm / 2,
+            margin_bottom_mm / 2,
+            f"B: {margin_bottom_mm:.1f}",
+            ha="center",
+            va="center",
+            fontsize=9,
+            color="gray",
+        )
+
+    # Top margin
+    if margin_top_mm > 1:
+        ax_diag.text(
+            margin_left_mm + axes_w_mm / 2,
+            margin_bottom_mm + axes_h_mm + margin_top_mm / 2,
+            f"T: {margin_top_mm:.1f}",
+            ha="center",
+            va="center",
+            fontsize=9,
+            color="gray",
+        )
+
+    # Rulers
+    if show_rulers:
+        # Horizontal ruler (bottom)
+        ruler_y = -10
+        for mm in range(0, int(fig_w_mm) + 1, 5):
+            ax_diag.plot([mm, mm], [ruler_y, ruler_y - 1], "k-", lw=0.5)
+            if mm % 10 == 0:
+                ax_diag.plot([mm, mm], [ruler_y, ruler_y - 2], "k-", lw=1)
+                ax_diag.text(
+                    mm, ruler_y - 3, f"{mm}", ha="center", fontsize=8
+                )
+
+        # Vertical ruler (left)
+        ruler_x = -10
+        for mm in range(0, int(fig_h_mm) + 1, 5):
+            ax_diag.plot([ruler_x, ruler_x - 1], [mm, mm], "k-", lw=0.5)
+            if mm % 10 == 0:
+                ax_diag.plot([ruler_x, ruler_x - 2], [mm, mm], "k-", lw=1)
+                ax_diag.text(
+                    ruler_x - 3, mm, f"{mm}", ha="right", fontsize=8
+                )
+
+    # Grid
+    if show_grid:
+        # 5mm grid
+        for mm in range(0, int(fig_w_mm) + 1, 5):
+            ax_diag.axvline(mm, color="lightgray", lw=0.5, alpha=0.5)
+        for mm in range(0, int(fig_h_mm) + 1, 5):
+            ax_diag.axhline(mm, color="lightgray", lw=0.5, alpha=0.5)
+
+    # Set limits and aspect
+    margin_extra = 15
+    ax_diag.set_xlim(-margin_extra, fig_w_mm + 5)
+    ax_diag.set_ylim(-margin_extra, fig_h_mm + 5)
+    ax_diag.set_aspect("equal")
+
+    # Labels
+    ax_diag.set_xlabel("Width (mm)", fontsize=12)
+    ax_diag.set_ylabel("Height (mm)", fontsize=12)
+
+    # Title
+    title = f"Dimension Viewer\n"
+    title += f"Figure: {fig_w_mm:.1f}×{fig_h_mm:.1f} mm ({info['figure_size_px'][0]}×{info['figure_size_px'][1]} px)\n"
+    title += f"Axes: {axes_w_mm:.1f}×{axes_h_mm:.1f} mm ({info['axes_size_px'][0]}×{info['axes_size_px'][1]} px) @ {dpi} DPI"
+    ax_diag.set_title(title, fontsize=12, fontweight="bold", pad=20)
+
+    # Legend
+    ax_diag.legend(loc="upper right", fontsize=10)
+
+    plt.tight_layout()
+
+    # Save if path provided
+    if output_path:
+        fig_diag.savefig(output_path, dpi=150, bbox_inches="tight")
+        print(f"✅ Dimension viewer saved to: {output_path}")
+
+    return fig_diag
+
+
+def compare_modes(
+    axes_width_mm=30, axes_height_mm=21, output_path=None
+):
+    """
+    Compare publication vs display modes side-by-side.
+
+    Creates a comparison figure showing the same axes in both modes.
+
+    Parameters
+    ----------
+    axes_width_mm : float, optional
+        Axes width in mm (default: 30)
+    axes_height_mm : float, optional
+        Axes height in mm (default: 21)
+    output_path : str, optional
+        If provided, save comparison to this path
+
+    Returns
+    -------
+    fig_comp : matplotlib.figure.Figure
+        Comparison figure
+
+    Examples
+    --------
+    >>> from scitex.plt.utils import compare_modes
+    >>> fig = compare_modes(30, 21, output_path='/tmp/mode_comparison.png')
+    >>> plt.show()
+    """
+    from ._figure_from_axes_mm import (
+        create_axes_with_size_mm,
+        print_dimension_info,
+    )
+
+    # Create publication mode
+    print("\n📐 PUBLICATION MODE:")
+    print("-" * 60)
+    fig_pub, ax_pub = create_axes_with_size_mm(
+        axes_width_mm=axes_width_mm,
+        axes_height_mm=axes_height_mm,
+        mode="publication",
+    )
+    x = np.linspace(0, 2 * np.pi, 100)
+    ax_pub.plot(x, np.sin(x), "b-", lw=1)
+    ax_pub.set_title("Publication Mode", fontsize=8)
+    ax_pub.set_xlabel("X", fontsize=7)
+    ax_pub.set_ylabel("Y", fontsize=7)
+    print_dimension_info(fig_pub, ax_pub)
+
+    # Create display mode
+    print("\n🖥️  DISPLAY MODE:")
+    print("-" * 60)
+    fig_disp, ax_disp = create_axes_with_size_mm(
+        axes_width_mm=axes_width_mm,
+        axes_height_mm=axes_height_mm,
+        mode="display",
+    )
+    ax_disp.plot(x, np.sin(x), "b-", lw=1)
+    ax_disp.set_title("Display Mode (3x scaled)", fontsize=8)
+    ax_disp.set_xlabel("X", fontsize=7)
+    ax_disp.set_ylabel("Y", fontsize=7)
+    print_dimension_info(fig_disp, ax_disp)
+
+    # Create comparison figure
+    fig_comp = plt.figure(figsize=(12, 5))
+
+    # Publication mode view
+    ax1 = fig_comp.add_subplot(121)
+    view_pub = view_dimensions(fig_pub, ax_pub, show_rulers=False)
+    ax1.set_title(
+        f"Publication Mode\n{axes_width_mm}×{axes_height_mm} mm @ 300 DPI",
+        fontweight="bold",
+    )
+
+    # Display mode view
+    ax2 = fig_comp.add_subplot(122)
+    view_disp = view_dimensions(fig_disp, ax_disp, show_rulers=False)
+    ax2.set_title(
+        f"Display Mode\n{axes_width_mm*3}×{axes_height_mm*3} mm @ 100 DPI (3x scaled)",
+        fontweight="bold",
+    )
+
+    plt.suptitle(
+        "Mode Comparison: Publication vs Display", fontsize=14, y=0.98
+    )
+    plt.tight_layout()
+
+    # Close original figures
+    plt.close(fig_pub)
+    plt.close(fig_disp)
+    plt.close(view_pub)
+    plt.close(view_disp)
+
+    # Save if path provided
+    if output_path:
+        fig_comp.savefig(output_path, dpi=150, bbox_inches="tight")
+        print(f"\n✅ Mode comparison saved to: {output_path}")
+
+    return fig_comp
+
+
+if __name__ == "__main__":
+    from ._figure_from_axes_mm import create_axes_with_size_mm
+
+    print("=" * 60)
+    print("DIMENSION VIEWER DEMO")
+    print("=" * 60)
+
+    # Create a figure
+    print("\n1. Creating a 30×21 mm axes (publication mode)")
+    fig, ax = create_axes_with_size_mm(
+        axes_width_mm=30,
+        axes_height_mm=21,
+        mode="publication",
+        style_mm={
+            "axis_thickness_mm": 0.2,
+            "tick_length_mm": 0.8,
+        },
+    )
+
+    # Plot something
+    x = np.linspace(0, 2 * np.pi, 100)
+    ax.plot(x, np.sin(x), "b-", lw=1)
+    ax.set_xlabel("X axis")
+    ax.set_ylabel("Y axis")
+    ax.set_title("Sample Plot")
+
+    # View dimensions
+    print("\n2. Viewing dimensions")
+    fig_diag = view_dimensions(
+        fig, ax, output_path="/tmp/dimension_viewer_demo.png"
+    )
+
+    # Compare modes
+    print("\n3. Comparing publication vs display modes")
+    fig_comp = compare_modes(30, 21, output_path="/tmp/mode_comparison.png")
+
+    print("\n✅ Demo complete!")
+    print("Check /tmp/dimension_viewer_demo.png and /tmp/mode_comparison.png")
+
+    plt.show()
+
+# EOF