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

scitex/fts/_fig/_editor/_cui/_bundle_resolver.py

@@ -0,0 +1,366 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/editor/edit/bundle_resolver.py
+
+"""Bundle path resolution for FTS bundles (unified format)."""
+
+import json as json_module
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Tuple
+
+__all__ = [
+    "resolve_pltz_bundle",
+    "resolve_figz_bundle",
+    "resolve_layered_pltz_bundle",
+    "resolve_stx_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) 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 FTS bundle.
+
+    FTS format structure:
+        bundle.zip (or bundle.d/)
+            canonical/
+                spec.json       # Main specification
+                data.csv        # Source data
+                encoding.json   # Data-to-visual mappings
+                theme.json      # Visual aesthetics
+            artifacts/
+                exports/        # PNG, SVG, PDF
+                cache/          # geometry_px.json
+
+    Parameters
+    ----------
+    bundle_dir : Path
+        Path to bundle directory.
+
+    Returns
+    -------
+    tuple
+        (json_path, csv_path, png_path, hitmap_path, bundle_spec)
+    """
+    # Load FTS bundle directly
+    bundle_data = {}
+    spec_path = bundle_dir / "canonical" / "spec.json"
+    if not spec_path.exists():
+        spec_path = bundle_dir / "spec.json"  # Legacy location
+
+    if spec_path.exists():
+        with open(spec_path) as f:
+            bundle_data["spec"] = json_module.load(f)
+
+    # Try to load encoding and theme
+    for fname in ["encoding.json", "theme.json"]:
+        fpath = bundle_dir / "canonical" / fname
+        if not fpath.exists():
+            fpath = bundle_dir / fname
+        if fpath.exists():
+            with open(fpath) as f:
+                bundle_data[fname.replace(".json", "")] = json_module.load(f)
+
+    csv_path = None
+    png_path = None
+    hitmap_path = None
+
+    # Find CSV (check canonical/ first, then root)
+    for search_dir in [bundle_dir / "canonical", bundle_dir]:
+        for f in search_dir.glob("*.csv"):
+            csv_path = f
+            break
+        if csv_path:
+            break
+
+    # Find exports (check artifacts/exports first, then exports/)
+    for exports_dir in [bundle_dir / "artifacts" / "exports", 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
+
+    # Merge spec with encoding and theme
+    bundle_spec = bundle_data.get("spec", {})
+    if "encoding" in bundle_data:
+        bundle_spec["encoding"] = bundle_data["encoding"]
+    if "theme" in bundle_data:
+        bundle_spec["theme"] = bundle_data["theme"]
+
+    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,
+    )
+
+
+def resolve_stx_bundle(path: Path) -> Tuple:
+    """
+    Resolve paths from a .stx bundle (unified FTS format).
+
+    Parameters
+    ----------
+    path : Path
+        Path to .stx bundle (.stx, .stx.d, .zip, or directory)
+
+    Returns
+    -------
+    tuple
+        (json_path, csv_path, png_path, hitmap_path, bundle_spec, element_info)
+    """
+    from scitex.fts import FTS
+
+    spath = str(path)
+
+    # Handle ZIP vs directory
+    if spath.endswith((".stx", ".zip")) and not spath.endswith(".stx.d"):
+        if not path.exists():
+            raise FileNotFoundError(f"Bundle not found: {path}")
+        temp_dir = tempfile.mkdtemp(prefix="scitex_edit_stx_")
+        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((".stx.d", ".d")):
+                bundle_dir = item
+                break
+    else:
+        bundle_dir = Path(path)
+        if not bundle_dir.exists():
+            raise FileNotFoundError(f"Bundle directory not found: {bundle_dir}")
+
+    # Load using FTS class
+    fts_bundle = FTS(bundle_dir)
+
+    # Find spec path (canonical/spec.json or spec.json)
+    spec_path = bundle_dir / "canonical" / "spec.json"
+    if not spec_path.exists():
+        spec_path = bundle_dir / "spec.json"
+
+    # Find exports (artifacts/exports or exports/)
+    png_path = None
+    hitmap_path = None
+    csv_path = None
+    for exports_dir in [bundle_dir / "artifacts" / "exports", 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
+
+    # Find CSV (canonical/data.csv or root)
+    for search_dir in [bundle_dir / "canonical", bundle_dir]:
+        for f in search_dir.glob("*.csv"):
+            csv_path = f
+            break
+        if csv_path:
+            break
+
+    # Build bundle spec from FTS
+    bundle_spec = fts_bundle.to_dict() if hasattr(fts_bundle, "to_dict") else {}
+
+    # Build element info for editor
+    element_info = {
+        "elements": getattr(fts_bundle, "elements", []),
+        "size_mm": fts_bundle.node.size_mm if fts_bundle.node else None,
+        "bundle_dir": str(bundle_dir),
+        "bundle_path": str(path),
+        "is_directory": bundle_dir.is_dir(),
+    }
+
+    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,
+        element_info,
+    )
+
+
+# EOF

scitex/fts/_fig/_editor/_cui/_editor_launcher.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_fig/_editor/_cui/_editor_launcher.py
+
+"""Main edit function for launching Flask visual editor."""
+
+from pathlib import Path
+from typing import Union
+
+from ._backend_detector import detect_best_backend, print_available_backends
+from ._bundle_resolver import (
+    resolve_figz_bundle,
+    resolve_pltz_bundle,
+)
+from ._path_resolver import resolve_figure_paths
+
+__all__ = ["edit"]
+
+
+def edit(
+    path: Union[str, Path],
+    apply_manual: bool = True,
+    port: int = 5050,
+) -> None:
+    """
+    Launch interactive Flask editor for figure style/annotation editing.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to figure file. Can be:
+        - .stx or .stx.d unified element bundle
+        - .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)
+    apply_manual : bool, optional
+        If True, load .manual.json overrides if exists (default: True)
+    port : int, optional
+        Port number for Flask editor. Default: 5050.
+
+    Returns
+    -------
+    None
+        Editor runs in Flask 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", {})
+
+    # Verify Flask is available
+    detect_best_backend()
+
+    # Print status
+    print_available_backends()
+    print(f"Launching Flask editor for: {json_path}")
+
+    # Launch Flask editor
+    _launch_flask(
+        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,
+    )
+
+
+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 .stx bundle (unified element format)
+    if spath.endswith(".stx.d") or spath.endswith(".stx"):
+        from ._bundle_resolver import resolve_stx_bundle
+
+        json_path, csv_path, png_path, hitmap_path, bundle_spec, panel_info = (
+            resolve_stx_bundle(path)
+        )
+    # Check if this is a .figz bundle (multi-panel figure)
+    elif 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_flask(
+    json_path,
+    metadata,
+    csv_data,
+    png_path,
+    hitmap_path,
+    manual_overrides,
+    port,
+    panel_info,
+):
+    """Launch Flask web editor."""
+    try:
+        from .._gui._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
+
+
+# EOF

