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

scitex/plt/utils/metadata/_dimensions.py

@@ -0,0 +1,239 @@
+#!/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).
+"""
+
+import warnings
+from typing import Dict
+
+
+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:
+        warnings.warn(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:
+        warnings.warn(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/_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

scitex/plt/utils/metadata/_image_text_artists.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_image_text_artists.py
+
+"""
+Image and text artist extraction utilities.
+
+This module provides functions to extract AxesImage (imshow) and Text (annotations)
+artists from matplotlib axes.
+"""
+
+import matplotlib.colors as mcolors
+
+
+def _extract_image_artists(mpl_ax):
+    """
+    Extract AxesImage artists (imshow).
+
+    Parameters
+    ----------
+    mpl_ax : matplotlib.axes.Axes
+        Raw matplotlib axes
+
+    Returns
+    -------
+    list
+        List of artist dictionaries
+    """
+    artists = []
+
+    for i, img in enumerate(mpl_ax.images):
+        img_type = type(img).__name__
+
+        artist = {}
+
+        scitex_id = getattr(img, "_scitex_id", None)
+        label = img.get_label() if hasattr(img, "get_label") else ""
+
+        if scitex_id:
+            artist["id"] = scitex_id
+        elif label and not label.startswith("_"):
+            artist["id"] = label
+        else:
+            artist["id"] = f"image_{i}"
+
+        artist["mark"] = "image"
+        artist["role"] = "image"
+        artist["legend_included"] = False
+        artist["zorder"] = img.get_zorder()
+
+        # Backend layer
+        backend = {
+            "name": "matplotlib",
+            "artist_class": img_type,
+            "props": {}
+        }
+        try:
+            cmap = img.get_cmap()
+            if cmap:
+                backend["props"]["cmap"] = cmap.name
+        except (ValueError, TypeError, AttributeError):
+            pass
+        try:
+            backend["props"]["vmin"] = float(img.norm.vmin) if img.norm else None
+            backend["props"]["vmax"] = float(img.norm.vmax) if img.norm else None
+        except (ValueError, TypeError, AttributeError):
+            pass
+        try:
+            backend["props"]["interpolation"] = img.get_interpolation()
+        except (ValueError, TypeError, AttributeError):
+            pass
+
+        artist["backend"] = backend
+        artists.append(artist)
+
+    return artists
+
+
+def _extract_text_artists(mpl_ax):
+    """
+    Extract Text artists (annotations, stats text, etc.).
+
+    Parameters
+    ----------
+    mpl_ax : matplotlib.axes.Axes
+        Raw matplotlib axes
+
+    Returns
+    -------
+    list
+        List of artist dictionaries
+    """
+    artists = []
+    text_count = 0
+
+    for i, text_obj in enumerate(mpl_ax.texts):
+        text_content = text_obj.get_text()
+        if not text_content or text_content.strip() == "":
+            continue
+
+        artist = {}
+
+        scitex_id = getattr(text_obj, "_scitex_id", None)
+
+        if scitex_id:
+            artist["id"] = scitex_id
+        else:
+            artist["id"] = f"text_{text_count}"
+
+        artist["mark"] = "text"
+
+        # Try to determine role from content or position
+        pos = text_obj.get_position()
+        # Check if this looks like stats annotation
+        if any(kw in text_content.lower() for kw in ['r=', 'p=', 'r²=', 'n=']):
+            artist["role"] = "stats_annotation"
+        else:
+            artist["role"] = "annotation"
+
+        artist["legend_included"] = False
+        artist["zorder"] = text_obj.get_zorder()
+
+        # Geometry - text position
+        artist["geometry"] = {
+            "x": pos[0],
+            "y": pos[1],
+        }
+
+        artist["text"] = text_content
+
+        # Backend layer
+        backend = {
+            "name": "matplotlib",
+            "artist_class": type(text_obj).__name__,
+            "props": {}
+        }
+
+        try:
+            color = text_obj.get_color()
+            backend["props"]["color"] = mcolors.to_hex(color, keep_alpha=False)
+        except (ValueError, TypeError):
+            pass
+
+        try:
+            backend["props"]["fontsize_pt"] = text_obj.get_fontsize()
+        except (ValueError, TypeError):
+            pass
+
+        try:
+            backend["props"]["ha"] = text_obj.get_ha()
+            backend["props"]["va"] = text_obj.get_va()
+        except (ValueError, TypeError):
+            pass
+
+        artist["backend"] = backend
+
+        # data_ref for text position - only if explicitly tracked
+        if scitex_id:
+            artist["data_ref"] = {
+                "x": f"text_{text_count}_x",
+                "y": f"text_{text_count}_y",
+                "content": f"text_{text_count}_content"
+            }
+
+        text_count += 1
+        artists.append(artist)
+
+    return artists

scitex/plt/utils/metadata/_label_parsing.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_label_parsing.py
+
+"""
+Label and unit parsing utilities.
+
+This module provides functions to parse axis labels and extract unit information
+from formatted strings like "Time [s]" or "Amplitude (a.u.)".
+"""
+
+import re
+
+
+def _parse_label_unit(label_text: str) -> tuple:
+    """
+    Parse label text to extract label and unit.
+
+    Handles formats like:
+    - "Time [s]" -> ("Time", "s")
+    - "Amplitude (a.u.)" -> ("Amplitude", "a.u.")
+    - "Value" -> ("Value", "")
+
+    Parameters
+    ----------
+    label_text : str
+        The full label text from axes
+
+    Returns
+    -------
+    tuple
+        (label, unit) where unit is empty string if not found
+    """
+    if not label_text:
+        return "", ""
+
+    # Try to match [...] pattern first (preferred format)
+    match = re.match(r"^(.+?)\s*\[([^\]]+)\]$", label_text)
+    if match:
+        return match.group(1).strip(), match.group(2).strip()
+
+    # Try to match (...) pattern
+    match = re.match(r"^(.+?)\s*\(([^\)]+)\)$", label_text)
+    if match:
+        return match.group(1).strip(), match.group(2).strip()
+
+    # No unit found
+    return label_text.strip(), ""
+
+
+def _get_csv_column_names(trace_id: str, ax_row: int = 0, ax_col: int = 0, variables: list = None) -> dict:
+    """
+    Get CSV column names using the single source of truth naming convention.
+
+    Format: ax-row-{row}-col-{col}_trace-id-{id}_variable-{var}
+
+    Parameters
+    ----------
+    trace_id : str
+        The trace identifier (e.g., "sine", "step")
+    ax_row : int
+        Row position of axes in grid (default: 0)
+    ax_col : int
+        Column position of axes in grid (default: 0)
+    variables : list, optional
+        List of variable names (default: ["x", "y"])
+
+    Returns
+    -------
+    dict
+        Dictionary mapping variable names to CSV column names
+    """
+    from .._csv_column_naming import get_csv_column_name
+
+    if variables is None:
+        variables = ["x", "y"]
+
+    data_ref = {}
+    for var in variables:
+        data_ref[var] = get_csv_column_name(var, ax_row, ax_col, trace_id=trace_id)
+
+    return data_ref

scitex/plt/utils/metadata/_legend_extraction.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: scitex/plt/utils/metadata/_legend_extraction.py
+
+"""
+Legend extraction utilities.
+
+This module provides functions to extract legend information from matplotlib axes.
+"""
+
+from typing import Optional
+
+
+def _extract_legend_info(ax) -> Optional[dict]:
+    """
+    Extract legend information from axes.
+
+    Uses matplotlib terminology for legend properties.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes to extract legend from
+
+    Returns
+    -------
+    dict or None
+        Legend info dictionary with matplotlib properties, or None if no legend
+    """
+    legend = ax.get_legend()
+    if legend is None:
+        return None
+
+    legend_info = {
+        "visible": legend.get_visible(),
+        "loc": legend._loc if hasattr(legend, "_loc") else "best",
+        "frameon": legend.get_frame_on() if hasattr(legend, "get_frame_on") else True,
+    }
+
+    # ncol - number of columns
+    if hasattr(legend, "_ncols"):
+        legend_info["ncol"] = legend._ncols
+    elif hasattr(legend, "_ncol"):
+        legend_info["ncol"] = legend._ncol
+
+    # Extract legend handles with artist references
+    # This allows reconstructing the legend by referencing artists
+    handles = []
+    texts = legend.get_texts()
+    legend_handles = legend.legend_handles if hasattr(legend, 'legend_handles') else []
+
+    # Get the raw matplotlib axes for accessing lines to match IDs
+    mpl_ax = ax._axis_mpl if hasattr(ax, "_axis_mpl") else ax
+
+    for i, text in enumerate(texts):
+        label_text = text.get_text()
+        handle_entry = {"label": label_text}
+
+        # Try to get artist_id from corresponding handle
+        artist_id = None
+        if i < len(legend_handles):
+            handle = legend_handles[i]
+            # Check if handle has scitex_id
+            if hasattr(handle, "_scitex_id"):
+                artist_id = handle._scitex_id
+
+        # Fallback: find matching artist by label in axes artists
+        if artist_id is None:
+            # Check lines
+            for line in mpl_ax.lines:
+                line_label = line.get_label()
+                if line_label == label_text:
+                    if hasattr(line, "_scitex_id"):
+                        artist_id = line._scitex_id
+                    elif not line_label.startswith("_"):
+                        artist_id = line_label
+                    break
+
+        # Check collections (scatter)
+        if artist_id is None:
+            for coll in mpl_ax.collections:
+                coll_label = coll.get_label() if hasattr(coll, "get_label") else ""
+                if coll_label == label_text:
+                    if hasattr(coll, "_scitex_id"):
+                        artist_id = coll._scitex_id
+                    elif coll_label and not coll_label.startswith("_"):
+                        artist_id = coll_label
+                    break
+
+        # Check patches (bar/hist/pie)
+        if artist_id is None:
+            for patch in mpl_ax.patches:
+                patch_label = patch.get_label() if hasattr(patch, "get_label") else ""
+                if patch_label == label_text:
+                    if hasattr(patch, "_scitex_id"):
+                        artist_id = patch._scitex_id
+                    elif patch_label and not patch_label.startswith("_"):
+                        artist_id = patch_label
+                    break
+
+        # Check images (imshow)
+        if artist_id is None:
+            for img in mpl_ax.images:
+                img_label = img.get_label() if hasattr(img, "get_label") else ""
+                if img_label == label_text:
+                    if hasattr(img, "_scitex_id"):
+                        artist_id = img._scitex_id
+                    elif img_label and not img_label.startswith("_"):
+                        artist_id = img_label
+                    break
+
+        if artist_id:
+            handle_entry["artist_id"] = artist_id
+
+        handles.append(handle_entry)
+
+    if handles:
+        legend_info["handles"] = handles
+
+    return legend_info