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

scitex/plt/styles/SCITEX_STYLE.yaml

@@ -102,3 +102,29 @@ behavior:
   hide_right_spine: true # Hide right spine
   grid: false            # Show grid
 
+# =============================================================================
+# THEME / COLOR MODE
+# =============================================================================
+# Dark mode uses eye-friendly colors optimized for dark backgrounds
+# Light mode uses standard black on white (default matplotlib behavior)
+theme:
+  mode: "light"          # "light" or "dark"
+
+  # Dark mode color palette (eye-friendly, reduced strain)
+  dark:
+    background: "transparent"  # Figure background (transparent by default)
+    axes_bg: "#1a1a2e"         # Axes background (deep navy-black)
+    text: "#e8e8e8"            # Text, labels, titles (soft white)
+    spine: "#4a4a5a"           # Axis spines (muted gray)
+    tick: "#e8e8e8"            # Tick marks and labels
+    grid: "#3a3a4a"            # Grid lines (subtle)
+
+  # Light mode color palette (publication standard)
+  light:
+    background: "transparent"  # Figure background
+    axes_bg: "white"           # Axes background
+    text: "black"              # Text, labels, titles
+    spine: "black"             # Axis spines
+    tick: "black"              # Tick marks and labels
+    grid: "#cccccc"            # Grid lines
+

scitex/plt/styles/__init__.py

