scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/plt/utils/_hitmap/_artist_extraction.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_hitmap/_artist_extraction.py
+
+"""
+Artist extraction functions for hitmap generation.
+
+This module provides functions to extract selectable artists from matplotlib
+figures and detect logical groups (histogram, bar series, etc.).
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+__all__ = [
+    "get_all_artists",
+    "get_all_artists_with_groups",
+    "detect_logical_groups",
+]
+
+
+def get_all_artists(fig, include_text: bool = False) -> List[Tuple[Any, int, str]]:
+    """
+    Extract all selectable artists from a figure.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to extract artists from.
+    include_text : bool
+        Whether to include text elements.
+
+    Returns
+    -------
+    list of tuple
+        List of (artist, axes_index, artist_type) tuples.
+    """
+    artists = []
+
+    for ax_idx, ax in enumerate(fig.axes):
+        # Lines (Line2D)
+        for line in ax.get_lines():
+            label = line.get_label()
+            if not label.startswith("_"):  # Skip internal lines
+                artists.append((line, ax_idx, "line"))
+
+        # Scatter plots (PathCollection)
+        for coll in ax.collections:
+            coll_type = type(coll).__name__
+            if "PathCollection" in coll_type:
+                artists.append((coll, ax_idx, "scatter"))
+            elif "PolyCollection" in coll_type or "FillBetween" in coll_type:
+                artists.append((coll, ax_idx, "fill"))
+            elif "QuadMesh" in coll_type:
+                artists.append((coll, ax_idx, "mesh"))
+
+        # Bars (Rectangle patches in containers)
+        for container in ax.containers:
+            if hasattr(container, "patches") and container.patches:
+                artists.append((container, ax_idx, "bar"))
+
+        # Individual patches (rectangles, circles, etc.)
+        for patch in ax.patches:
+            patch_type = type(patch).__name__
+            if patch_type == "Rectangle":
+                artists.append((patch, ax_idx, "rectangle"))
+            elif patch_type in ("Circle", "Ellipse"):
+                artists.append((patch, ax_idx, "circle"))
+            elif patch_type == "Polygon":
+                artists.append((patch, ax_idx, "polygon"))
+
+        # Images
+        for img in ax.images:
+            artists.append((img, ax_idx, "image"))
+
+        # Text (optional)
+        if include_text:
+            for text in ax.texts:
+                if text.get_text():
+                    artists.append((text, ax_idx, "text"))
+
+    return artists
+
+
+def detect_logical_groups(fig) -> Dict[str, Dict[str, Any]]:
+    """
+    Detect logical groups in a matplotlib figure.
+
+    Logical groups represent high-level plot elements that may consist of
+    multiple physical matplotlib artists. For example:
+    - Histogram: Many Rectangle patches grouped as one "histogram"
+    - Bar series: BarContainer with multiple bars
+    - Box plot: Box, whiskers, caps, median, fliers as one "boxplot"
+    - Error bars: Line + error caps as one "errorbar"
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to analyze.
+
+    Returns
+    -------
+    dict
+        Dictionary mapping group_id to group info.
+    """
+    groups = {}
+    group_counter = {}
+
+    def get_group_id(group_type: str, ax_idx: int) -> str:
+        """Generate unique group ID."""
+        key = f"{group_type}_{ax_idx}"
+        if key not in group_counter:
+            group_counter[key] = 0
+        idx = group_counter[key]
+        group_counter[key] += 1
+        return f"{group_type}_{ax_idx}_{idx}"
+
+    for ax_idx, ax in enumerate(fig.axes):
+        # Detect BarContainers (covers bar charts and histograms)
+        bar_containers = [
+            c for c in ax.containers if "BarContainer" in type(c).__name__
+        ]
+        n_bar_containers = len(bar_containers)
+
+        for container in ax.containers:
+            container_type = type(container).__name__
+
+            if "BarContainer" in container_type:
+                patches = (
+                    list(container.patches) if hasattr(container, "patches") else []
+                )
+                if not patches:
+                    continue
+
+                # Check if bars are adjacent (histogram) or spaced (bar chart)
+                is_histogram = False
+                if len(patches) > 1:
+                    widths = [p.get_width() for p in patches]
+                    x_positions = [p.get_x() for p in patches]
+                    if len(x_positions) > 1:
+                        gaps = [
+                            x_positions[i + 1] - (x_positions[i] + widths[i])
+                            for i in range(len(x_positions) - 1)
+                        ]
+                        avg_width = sum(widths) / len(widths)
+                        is_histogram = all(abs(g) < avg_width * 0.1 for g in gaps)
+
+                if is_histogram:
+                    group_type = "histogram"
+                    group_id = get_group_id(group_type, ax_idx)
+                    label = ""
+                    if hasattr(container, "get_label"):
+                        label = container.get_label()
+                    if not label or label.startswith("_"):
+                        label = f"{group_type}_{len([g for g in groups if group_type in g])}"
+
+                    groups[group_id] = {
+                        "type": group_type,
+                        "label": label,
+                        "axes_index": ax_idx,
+                        "artists": patches,
+                        "artist_types": ["rectangle"] * len(patches),
+                        "role": "logical",
+                        "member_count": len(patches),
+                    }
+
+                elif n_bar_containers > 1:
+                    group_type = "bar_series"
+                    group_id = get_group_id(group_type, ax_idx)
+                    label = ""
+                    if hasattr(container, "get_label"):
+                        label = container.get_label()
+                    if not label or label.startswith("_"):
+                        label = f"{group_type}_{len([g for g in groups if group_type in g])}"
+
+                    groups[group_id] = {
+                        "type": group_type,
+                        "label": label,
+                        "axes_index": ax_idx,
+                        "artists": patches,
+                        "artist_types": ["rectangle"] * len(patches),
+                        "role": "logical",
+                        "member_count": len(patches),
+                    }
+
+            elif "ErrorbarContainer" in container_type:
+                group_id = get_group_id("errorbar", ax_idx)
+                artists = []
+                artist_types = []
+
+                if hasattr(container, "lines"):
+                    data_line, caplines, barlinecols = container.lines
+                    if data_line:
+                        artists.append(data_line)
+                        artist_types.append("line")
+                    artists.extend(caplines)
+                    artist_types.extend(["line"] * len(caplines))
+                    artists.extend(barlinecols)
+                    artist_types.extend(["line_collection"] * len(barlinecols))
+
+                label = container.get_label() if hasattr(container, "get_label") else ""
+                if not label or label.startswith("_"):
+                    label = f"errorbar_{len([g for g in groups if 'errorbar' in g])}"
+
+                groups[group_id] = {
+                    "type": "errorbar",
+                    "label": label,
+                    "axes_index": ax_idx,
+                    "artists": artists,
+                    "artist_types": artist_types,
+                    "role": "logical",
+                    "member_count": len(artists),
+                }
+
+        # Detect pie charts (Wedge patches)
+        wedges = [p for p in ax.patches if type(p).__name__ == "Wedge"]
+        if wedges:
+            group_id = get_group_id("pie", ax_idx)
+            groups[group_id] = {
+                "type": "pie",
+                "label": "Pie Chart",
+                "axes_index": ax_idx,
+                "artists": wedges,
+                "artist_types": ["wedge"] * len(wedges),
+                "role": "logical",
+                "member_count": len(wedges),
+            }
+
+        # Detect contour sets
+        poly_collections = [
+            c
+            for c in ax.collections
+            if "PolyCollection" in type(c).__name__
+            and hasattr(c, "get_array")
+            and c.get_array() is not None
+        ]
+        if len(poly_collections) > 2:
+            group_id = get_group_id("contour", ax_idx)
+            groups[group_id] = {
+                "type": "contour",
+                "label": "Contour Plot",
+                "axes_index": ax_idx,
+                "artists": poly_collections,
+                "artist_types": ["poly_collection"] * len(poly_collections),
+                "role": "logical",
+                "member_count": len(poly_collections),
+            }
+
+    return groups
+
+
+def get_all_artists_with_groups(
+    fig, include_text: bool = False
+) -> Tuple[List[Tuple[Any, int, str, Optional[str]]], Dict[str, Dict[str, Any]]]:
+    """
+    Extract all selectable artists from a figure with logical group information.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to extract artists from.
+    include_text : bool
+        Whether to include text elements.
+
+    Returns
+    -------
+    tuple
+        (artists_list, groups_dict) where:
+        - artists_list: List of (artist, axes_index, artist_type, group_id) tuples
+        - groups_dict: Dictionary of logical groups
+    """
+    groups = detect_logical_groups(fig)
+
+    artist_to_group = {}
+    for group_id, group_info in groups.items():
+        for artist in group_info["artists"]:
+            artist_to_group[id(artist)] = group_id
+
+    artists_with_groups = []
+
+    for ax_idx, ax in enumerate(fig.axes):
+        # Lines
+        for line in ax.get_lines():
+            label = line.get_label()
+            if not label.startswith("_"):
+                group_id = artist_to_group.get(id(line))
+                artists_with_groups.append((line, ax_idx, "line", group_id))
+
+        # Collections
+        for coll in ax.collections:
+            coll_type = type(coll).__name__
+            group_id = artist_to_group.get(id(coll))
+            if "PathCollection" in coll_type:
+                artists_with_groups.append((coll, ax_idx, "scatter", group_id))
+            elif "PolyCollection" in coll_type or "FillBetween" in coll_type:
+                artists_with_groups.append((coll, ax_idx, "fill", group_id))
+            elif "QuadMesh" in coll_type:
+                artists_with_groups.append((coll, ax_idx, "mesh", group_id))
+
+        # Bars
+        processed_patches = set()
+        for container in ax.containers:
+            if hasattr(container, "patches") and container.patches:
+                group_id = artist_to_group.get(id(container.patches[0]))
+                if group_id:
+                    artists_with_groups.append((container, ax_idx, "bar", group_id))
+                    for patch in container.patches:
+                        processed_patches.add(id(patch))
+                else:
+                    for patch in container.patches:
+                        artists_with_groups.append((patch, ax_idx, "rectangle", None))
+                        processed_patches.add(id(patch))
+
+        # Patches
+        for patch in ax.patches:
+            if id(patch) in processed_patches:
+                continue
+            patch_type = type(patch).__name__
+            group_id = artist_to_group.get(id(patch))
+            if patch_type == "Rectangle":
+                artists_with_groups.append((patch, ax_idx, "rectangle", group_id))
+            elif patch_type in ("Circle", "Ellipse"):
+                artists_with_groups.append((patch, ax_idx, "circle", group_id))
+            elif patch_type == "Polygon":
+                artists_with_groups.append((patch, ax_idx, "polygon", group_id))
+            elif patch_type == "Wedge":
+                artists_with_groups.append((patch, ax_idx, "wedge", group_id))
+
+        # Images
+        for img in ax.images:
+            group_id = artist_to_group.get(id(img))
+            artists_with_groups.append((img, ax_idx, "image", group_id))
+
+        # Text
+        if include_text:
+            for text in ax.texts:
+                if text.get_text():
+                    group_id = artist_to_group.get(id(text))
+                    artists_with_groups.append((text, ax_idx, "text", group_id))
+
+    return artists_with_groups, groups
+
+
+# EOF

scitex/plt/utils/_hitmap/_color_application.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_hitmap/_color_application.py
+
+"""
+Color application and restoration functions for hitmap generation.
+
+This module provides functions to apply unique ID colors to matplotlib artists
+and restore original colors after hitmap rendering.
+"""
+
+from typing import Any, Dict, List, Tuple
+
+from ._artist_extraction import get_all_artists, get_all_artists_with_groups
+from ._color_conversion import id_to_rgb
+from ._constants import HITMAP_AXES_COLOR, HITMAP_BACKGROUND_COLOR
+
+__all__ = [
+    "apply_id_color",
+    "apply_hitmap_colors",
+    "restore_original_colors",
+    "prepare_hitmap_figure",
+    "restore_figure_props",
+]
+
+
+def apply_id_color(artist, hex_color: str):
+    """Apply ID color to an artist, handling different artist types."""
+    if hasattr(artist, "set_color"):
+        artist.set_color(hex_color)
+        if hasattr(artist, "set_antialiased"):
+            artist.set_antialiased(False)
+
+    elif hasattr(artist, "set_facecolor"):
+        artist.set_facecolor(hex_color)
+        if hasattr(artist, "set_edgecolor"):
+            artist.set_edgecolor(hex_color)
+        if hasattr(artist, "set_alpha"):
+            artist.set_alpha(1.0)
+        if hasattr(artist, "set_antialiased"):
+            artist.set_antialiased(False)
+
+    # Handle BarContainer
+    if hasattr(artist, "patches"):
+        for patch in artist.patches:
+            patch.set_facecolor(hex_color)
+            patch.set_edgecolor(hex_color)
+            if hasattr(patch, "set_antialiased"):
+                patch.set_antialiased(False)
+
+
+def apply_hitmap_colors(
+    fig,
+    include_text: bool = False,
+) -> Tuple[List[Dict[str, Any]], Dict[int, Dict[str, Any]], Dict[str, Dict[str, Any]]]:
+    """
+    Apply unique ID colors to data elements in a figure.
+
+    Also detects logical groups (histogram, bar_series, etc.) and assigns
+    group_id to each element for hierarchical selection.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to modify.
+    include_text : bool
+        Whether to include text elements.
+
+    Returns
+    -------
+    tuple
+        (original_props, color_map, groups) where:
+        - original_props: list of dicts with original artist properties
+        - color_map: dict mapping ID to element info
+        - groups: dict mapping group_id to logical group info
+    """
+    artists_with_groups, groups = get_all_artists_with_groups(fig, include_text)
+
+    original_props = []
+    color_map = {}
+
+    for i, (artist, ax_idx, artist_type, group_id) in enumerate(artists_with_groups):
+        element_id = i + 1
+        r, g, b = id_to_rgb(element_id)
+        hex_color = f"#{r:02x}{g:02x}{b:02x}"
+
+        # Store original properties
+        props = {"artist": artist, "type": artist_type}
+        try:
+            if hasattr(artist, "get_color"):
+                props["color"] = artist.get_color()
+            if hasattr(artist, "get_facecolor"):
+                props["facecolor"] = artist.get_facecolor()
+            if hasattr(artist, "get_edgecolor"):
+                props["edgecolor"] = artist.get_edgecolor()
+            if hasattr(artist, "get_alpha"):
+                props["alpha"] = artist.get_alpha()
+            if hasattr(artist, "get_antialiased"):
+                props["antialiased"] = artist.get_antialiased()
+            if hasattr(artist, "get_linewidth"):
+                props["linewidth"] = artist.get_linewidth()
+        except Exception:
+            pass
+        original_props.append(props)
+
+        # Build color map entry with group information
+        label = ""
+        if hasattr(artist, "get_label"):
+            label = artist.get_label()
+            if label.startswith("_"):
+                label = f"{artist_type}_{i}"
+
+        role = "physical" if group_id else "standalone"
+
+        color_map[element_id] = {
+            "id": element_id,
+            "type": artist_type,
+            "label": label,
+            "axes_index": ax_idx,
+            "rgb": [r, g, b],
+            "group_id": group_id,
+            "role": role,
+        }
+
+        # Apply ID color
+        try:
+            apply_id_color(artist, hex_color)
+        except Exception:
+            pass
+
+    # Add RGB color to groups for logical selection
+    group_id_start = len(artists_with_groups) + 1
+    groups_with_colors = {}
+    for i, (gid, ginfo) in enumerate(groups.items()):
+        logical_id = group_id_start + i
+        r, g, b = id_to_rgb(logical_id)
+
+        # Find member element IDs
+        member_ids = []
+        for elem_id, elem_info in color_map.items():
+            if elem_info.get("group_id") == gid:
+                member_ids.append(elem_id)
+
+        groups_with_colors[gid] = {
+            "id": logical_id,
+            "type": ginfo["type"],
+            "label": ginfo["label"],
+            "axes_index": ginfo["axes_index"],
+            "rgb": [r, g, b],
+            "role": "logical",
+            "member_ids": member_ids,
+            "member_count": ginfo["member_count"],
+        }
+
+    return original_props, color_map, groups_with_colors
+
+
+def restore_original_colors(original_props: List[Dict[str, Any]]):
+    """
+    Restore original colors to artists after hitmap generation.
+
+    Parameters
+    ----------
+    original_props : list
+        List of dicts with original artist properties.
+    """
+    for props in original_props:
+        artist = props["artist"]
+        try:
+            if "color" in props and hasattr(artist, "set_color"):
+                artist.set_color(props["color"])
+            if "facecolor" in props and hasattr(artist, "set_facecolor"):
+                artist.set_facecolor(props["facecolor"])
+            if "edgecolor" in props and hasattr(artist, "set_edgecolor"):
+                artist.set_edgecolor(props["edgecolor"])
+            if "alpha" in props and hasattr(artist, "set_alpha"):
+                artist.set_alpha(props["alpha"])
+            if "antialiased" in props and hasattr(artist, "set_antialiased"):
+                artist.set_antialiased(props["antialiased"])
+            if "linewidth" in props and hasattr(artist, "set_linewidth"):
+                artist.set_linewidth(props["linewidth"])
+        except Exception:
+            pass
+
+
+def prepare_hitmap_figure(
+    fig,
+    include_text: bool = False,
+) -> Tuple[Dict[int, Dict[str, Any]], List[Dict[str, Any]]]:
+    """
+    Prepare a figure for hitmap rendering by coloring elements with unique IDs.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to prepare for hitmap rendering.
+    include_text : bool
+        Whether to include text elements.
+
+    Returns
+    -------
+    tuple
+        (color_map, original_props) where:
+        - color_map: dict mapping ID to element info
+        - original_props: list of dicts with original properties
+    """
+    artists = get_all_artists(fig, include_text)
+
+    if not artists:
+        return {}, []
+
+    original_props = []
+    color_map = {}
+
+    for i, (artist, ax_idx, artist_type) in enumerate(artists):
+        element_id = i + 1
+        r, g, b = id_to_rgb(element_id)
+        hex_color = f"#{r:02x}{g:02x}{b:02x}"
+
+        # Store original properties
+        props = {"artist": artist, "type": artist_type}
+        try:
+            if hasattr(artist, "get_color"):
+                props["color"] = artist.get_color()
+            if hasattr(artist, "get_facecolor"):
+                props["facecolor"] = artist.get_facecolor()
+            if hasattr(artist, "get_edgecolor"):
+                props["edgecolor"] = artist.get_edgecolor()
+            if hasattr(artist, "get_alpha"):
+                props["alpha"] = artist.get_alpha()
+            if hasattr(artist, "get_antialiased"):
+                props["antialiased"] = artist.get_antialiased()
+        except Exception:
+            pass
+        original_props.append(props)
+
+        # Build color map entry
+        label = ""
+        if hasattr(artist, "get_label"):
+            label = artist.get_label()
+            if label.startswith("_"):
+                label = f"{artist_type}_{i}"
+
+        color_map[element_id] = {
+            "id": element_id,
+            "type": artist_type,
+            "label": label,
+            "axes_index": ax_idx,
+            "rgb": [r, g, b],
+        }
+
+        # Apply ID color
+        try:
+            apply_id_color(artist, hex_color)
+        except Exception:
+            pass
+
+    # Hide non-artist elements
+    axes_props = []
+    for ax in fig.axes:
+        ax_props = {
+            "ax": ax,
+            "grid_visible": (
+                ax.xaxis.get_gridlines()[0].get_visible()
+                if ax.xaxis.get_gridlines()
+                else False
+            ),
+            "facecolor": ax.get_facecolor(),
+            "spines_visible": {k: v.get_visible() for k, v in ax.spines.items()},
+            "xlabel": ax.get_xlabel(),
+            "ylabel": ax.get_ylabel(),
+            "title": ax.get_title(),
+            "legend_visible": (
+                ax.get_legend().get_visible() if ax.get_legend() else None
+            ),
+            "tick_params": {},
+        }
+        axes_props.append(ax_props)
+
+        ax.grid(False)
+        for spine in ax.spines.values():
+            spine.set_color(HITMAP_AXES_COLOR)
+        ax.set_facecolor(HITMAP_BACKGROUND_COLOR)
+        ax.tick_params(colors=HITMAP_AXES_COLOR, labelcolor=HITMAP_AXES_COLOR)
+        ax.xaxis.label.set_color(HITMAP_AXES_COLOR)
+        ax.yaxis.label.set_color(HITMAP_AXES_COLOR)
+        ax.title.set_color(HITMAP_AXES_COLOR)
+        if ax.get_legend():
+            ax.get_legend().set_visible(False)
+
+    original_props.append(
+        {
+            "type": "_figure_patch",
+            "facecolor": fig.patch.get_facecolor(),
+            "axes_props": axes_props,
+        }
+    )
+    fig.patch.set_facecolor(HITMAP_BACKGROUND_COLOR)
+
+    return color_map, original_props
+
+
+def restore_figure_props(original_props: List[Dict[str, Any]]):
+    """
+    Restore figure properties after hitmap rendering.
+
+    Parameters
+    ----------
+    original_props : list
+        List of property dicts from prepare_hitmap_figure().
+    """
+    for props in original_props:
+        if props.get("type") == "_figure_patch":
+            if "axes_props" in props:
+                for ax_props in props["axes_props"]:
+                    ax = ax_props["ax"]
+                    ax.set_facecolor(ax_props["facecolor"])
+                    for spine_name, visible in ax_props["spines_visible"].items():
+                        ax.spines[spine_name].set_visible(visible)
+                    ax.set_xlabel(ax_props["xlabel"])
+                    ax.set_ylabel(ax_props["ylabel"])
+                    ax.set_title(ax_props["title"])
+                    if ax_props["legend_visible"] is not None and ax.get_legend():
+                        ax.get_legend().set_visible(ax_props["legend_visible"])
+            continue
+
+        artist = props.get("artist")
+        if not artist:
+            continue
+
+        try:
+            if "color" in props and hasattr(artist, "set_color"):
+                artist.set_color(props["color"])
+            if "facecolor" in props and hasattr(artist, "set_facecolor"):
+                artist.set_facecolor(props["facecolor"])
+            if "edgecolor" in props and hasattr(artist, "set_edgecolor"):
+                artist.set_edgecolor(props["edgecolor"])
+            if "alpha" in props and hasattr(artist, "set_alpha"):
+                artist.set_alpha(props["alpha"])
+            if "antialiased" in props and hasattr(artist, "set_antialiased"):
+                artist.set_antialiased(props["antialiased"])
+        except Exception:
+            pass
+
+
+# EOF