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

scitex/plt/utils/_hitmap/_color_conversion.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_hitmap/_color_conversion.py
+
+"""
+Color conversion functions for hitmap ID encoding.
+
+This module provides functions to convert between element IDs and RGB colors
+for pixel-perfect element identification in hit maps.
+"""
+
+import colorsys
+import hashlib
+from typing import Tuple
+
+__all__ = [
+    "id_to_rgb",
+    "rgb_to_id",
+    "rgb_to_id_lookup",
+]
+
+# Hand-picked palette for first 12 elements (most common case)
+DISTINCT_COLORS = [
+    (255, 0, 0),  # 1: Red
+    (0, 200, 0),  # 2: Green
+    (0, 100, 255),  # 3: Blue
+    (255, 200, 0),  # 4: Yellow/Gold
+    (255, 0, 200),  # 5: Magenta/Pink
+    (0, 220, 220),  # 6: Cyan
+    (255, 100, 0),  # 7: Orange
+    (150, 0, 255),  # 8: Purple
+    (0, 255, 100),  # 9: Spring Green
+    (255, 100, 150),  # 10: Salmon/Rose
+    (100, 255, 0),  # 11: Lime
+    (100, 150, 255),  # 12: Sky Blue
+]
+
+
+def id_to_rgb(element_id: int) -> Tuple[int, int, int]:
+    """
+    Convert element ID to unique, human-readable RGB color.
+
+    Uses a hash function to generate visually distinct colors that are:
+    1. Deterministic (same ID always gives same color)
+    2. Visually distinct (spread across the color space)
+    3. Bright and saturated (easy to see)
+
+    The first 12 elements use a hand-picked palette for maximum distinctness.
+    Beyond that, uses hash-based HSV generation with high saturation.
+
+    Parameters
+    ----------
+    element_id : int
+        Element ID (1-based). ID 0 is reserved for background.
+
+    Returns
+    -------
+    tuple
+        (R, G, B) values (0-255)
+    """
+    if element_id <= 0:
+        return (0, 0, 0)  # Background
+
+    if element_id <= len(DISTINCT_COLORS):
+        return DISTINCT_COLORS[element_id - 1]
+
+    # For IDs > 12, use hash-based color generation
+    hash_bytes = hashlib.md5(str(element_id).encode()).digest()
+
+    # Use hash bytes to generate HSV values
+    hue = int.from_bytes(hash_bytes[0:2], "big") / 65535.0
+    saturation = 0.7 + (int.from_bytes(hash_bytes[2:3], "big") / 255.0) * 0.3
+    value = 0.75 + (int.from_bytes(hash_bytes[3:4], "big") / 255.0) * 0.25
+
+    r, g, b = colorsys.hsv_to_rgb(hue, saturation, value)
+    return (int(r * 255), int(g * 255), int(b * 255))
+
+
+def rgb_to_id(r: int, g: int, b: int) -> int:
+    """
+    Convert RGB color back to element ID using 24-bit encoding.
+
+    Parameters
+    ----------
+    r, g, b : int
+        RGB values (0-255)
+
+    Returns
+    -------
+    int
+        Element ID
+    """
+    return (r << 16) | (g << 8) | b
+
+
+def rgb_to_id_lookup(r: int, g: int, b: int, color_map: dict) -> int:
+    """
+    Convert RGB color back to element ID using the color map.
+
+    Since we use human-readable colors, we need to look up in the map.
+
+    Parameters
+    ----------
+    r, g, b : int
+        RGB values (0-255)
+    color_map : dict
+        Color map from generate_hitmap_id_colors (maps ID -> info with 'rgb' key)
+
+    Returns
+    -------
+    int
+        Element ID, or 0 if not found
+    """
+    rgb = [r, g, b]
+    for element_id, info in color_map.items():
+        if info.get("rgb") == rgb:
+            return element_id
+    return 0
+
+
+# EOF

