scitex 2.5.0__py3-none-any.whl → 2.7.3__py3-none-any.whl

scitex/plt/utils/metadata/_dimensions.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_dimensions.py
+
+"""
+Dimension extraction utilities for axes and figure metadata.
+
+This module provides functions to extract size, position, and bounding box
+information from matplotlib figures and axes in multiple units (mm, inch, px).
+"""
+
+from typing import Dict
+
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_axes_dimensions(fig, ax, ax_index: int) -> dict:
+    """
+    Extract dimension information for a single axes.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The parent figure
+    ax : matplotlib.axes.Axes
+        The axes to extract dimensions from
+    ax_index : int
+        Index of this axes in the figure (for position tracking)
+
+    Returns
+    -------
+    dict
+        Dimension metadata containing:
+        - size_mm, size_inch, size_px
+        - bounds_figure_fraction
+        - position_in_grid
+        - margins_mm, margins_inch
+        - bbox_mm, bbox_inch, bbox_px
+    """
+    ax_metadata = {}
+
+    try:
+        from .._figure_from_axes_mm import get_dimension_info
+
+        dim_info = get_dimension_info(fig, ax)
+
+        # Size in multiple units
+        ax_metadata["size_mm"] = dim_info.get("axes_size_mm", [])
+        if "axes_size_inch" in dim_info:
+            ax_metadata["size_inch"] = dim_info["axes_size_inch"]
+        if "axes_size_px" in dim_info:
+            ax_metadata["size_px"] = dim_info["axes_size_px"]
+
+        # Position in figure coordinates (normalized 0-1 values)
+        # Uses matplotlib terminology: bounds_figure_fraction
+        if "axes_position" in dim_info:
+            ax_metadata["bounds_figure_fraction"] = list(dim_info["axes_position"])
+
+        # Position in grid (row, col)
+        if hasattr(ax, "_scitex_metadata") and "position_in_grid" in ax._scitex_metadata:
+            ax_metadata["position_in_grid"] = ax._scitex_metadata["position_in_grid"]
+        else:
+            # Calculate from ax_index if we have grid info
+            ax_metadata["position_in_grid"] = [ax_index, 0]  # Default single column
+
+        # Margins in mm and inch
+        if "margins_mm" in dim_info:
+            ax_metadata["margins_mm"] = dim_info["margins_mm"]
+        if "margins_inch" in dim_info:
+            ax_metadata["margins_inch"] = dim_info["margins_inch"]
+
+        # Bounding box with intuitive keys
+        if "axes_bbox_px" in dim_info:
+            bbox = dim_info["axes_bbox_px"]
+            ax_metadata["bbox_px"] = _normalize_bbox(bbox)
+        if "axes_bbox_mm" in dim_info:
+            bbox = dim_info["axes_bbox_mm"]
+            ax_metadata["bbox_mm"] = _normalize_bbox(bbox)
+        if "axes_bbox_inch" in dim_info:
+            bbox = dim_info["axes_bbox_inch"]
+            ax_metadata["bbox_inch"] = _normalize_bbox(bbox)
+
+    except Exception as e:
+        logger.warning(f"Could not extract dimension info for axes {ax_index}: {e}")
+
+    return ax_metadata
+
+
+def _normalize_bbox(bbox: dict) -> dict:
+    """
+    Normalize bounding box dictionary to consistent format.
+
+    Converts from x0/y0/x1/y1 to x_left/y_bottom/x_right/y_top format.
+
+    Parameters
+    ----------
+    bbox : dict
+        Bounding box with either x0/y0/x1/y1 or x_left/y_bottom/x_right/y_top keys
+
+    Returns
+    -------
+    dict
+        Normalized bounding box with x_left, x_right, y_top, y_bottom, width, height
+    """
+    return {
+        "x_left": bbox.get("x0", bbox.get("x_left", 0)),
+        "x_right": bbox.get("x1", bbox.get("x_right", 0)),
+        "y_top": bbox.get("y0", bbox.get("y_top", 0)),
+        "y_bottom": bbox.get("y1", bbox.get("y_bottom", 0)),
+        "width": bbox.get("width", 0),
+        "height": bbox.get("height", 0),
+    }
+
+
+def _extract_axis_info(ax, axis_name: str = "xaxis") -> dict:
+    """
+    Extract axis information (label, unit, scale, limits).
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to extract axis info from
+    axis_name : str
+        Either 'xaxis' or 'yaxis'
+
+    Returns
+    -------
+    dict
+        Axis metadata with label, unit, scale, and lim
+    """
+    from ._label_parsing import _parse_label_unit
+
+    if axis_name == "xaxis":
+        label_text = ax.get_xlabel()
+        scale = ax.get_xscale()
+        lim = list(ax.get_xlim())
+    else:  # yaxis
+        label_text = ax.get_ylabel()
+        scale = ax.get_yscale()
+        lim = list(ax.get_ylim())
+
+    label, unit = _parse_label_unit(label_text)
+
+    return {
+        "label": label,
+        "unit": unit,
+        "scale": scale,
+        "lim": lim,
+    }
+
+
+def _extract_figure_dimensions(fig) -> dict:
+    """
+    Extract figure-level dimensions.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to extract dimensions from
+
+    Returns
+    -------
+    dict
+        Figure dimensions with size_mm, size_inch, size_px, and dpi
+    """
+    fig_metadata = {}
+
+    try:
+        # Get figure size from metadata if available
+        if hasattr(fig, "_scitex_metadata"):
+            scitex_meta = fig._scitex_metadata
+            if "size_mm" in scitex_meta:
+                fig_metadata["size_mm"] = list(scitex_meta["size_mm"])
+            if "size_inch" in scitex_meta:
+                fig_metadata["size_inch"] = list(scitex_meta["size_inch"])
+
+        # Get figure size in inches (always available)
+        width_inch, height_inch = fig.get_size_inches()
+        if "size_inch" not in fig_metadata:
+            fig_metadata["size_inch"] = [width_inch, height_inch]
+
+        # Convert to mm if not in metadata
+        if "size_mm" not in fig_metadata:
+            fig_metadata["size_mm"] = [width_inch * 25.4, height_inch * 25.4]
+
+        # Get DPI
+        dpi = fig.get_dpi()
+        fig_metadata["dpi"] = dpi
+
+        # Calculate pixel size
+        fig_metadata["size_px"] = [width_inch * dpi, height_inch * dpi]
+
+    except Exception as e:
+        logger.warning(f"Could not extract figure dimensions: {e}")
+
+    return fig_metadata
+
+
+def _collect_grid_info(ax_wrapper) -> tuple:
+    """
+    Extract grid shape and axes positions from an axes wrapper.
+
+    Parameters
+    ----------
+    ax_wrapper
+        AxesWrapper or similar object with _axes_scitex attribute
+
+    Returns
+    -------
+    tuple
+        (all_axes, grid_shape) where all_axes is a list of (ax, row, col) tuples
+    """
+    import numpy as np
+
+    all_axes = []
+    grid_shape = (1, 1)
+
+    if hasattr(ax_wrapper, "_axes_scitex"):
+        axes_array = ax_wrapper._axes_scitex
+        if isinstance(axes_array, np.ndarray):
+            grid_shape = axes_array.shape
+            for i, ax_row in enumerate(axes_array):
+                if axes_array.ndim == 1:
+                    # 1D array: treat as single column
+                    all_axes.append((ax_row, i, 0))
+                else:
+                    # 2D array
+                    for j, ax_item in enumerate(ax_row):
+                        all_axes.append((ax_item, i, j))
+        else:
+            # Single axes
+            all_axes.append((axes_array, 0, 0))
+    elif hasattr(ax_wrapper, "_ax"):
+        # Single AxisWrapper
+        all_axes.append((ax_wrapper, 0, 0))
+    else:
+        # Fallback: matplotlib axes
+        all_axes.append((ax_wrapper, 0, 0))
+
+    return all_axes, grid_shape

