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

scitex/plt/utils/_hitmap.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-# Timestamp: "2025-12-12 (ywatanabe)"
-# File: scitex/plt/utils/_hitmap.py
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_hitmap.py
 
 """
 Hit map generation utilities for interactive element selection.
@@ -20,1624 +19,55 @@ Based on experimental results (see FIGZ_PLTZ_STATSZ.md):
 Reserved colors:
 - Black (#000000, ID=0): Background/no element
 - Dark gray (#010101, ID=65793): Non-selectable axes elements (spines, labels, ticks)
+
+This module re-exports all functions from the _hitmap package for backward
+compatibility. The actual implementation is in the _hitmap/ subpackage.
 """
 
-import warnings
-from typing import Dict, List, Any, Optional, Tuple
-import numpy as np
+# Re-export all public API from the _hitmap package
+from ._hitmap import (
+    HITMAP_AXES_COLOR,
+    HITMAP_BACKGROUND_COLOR,
+    _apply_id_color,
+    _id_to_rgb,
+    _prepare_hitmap_figure,
+    _restore_figure_props,
+    _rgb_to_id_lookup,
+    _to_native,
+    apply_hitmap_colors,
+    detect_logical_groups,
+    extract_path_data,
+    extract_selectable_regions,
+    generate_hitmap_id_colors,
+    generate_hitmap_with_bbox_tight,
+    get_all_artists,
+    get_all_artists_with_groups,
+    query_hitmap_neighborhood,
+    restore_original_colors,
+    save_hitmap_png,
+)
 
 __all__ = [
-    'get_all_artists',
-    'get_all_artists_with_groups',
-    'detect_logical_groups',
-    'generate_hitmap_id_colors',
-    'extract_path_data',
-    'extract_selectable_regions',
-    'query_hitmap_neighborhood',
-    'save_hitmap_png',
-    'apply_hitmap_colors',
-    'restore_original_colors',
-    'generate_hitmap_with_bbox_tight',
-    'HITMAP_BACKGROUND_COLOR',
-    'HITMAP_AXES_COLOR',
-    '_rgb_to_id_lookup',
+    "get_all_artists",
+    "get_all_artists_with_groups",
+    "detect_logical_groups",
+    "generate_hitmap_id_colors",
+    "extract_path_data",
+    "extract_selectable_regions",
+    "query_hitmap_neighborhood",
+    "save_hitmap_png",
+    "apply_hitmap_colors",
+    "restore_original_colors",
+    "generate_hitmap_with_bbox_tight",
+    "HITMAP_BACKGROUND_COLOR",
+    "HITMAP_AXES_COLOR",
+    "_rgb_to_id_lookup",
+    "_to_native",
+    "_id_to_rgb",
+    "_apply_id_color",
+    "_prepare_hitmap_figure",
+    "_restore_figure_props",
 ]
 
 
