scitex 2.7.3__py3-none-any.whl → 2.10.0__py3-none-any.whl

scitex/fig/editor/_mpl_editor.py

@@ -228,7 +228,7 @@ class MplEditor:
 
     def _save(self, event):
         """Save to .manual.json."""
-        from ._edit import save_manual_overrides
+        from .edit import save_manual_overrides
 
         try:
             manual_path = save_manual_overrides(self.json_path, self.current_overrides)

scitex/fig/editor/_qt_editor.py

@@ -1017,7 +1017,7 @@ class QtEditorWindow:
 
     def _save_manual(self):
         """Save to .manual.json."""
-        from ._edit import save_manual_overrides
+        from .edit import save_manual_overrides
 
         try:
             self._collect_overrides()

scitex/fig/editor/_tkinter_editor.py

@@ -490,7 +490,7 @@ class TkinterEditor:
 
     def _save_manual(self):
         """Save current overrides to .manual.json."""
-        from ._edit import save_manual_overrides
+        from .edit import save_manual_overrides
 
         try:
             manual_path = save_manual_overrides(self.json_path, self.current_overrides)

scitex/fig/editor/edit/__init__.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-14 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fig/editor/edit/__init__.py
+
+"""Edit module for launching visual figure editors.
+
+This module provides the main edit() function and supporting utilities for:
+- Backend detection and selection (flask, dearpygui, qt, tkinter, mpl)
+- Path resolution for figure files (.json, .csv, .png)
+- Bundle resolution for .pltz and .figz formats
+- Panel data loading for multi-panel figures
+- Manual override handling (.manual.json)
+"""
+
+from .editor_launcher import edit
+from .backend_detector import (
+    detect_best_backend,
+    print_available_backends,
+)
+from .path_resolver import resolve_figure_paths
+from .bundle_resolver import (
+    resolve_pltz_bundle,
+    resolve_figz_bundle,
+    resolve_layered_pltz_bundle,
+)
+from .panel_loader import load_panel_data
+from .manual_handler import compute_file_hash, save_manual_overrides
+
+__all__ = [
+    # Main entry point
+    "edit",
+    # Backend detection
+    "detect_best_backend",
+    "print_available_backends",
+    # Path resolution
+    "resolve_figure_paths",
+    # Bundle resolution
+    "resolve_pltz_bundle",
+    "resolve_figz_bundle",
+    "resolve_layered_pltz_bundle",
+    # Panel loading
+    "load_panel_data",
+    # Manual overrides
+    "compute_file_hash",
+    "save_manual_overrides",
+]
+
+
+# EOF

scitex/fig/editor/edit/backend_detector.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-14 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fig/editor/edit/backend_detector.py
+
+"""Backend detection and selection for figure editor."""
+
+import warnings
+
+__all__ = ["print_available_backends", "detect_best_backend"]
+
+# Backend packages mapping
+BACKENDS = {
+    "flask": ["flask"],
+    "dearpygui": ["dearpygui"],
+    "qt": ["PyQt6", "PyQt5", "PySide6", "PySide2"],
+    "tkinter": ["tkinter"],
+    "mpl": ["matplotlib"],
+}
+
+
+def print_available_backends() -> None:
+    """Print available backends status."""
+    print("\n" + "=" * 50)
+    print("SciTeX Visual Editor - Available Backends")
+    print("=" * 50)
+
+    for backend, packages in BACKENDS.items():
+        available = False
+        available_pkg = None
+        for pkg in packages:
+            try:
+                __import__(pkg)
+                available = True
+                available_pkg = pkg
+                break
+            except ImportError:
+                pass
+
+        status = f"[OK] {available_pkg}" if available else "[NOT INSTALLED]"
+        print(f"  {backend:12s}: {status}")
+
+    print("=" * 50)
+    print("Install: pip install scitex[gui]")
+    print("=" * 50 + "\n")
+
+
+def detect_best_backend() -> str:
+    """
+    Detect the best available GUI backend with graceful degradation.
+
+    Order: flask > dearpygui > qt > tkinter > mpl
+    Shows warnings when falling back to less capable backends.
+    """
+    # Try Flask - best for modern UI
+    try:
+        import flask
+        return "flask"
+    except ImportError:
+        pass
+
+    # Try DearPyGui - GPU-accelerated, modern
+    try:
+        import dearpygui
+        return "dearpygui"
+    except ImportError:
+        warnings.warn(
+            "Flask not available. Consider: pip install flask\nTrying DearPyGui..."
+        )
+
+    # Try DearPyGui again
+    try:
+        import dearpygui
+        return "dearpygui"
+    except ImportError:
+        pass
+
+    # Try Qt (richest desktop features)
+    for qt_pkg in ["PyQt6", "PyQt5", "PySide6", "PySide2"]:
+        try:
+            __import__(qt_pkg)
+            warnings.warn(
+                "DearPyGui not available. Consider: pip install dearpygui\n"
+                "Using Qt backend instead."
+            )
+            return "qt"
+        except ImportError:
+            pass
+
+    # Try Tkinter (built-in, good features)
+    try:
+        import tkinter
+        warnings.warn(
+            "Qt not available. Consider: pip install PyQt6\n"
+            "Using Tkinter backend (basic features)."
+        )
+        return "tkinter"
+    except ImportError:
+        pass
+
+    # Fall back to matplotlib interactive (always works)
+    warnings.warn(
+        "No GUI toolkit found. Using minimal matplotlib editor.\n"
+        "For better experience, install: pip install flask (web) or pip install PyQt6 (desktop)"
+    )
+    return "mpl"
+
+
+# EOF