scitex/plt/utils/metadata/_editable_export.py

@@ -0,0 +1,405 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-10 (ywatanabe)"
+# File: scitex/plt/utils/metadata/_editable_export.py
+
+"""
+Main export function for Schema v0.3 (scitex.plt.figure.editable).
+
+This module provides the top-level export_editable_figure() function that
+orchestrates geometry extraction for all elements in a matplotlib figure,
+producing a JSON-serializable dictionary suitable for interactive editing.
+"""
+
+from typing import Dict, Any, Optional, List
+import numpy as np
+from datetime import datetime
+
+from ._geometry_extraction import (
+    extract_axes_bbox_px,
+    extract_line_geometry,
+    extract_scatter_geometry,
+    extract_polygon_geometry,
+    extract_rectangle_geometry,
+    extract_bar_group_geometry,
+    extract_text_geometry,
+    extract_image_geometry,
+)
+
+
+def export_editable_figure(
+    fig,
+    title: str = "",
+    description: str = "",
+    include_full_paths: bool = False,
+    simplify_threshold: float = 0.5,
+) -> Dict[str, Any]:
+    """
+    Export a matplotlib figure with geometry data for interactive editing.
+
+    This produces a Schema v0.3 compliant dictionary with axes-local pixel
+    coordinates for all visual elements, suitable for shape-based hit testing.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure or scitex.plt.FigureWrapper
+        The figure to export
+    title : str
+        Optional title for the figure metadata
+    description : str
+        Optional description for the figure metadata
+    include_full_paths : bool
+        If True, include full (unsimplified) paths for lines. Default False.
+    simplify_threshold : float
+        Maximum pixel error for path simplification. Default 0.5.
+
+    Returns
+    -------
+    dict
+        Schema v0.3 compliant dictionary with structure:
+        - scitex_schema: "scitex.plt.figure.editable"
+        - scitex_schema_version: "0.3.0"
+        - figure: {size_px, dpi, ...}
+        - axes: {ax_id: {bbox_px, ...}, ...}
+        - elements: {elem_id: {geometry_px, style, ...}, ...}
+        - statistics: {} (placeholder for stats integration)
+        - data: {} (placeholder for linked data)
+        - output: {} (rendering metadata)
+    """
+    # Handle scitex FigureWrapper
+    mpl_fig = fig.figure if hasattr(fig, 'figure') else fig
+
+    # Ensure we have a renderer
+    try:
+        renderer = mpl_fig.canvas.get_renderer()
+    except Exception:
+        mpl_fig.canvas.draw()
+        renderer = mpl_fig.canvas.get_renderer()
+
+    # Figure dimensions
+    fig_width_px = int(mpl_fig.get_figwidth() * mpl_fig.dpi)
+    fig_height_px = int(mpl_fig.get_figheight() * mpl_fig.dpi)
+
+    # Build output structure
+    output = {
+        "scitex_schema": "scitex.plt.figure.editable",
+        "scitex_schema_version": "0.3.0",
+        "meta": {
+            "title": title,
+            "description": description,
+            "exported_at": datetime.now().isoformat(),
+        },
+        "figure": {
+            "size_px": [fig_width_px, fig_height_px],
+            "dpi": mpl_fig.dpi,
+            "figsize_inches": [mpl_fig.get_figwidth(), mpl_fig.get_figheight()],
+        },
+        "axes": {},
+        "elements": {},
+        "statistics": {},
+        "data": {},
+        "output": {
+            "format": "png",
+            "width_px": fig_width_px,
+            "height_px": fig_height_px,
+        },
+    }
+
+    # Get all axes
+    axes_list = mpl_fig.get_axes()
+
+    for ax_idx, ax in enumerate(axes_list):
+        # Handle scitex AxisWrapper
+        mpl_ax = ax._axis_mpl if hasattr(ax, '_axis_mpl') else ax
+
+        ax_id = f"ax_{ax_idx:02d}"
+
+        # Extract axes bbox
+        axes_bbox = extract_axes_bbox_px(mpl_ax, mpl_fig)
+        output["axes"][ax_id] = {
+            "bbox_px": axes_bbox,
+            "position": list(mpl_ax.get_position().bounds),
+            "xlim": list(mpl_ax.get_xlim()),
+            "ylim": list(mpl_ax.get_ylim()),
+        }
+
+        # Extract elements from this axes
+        elements = _extract_axes_elements(
+            mpl_ax, mpl_fig, ax_id, renderer,
+            include_full_paths=include_full_paths,
+            simplify_threshold=simplify_threshold,
+        )
+        output["elements"].update(elements)
+
+    return output
+
+
+def _extract_axes_elements(
+    ax, fig, ax_id: str, renderer,
+    include_full_paths: bool = False,
+    simplify_threshold: float = 0.5,
+) -> Dict[str, Any]:
+    """
+    Extract all visual elements from a single axes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes object
+    fig : matplotlib.figure.Figure
+        The figure object
+    ax_id : str
+        Identifier for the axes (e.g., "ax_00")
+    renderer : RendererBase
+        Matplotlib renderer for text bbox extraction
+    include_full_paths : bool
+        Include unsimplified paths
+    simplify_threshold : float
+        Path simplification threshold in pixels
+
+    Returns
+    -------
+    dict
+        Dictionary of {element_id: element_data}
+    """
+    elements = {}
+    zorder_counter = 0
+
+    # Extract lines (Line2D)
+    for idx, line in enumerate(ax.lines):
+        elem_id = f"{ax_id}_line_{idx:02d}"
+        label = line.get_label()
+        if label is None or label.startswith('_'):
+            label = f"line_{idx}"
+
+        geom = extract_line_geometry(line, ax, fig, simplify_threshold)
+
+        elements[elem_id] = {
+            "id": elem_id,
+            "axes_id": ax_id,
+            "element_type": "line",
+            "label": label,
+            "geometry_px": geom,
+            "style": _extract_line_style(line),
+            "editable_styles": ["color", "linewidth", "linestyle", "alpha", "marker"],
+            "zorder": line.get_zorder(),
+            "visible": line.get_visible(),
+        }
+        zorder_counter += 1
+
+    # Extract collections (scatter, polygon fills, etc.)
+    for idx, coll in enumerate(ax.collections):
+        coll_type = type(coll).__name__
+
+        if coll_type == "PathCollection":
+            # Scatter plot
+            elem_id = f"{ax_id}_scatter_{idx:02d}"
+            label = coll.get_label()
+            if label is None or label.startswith('_'):
+                label = f"scatter_{idx}"
+
+            geom = extract_scatter_geometry(coll, ax, fig)
+
+            elements[elem_id] = {
+                "id": elem_id,
+                "axes_id": ax_id,
+                "element_type": "scatter",
+                "label": label,
+                "geometry_px": geom,
+                "style": _extract_scatter_style(coll),
+                "editable_styles": ["facecolor", "edgecolor", "s", "alpha", "marker"],
+                "zorder": coll.get_zorder(),
+                "visible": coll.get_visible(),
+            }
+
+        elif coll_type in ("PolyCollection", "FillBetweenPolyCollection"):
+            # Fill_between, violin, etc.
+            elem_id = f"{ax_id}_fill_{idx:02d}"
+            label = coll.get_label()
+            if label is None or label.startswith('_'):
+                label = f"fill_{idx}"
+
+            geom = extract_polygon_geometry(coll, ax, fig)
+
+            elements[elem_id] = {
+                "id": elem_id,
+                "axes_id": ax_id,
+                "element_type": "fill",
+                "label": label,
+                "geometry_px": geom,
+                "style": _extract_polygon_style(coll),
+                "editable_styles": ["facecolor", "edgecolor", "alpha"],
+                "zorder": coll.get_zorder(),
+                "visible": coll.get_visible(),
+            }
+
+        elif coll_type == "LineCollection":
+            # Multiple lines (e.g., errorbar caps)
+            elem_id = f"{ax_id}_linecoll_{idx:02d}"
+            elements[elem_id] = {
+                "id": elem_id,
+                "axes_id": ax_id,
+                "element_type": "line_collection",
+                "label": f"linecoll_{idx}",
+                "geometry_px": {"coord_space": "axes", "bbox": None},
+                "style": {},
+                "editable_styles": ["color", "linewidth", "alpha"],
+                "zorder": coll.get_zorder(),
+                "visible": coll.get_visible(),
+            }
+
+    # Extract patches (bars, rectangles)
+    bar_patches = []
+    other_patches = []
+
+    for patch in ax.patches:
+        patch_type = type(patch).__name__
+        if patch_type == "Rectangle":
+            # Check if it's part of a bar plot (has nonzero width and height)
+            if patch.get_width() != 0 and patch.get_height() != 0:
+                bar_patches.append(patch)
+            else:
+                other_patches.append(patch)
+        else:
+            other_patches.append(patch)
+
+    # Group bar patches by similar x position (bars) or y position (horizontal bars)
+    if bar_patches:
+        elem_id = f"{ax_id}_bars"
+        geom = extract_bar_group_geometry(bar_patches, ax, fig)
+
+        elements[elem_id] = {
+            "id": elem_id,
+            "axes_id": ax_id,
+            "element_type": "bar",
+            "label": "bars",
+            "geometry_px": geom,
+            "style": _extract_bar_style(bar_patches[0] if bar_patches else None),
+            "editable_styles": ["facecolor", "edgecolor", "alpha", "linewidth"],
+            "zorder": bar_patches[0].get_zorder() if bar_patches else 0,
+            "visible": True,
+        }
+
+    # Extract images
+    for idx, img in enumerate(ax.images):
+        elem_id = f"{ax_id}_image_{idx:02d}"
+        geom = extract_image_geometry(img, ax, fig)
+
+        elements[elem_id] = {
+            "id": elem_id,
+            "axes_id": ax_id,
+            "element_type": "image",
+            "label": f"image_{idx}",
+            "geometry_px": geom,
+            "style": {"cmap": str(img.get_cmap().name), "alpha": img.get_alpha()},
+            "editable_styles": ["cmap", "alpha", "clim"],
+            "zorder": img.get_zorder(),
+            "visible": img.get_visible(),
+        }
+
+    # Extract texts (excluding axis labels and title which are handled separately)
+    for idx, text in enumerate(ax.texts):
+        if not text.get_text():
+            continue
+
+        elem_id = f"{ax_id}_text_{idx:02d}"
+        geom = extract_text_geometry(text, ax, fig)
+
+        elements[elem_id] = {
+            "id": elem_id,
+            "axes_id": ax_id,
+            "element_type": "text",
+            "label": text.get_text()[:20],
+            "text": text.get_text(),
+            "geometry_px": geom,
+            "style": _extract_text_style(text),
+            "editable_styles": ["fontsize", "color", "fontweight", "alpha"],
+            "zorder": text.get_zorder(),
+            "visible": text.get_visible(),
+        }
+
+    return elements
+
+
+def _extract_line_style(line) -> Dict[str, Any]:
+    """Extract style properties from a Line2D."""
+    color = line.get_color()
+    if isinstance(color, np.ndarray):
+        color = color.tolist()
+
+    return {
+        "color": color,
+        "linewidth": line.get_linewidth(),
+        "linestyle": line.get_linestyle(),
+        "alpha": line.get_alpha(),
+        "marker": line.get_marker(),
+        "markersize": line.get_markersize(),
+    }
+
+
+def _extract_scatter_style(coll) -> Dict[str, Any]:
+    """Extract style properties from a PathCollection (scatter)."""
+    facecolors = coll.get_facecolors()
+    edgecolors = coll.get_edgecolors()
+
+    fc = facecolors[0].tolist() if len(facecolors) > 0 else [0, 0, 0, 1]
+    ec = edgecolors[0].tolist() if len(edgecolors) > 0 else [0, 0, 0, 1]
+
+    sizes = coll.get_sizes()
+    s = float(sizes[0]) if len(sizes) > 0 else 36
+
+    return {
+        "facecolor": fc,
+        "edgecolor": ec,
+        "s": s,
+        "alpha": coll.get_alpha(),
+    }
+
+
+def _extract_polygon_style(coll) -> Dict[str, Any]:
+    """Extract style properties from a PolyCollection."""
+    facecolors = coll.get_facecolors()
+    edgecolors = coll.get_edgecolors()
+
+    fc = facecolors[0].tolist() if len(facecolors) > 0 else [0, 0, 0, 0.3]
+    ec = edgecolors[0].tolist() if len(edgecolors) > 0 else [0, 0, 0, 1]
+
+    return {
+        "facecolor": fc,
+        "edgecolor": ec,
+        "alpha": coll.get_alpha(),
+    }
+
+
+def _extract_bar_style(patch) -> Dict[str, Any]:
+    """Extract style properties from a Rectangle patch."""
+    if patch is None:
+        return {}
+
+    fc = patch.get_facecolor()
+    ec = patch.get_edgecolor()
+
+    return {
+        "facecolor": list(fc) if hasattr(fc, '__iter__') else fc,
+        "edgecolor": list(ec) if hasattr(ec, '__iter__') else ec,
+        "linewidth": patch.get_linewidth(),
+        "alpha": patch.get_alpha(),
+    }
+
+
+def _extract_text_style(text) -> Dict[str, Any]:
+    """Extract style properties from a Text object."""
+    return {
+        "fontsize": text.get_fontsize(),
+        "color": text.get_color(),
+        "fontweight": text.get_fontweight(),
+        "fontstyle": text.get_fontstyle(),
+        "fontfamily": text.get_fontfamily(),
+        "alpha": text.get_alpha(),
+        "ha": text.get_ha(),
+        "va": text.get_va(),
+        "rotation": text.get_rotation(),
+    }
+
+
+# EOF