@@ -37,6 +37,13 @@ from .presets import (
     set_style,
     get_style,
     resolve_style_value,
+    # DPI utilities
+    get_default_dpi,
+    get_display_dpi,
+    get_preview_dpi,
+    DPI_SAVE,
+    DPI_DISPLAY,
+    DPI_PREVIEW,
 )
 
 __all__ = [
@@ -51,6 +58,13 @@ __all__ = [
     "set_style",
     "get_style",
     "resolve_style_value",
+    # DPI utilities
+    "get_default_dpi",
+    "get_display_dpi",
+    "get_preview_dpi",
+    "DPI_SAVE",
+    "DPI_DISPLAY",
+    "DPI_PREVIEW",
 ]
 
 

scitex/plt/styles/presets.py

@@ -40,6 +40,13 @@ __all__ = [
     "set_style",
     "get_style",
     "resolve_style_value",
+    # DPI utilities
+    "get_default_dpi",
+    "get_display_dpi",
+    "get_preview_dpi",
+    "DPI_SAVE",
+    "DPI_DISPLAY",
+    "DPI_PREVIEW",
 ]
 
 from pathlib import Path
@@ -79,6 +86,77 @@ def resolve_style_value(
     return _get_config().resolve(key, direct_val, default, type)
 
 
+# =============================================================================
+# DPI Resolution - Central Source of Truth
+# =============================================================================
+#
+# DPI Priority Chain:
+#   1. Bundle's geometry_px.json (highest - existing figure's actual DPI)
+#   2. User override / session setting
+#   3. SCITEX_STYLE.yaml output.dpi (project default)
+#   4. Hardcoded fallback (only if config missing)
+#
+# Usage:
+#   from scitex.plt.styles import get_default_dpi, DPI_SAVE
+#
+#   # For saving figures (publication quality)
+#   fig.savefig("out.png", dpi=get_default_dpi())
+#
+#   # For display/preview (lower resolution)
+#   fig.savefig("preview.png", dpi=get_display_dpi())
+#
+#   # When loading from bundle, use bundle's DPI:
+#   dpi = bundle.get("geometry", {}).get("dpi") or get_default_dpi()
+#
+
+# Fallback values (only used if config unavailable)
+_FALLBACK_DPI_SAVE = 300
+_FALLBACK_DPI_DISPLAY = 100
+_FALLBACK_DPI_PREVIEW = 150
+
+
+def get_default_dpi() -> int:
+    """Get default DPI for saving/publication from config.
+
+    Priority: SCITEX_STYLE.yaml → env var → fallback 300
+
+    Returns:
+        int: DPI value for publication-quality output
+    """
+    return int(resolve_style_value("output.dpi", None, _FALLBACK_DPI_SAVE, int))
+
+
+def get_display_dpi() -> int:
+    """Get DPI for screen display (lower resolution for speed).
+
+    Returns approximately 1/3 of save DPI, minimum 100.
+
+    Returns:
+        int: DPI value for screen display
+    """
+    save_dpi = get_default_dpi()
+    return max(_FALLBACK_DPI_DISPLAY, save_dpi // 3)
+
+
+def get_preview_dpi() -> int:
+    """Get DPI for editor previews and thumbnails.
+
+    Returns 1/2 of save DPI, clamped between 100-200.
+
+    Returns:
+        int: DPI value for previews
+    """
+    save_dpi = get_default_dpi()
+    return max(_FALLBACK_DPI_DISPLAY, min(200, save_dpi // 2))
+
+
+# Module-level constants (evaluated at import time)
+# Use functions for dynamic resolution, constants for static defaults
+DPI_SAVE = _FALLBACK_DPI_SAVE      # Use get_default_dpi() for dynamic
+DPI_DISPLAY = _FALLBACK_DPI_DISPLAY
+DPI_PREVIEW = _FALLBACK_DPI_PREVIEW
+
+
 def load_style(path: Optional[Union[str, Path]] = None) -> Dict[str, Any]:
     """Load style from YAML as subplots kwargs."""
     cfg = _get_config(Path(path) if path else None)

scitex/plt/utils/__init__.py

@@ -6,7 +6,7 @@ from ._calc_nice_ticks import calc_nice_ticks
 from ._close import close
 from ._colorbar import add_shared_colorbar, colorbar
 from ._configure_mpl import configure_mpl
-from ._figure_mm import apply_style_mm, create_figure_ax_mm
+from ._figure_mm import apply_style_mm, create_figure_ax_mm, THEME_COLORS, _apply_theme_colors
 from ._histogram_utils import HistogramBinManager, histogram_bin_manager
 from ._im2grid import im2grid
 from ._is_valid_axis import assert_valid_axis, is_valid_axis
@@ -48,6 +48,13 @@ from ._csv_column_naming import (
     parse_csv_column_name,
     sanitize_trace_id,
 )
+from ._hitmap import (
+    extract_path_data,
+    generate_hitmap_id_colors,
+    get_all_artists,
+    query_hitmap_neighborhood,
+    save_hitmap_png,
+)
 
 __all__ = [
     "HistogramBinManager",
@@ -79,6 +86,9 @@ __all__ = [
     "cross_ref",
     "enhance_scitex_save_with_captions",
     "export_captions",
+    "extract_path_data",
+    "generate_hitmap_id_colors",
+    "get_all_artists",
     "get_csv_column_name",
     "get_csv_column_prefix",
     "get_dimension_info",
@@ -94,8 +104,10 @@ __all__ = [
     "parse_csv_column_name",
     "print_dimension_info",
     "pt_to_mm",
+    "query_hitmap_neighborhood",
     "quick_caption",
     "sanitize_trace_id",
+    "save_hitmap_png",
     "save_with_caption",
     "verify_csv_json_consistency",
     "view_dimensions",

scitex/plt/utils/_collect_figure_metadata.py

@@ -15,6 +15,10 @@ __FILE__ = __file__
 
 from typing import Dict, Optional, Union, List
 
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
 # Precision settings for JSON output
 PRECISION = {
     "mm": 2,      # Millimeters: 0.01mm precision (10 microns)
@@ -205,8 +209,7 @@ def _collect_single_axes_metadata(fig, ax, ax_index: int) -> dict:
             }
 
     except Exception as e:
-        import warnings
-        warnings.warn(f"Could not extract dimension info for axes {ax_index}: {e}")
+        logger.warning(f"Could not extract dimension info for axes {ax_index}: {e}")
 
     # Extract axes labels and units
     # X-axis - using matplotlib terminology (xaxis)
@@ -444,8 +447,7 @@ def collect_figure_metadata(fig, ax=None) -> Dict:
             if "axes_bbox_mm" in dim_info:
                 metadata["axes_bbox_mm"] = dim_info["axes_bbox_mm"]
         except Exception as e:
-            import warnings
-            warnings.warn(f"Could not extract figure dimension info: {e}")
+            logger.warning(f"Could not extract figure dimension info: {e}")
 
     # Collect per-axes metadata
     if all_axes:
@@ -461,8 +463,7 @@ def collect_figure_metadata(fig, ax=None) -> Dict:
                     ax_metadata["grid_position"] = {"row": row, "col": col}
                     metadata["axes"][ax_key] = ax_metadata
             except Exception as e:
-                import warnings
-                warnings.warn(f"Could not extract metadata for {ax_key}: {e}")
+                logger.warning(f"Could not extract metadata for {ax_key}: {e}")
 
     # Add scitex-specific metadata if axes was tagged
     scitex_meta = None
@@ -542,11 +543,8 @@ def collect_figure_metadata(fig, ax=None) -> Dict:
                         f"For {requested_font}: sudo apt-get install ttf-mscorefonts-installer && fc-cache -fv"
                     )
                 except ImportError:
-                    import warnings
-
-                    warnings.warn(
-                        f"Font mismatch: Requested '{requested_font}' but using '{actual_font}'",
-                        UserWarning,
+                    logger.warning(
+                        f"Font mismatch: Requested '{requested_font}' but using '{actual_font}'"
                     )
         else:
             # If no style section, add font info to runtime section
@@ -688,9 +686,7 @@ def collect_figure_metadata(fig, ax=None) -> Dict:
 
         except Exception as e:
             # If Phase 1 extraction fails, continue without it
-            import warnings
-
-            warnings.warn(f"Could not extract Phase 1 metadata: {e}")
+            logger.warning(f"Could not extract Phase 1 metadata: {e}")
 
     # Apply precision rounding to all numeric values
     metadata = _round_metadata(metadata)

scitex/plt/utils/_configure_mpl.py

@@ -318,25 +318,13 @@ def configure_mpl(
             )
 
             # Warn user about missing Arial using scitex.logging
-            try:
-                from scitex.logging import getLogger
+            from scitex import logging as _logging
 
-                logger = getLogger(__name__)
-                logger.warning(
-                    "Arial font not found. Using fallback fonts (Helvetica/DejaVu Sans). "
-                    "For publication figures with Arial: sudo apt-get install ttf-mscorefonts-installer && fc-cache -fv"
-                )
-            except ImportError:
-                # Fallback to warnings if scitex.logging not available
-                import warnings
-
-                warnings.warn(
-                    "Arial font not found on system. Using fallback fonts (Helvetica/DejaVu Sans). "
-                    "For publication-quality figures with Arial, install Microsoft Core Fonts: "
-                    "sudo apt-get install ttf-mscorefonts-installer && fc-cache -fv",
-                    UserWarning,
-                    stacklevel=2,
-                )
+            _logger = _logging.getLogger(__name__)
+            _logger.warning(
+                "Arial font not found. Using fallback fonts (Helvetica/DejaVu Sans). "
+                "For publication figures with Arial: sudo apt-get install ttf-mscorefonts-installer && fc-cache -fv"
+            )
 
         # Suppress matplotlib's own font warnings
         import logging

scitex/plt/utils/_crop.py

@@ -97,6 +97,7 @@ def crop(
     overwrite: bool = False,
     verbose: bool = False,
     return_offset: bool = False,
+    crop_box: Optional[Tuple[int, int, int, int]] = None,
 ) -> str:
     """
     Crop a figure image to its content area with a specified margin.
@@ -113,7 +114,8 @@ def crop(
         Path to save the cropped image. If None and overwrite=True,
         overwrites the input. If None and overwrite=False, adds '_cropped' suffix.
     margin : int, optional
-        Margin in pixels to add around the content area (default: 12, ~1mm at 300 DPI)
+        Margin in pixels to add around the content area (default: 12, ~1mm at 300 DPI).
+        Only used when crop_box is None (auto-detection mode).
     overwrite : bool, optional
         Whether to overwrite the input file (default: False)
     verbose : bool, optional
@@ -121,6 +123,10 @@ def crop(
     return_offset : bool, optional
         If True, also return the crop offset (left, upper) for metadata adjustment.
         Default is False.
+    crop_box : tuple, optional
+        Explicit crop coordinates (left, upper, right, lower). If provided,
+        skips auto-detection and uses these exact coordinates for cropping.
+        This is useful for applying the same crop to multiple images (e.g., hitmap).
 
     Returns
     -------
@@ -144,6 +150,11 @@ def crop(
 
     >>> # Or crop in place
     >>> stx.plt.crop("figure.png", overwrite=True)
+
+    >>> # Apply explicit crop coordinates (e.g., for hitmap)
+    >>> _, offset = stx.plt.crop("figure.png", return_offset=True)
+    >>> crop_box = (offset['left'], offset['upper'], offset['right'], offset['lower'])
+    >>> stx.plt.crop("hitmap.png", crop_box=crop_box)
     """
     # Determine output path
     if output_path is None:
@@ -164,19 +175,26 @@ def crop(
         if "dpi" in img.info:
             print(f"Original DPI: {img.info['dpi']}")
 
-    # Find the content area (returns left, upper, right, lower)
-    left, upper, right, lower = find_content_area(input_path)
-
-    if verbose:
-        print(
-            f"Content area detected at: left={left}, upper={upper}, right={right}, lower={lower}"
-        )
-
-    # Calculate the coordinates with margin, clamping to the image boundaries
-    left = max(left - margin, 0)
-    upper = max(upper - margin, 0)
-    right = min(right + margin, img.width)
-    lower = min(lower + margin, img.height)
+    # Use explicit crop_box if provided, otherwise auto-detect
+    if crop_box is not None:
+        # Use explicit crop coordinates (no margin adjustment - use as-is)
+        left, upper, right, lower = crop_box
+        if verbose:
+            print(f"Using explicit crop_box: left={left}, upper={upper}, right={right}, lower={lower}")
+    else:
+        # Find the content area (returns left, upper, right, lower)
+        left, upper, right, lower = find_content_area(input_path)
+
+        if verbose:
+            print(
+                f"Content area detected at: left={left}, upper={upper}, right={right}, lower={lower}"
+            )
+
+        # Calculate the coordinates with margin, clamping to the image boundaries
+        left = max(left - margin, 0)
+        upper = max(upper - margin, 0)
+        right = min(right + margin, img.width)
+        lower = min(lower + margin, img.height)
 
     if verbose:
         print(f"Cropping to: left={left}, upper={upper}, right={right}, lower={lower}")

scitex/plt/utils/_csv_column_naming.py

@@ -40,6 +40,7 @@ __all__ = [
     "get_csv_column_prefix",
     "parse_csv_column_name",
     "sanitize_trace_id",
+    "get_unique_trace_id",
 ]
 
 
@@ -91,6 +92,59 @@ def sanitize_trace_id(trace_id: str) -> str:
     return sanitized if sanitized else "unnamed"
 
 
+def get_unique_trace_id(trace_id: str, existing_ids: set) -> str:
+    """Get unique trace ID, adding suffix if collision detected.
+
+    This function ensures trace IDs remain unique even when multiple traces
+    have IDs that sanitize to the same value (e.g., "A" and "a" both become "a").
+    When a collision is detected, suffixes are added: a -> a-1 -> a-2, etc.
+
+    Parameters
+    ----------
+    trace_id : str
+        Raw trace identifier
+    existing_ids : set
+        Set of already-used trace IDs (will be modified in-place)
+
+    Returns
+    -------
+    str
+        Unique sanitized trace ID
+
+    Examples
+    --------
+    >>> ids = set()
+    >>> get_unique_trace_id("A", ids)
+    'a'
+    >>> ids
+    {'a'}
+    >>> get_unique_trace_id("a", ids)  # collision!
+    'a-1'
+    >>> ids
+    {'a', 'a-1'}
+    >>> get_unique_trace_id("A ", ids)  # another collision!
+    'a-2'
+    >>> ids
+    {'a', 'a-1', 'a-2'}
+    >>> get_unique_trace_id("B", ids)  # no collision
+    'b'
+    """
+    base_id = sanitize_trace_id(trace_id)
+
+    if base_id not in existing_ids:
+        existing_ids.add(base_id)
+        return base_id
+
+    # Find unique suffix
+    counter = 1
+    while f"{base_id}-{counter}" in existing_ids:
+        counter += 1
+
+    unique_id = f"{base_id}-{counter}"
+    existing_ids.add(unique_id)
+    return unique_id
+
+
 def get_csv_column_prefix(
     ax_row: int = 0, ax_col: int = 0, trace_id: str = None, trace_index: int = None
 ) -> str:

scitex/plt/utils/_figure_mm.py

@@ -10,11 +10,13 @@ This module provides functions to create matplotlib figures and axes with
 precise millimeter-based control over dimensions, margins, and styling.
 This is particularly useful for creating publication-quality figures that
 need to meet specific size requirements (e.g., Nature, Science journals).
+
+Supports dark/light theme modes for eye-friendly visualization.
 """
 
 __FILE__ = __file__
 
-from typing import Dict, Optional, Tuple, TYPE_CHECKING
+from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
 
 import matplotlib.pyplot as plt
 from matplotlib.axes import Axes
@@ -22,6 +24,111 @@ from matplotlib.figure import Figure
 
 from ._units import mm_to_inch, mm_to_pt
 
+# Default theme color palettes
+# Both modes use transparent background by default for flexibility
+# Dark mode: all text elements (labels, ticks, spines) use same soft white color
+# Light mode: all text elements use black
+THEME_COLORS = {
+    "dark": {
+        "background": "transparent",   # Transparent for overlay on dark backgrounds
+        "axes_bg": "transparent",      # Transparent axes background
+        "text": "#e8e8e8",             # Soft white (reduced strain)
+        "spine": "#e8e8e8",            # Same as text (like black in light mode)
+        "tick": "#e8e8e8",             # Same as text
+        "grid": "#3a3a4a",             # Subtle grid
+    },
+    "light": {
+        "background": "transparent",  # Transparent for overlay on light backgrounds
+        "axes_bg": "transparent",      # Transparent axes background
+        "text": "black",               # Black text
+        "spine": "black",              # Black spines
+        "tick": "black",               # Black ticks
+        "grid": "#cccccc",             # Light gray grid
+    },
+}
+
+
+def _apply_theme_colors(
+    ax: Axes,
+    theme: str = "light",
+    custom_colors: Optional[Dict[str, str]] = None
+) -> None:
+    """
+    Apply theme colors to axes for dark/light mode support.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes to apply theme to
+    theme : str
+        Color theme: "light" or "dark" (default: "light")
+    custom_colors : dict, optional
+        Custom color overrides. Keys: background, axes_bg, text, spine, tick, grid
+
+    Examples
+    --------
+    >>> fig, ax = plt.subplots()
+    >>> _apply_theme_colors(ax, theme="dark")  # Eye-friendly dark mode
+    """
+    # Get base theme colors
+    colors = THEME_COLORS.get(theme, THEME_COLORS["light"]).copy()
+
+    # Apply custom overrides
+    if custom_colors:
+        colors.update(custom_colors)
+
+    # Apply axes background
+    if colors["axes_bg"] != "transparent":
+        ax.set_facecolor(colors["axes_bg"])
+        ax.patch.set_alpha(1.0)
+    else:
+        ax.patch.set_alpha(0.0)
+
+    # Apply figure background if accessible
+    fig = ax.get_figure()
+    if fig is not None:
+        if colors["background"] != "transparent":
+            fig.patch.set_facecolor(colors["background"])
+            fig.patch.set_alpha(1.0)
+        else:
+            fig.patch.set_alpha(0.0)
+
+    # Apply text colors (labels, titles)
+    ax.xaxis.label.set_color(colors["text"])
+    ax.yaxis.label.set_color(colors["text"])
+    ax.title.set_color(colors["text"])
+
+    # Apply spine colors
+    for spine in ax.spines.values():
+        spine.set_color(colors["spine"])
+
+    # Apply tick colors (both marks and labels)
+    ax.tick_params(colors=colors["tick"], which="both")
+    for label in ax.get_xticklabels() + ax.get_yticklabels():
+        label.set_color(colors["tick"])
+
+    # Apply legend colors if legend exists
+    legend = ax.get_legend()
+    if legend is not None:
+        # Legend text color
+        for text in legend.get_texts():
+            text.set_color(colors["text"])
+        # Legend title if present
+        title = legend.get_title()
+        if title:
+            title.set_color(colors["text"])
+        # Legend frame
+        frame = legend.get_frame()
+        if frame:
+            if colors["axes_bg"] != "transparent":
+                frame.set_facecolor(colors["axes_bg"])
+            frame.set_edgecolor(colors["spine"])
+
+    # Store theme in axes metadata for reference
+    if hasattr(ax, "_scitex_metadata"):
+        ax._scitex_metadata["theme"] = theme
+        ax._scitex_metadata["theme_colors"] = colors
+
 if TYPE_CHECKING:
     from scitex.plt._subplots._FigWrapper import FigWrapper
     from scitex.plt._subplots._AxisWrapper import AxisWrapper
@@ -197,6 +304,8 @@ def apply_style_mm(ax: Axes, style: Dict) -> float:
         - 'axis_font_size_pt' (float): Axis label font size in points (default: 8)
         - 'tick_font_size_pt' (float): Tick label font size in points (default: 7)
         - 'n_ticks' (int): Number of ticks on each axis (default: 4)
+        - 'theme' (str): Color theme "light" or "dark" (default: "light")
+        - 'theme_colors' (dict): Custom theme color overrides
 
     Returns
     -------
@@ -213,6 +322,7 @@ def apply_style_mm(ax: Axes, style: Dict) -> float:
     ...     'tick_thickness_mm': 0.2,
     ...     'axis_font_size_pt': 7,
     ...     'tick_font_size_pt': 7,
+    ...     'theme': 'dark',  # Enable dark mode
     ... }
     >>> trace_lw = apply_style_mm(ax, style)
     >>> ax.plot(x, y, lw=trace_lw)
@@ -224,6 +334,11 @@ def apply_style_mm(ax: Axes, style: Dict) -> float:
     - The returned trace linewidth should be used when plotting to maintain
       consistent styling across all plot elements
     """
+    # Apply theme colors (dark/light mode)
+    theme = style.get("theme", "light")
+    theme_colors = style.get("theme_colors", None)
+    _apply_theme_colors(ax, theme, theme_colors)
+
     # Convert spine thickness from mm to points
     axis_lw_pt = mm_to_pt(style.get("axis_thickness_mm", 0.2))
     for spine in ax.spines.values():