scitex/fig/editor/edit/bundle_resolver.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-14 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fig/editor/edit/bundle_resolver.py
+
+"""Bundle path resolution for .pltz and .figz formats."""
+
+import json as json_module
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Optional, Tuple, Dict, Any
+
+__all__ = ["resolve_pltz_bundle", "resolve_figz_bundle", "resolve_layered_pltz_bundle"]
+
+
+def resolve_figz_bundle(path: Path, panel_index: int = 0) -> Tuple:
+    """
+    Resolve paths from a .figz bundle (multi-panel figure).
+
+    Uses in-memory zip reading for .pltz panels - no disk extraction.
+
+    Parameters
+    ----------
+    path : Path
+        Path to .figz bundle (.figz or .figz.d)
+    panel_index : int, optional
+        Index of panel to open (default: 0 for first panel)
+
+    Returns
+    -------
+    tuple
+        (json_path, csv_path, png_path, hitmap_path, bundle_spec, panel_info)
+    """
+    spath = str(path)
+    figz_is_zip = False
+
+    # Handle ZIP vs directory for figz
+    if spath.endswith('.figz') and not spath.endswith('.figz.d'):
+        figz_is_zip = True
+        if not path.exists():
+            raise FileNotFoundError(f"Figz bundle not found: {path}")
+        # For figz zip, extract to access nested pltz
+        temp_dir = tempfile.mkdtemp(prefix='scitex_edit_figz_')
+        with zipfile.ZipFile(path, 'r') as zf:
+            zf.extractall(temp_dir)
+        bundle_dir = Path(temp_dir)
+        for item in bundle_dir.iterdir():
+            if item.is_dir() and str(item).endswith('.figz.d'):
+                bundle_dir = item
+                break
+    else:
+        bundle_dir = Path(path)
+        if not bundle_dir.exists():
+            raise FileNotFoundError(f"Figz bundle directory not found: {bundle_dir}")
+
+    # Find nested pltz bundles
+    panel_paths = []
+    panel_is_zip = []
+
+    for item in sorted(bundle_dir.iterdir(), key=lambda x: x.name):
+        if item.is_dir() and str(item).endswith('.pltz.d'):
+            panel_paths.append(str(item))
+            panel_is_zip.append(False)
+        elif item.is_file() and str(item).endswith('.pltz'):
+            panel_paths.append(str(item))
+            panel_is_zip.append(True)
+
+    if not panel_paths:
+        raise FileNotFoundError(f"No .pltz panels found in figz bundle: {bundle_dir}")
+
+    # Validate panel index
+    if panel_index < 0 or panel_index >= len(panel_paths):
+        panel_index = 0
+
+    selected_panel_path = panel_paths[panel_index]
+    panel_name = Path(selected_panel_path).name
+    print(f"Opening panel: {panel_name}")
+    if len(panel_paths) > 1:
+        print(f"  (Figz contains {len(panel_paths)} panels)")
+
+    # Build panel info
+    panel_names = [Path(p).name for p in panel_paths]
+    panel_info = {
+        "panels": panel_names,
+        "panel_paths": panel_paths,
+        "panel_is_zip": panel_is_zip,
+        "current_index": panel_index,
+        "figz_dir": str(bundle_dir),
+        "figz_is_zip": figz_is_zip,
+        "bundle_path": str(path) if figz_is_zip else None,  # Original figz zip path for export/download
+    }
+
+    # Resolve the selected panel
+    result = resolve_pltz_bundle(Path(selected_panel_path))
+    return result + (panel_info,)
+
+
+def resolve_pltz_bundle(path: Path) -> Tuple:
+    """
+    Resolve paths from a .pltz bundle (directory or ZIP).
+
+    Supports both:
+    - Legacy format (single {basename}.json)
+    - Layered format v2.0 (spec.json + style.json + cache/)
+
+    Parameters
+    ----------
+    path : Path
+        Path to .pltz bundle (.pltz or .pltz.d)
+
+    Returns
+    -------
+    tuple
+        (json_path, csv_path, png_path, hitmap_path, bundle_spec)
+    """
+    spath = str(path)
+
+    # Handle ZIP vs directory
+    if spath.endswith('.pltz') and not spath.endswith('.pltz.d'):
+        if not path.exists():
+            raise FileNotFoundError(f"Bundle not found: {path}")
+        temp_dir = tempfile.mkdtemp(prefix='scitex_edit_')
+        with zipfile.ZipFile(path, 'r') as zf:
+            zf.extractall(temp_dir)
+        bundle_dir = Path(temp_dir)
+        for item in bundle_dir.iterdir():
+            if item.is_dir() and str(item).endswith('.pltz.d'):
+                bundle_dir = item
+                break
+    else:
+        bundle_dir = Path(path)
+        if not bundle_dir.exists():
+            raise FileNotFoundError(f"Bundle directory not found: {bundle_dir}")
+
+    # Check if this is a layered bundle (v2.0)
+    spec_path = bundle_dir / "spec.json"
+    if spec_path.exists():
+        return resolve_layered_pltz_bundle(bundle_dir)
+
+    # === Legacy format ===
+    json_path = None
+    csv_path = None
+    png_path = None
+    svg_path = None
+    hitmap_path = None
+    bundle_spec = None
+
+    for f in bundle_dir.iterdir():
+        name = f.name
+        if name.endswith('.json') and not name.endswith('.manual.json'):
+            json_path = f
+        elif name.endswith('.csv'):
+            csv_path = f
+        elif name.endswith('_hitmap.png'):
+            hitmap_path = f
+        elif name.endswith('.svg') and '_hitmap' not in name:
+            svg_path = f
+        elif name.endswith('.png') and '_hitmap' not in name and '_overview' not in name:
+            png_path = f
+
+    # Prefer SVG for display
+    if svg_path:
+        png_path = svg_path
+
+    if json_path and json_path.exists():
+        with open(json_path, 'r') as f:
+            bundle_spec = json_module.load(f)
+
+    return (
+        json_path,
+        csv_path if csv_path and csv_path.exists() else None,
+        png_path if png_path and png_path.exists() else None,
+        hitmap_path if hitmap_path and hitmap_path.exists() else None,
+        bundle_spec,
+    )
+
+
+def resolve_layered_pltz_bundle(bundle_dir: Path) -> Tuple:
+    """
+    Resolve paths from a layered .pltz bundle (v2.0 format).
+
+    Layered format structure:
+        plot.pltz.d/
+            spec.json           # Semantic
+            style.json          # Appearance
+            {basename}.csv      # Data
+            exports/            # PNG, SVG, hitmap
+            cache/              # geometry_px.json
+
+    Parameters
+    ----------
+    bundle_dir : Path
+        Path to .pltz.d bundle directory.
+
+    Returns
+    -------
+    tuple
+        (json_path, csv_path, png_path, hitmap_path, bundle_spec)
+    """
+    from scitex.plt.io import load_layered_pltz_bundle
+
+    bundle_data = load_layered_pltz_bundle(bundle_dir)
+    spec_path = bundle_dir / "spec.json"
+    csv_path = None
+    png_path = None
+    hitmap_path = None
+
+    # Find CSV
+    for f in bundle_dir.glob("*.csv"):
+        csv_path = f
+        break
+
+    # Find exports
+    exports_dir = bundle_dir / "exports"
+    if exports_dir.exists():
+        for f in exports_dir.iterdir():
+            name = f.name
+            if name.endswith('_hitmap.png'):
+                hitmap_path = f
+            elif name.endswith('.svg') and '_hitmap' not in name:
+                png_path = f
+            elif name.endswith('.png') and '_hitmap' not in name and png_path is None:
+                png_path = f
+
+    bundle_spec = bundle_data.get("merged", {})
+
+    if hitmap_path and "hit_regions" in bundle_spec:
+        bundle_spec["hit_regions"]["hit_map"] = str(hitmap_path.name)
+
+    return (
+        spec_path,
+        csv_path if csv_path and csv_path.exists() else None,
+        png_path if png_path and png_path.exists() else None,
+        hitmap_path if hitmap_path and hitmap_path.exists() else None,
+        bundle_spec,
+    )
+
+
+# EOF