scitex/fts/_fig/_editor/_cui/_manual_handler.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+# Timestamp: "2025-12-14 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fig/editor/edit/manual_handler.py
+
+"""Manual override handling for figure editor."""
+
+import hashlib
+from pathlib import Path
+
+__all__ = ["compute_file_hash", "save_manual_overrides"]
+
+
+def compute_file_hash(path: Path) -> str:
+    """Compute SHA256 hash of file contents."""
+    with open(path, "rb") as f:
+        return hashlib.sha256(f.read()).hexdigest()
+
+
+def save_manual_overrides(json_path: Path, overrides: dict) -> Path:
+    """
+    Save manual overrides to .manual.json file.
+
+    Parameters
+    ----------
+    json_path : Path
+        Path to base JSON file
+    overrides : dict
+        Override settings (styles, annotations, etc.)
+
+    Returns
+    -------
+    Path
+        Path to saved manual.json file
+    """
+    import scitex as stx
+
+    manual_path = json_path.with_suffix(".manual.json")
+
+    # Compute hash of base JSON for staleness detection
+    base_hash = compute_file_hash(json_path)
+
+    manual_data = {
+        "base_file": json_path.name,
+        "base_hash": base_hash,
+        "overrides": overrides,
+    }
+
+    stx.io.save(manual_data, manual_path)
+    return manual_path
+
+
+# EOF