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

scitex/plt/_subplots/_AxisWrapperMixins/_SeabornMixin/_wrappers.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-12-13 (ywatanabe)"
 # File: _wrappers.py - Seaborn plot wrappers
 
@@ -113,20 +112,16 @@ class SeabornWrappersMixin:
             "sns_boxplot", data=data, x=x, y=y, track=track, id=id, **kwargs
         )
 
-        # Post-processing: Style boxplot with black medians
+        # Post-processing: Style boxplot elements (0.2mm black lines)
         from scitex.plt.utils import mm_to_pt
 
         lw_pt = mm_to_pt(0.2)
-
         for line in self._axis_mpl.get_lines():
             line.set_linewidth(lw_pt)
-            xdata = line.get_xdata()
-            ydata = line.get_ydata()
-            if len(xdata) == 2 and len(ydata) == 2:
-                if ydata[0] == ydata[1]:
-                    x_span = abs(xdata[1] - xdata[0])
-                    if x_span < 0.4:
-                        line.set_color("black")
+            line.set_color("black")
+        for patch in self._axis_mpl.patches:
+            patch.set_linewidth(lw_pt)
+            patch.set_edgecolor("black")
 
         if strip:
             strip_kwargs = kwargs.copy()

scitex/plt/docs/EXTERNAL_PACKAGE_BRANDING.md

@@ -0,0 +1,149 @@
+# External Package Branding Guide
+
+When scitex wraps external packages (like `figrecipe` for `scitex.plt` or `crossref-local` for `scitex.scholar`), those packages should support configurable branding so documentation and error messages show the scitex namespace.
+
+## When to Use Branding
+
+- **Use branding**: External packages that scitex wraps (figrecipe, crossref-local, etc.)
+- **Don't use branding**: Internal scitex modules (scitex.audio, scitex.stats, etc.) - just hardcode `SCITEX_*` prefix
+
+## Pattern Overview
+
+The external package provides a `_branding.py` module that:
+1. Reads brand name from environment variable
+2. Derives environment variable prefix from brand name
+3. Provides helper functions for rebranding text/docstrings
+
+## Implementation Template
+
+```python
+# external_package/_branding.py
+
+import os
+import re
+from typing import Optional
+
+# Environment variables for branding
+# Parent package sets these before importing
+BRAND_NAME = os.environ.get("{PACKAGE}_BRAND", "{package}")
+BRAND_ALIAS = os.environ.get("{PACKAGE}_ALIAS", "{alias}")
+
+# Original values for replacement
+_ORIGINAL_NAME = "{package}"
+_ORIGINAL_ALIAS = "{alias}"
+
+
+def _brand_to_env_prefix(brand: str) -> str:
+    """Convert brand name to environment variable prefix.
+
+    Examples:
+        "figrecipe" -> "FIGRECIPE"
+        "scitex.plt" -> "SCITEX_PLT"
+        "crossref-local" -> "CROSSREF_LOCAL"
+    """
+    return brand.upper().replace(".", "_").replace("-", "_")
+
+
+# Environment variable prefix based on brand
+ENV_PREFIX = _brand_to_env_prefix(BRAND_NAME)
+
+
+def get_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Get environment variable with brand-aware prefix.
+
+    Checks {ENV_PREFIX}_{key} first, then falls back to original prefix.
+    """
+    value = os.environ.get(f"{ENV_PREFIX}_{key}")
+    if value is not None:
+        return value
+
+    # Fall back to original prefix if different
+    original_prefix = _brand_to_env_prefix(_ORIGINAL_NAME)
+    if ENV_PREFIX != original_prefix:
+        value = os.environ.get(f"{original_prefix}_{key}")
+        if value is not None:
+            return value
+
+    return default
+
+
+def rebrand_text(text: Optional[str]) -> Optional[str]:
+    """Apply branding to a text string (docstrings, error messages)."""
+    if text is None:
+        return None
+
+    if BRAND_NAME == _ORIGINAL_NAME and BRAND_ALIAS == _ORIGINAL_ALIAS:
+        return text
+
+    result = text
+
+    # Replace import statements
+    result = re.sub(
+        rf"import\s+{_ORIGINAL_NAME}\s+as\s+{_ORIGINAL_ALIAS}",
+        f"import {BRAND_NAME} as {BRAND_ALIAS}",
+        result,
+    )
+
+    # Replace "from package" statements
+    result = re.sub(
+        rf"from\s+{_ORIGINAL_NAME}(\s+import|\s*\.)",
+        lambda m: f"from {BRAND_NAME}{m.group(1)}",
+        result,
+    )
+
+    return result
+
+
+def get_mcp_server_name() -> str:
+    """Get the MCP server name based on branding."""
+    return BRAND_NAME.replace(".", "-")
+```
+
+## Usage in Parent Package (scitex)
+
+```python
+# scitex/plt/__init__.py
+import os
+
+# Set branding BEFORE importing the external package
+os.environ["FIGRECIPE_BRAND"] = "scitex.plt"
+os.environ["FIGRECIPE_ALIAS"] = "plt"
+
+# Now import - docstrings will show scitex.plt instead of figrecipe
+from figrecipe import *
+```
+
+## Port Scheme
+
+SciTeX uses port scheme 3129X (sa-i-te-ku-su → 3-1-2-9 in Japanese):
+
+| Port  | Service          |
+|-------|------------------|
+| 31290 | scitex-cloud     |
+| 31291 | crossref-local   |
+| 31292 | openalex         |
+| 31293 | scitex-audio     |
+
+## Environment Variable Pattern
+
+External packages should use `{ENV_PREFIX}_{SETTING}`:
+
+```
+SCITEX_PLT_MODE=local
+CROSSREF_LOCAL_API_URL=http://localhost:31291
+SCITEX_AUDIO_RELAY_URL=http://localhost:31293
+```
+
+## Example: crossref-local
+
+See GitHub Issue: https://github.com/ywatanabe1989/crossref-local/issues/11
+
+The crossref-local package should implement:
+- `CROSSREF_LOCAL_BRAND` / `CROSSREF_LOCAL_ALIAS` env vars
+- Dynamic `ENV_PREFIX` derived from brand name
+- When used via scitex.scholar, shows `scitex.scholar` in docs
+
+## References
+
+- figrecipe/_branding.py - Reference implementation
+- scitex/audio/_branding.py - Simple internal module (no rebranding needed)