scitex/fig/editor/edit/editor_launcher.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-14 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fig/editor/edit/editor_launcher.py
+
+"""Main edit function for launching visual editor."""
+
+from pathlib import Path
+from typing import Union, Literal
+
+from .backend_detector import print_available_backends, detect_best_backend
+from .path_resolver import resolve_figure_paths
+from .bundle_resolver import resolve_pltz_bundle, resolve_figz_bundle
+
+__all__ = ["edit"]
+
+
+def edit(
+    path: Union[str, Path],
+    backend: Literal["auto", "flask", "dearpygui", "qt", "tkinter", "mpl"] = "auto",
+    apply_manual: bool = True,
+    port: int = 5050,
+) -> None:
+    """
+    Launch interactive editor for figure style/annotation editing.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to figure file. Can be:
+        - .pltz.d directory bundle (recommended for hitmap selection)
+        - .pltz ZIP bundle
+        - .figz or .figz.d multi-panel bundle
+        - JSON file (figure.json or figure.manual.json)
+        - CSV file (figure.csv) - for data-only start
+        - PNG file (figure.png)
+    backend : str, optional
+        GUI backend to use (default: "auto"):
+        - "auto": Pick best available (flask -> dearpygui -> qt -> tkinter -> mpl)
+        - "flask": Browser-based editor (Flask, modern UI)
+        - "dearpygui": GPU-accelerated modern GUI
+        - "qt": Rich desktop editor (requires PyQt5/6 or PySide2/6)
+        - "tkinter": Built-in Python GUI
+        - "mpl": Minimal matplotlib interactive mode
+    apply_manual : bool, optional
+        If True, load .manual.json overrides if exists (default: True)
+    port : int, optional
+        Port number for web-based editors. Default: 5050.
+
+    Returns
+    -------
+    None
+        Editor runs in GUI event loop. Changes saved to .manual.json.
+    """
+    path = Path(path)
+    spath = str(path)
+    parent_str = str(path.parent) if path.is_file() else ""
+
+    # Panel info for multi-panel figures
+    panel_info = None
+
+    # Resolve paths based on input type
+    json_path, csv_path, png_path, hitmap_path, bundle_spec, panel_info = _resolve_paths(
+        path, spath, parent_str
+    )
+
+    if not json_path.exists():
+        raise FileNotFoundError(f"JSON file not found: {json_path}")
+
+    # Load data
+    import scitex as stx
+
+    metadata = bundle_spec if bundle_spec else stx.io.load(json_path)
+    csv_data = None
+    if csv_path and csv_path.exists():
+        csv_data = stx.io.load(csv_path)
+
+    # Load manual overrides if exists
+    manual_path = json_path.with_suffix(".manual.json")
+    manual_overrides = None
+    if apply_manual and manual_path.exists():
+        manual_data = stx.io.load(manual_path)
+        manual_overrides = manual_data.get("overrides", {})
+
+    # Resolve backend if "auto"
+    if backend == "auto":
+        backend = detect_best_backend()
+
+    # Print status
+    print_available_backends()
+    print(f"Launching {backend} editor for: {json_path}")
+
+    # Launch appropriate backend
+    _launch_backend(
+        backend=backend,
+        json_path=json_path,
+        metadata=metadata,
+        csv_data=csv_data,
+        png_path=png_path,
+        hitmap_path=hitmap_path,
+        manual_overrides=manual_overrides,
+        bundle_spec=bundle_spec,
+        panel_info=panel_info,
+        port=port,
+    )
+
+
+def _resolve_paths(path: Path, spath: str, parent_str: str) -> tuple:
+    """Resolve paths based on input type."""
+    panel_info = None
+    hitmap_path = None
+    bundle_spec = None
+
+    # Check if this is a .figz bundle (multi-panel figure)
+    if spath.endswith('.figz.d') or spath.endswith('.figz'):
+        json_path, csv_path, png_path, hitmap_path, bundle_spec, panel_info = resolve_figz_bundle(path)
+    # Check if this is a .pltz bundle
+    elif spath.endswith('.pltz.d') or spath.endswith('.pltz') or parent_str.endswith('.pltz.d'):
+        bundle_path = path.parent if parent_str.endswith('.pltz.d') else path
+        json_path, csv_path, png_path, hitmap_path, bundle_spec = resolve_pltz_bundle(bundle_path)
+    # Check if file is inside a .figz.d
+    elif parent_str.endswith('.figz.d') or (path.parent.parent and str(path.parent.parent).endswith('.figz.d')):
+        figz_path = path.parent if parent_str.endswith('.figz.d') else path.parent.parent
+        json_path, csv_path, png_path, hitmap_path, bundle_spec, panel_info = resolve_figz_bundle(figz_path)
+    else:
+        # Standard file paths
+        json_path, csv_path, png_path = resolve_figure_paths(path)
+
+    return json_path, csv_path, png_path, hitmap_path, bundle_spec, panel_info
+
+
+def _launch_backend(
+    backend: str,
+    json_path: Path,
+    metadata: dict,
+    csv_data,
+    png_path,
+    hitmap_path,
+    manual_overrides,
+    bundle_spec,
+    panel_info,
+    port: int,
+) -> None:
+    """Launch the specified editor backend."""
+    if backend == "flask":
+        _launch_flask(json_path, metadata, csv_data, png_path, hitmap_path, manual_overrides, port, panel_info)
+    elif backend == "dearpygui":
+        _launch_dearpygui(json_path, metadata, csv_data, png_path, manual_overrides)
+    elif backend == "qt":
+        _launch_qt(json_path, metadata, csv_data, png_path, manual_overrides, hitmap_path, bundle_spec)
+    elif backend == "tkinter":
+        _launch_tkinter(json_path, metadata, csv_data, manual_overrides)
+    elif backend == "mpl":
+        _launch_mpl(json_path, metadata, csv_data, manual_overrides)
+    else:
+        raise ValueError(
+            f"Unknown backend: {backend}. "
+            "Use 'auto', 'flask', 'dearpygui', 'qt', 'tkinter', or 'mpl'."
+        )
+
+
+def _launch_flask(json_path, metadata, csv_data, png_path, hitmap_path, manual_overrides, port, panel_info):
+    """Launch Flask web editor."""
+    try:
+        from .._flask_editor import WebEditor
+        editor = WebEditor(
+            json_path=json_path,
+            metadata=metadata,
+            csv_data=csv_data,
+            png_path=png_path,
+            hitmap_path=hitmap_path,
+            manual_overrides=manual_overrides,
+            port=port,
+            panel_info=panel_info,
+        )
+        editor.run()
+    except ImportError as e:
+        raise ImportError("Flask backend requires Flask. Install with: pip install flask") from e
+
+
+def _launch_dearpygui(json_path, metadata, csv_data, png_path, manual_overrides):
+    """Launch DearPyGui editor."""
+    try:
+        from .._dearpygui_editor import DearPyGuiEditor
+        editor = DearPyGuiEditor(
+            json_path=json_path,
+            metadata=metadata,
+            csv_data=csv_data,
+            png_path=png_path,
+            manual_overrides=manual_overrides,
+        )
+        editor.run()
+    except ImportError as e:
+        raise ImportError("DearPyGui backend requires dearpygui. Install with: pip install dearpygui") from e
+
+
+def _launch_qt(json_path, metadata, csv_data, png_path, manual_overrides, hitmap_path, bundle_spec):
+    """Launch Qt editor."""
+    try:
+        from .._qt_editor import QtEditor
+        editor = QtEditor(
+            json_path=json_path,
+            metadata=metadata,
+            csv_data=csv_data,
+            png_path=png_path,
+            manual_overrides=manual_overrides,
+            hitmap_path=hitmap_path,
+            bundle_spec=bundle_spec,
+        )
+        editor.run()
+    except ImportError as e:
+        raise ImportError("Qt backend requires PyQt5/PyQt6 or PySide2/PySide6. Install with: pip install PyQt6") from e
+
+
+def _launch_tkinter(json_path, metadata, csv_data, manual_overrides):
+    """Launch Tkinter editor."""
+    from .._tkinter_editor import TkinterEditor
+    editor = TkinterEditor(
+        json_path=json_path,
+        metadata=metadata,
+        csv_data=csv_data,
+        manual_overrides=manual_overrides,
+    )
+    editor.run()
+
+
+def _launch_mpl(json_path, metadata, csv_data, manual_overrides):
+    """Launch matplotlib editor."""
+    from .._mpl_editor import MplEditor
+    editor = MplEditor(
+        json_path=json_path,
+        metadata=metadata,
+        csv_data=csv_data,
+        manual_overrides=manual_overrides,
+    )
+    editor.run()
+
+
+# EOF