scitex/plt/utils/_hitmap/_constants.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_hitmap/_constants.py
+
+"""
+Constants and type conversion utilities for hitmap generation.
+"""
+
+from typing import Any
+
+import numpy as np
+
+# Reserved colors for hitmap (human-readable)
+HITMAP_BACKGROUND_COLOR = "#1a1a1a"  # Dark gray (not pure black, easier to see)
+HITMAP_AXES_COLOR = "#404040"  # Medium gray (non-selectable axes elements)
+
+
+def to_native(obj: Any) -> Any:
+    """Convert numpy types to native Python types for JSON serialization."""
+    if isinstance(obj, np.integer):
+        return int(obj)
+    elif isinstance(obj, np.floating):
+        return float(obj)
+    elif isinstance(obj, np.ndarray):
+        return obj.tolist()
+    elif isinstance(obj, dict):
+        return {k: to_native(v) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [to_native(v) for v in obj]
+    return obj
+
+
+__all__ = [
+    "HITMAP_BACKGROUND_COLOR",
+    "HITMAP_AXES_COLOR",
+    "to_native",
+]
+
+
+# EOF

scitex/plt/utils/_hitmap/_hitmap_core.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_hitmap/_hitmap_core.py
+
+"""
+Core hitmap generation functions.
+
+This module provides the main hitmap generation functions using unique ID colors
+for pixel-perfect element selection.
+"""
+
+import io
+from typing import TYPE_CHECKING, Any, Dict, Tuple
+
+import numpy as np
+
+from ._artist_extraction import get_all_artists
+from ._color_application import apply_id_color
+from ._color_conversion import id_to_rgb
+from ._constants import HITMAP_AXES_COLOR, HITMAP_BACKGROUND_COLOR
+
+if TYPE_CHECKING:
+    from PIL import Image
+
+__all__ = [
+    "generate_hitmap_id_colors",
+    "generate_hitmap_with_bbox_tight",
+]
+
+
+def generate_hitmap_id_colors(
+    fig,
+    dpi: int = 100,
+    include_text: bool = False,
+) -> Tuple[np.ndarray, Dict[int, Dict[str, Any]]]:
+    """
+    Generate a hit map using unique ID colors (fastest method).
+
+    Assigns unique RGB colors to each element, renders once, and creates
+    a pixel-perfect hit map where each pixel's RGB values encode the
+    element ID using 24-bit color space (~16.7M unique IDs).
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to generate hit map for.
+    dpi : int
+        Resolution for hit map rendering.
+    include_text : bool
+        Whether to include text elements in hit map.
+
+    Returns
+    -------
+    tuple
+        (hitmap_array, color_map) where:
+        - hitmap_array: uint32 array with element IDs (0 = background)
+        - color_map: dict mapping ID to element info
+
+    Notes
+    -----
+    Performance: ~89ms for complex figures (33x faster than sequential)
+    """
+    artists = get_all_artists(fig, include_text)
+
+    if not artists:
+        h = int(fig.get_figheight() * dpi)
+        w = int(fig.get_figwidth() * dpi)
+        return np.zeros((h, w), dtype=np.uint32), {}
+
+    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 and disable anti-aliasing
+        try:
+            apply_id_color(artist, hex_color)
+        except Exception:
+            pass
+
+    # Make non-artist elements the reserved axes color
+    axes_color = HITMAP_AXES_COLOR
+    for ax in fig.axes:
+        ax.grid(False)
+        for spine in ax.spines.values():
+            spine.set_color(axes_color)
+        ax.set_facecolor(HITMAP_BACKGROUND_COLOR)
+        ax.tick_params(colors=axes_color, labelcolor=axes_color)
+        ax.xaxis.label.set_color(axes_color)
+        ax.yaxis.label.set_color(axes_color)
+        ax.title.set_color(axes_color)
+        if ax.get_legend():
+            ax.get_legend().set_visible(False)
+
+    fig.patch.set_facecolor(HITMAP_BACKGROUND_COLOR)
+
+    # Render
+    fig.canvas.draw()
+    img = np.array(fig.canvas.buffer_rgba())
+    # Convert RGB to element ID using 24-bit encoding
+    hitmap = (
+        (img[:, :, 0].astype(np.uint32) << 16)
+        | (img[:, :, 1].astype(np.uint32) << 8)
+        | img[:, :, 2].astype(np.uint32)
+    )
+
+    # Restore original 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"])
+        except Exception:
+            pass
+
+    return hitmap, color_map
+
+
+def generate_hitmap_with_bbox_tight(
+    fig,
+    dpi: int = 150,
+    include_text: bool = False,
+) -> Tuple["Image.Image", Dict[int, Dict[str, Any]]]:
+    """
+    Generate a hitmap image with bbox_inches='tight' to match PNG output.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The figure to generate hit map for.
+    dpi : int
+        Resolution for hit map rendering.
+    include_text : bool
+        Whether to include text elements in hit map.
+
+    Returns
+    -------
+    tuple
+        (hitmap_image, color_map) where:
+        - hitmap_image: PIL.Image.Image with RGB-encoded element IDs
+        - color_map: dict mapping ID to element info
+    """
+    from PIL import Image
+
+    artists = get_all_artists(fig, include_text)
+
+    if not artists:
+        buf = io.BytesIO()
+        fig.savefig(buf, format="png", dpi=dpi, bbox_inches="tight")
+        buf.seek(0)
+        img = Image.open(buf).convert("RGB")
+        black_img = Image.new("RGB", img.size, (0, 0, 0))
+        return black_img, {}
+
+    original_props = []
+    original_ax_props = []
+
+    # Store original axes properties
+    for ax in fig.axes:
+        ax_props = {
+            "ax": ax,
+            "facecolor": ax.get_facecolor(),
+            "grid_visible": (
+                ax.xaxis.get_gridlines()[0].get_visible()
+                if ax.xaxis.get_gridlines()
+                else False
+            ),
+            "spines": {name: spine.get_visible() for name, spine in ax.spines.items()},
+            "xlabel": ax.get_xlabel(),
+            "ylabel": ax.get_ylabel(),
+            "title": ax.get_title(),
+            "tick_params": {},
+        }
+        if ax.get_legend():
+            ax_props["legend_visible"] = ax.get_legend().get_visible()
+        original_ax_props.append(ax_props)
+
+    original_fig_facecolor = fig.patch.get_facecolor()
+
+    # Build color map
+    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
+
+    # Make non-artist elements reserved axes color
+    axes_color = HITMAP_AXES_COLOR
+    for ax in fig.axes:
+        ax.grid(False)
+        for spine in ax.spines.values():
+            spine.set_color(axes_color)
+        ax.set_facecolor(HITMAP_BACKGROUND_COLOR)
+        ax.tick_params(colors=axes_color, labelcolor=axes_color)
+        ax.xaxis.label.set_color(axes_color)
+        ax.yaxis.label.set_color(axes_color)
+        ax.title.set_color(axes_color)
+        if ax.get_legend():
+            ax.get_legend().set_visible(False)
+
+    fig.patch.set_facecolor(HITMAP_BACKGROUND_COLOR)
+
+    # Save hitmap with bbox_inches='tight'
+    buf = io.BytesIO()
+    fig.savefig(
+        buf,
+        format="png",
+        dpi=dpi,
+        bbox_inches="tight",
+        facecolor=HITMAP_BACKGROUND_COLOR,
+    )
+    buf.seek(0)
+    hitmap_img = Image.open(buf).convert("RGB")
+
+    # Restore original 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"])
+        except Exception:
+            pass
+
+    # Restore axes properties
+    for ax_props in original_ax_props:
+        ax = ax_props["ax"]
+        try:
+            ax.set_facecolor(ax_props["facecolor"])
+            for name, visible in ax_props["spines"].items():
+                ax.spines[name].set_visible(visible)
+            ax.set_xlabel(ax_props["xlabel"])
+            ax.set_ylabel(ax_props["ylabel"])
+            ax.set_title(ax_props["title"])
+            if "legend_visible" in ax_props and ax.get_legend():
+                ax.get_legend().set_visible(ax_props["legend_visible"])
+        except Exception:
+            pass
+
+    fig.patch.set_facecolor(original_fig_facecolor)
+
+    return hitmap_img, color_map
+
+
+# EOF