scitex/plt/gallery/README.md

@@ -1,7 +1,7 @@
 <!-- ---
 !-- Timestamp: 2025-12-08 23:59:46
 !-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/plt/gallery/README.md
+!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/gallery/README.md
 !-- --- -->
 
 # SciTeX Plot Gallery

scitex/plt/utils/_hitmap/__init__.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/plt/utils/_hitmap/__init__.py
+
+"""
+Hit map generation utilities for interactive element selection.
+
+This package provides functions to generate hit maps for matplotlib figures,
+enabling pixel-perfect element selection in web editors and interactive tools.
+
+Supported methods:
+1. ID Colors: Single render with unique colors per element (~89ms)
+2. Export Path Data: Extract geometry for client-side hit testing (~192ms)
+
+Reserved colors:
+- Black (#000000, ID=0): Background/no element
+- Dark gray (#010101, ID=65793): Non-selectable axes elements (spines, labels, ticks)
+"""
+
+from ._artist_extraction import (
+    detect_logical_groups,
+    get_all_artists,
+    get_all_artists_with_groups,
+)
+from ._color_application import (
+    apply_hitmap_colors,
+    apply_id_color,
+    prepare_hitmap_figure,
+    restore_figure_props,
+    restore_original_colors,
+)
+from ._color_conversion import id_to_rgb, rgb_to_id, rgb_to_id_lookup
+from ._constants import HITMAP_AXES_COLOR, HITMAP_BACKGROUND_COLOR, to_native
+from ._hitmap_core import generate_hitmap_id_colors, generate_hitmap_with_bbox_tight
+from ._path_extraction import extract_path_data, extract_selectable_regions
+from ._query import query_hitmap_neighborhood, save_hitmap_png
+
+# Backward compatibility aliases
+_to_native = to_native
+_id_to_rgb = id_to_rgb
+_rgb_to_id = rgb_to_id
+_rgb_to_id_lookup = rgb_to_id_lookup
+_apply_id_color = apply_id_color
+_prepare_hitmap_figure = prepare_hitmap_figure
+_restore_figure_props = restore_figure_props
+
+__all__ = [
+    # Constants
+    "HITMAP_BACKGROUND_COLOR",
+    "HITMAP_AXES_COLOR",
+    # Artist extraction
+    "get_all_artists",
+    "get_all_artists_with_groups",
+    "detect_logical_groups",
+    # Color conversion
+    "id_to_rgb",
+    "rgb_to_id",
+    "rgb_to_id_lookup",
+    # Core hitmap generation
+    "generate_hitmap_id_colors",
+    "generate_hitmap_with_bbox_tight",
+    # Path extraction
+    "extract_path_data",
+    "extract_selectable_regions",
+    # Query and save
+    "query_hitmap_neighborhood",
+    "save_hitmap_png",
+    # Color application
+    "apply_hitmap_colors",
+    "restore_original_colors",
+    # Backward compatibility
+    "_to_native",
+    "_id_to_rgb",
+    "_rgb_to_id",
+    "_rgb_to_id_lookup",
+    "_apply_id_color",
+    "_prepare_hitmap_figure",
+    "_restore_figure_props",
+]
+
+
+# EOF

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