scitex/plt/utils/metadata/_figure_metadata.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_figure_metadata.py
+
+"""
+Figure-level metadata collection.
+
+This module provides functions to collect figure-level metadata including
+dimensions, DPI, and overall figure properties.
+"""
+
+from typing import Dict
+from ._dimensions import _extract_figure_dimensions
+
+
+def _collect_figure_metadata(fig) -> dict:
+    """
+    Collect figure-level metadata.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to collect metadata from
+
+    Returns
+    -------
+    dict
+        Figure metadata with size_mm, size_inch, size_px, and dpi
+    """
+    return _extract_figure_dimensions(fig)
+
+
+def _initialize_metadata_structure() -> dict:
+    """
+    Initialize the base metadata structure with schema info.
+
+    Returns
+    -------
+    dict
+        Base metadata dictionary with schema, version, UUID, and runtime info
+    """
+    import datetime
+    import uuid
+    import matplotlib
+    import scitex
+
+    metadata = {
+        "scitex_schema": "scitex.plt.figure",
+        "scitex_schema_version": "0.1.0",
+        "figure_uuid": str(uuid.uuid4()),
+        "runtime": {
+            "scitex_version": scitex.__version__,
+            "matplotlib_version": matplotlib.__version__,
+            "created_at": datetime.datetime.now().isoformat(),
+        },
+    }
+
+    return metadata