-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
-
-
-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:
-        {
-            "histogram_0": {
-                "type": "histogram",
-                "label": "...",
-                "axes_index": 0,
-                "artists": [list of matplotlib artists],
-                "role": "logical"
-            },
-            ...
-        }
-    """
-    groups = {}
-    group_counter = {}  # Track count per type for unique IDs
-
-    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):
-        # 1. Detect BarContainers (covers bar charts and histograms)
-        # First, count how many BarContainers exist on this axis
-        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:
-                # Determine if it's a histogram, grouped bar series, or simple categorical bar
-                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:
-                    # Check if bars are adjacent (no gaps between them)
-                    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)]
-                        # If gaps are very small relative to bar width, it's a histogram
-                        avg_width = sum(widths) / len(widths)
-                        is_histogram = all(abs(g) < avg_width * 0.1 for g in gaps)
-
-                if is_histogram:
-                    # Histogram: group all bins together
-                    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:
-                    # Multiple bar containers = grouped bar chart
-                    # Group bars by series (each container is a series)
-                    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),
-                    }
-
-                # else: Single bar container with spaced bars = simple categorical bar chart
-                # Don't create a group - each bar is standalone and selectable individually
-
-            elif 'ErrorbarContainer' in container_type:
-                # Error bar container
-                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),
-                }
-
-        # 2. Detect box plots (look for specific pattern of artists)
-        # Box plots create: boxes (Rectangle), whiskers (Line2D), caps (Line2D),
-        # medians (Line2D), fliers (Line2D)
-        # They are typically created via ax.bxp() or ax.boxplot()
-        if hasattr(ax, '_boxplot_info'):
-            # Some matplotlib versions store boxplot info
-            pass  # Handle if available
-
-        # 3. 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),
-            }
-
-        # 4. Detect contour sets (multiple PolyCollections from same contour call)
-        # Contours typically have collections with increasing/decreasing levels
-        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:
-            # Likely a contour plot
-            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.
-
-    This is an enhanced version of get_all_artists() that also detects and
-    returns logical groups (e.g., histogram bins grouped as one element).
-
-    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
-
-    Examples
-    --------
-    >>> artists, groups = get_all_artists_with_groups(fig)
-    >>> for artist, ax_idx, atype, group_id in artists:
-    ...     if group_id:
-    ...         print(f"{atype} belongs to group {group_id}")
-    """
-    # First, detect logical groups
-    groups = detect_logical_groups(fig)
-
-    # Create a mapping from artist to group_id
-    artist_to_group = {}
-    for group_id, group_info in groups.items():
-        for artist in group_info['artists']:
-            artist_to_group[id(artist)] = group_id
-
-    # Now get all artists with group information
-    artists_with_groups = []
-
-    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
-                group_id = artist_to_group.get(id(line))
-                artists_with_groups.append((line, ax_idx, 'line', group_id))
-
-        # Scatter plots (PathCollection)
-        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 - handle both container level and individual patches
-        processed_patches = set()
-        for container in ax.containers:
-            if hasattr(container, 'patches') and container.patches:
-                # Check if first patch belongs to a group
-                group_id = artist_to_group.get(id(container.patches[0]))
-
-                if group_id:
-                    # Grouped bars (histogram or bar_series): add container as single element
-                    artists_with_groups.append((container, ax_idx, 'bar', group_id))
-                    # Mark patches as processed
-                    for patch in container.patches:
-                        processed_patches.add(id(patch))
-                else:
-                    # Simple categorical bar: add each patch individually (standalone)
-                    for patch in container.patches:
-                        artists_with_groups.append((patch, ax_idx, 'rectangle', None))
-                        processed_patches.add(id(patch))
-
-        # Individual patches (rectangles, circles, etc.) not in containers
-        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 (optional)
-        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
-
-
-def _id_to_rgb(element_id: int) -> Tuple[int, int, int]:
-    """
-    Convert element ID to unique, human-readable RGB color using hash-based generation.
-
-    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)
-
-    Notes
-    -----
-    The hash ensures:
-    - Same element_id always maps to the same color
-    - Colors are well-distributed across the spectrum
-    - Avoids dark colors (reserved for background/axes)
-    """
-    import colorsys
-    import hashlib
-
-    if element_id <= 0:
-        return (0, 0, 0)  # Background
-
-    # Hand-picked palette for first 12 elements (most common case)
-    # These are maximally distinct primary/secondary colors
-    DISTINCT_COLORS = [
-        (255, 0, 0),      # 1: Red
-        (0, 200, 0),      # 2: Green (slightly darker for visibility)
-        (0, 100, 255),    # 3: Blue (lighter for visibility)
-        (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
-    ]
-
-    if element_id <= len(DISTINCT_COLORS):
-        return DISTINCT_COLORS[element_id - 1]
-
-    # For IDs > 12, use hash-based color generation
-    # Hash the ID to get a pseudo-random but deterministic value
-    hash_bytes = hashlib.md5(str(element_id).encode()).digest()
-
-    # Use hash bytes to generate HSV values
-    # Hue: full range (0-1) for variety
-    hue = int.from_bytes(hash_bytes[0:2], 'big') / 65535.0
-
-    # Saturation: high (0.7-1.0) for vivid colors
-    saturation = 0.7 + (int.from_bytes(hash_bytes[2:3], 'big') / 255.0) * 0.3
-
-    # Value: high (0.75-1.0) to avoid dark colors
-    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_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
-
-
-# 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 _rgb_to_id(r: int, g: int, b: int) -> int:
-    """Convert RGB color back to element ID."""
-    return (r << 16) | (g << 8) | b
-
-
-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)
-    Uses RGB 24-bit encoding for up to ~16.7 million unique element IDs.
-    """
-    import matplotlib.pyplot as plt
-    import copy
-
-    # Get all artists
-    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), {}
-
-    # Store original properties for restoration
-    original_props = []
-
-    # Build color map
-    color_map = {}
-
-    for i, (artist, ax_idx, artist_type) in enumerate(artists):
-        element_id = i + 1
-        # Use full RGB 24-bit encoding for unique ID colors
-        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 (use element_id as key)
-        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 (NOT black)
-    # This distinguishes axes from background while making them non-selectable
-    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 _apply_id_color(artist, hex_color: str):
-    """Apply ID color to an artist, handling different artist types."""
-    artist_type = type(artist).__name__
-
-    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 _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.
-
-    This function modifies the figure in-place by:
-    1. Assigning unique RGB colors to each artist (24-bit ID encoding)
-    2. Hiding non-selectable elements (axes, spines, grid, etc.)
-    3. Setting background to black (ID = 0)
-
-    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 artist properties (for restoration)
-
-    Notes
-    -----
-    After calling this function, you can render the figure using savefig()
-    with bbox_inches='tight' to get a pixel-perfect hitmap.
-    Call _restore_figure_props(original_props) to restore the figure.
-    """
-    artists = get_all_artists(fig, include_text)
-
-    if not artists:
-        return {}, []
-
-    # Store original properties for restoration
-    original_props = []
-
-    # Build color map
-    color_map = {}
-
-    for i, (artist, ax_idx, artist_type) in enumerate(artists):
-        element_id = i + 1
-        # Use full RGB 24-bit encoding for unique ID colors
-        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
-
-    # Hide non-artist elements (we need to save these for restoration too)
-    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': {},  # Complex to save/restore, skip for now
-        }
-        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)
-
-    # Save figure background
-    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':
-            # Restore axes and figure background
-            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
-
-
-def extract_path_data(
-    fig,
-    include_text: bool = False,
-) -> Dict[str, Any]:
-    """
-    Extract path/geometry data for client-side hit testing.
-
-    Extracts bounding boxes and path coordinates for all selectable elements,
-    enabling JavaScript-based hit testing in web editors.
-
-    Parameters
-    ----------
-    fig : matplotlib.figure.Figure
-        The figure to extract data from.
-    include_text : bool
-        Whether to include text elements.
-
-    Returns
-    -------
-    dict
-        Exported data structure with figure info and artist geometries.
-
-    Notes
-    -----
-    Performance: ~192ms extraction, ~0.01ms client-side queries
-    Supports: resize/zoom (transform coordinates client-side)
-    """
-    with warnings.catch_warnings():
-        warnings.filterwarnings("ignore", message=".*tight_layout.*")
-        fig.canvas.draw()  # Ensure transforms are computed
-
-    artists = get_all_artists(fig, include_text)
-
-    dpi = fig.dpi
-    fig_width_px = int(fig.get_figwidth() * dpi)
-    fig_height_px = int(fig.get_figheight() * dpi)
-
-    export = {
-        'figure': {
-            'width_px': fig_width_px,
-            'height_px': fig_height_px,
-            'dpi': dpi,
-        },
-        'axes': [],
-        'artists': [],
-    }
-
-    # Export axes info
-    for ax in fig.axes:
-        bbox = ax.get_position()
-        export['axes'].append({
-            'xlim': list(ax.get_xlim()),
-            'ylim': list(ax.get_ylim()),
-            'bbox_norm': {
-                'x0': bbox.x0,
-                'y0': bbox.y0,
-                'x1': bbox.x1,
-                'y1': bbox.y1,
-            },
-            'bbox_px': {
-                'x0': int(bbox.x0 * fig_width_px),
-                'y0': int((1 - bbox.y1) * fig_height_px),
-                'x1': int(bbox.x1 * fig_width_px),
-                'y1': int((1 - bbox.y0) * fig_height_px),
-            },
-        })
-
-    # Export artist geometries
-    renderer = fig.canvas.get_renderer()
-
-    for i, (artist, ax_idx, artist_type) in enumerate(artists):
-        artist_data = {
-            'id': i,
-            'type': artist_type,
-            'axes_index': ax_idx,
-            'label': '',
-        }
-
-        # Get label
-        if hasattr(artist, 'get_label'):
-            label = artist.get_label()
-            artist_data['label'] = label if not label.startswith('_') else f'{artist_type}_{i}'
-
-        # Get bounding box
-        try:
-            bbox = artist.get_window_extent(renderer)
-            artist_data['bbox_px'] = {
-                'x0': float(bbox.x0),
-                'y0': float(fig_height_px - bbox.y1),  # Flip Y
-                'x1': float(bbox.x1),
-                'y1': float(fig_height_px - bbox.y0),
-            }
-        except Exception:
-            artist_data['bbox_px'] = None
-
-        # Extract type-specific geometry
-        try:
-            if artist_type == 'line' and hasattr(artist, 'get_xydata'):
-                xy = artist.get_xydata()
-                transform = artist.get_transform()
-                xy_px = transform.transform(xy)
-                # Flip Y and limit points for JSON size
-                xy_px[:, 1] = fig_height_px - xy_px[:, 1]
-                # Sample if too many points
-                if len(xy_px) > 100:
-                    indices = np.linspace(0, len(xy_px) - 1, 100, dtype=int)
-                    xy_px = xy_px[indices]
-                artist_data['path_px'] = xy_px.tolist()
-                artist_data['linewidth'] = artist.get_linewidth()
-
-            elif artist_type == 'scatter' and hasattr(artist, 'get_offsets'):
-                offsets = artist.get_offsets()
-                transform = artist.get_transform()
-                offsets_px = transform.transform(offsets)
-                offsets_px[:, 1] = fig_height_px - offsets_px[:, 1]
-                artist_data['points_px'] = offsets_px.tolist()
-                sizes = artist.get_sizes()
-                artist_data['sizes'] = sizes.tolist() if len(sizes) > 0 else [36]
-
-            elif artist_type == 'fill' and hasattr(artist, 'get_paths'):
-                paths = artist.get_paths()
-                if paths:
-                    transform = artist.get_transform()
-                    vertices = paths[0].vertices
-                    vertices_px = transform.transform(vertices)
-                    vertices_px[:, 1] = fig_height_px - vertices_px[:, 1]
-                    # Sample if too many vertices
-                    if len(vertices_px) > 100:
-                        indices = np.linspace(0, len(vertices_px) - 1, 100, dtype=int)
-                        vertices_px = vertices_px[indices]
-                    artist_data['polygon_px'] = vertices_px.tolist()
-
-            elif artist_type == 'bar' and hasattr(artist, 'patches'):
-                bars = []
-                ax = fig.axes[ax_idx]
-                for patch in artist.patches:
-                    # Get data coordinates
-                    x_data = patch.get_x()
-                    y_data = patch.get_y()
-                    w_data = patch.get_width()
-                    h_data = patch.get_height()
-                    bars.append({
-                        'x': x_data,
-                        'y': y_data,
-                        'width': w_data,
-                        'height': h_data,
-                    })
-                artist_data['bars_data'] = bars
-
-            elif artist_type == 'rectangle':
-                artist_data['rectangle'] = {
-                    'x': artist.get_x(),
-                    'y': artist.get_y(),
-                    'width': artist.get_width(),
-                    'height': artist.get_height(),
-                }
-
-        except Exception as e:
-            artist_data['error'] = str(e)
-
-        export['artists'].append(artist_data)
-
-    # Convert all numpy types to native Python for JSON serialization
-    return _to_native(export)
-
-
-def extract_selectable_regions(fig) -> Dict[str, Any]:
-    """
-    Extract bounding boxes for axis/annotation elements (non-data elements).
-
-    This provides a complementary approach to the color-based hitmap:
-    - Data elements: Use hitmap color lookup (pixel-perfect)
-    - Axis elements: Use bounding box hit testing (calculated)
-
-    The client-side hit test logic:
-    1. Check selectable_regions bounding boxes first (fast rectangle test)
-    2. If no match, sample hitmap color for data elements
-
-    Parameters
-    ----------
-    fig : matplotlib.figure.Figure
-        The figure to extract regions from.
-
-    Returns
-    -------
-    dict
-        Dictionary with selectable regions:
-        {
-            "axes": [{
-                "index": 0,
-                "title": {"bbox_px": [x0, y0, x1, y1], "text": "..."},
-                "xlabel": {"bbox_px": [...], "text": "..."},
-                "ylabel": {"bbox_px": [...], "text": "..."},
-                "xaxis": {
-                    "spine": {"bbox_px": [...]},
-                    "ticks": [{"bbox_px": [...], "position": 0.0}, ...],
-                    "ticklabels": [{"bbox_px": [...], "text": "0"}, ...]
-                },
-                "yaxis": {...},
-                "legend": {
-                    "bbox_px": [...],
-                    "entries": [{"bbox_px": [...], "label": "Series A"}, ...]
-                }
-            }]
-        }
-    """
-    with warnings.catch_warnings():
-        warnings.filterwarnings("ignore", message=".*tight_layout.*")
-        fig.canvas.draw()  # Ensure transforms are computed
-
-    dpi = fig.dpi
-    fig_width_px = int(fig.get_figwidth() * dpi)
-    fig_height_px = int(fig.get_figheight() * dpi)
-
-    renderer = fig.canvas.get_renderer()
-
-    def get_bbox_px(artist) -> Optional[List[float]]:
-        """Get bounding box in pixels (y-flipped for image coordinates)."""
-        try:
-            bbox = artist.get_window_extent(renderer)
-            if bbox.width > 0 and bbox.height > 0:
-                return [
-                    float(bbox.x0),
-                    float(fig_height_px - bbox.y1),  # Flip Y
-                    float(bbox.x1),
-                    float(fig_height_px - bbox.y0),
-                ]
-        except Exception:
-            pass
-        return None
-
-    def get_text_info(text_artist) -> Optional[Dict[str, Any]]:
-        """Extract text element info with bounding box."""
-        if text_artist is None:
-            return None
-        text = text_artist.get_text()
-        if not text or not text.strip():
-            return None
-        bbox = get_bbox_px(text_artist)
-        if bbox is None:
-            return None
-        return {
-            "bbox_px": bbox,
-            "text": text,
-            "fontsize": text_artist.get_fontsize(),
-            "color": text_artist.get_color(),
-        }
-
-    regions = {"axes": []}
-
-    for ax_idx, ax in enumerate(fig.axes):
-        ax_region = {"index": ax_idx}
-
-        # Title
-        title_info = get_text_info(ax.title)
-        if title_info:
-            ax_region["title"] = title_info
-
-        # X label
-        xlabel_info = get_text_info(ax.xaxis.label)
-        if xlabel_info:
-            ax_region["xlabel"] = xlabel_info
-
-        # Y label
-        ylabel_info = get_text_info(ax.yaxis.label)
-        if ylabel_info:
-            ax_region["ylabel"] = ylabel_info
-
-        # X axis elements
-        xaxis_info = {"spine": None, "ticks": [], "ticklabels": []}
-
-        # X spine (bottom)
-        if ax.spines['bottom'].get_visible():
-            spine_bbox = get_bbox_px(ax.spines['bottom'])
-            if spine_bbox:
-                xaxis_info["spine"] = {"bbox_px": spine_bbox}
-
-        # X ticks and tick labels
-        for tick in ax.xaxis.get_major_ticks():
-            # Tick mark
-            if tick.tick1line.get_visible():
-                tick_bbox = get_bbox_px(tick.tick1line)
-                if tick_bbox:
-                    xaxis_info["ticks"].append({
-                        "bbox_px": tick_bbox,
-                        "position": float(tick.get_loc()) if hasattr(tick, 'get_loc') else None,
-                    })
-
-            # Tick label
-            if tick.label1.get_visible():
-                label_info = get_text_info(tick.label1)
-                if label_info:
-                    xaxis_info["ticklabels"].append(label_info)
-
-        if xaxis_info["spine"] or xaxis_info["ticks"] or xaxis_info["ticklabels"]:
-            ax_region["xaxis"] = xaxis_info
-
-        # Y axis elements
-        yaxis_info = {"spine": None, "ticks": [], "ticklabels": []}
-
-        # Y spine (left)
-        if ax.spines['left'].get_visible():
-            spine_bbox = get_bbox_px(ax.spines['left'])
-            if spine_bbox:
-                yaxis_info["spine"] = {"bbox_px": spine_bbox}
-
-        # Y ticks and tick labels
-        for tick in ax.yaxis.get_major_ticks():
-            # Tick mark
-            if tick.tick1line.get_visible():
-                tick_bbox = get_bbox_px(tick.tick1line)
-                if tick_bbox:
-                    yaxis_info["ticks"].append({
-                        "bbox_px": tick_bbox,
-                        "position": float(tick.get_loc()) if hasattr(tick, 'get_loc') else None,
-                    })
-
-            # Tick label
-            if tick.label1.get_visible():
-                label_info = get_text_info(tick.label1)
-                if label_info:
-                    yaxis_info["ticklabels"].append(label_info)
-
-        if yaxis_info["spine"] or yaxis_info["ticks"] or yaxis_info["ticklabels"]:
-            ax_region["yaxis"] = yaxis_info
-
-        # Legend
-        legend = ax.get_legend()
-        if legend and legend.get_visible():
-            legend_info = {"bbox_px": None, "entries": []}
-
-            legend_bbox = get_bbox_px(legend)
-            if legend_bbox:
-                legend_info["bbox_px"] = legend_bbox
-
-            # Legend entries
-            for text in legend.get_texts():
-                entry_info = get_text_info(text)
-                if entry_info:
-                    legend_info["entries"].append(entry_info)
-
-            # Legend handles (the visual markers)
-            try:
-                handles = legend.legendHandles
-                for i, handle in enumerate(handles):
-                    handle_bbox = get_bbox_px(handle)
-                    if handle_bbox and i < len(legend_info["entries"]):
-                        legend_info["entries"][i]["handle_bbox_px"] = handle_bbox
-            except Exception:
-                pass
-
-            if legend_info["bbox_px"] or legend_info["entries"]:
-                ax_region["legend"] = legend_info
-
-        regions["axes"].append(ax_region)
-
-    # Convert all numpy types to native Python for JSON serialization
-    return _to_native(regions)
-
-
-def query_hitmap_neighborhood(
-    hitmap: np.ndarray,
-    x: int,
-    y: int,
-    color_map: Dict[int, Dict[str, Any]],
-    radius: int = 2,
-) -> List[Dict[str, Any]]:
-    """
-    Query hit map with neighborhood sampling for smart selection.
-
-    Finds all element IDs in a neighborhood around the click point,
-    enabling selection of overlapping elements and thin lines.
-
-    Parameters
-    ----------
-    hitmap : np.ndarray
-        Hit map array (uint32, element IDs from RGB encoding).
-    x : int
-        X coordinate (column) of click point.
-    y : int
-        Y coordinate (row) of click point.
-    color_map : dict
-        Mapping from element ID to element info.
-    radius : int
-        Sampling radius (e.g., 2 = 5×5 neighborhood).
-
-    Returns
-    -------
-    list of dict
-        List of element info dicts for all elements found in neighborhood,
-        sorted by distance from click point (closest first).
-
-    Notes
-    -----
-    Use cases:
-    - Alt+Click to select objects underneath (lower z-order)
-    - Click on thin lines that might be missed with exact pixel
-    - Show candidate list when multiple elements overlap
-    """
-    h, w = hitmap.shape
-    found_ids = set()
-    id_distances = {}
-
-    # Sample neighborhood
-    for dy in range(-radius, radius + 1):
-        for dx in range(-radius, radius + 1):
-            ny, nx = y + dy, x + dx
-            if 0 <= ny < h and 0 <= nx < w:
-                element_id = int(hitmap[ny, nx])
-                if element_id > 0 and element_id in color_map:
-                    found_ids.add(element_id)
-                    # Track minimum distance for each ID
-                    dist = abs(dx) + abs(dy)  # Manhattan distance
-                    if element_id not in id_distances or dist < id_distances[element_id]:
-                        id_distances[element_id] = dist
-
-    # Sort by distance (closest first), then by ID for stability
-    sorted_ids = sorted(found_ids, key=lambda eid: (id_distances[eid], eid))
-
-    return [color_map[eid] for eid in sorted_ids]
-
-
-def save_hitmap_png(hitmap: np.ndarray, path: str, color_map: Dict = None):
-    """
-    Save hit map as a PNG file (RGB encoding for 24-bit IDs).
-
-    Parameters
-    ----------
-    hitmap : np.ndarray
-        Hit map array (uint32, element IDs from 24-bit RGB encoding).
-    path : str
-        Output path for PNG file.
-    color_map : dict, optional
-        Color map for visualization.
-    """
-    import matplotlib.pyplot as plt
-    from PIL import Image
-
-    # Convert 24-bit IDs back to RGB for PNG storage
-    h, w = hitmap.shape
-    rgb = np.zeros((h, w, 3), dtype=np.uint8)
-    rgb[:, :, 0] = (hitmap >> 16) & 0xFF  # R
-    rgb[:, :, 1] = (hitmap >> 8) & 0xFF   # G
-    rgb[:, :, 2] = hitmap & 0xFF          # B
-
-    # Save as RGB PNG (preserves exact ID values)
-    img = Image.fromarray(rgb, mode='RGB')
-    img.save(path)
-
-
-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.
-
-    This function modifies data elements (lines, patches, etc.) to have unique
-    RGB colors for hit testing, while keeping axes/spines/labels unchanged.
-    This preserves the bbox_inches='tight' bounding box calculation.
-
-    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 for restoration
-        - color_map: dict mapping ID to element info (includes group_id, role)
-        - groups: dict mapping group_id to logical group info
-    """
-    # Get artists with group information
-    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}'
-
-        # Determine role based on group membership
-        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,  # NEW: logical group this element belongs to
-            'role': role,  # NEW: 'physical' (part of group), 'standalone' (no group), or 'logical' (is a group)
-        }
-
-        # Apply ID color
-        try:
-            _apply_id_color(artist, hex_color)
-        except Exception:
-            pass
-
-    # Add RGB color to groups for logical selection
-    # Groups get IDs starting after all physical elements
-    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 (from apply_hitmap_colors).
-    """
-    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 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.
-
-    This function generates a hitmap that exactly matches the PNG saved with
-    bbox_inches='tight'. The key insight is that both PNG and hitmap must use
-    the same savefig parameters to have identical cropping.
-
-    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
-    """
-    import matplotlib.pyplot as plt
-    from PIL import Image
-    import io
-    import tempfile
-
-    # Get all artists
-    artists = get_all_artists(fig, include_text)
-
-    if not artists:
-        # Return empty black image with same size as PNG would have
-        buf = io.BytesIO()
-        fig.savefig(buf, format='png', dpi=dpi, bbox_inches='tight')
-        buf.seek(0)
-        img = Image.open(buf).convert('RGB')
-        # Create black image of same size
-        black_img = Image.new('RGB', img.size, (0, 0, 0))
-        return black_img, {}
-
-    # Store original properties for restoration
-    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': {
-                'left': ax.yaxis.get_tick_params()['left'] if hasattr(ax.yaxis.get_tick_params(), '__getitem__') else True,
-                'bottom': ax.xaxis.get_tick_params()['bottom'] if hasattr(ax.xaxis.get_tick_params(), '__getitem__') else True,
-            },
-        }
-        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 a reserved "axes" color (NOT black/invisible)
-    # This preserves bbox_inches='tight' bounds while distinguishing from background
-    # Use HITMAP_AXES_COLOR (#010101) which maps to ID 65793 (non-selectable)
-    axes_color = HITMAP_AXES_COLOR
-    for ax in fig.axes:
-        ax.grid(False)
-        # Make spines the reserved axes color instead of black
-        for spine in ax.spines.values():
-            spine.set_color(axes_color)
-        ax.set_facecolor(HITMAP_BACKGROUND_COLOR)  # Keep facecolor as background
-        # Make tick labels the reserved axes color
-        ax.tick_params(colors=axes_color, labelcolor=axes_color)
-        # Make axis labels the reserved axes color
-        ax.xaxis.label.set_color(axes_color)
-        ax.yaxis.label.set_color(axes_color)
-        # Make title the reserved 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' - SAME as PNG
-    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