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

scitex/{fig → canvas}/__init__.py

@@ -1,9 +1,8 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: 2025-12-08
 # File: ./src/scitex/vis/__init__.py
 """
-SciTeX Visualization Module (scitex.fig)
+SciTeX Visualization Module (scitex.canvas)
 
 Canvas-based composition of publication-quality figures.
 
@@ -19,7 +18,7 @@ Quick Start:
 >>> # Create canvas and add panels
 >>> stx.vis.create_canvas("/output", "fig1")
 >>> stx.vis.add_panel("/output", "fig1", "panel_a", source="plot.png",
-...                   position=(10, 10), size=(80, 60), label="A")
+...                   xy_mm=(10, 10), size_mm=(80, 60), label="A")
 >>>
 >>> # Save with stx.io (auto-exports PNG/PDF/SVG)
 >>> canvas = stx.io.load("/output/fig1.canvas")
@@ -34,46 +33,31 @@ Directory Structure:
 """
 
 # Submodules for advanced use
-from . import io
-from . import model
-from . import backend
-from . import utils
-from . import editor
+from . import backend, editor, io, model, utils
 
 # Canvas class
 from .canvas import Canvas
 
+# Editor
+from .editor import edit
+
+# Data integrity
+# Export (usually handled by stx.io.save, but available for explicit use)
 # =============================================================================
 # Primary API (minimal, reusable, flexible)
 # =============================================================================
-
 # Canvas operations
-from .io import (
-    ensure_canvas_directory as create_canvas,
-    get_canvas_directory_path as get_canvas_path,
-    canvas_directory_exists as canvas_exists,
-    list_canvas_directories as list_canvases,
-    delete_canvas_directory as delete_canvas,
-)
-
 # Panel operations
-from .io import (
-    add_panel_from_scitex,
-    add_panel_from_image,
-    update_panel,
-    remove_panel,
-    list_panels,
-)
-
-# Export (usually handled by stx.io.save, but available for explicit use)
+from .io import add_panel_from_image, add_panel_from_scitex
+from .io import canvas_directory_exists as canvas_exists
+from .io import delete_canvas_directory as delete_canvas
+from .io import ensure_canvas_directory as create_canvas
 from .io import export_canvas_to_file as export_canvas
-
-# Data integrity
+from .io import get_canvas_directory_path as get_canvas_path
+from .io import list_canvas_directories as list_canvases
+from .io import list_panels, remove_panel, update_panel
 from .io import verify_all_data_hashes as verify_data
 
-# Editor
-from .editor import edit
-
 
 # =============================================================================
 # Convenience wrapper for add_panel
@@ -83,8 +67,8 @@ def add_panel(
     canvas_name,
     panel_name,
     source,
-    position=(0, 0),
-    size=(50, 50),
+    xy_mm=(0, 0),
+    size_mm=(50, 50),
     label="",
     bundle=False,
     **kwargs,
@@ -102,10 +86,10 @@ def add_panel(
         Name for the panel
     source : str or Path
         Source file (PNG, JPG, SVG)
-    position : tuple
-        (x_mm, y_mm) position on canvas
-    size : tuple
-        (width_mm, height_mm) panel size
+    xy_mm : tuple
+        (x_mm, y_mm) position on canvas in millimeters
+    size_mm : tuple
+        (width_mm, height_mm) panel size in millimeters
     label : str
         Panel label (A, B, C...)
     bundle : bool
@@ -117,8 +101,8 @@ def add_panel(
 
     source = Path(source)
     panel_properties = {
-        "position": {"x_mm": position[0], "y_mm": position[1]},
-        "size": {"width_mm": size[0], "height_mm": size[1]},
+        "position": {"x_mm": xy_mm[0], "y_mm": xy_mm[1]},
+        "size": {"width_mm": size_mm[0], "height_mm": size_mm[1]},
         **kwargs,
     }
     if label:
@@ -147,32 +131,33 @@ def add_panel(
 
 
 # =============================================================================
-# .figz Bundle Support
+# .figure Bundle Support
 # =============================================================================
 
-def save_figz(
+
+def save_figure(
     panels,
     path,
     spec=None,
     as_zip=None,
 ):
     """
-    Save panels as a .figz publication figure bundle.
+    Save panels as a .figure publication figure bundle.
 
     Parameters
     ----------
     panels : dict
-        Dictionary mapping panel IDs to .pltz bundle paths or data.
-        Example: {"A": "timecourse.pltz.d", "B": "barplot.pltz.d"}
+        Dictionary mapping panel IDs to .plot bundle paths or data.
+        Example: {"A": "timecourse.plot", "B": "barplot.plot"}
     path : str or Path
-        Output path (e.g., "Figure1.figz" or "Figure1.figz.d").
-        - Path ending with ".figz" creates ZIP archive (default behavior)
-        - Path ending with ".figz.d" creates directory bundle
+        Output path (e.g., "Figure1.figure.zip" or "Figure1.figure").
+        - Path ending with ".zip" creates ZIP archive
+        - Path ending with ".figure" creates directory bundle
     spec : dict, optional
         Figure specification. Auto-generated if None.
     as_zip : bool, optional
         If True, save as ZIP archive. If False, save as directory.
-        Default: auto-detect from path (ZIP for .figz, directory for .figz.d).
+        Default: auto-detect from path.
 
     Returns
     -------
@@ -181,24 +166,25 @@ def save_figz(
 
     Examples
     --------
-    >>> import scitex.fig as sfig
+    >>> import scitex.canvas as sfig
     >>> panels = {
-    ...     "A": "timecourse.pltz.d",
-    ...     "B": "barplot.pltz.d"
+    ...     "A": "timecourse.plot",
+    ...     "B": "barplot.plot"
     ... }
-    >>> sfig.save_figz(panels, "Figure1.figz")    # Creates ZIP
-    >>> sfig.save_figz(panels, "Figure1.figz.d")  # Creates directory
+    >>> sfig.save_figure(panels, "Figure1.figure.zip")  # Creates ZIP
+    >>> sfig.save_figure(panels, "Figure1.figure")      # Creates directory
     """
-    from pathlib import Path
     import shutil
-    from scitex.io.bundle import save, BundleType
+    from pathlib import Path
+
+    from scitex.io.bundle import BundleType, save
 
     p = Path(path)
     spath = str(path)
 
     # Auto-detect as_zip from path suffix if not specified
     if as_zip is None:
-        as_zip = not spath.endswith(".d")
+        as_zip = spath.endswith(".zip")
 
     # Auto-generate spec if not provided
     if spec is None:
@@ -206,28 +192,28 @@ def save_figz(
 
     # Build bundle data - pass source paths directly for file copying
     bundle_data = {
-        'spec': spec,
-        'plots': {},
+        "spec": spec,
+        "plots": {},
     }
 
     # Pass source paths directly (not loaded data) to preserve all files
-    for panel_id, pltz_source in panels.items():
-        pltz_path = Path(pltz_source)
-        if pltz_path.exists():
+    for panel_id, plot_source in panels.items():
+        plot_path = Path(plot_source)
+        if plot_path.exists():
             # Store source path for direct copying
-            bundle_data['plots'][panel_id] = str(pltz_path)
+            bundle_data["plots"][panel_id] = str(plot_path)
 
-    return save(bundle_data, p, bundle_type=BundleType.FIGZ, as_zip=as_zip)
+    return save(bundle_data, p, bundle_type=BundleType.FIGURE, as_zip=as_zip)
 
 
-def load_figz(path):
+def load_figure(path):
     """
-    Load a .figz bundle.
+    Load a .figure bundle.
 
     Parameters
     ----------
     path : str or Path
-        Path to .figz bundle (directory or ZIP).
+        Path to .figure bundle (directory or ZIP).
 
     Returns
     -------
@@ -238,7 +224,7 @@ def load_figz(path):
 
     Examples
     --------
-    >>> figure = scitex.fig.load_figz("Figure1.figz.d")
+    >>> figure = scitex.canvas.load_figure("Figure1.figure")
     >>> print(figure['spec']['figure']['title'])
     >>> panel_a = figure['panels']['A']
     >>> print(panel_a['spec'], panel_a['data'])
@@ -247,19 +233,19 @@ def load_figz(path):
 
     bundle = load(path)
 
-    if bundle['type'] != 'figz':
-        raise ValueError(f"Not a .figz bundle: {path}")
+    if bundle["type"] != "figure":
+        raise ValueError(f"Not a .figure bundle: {path}")
 
     result = {
-        'spec': bundle.get('spec', {}),
-        'panels': {},
+        "spec": bundle.get("spec", {}),
+        "panels": {},
     }
 
     # Return spec and data for each panel (reconstruction is optional)
-    for panel_id, plot_bundle in bundle.get('plots', {}).items():
-        result['panels'][panel_id] = {
-            'spec': plot_bundle.get('spec', {}),
-            'data': plot_bundle.get('data'),
+    for panel_id, plot_bundle in bundle.get("plots", {}).items():
+        result["panels"][panel_id] = {
+            "spec": plot_bundle.get("spec", {}),
+            "data": plot_bundle.get("data"),
         }
 
     return result
@@ -270,17 +256,17 @@ def _generate_figure_spec(panels):
     from pathlib import Path
 
     spec = {
-        'schema': {'name': 'scitex.fig.figure', 'version': '1.0.0'},
-        'figure': {
-            'id': 'figure',
-            'title': '',
-            'caption': '',
-            'styles': {
-                'size': {'width_mm': 180, 'height_mm': 120},
-                'background': '#ffffff',
+        "schema": {"name": "scitex.canvas.figure", "version": "1.0.0"},
+        "figure": {
+            "id": "figure",
+            "title": "",
+            "caption": "",
+            "styles": {
+                "size": {"width_mm": 180, "height_mm": 120},
+                "background": "#ffffff",
             },
         },
-        'panels': [],
+        "panels": [],
     }
 
     # Auto-layout panels
@@ -305,15 +291,17 @@ def _generate_figure_spec(panels):
         x = margin + col * (panel_w + margin)
         y = margin + row * (panel_h + margin)
 
-        # Note: save_bundle uses panel_id for the directory name (e.g., A.pltz.d)
-        spec['panels'].append({
-            'id': panel_id,
-            'label': panel_id,
-            'caption': '',
-            'plot': f"{panel_id}.pltz.d",
-            'position': {'x_mm': x, 'y_mm': y},
-            'size': {'width_mm': panel_w, 'height_mm': panel_h},
-        })
+        # Note: save_bundle uses panel_id for the directory name (e.g., A.plot)
+        spec["panels"].append(
+            {
+                "id": panel_id,
+                "label": panel_id,
+                "caption": "",
+                "plot": f"{panel_id}.plot",
+                "position": {"x_mm": x, "y_mm": y},
+                "size": {"width_mm": panel_w, "height_mm": panel_h},
+            }
+        )
 
     return spec
 
@@ -344,9 +332,9 @@ __all__ = [
     "verify_data",
     # Editor
     "edit",
-    # .figz bundle
-    "save_figz",
-    "load_figz",
+    # .figure bundle
+    "save_figure",
+    "load_figure",
 ]
 
 # EOF

scitex/canvas/_mcp_handlers.py

@@ -0,0 +1,372 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-08
+# File: src/scitex/canvas/_mcp_handlers.py
+# ----------------------------------------
+
+"""
+MCP Handler implementations for SciTeX canvas module.
+
+Provides async handlers for multi-panel figure composition.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+
+async def create_canvas_handler(
+    parent_dir: str,
+    canvas_name: str,
+    width_mm: float = 180,
+    height_mm: float = 120,
+) -> dict:
+    """
+    Create a new canvas workspace.
+
+    Parameters
+    ----------
+    parent_dir : str
+        Parent directory for canvas
+    canvas_name : str
+        Name for the canvas
+    width_mm : float
+        Canvas width in mm
+    height_mm : float
+        Canvas height in mm
+
+    Returns
+    -------
+    dict
+        Success status and canvas info
+    """
+    try:
+        import scitex.canvas as canvas_module
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            None,
+            lambda: canvas_module.create_canvas(
+                parent_dir,
+                canvas_name,
+            ),
+        )
+
+        canvas_path = canvas_module.get_canvas_path(parent_dir, canvas_name)
+
+        return {
+            "success": True,
+            "canvas_name": canvas_name,
+            "canvas_path": str(canvas_path),
+            "size_mm": {"width": width_mm, "height": height_mm},
+            "message": f"Created canvas '{canvas_name}' at {canvas_path}",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def add_panel_handler(
+    parent_dir: str,
+    canvas_name: str,
+    panel_name: str,
+    source: str,
+    x_mm: float = 0,
+    y_mm: float = 0,
+    width_mm: float = 50,
+    height_mm: float = 50,
+    label: Optional[str] = None,
+) -> dict:
+    """
+    Add a panel to a canvas.
+
+    Parameters
+    ----------
+    parent_dir : str
+        Parent directory containing canvas
+    canvas_name : str
+        Canvas name
+    panel_name : str
+        Name for this panel
+    source : str
+        Path to source file
+    x_mm, y_mm : float
+        Position in mm
+    width_mm, height_mm : float
+        Size in mm
+    label : str, optional
+        Panel label (A, B, C...)
+
+    Returns
+    -------
+    dict
+        Success status and panel info
+    """
+    try:
+        import scitex.canvas as canvas_module
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            None,
+            lambda: canvas_module.add_panel(
+                parent_dir=parent_dir,
+                canvas_name=canvas_name,
+                panel_name=panel_name,
+                source=source,
+                xy_mm=(x_mm, y_mm),
+                size_mm=(width_mm, height_mm),
+                label=label or "",
+            ),
+        )
+
+        return {
+            "success": True,
+            "canvas_name": canvas_name,
+            "panel_name": panel_name,
+            "source": source,
+            "position_mm": {"x": x_mm, "y": y_mm},
+            "size_mm": {"width": width_mm, "height": height_mm},
+            "label": label,
+            "message": f"Added panel '{panel_name}' to canvas '{canvas_name}'",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def list_panels_handler(
+    parent_dir: str,
+    canvas_name: str,
+) -> dict:
+    """
+    List all panels in a canvas.
+
+    Parameters
+    ----------
+    parent_dir : str
+        Parent directory
+    canvas_name : str
+        Canvas name
+
+    Returns
+    -------
+    dict
+        Success status and panel list
+    """
+    try:
+        import scitex.canvas as canvas_module
+
+        loop = asyncio.get_event_loop()
+        panels = await loop.run_in_executor(
+            None,
+            lambda: canvas_module.list_panels(parent_dir, canvas_name),
+        )
+
+        return {
+            "success": True,
+            "canvas_name": canvas_name,
+            "count": len(panels) if panels else 0,
+            "panels": panels or [],
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def remove_panel_handler(
+    parent_dir: str,
+    canvas_name: str,
+    panel_name: str,
+) -> dict:
+    """
+    Remove a panel from a canvas.
+
+    Parameters
+    ----------
+    parent_dir : str
+        Parent directory
+    canvas_name : str
+        Canvas name
+    panel_name : str
+        Panel to remove
+
+    Returns
+    -------
+    dict
+        Success status
+    """
+    try:
+        import scitex.canvas as canvas_module
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            None,
+            lambda: canvas_module.remove_panel(parent_dir, canvas_name, panel_name),
+        )
+
+        return {
+            "success": True,
+            "canvas_name": canvas_name,
+            "panel_name": panel_name,
+            "message": f"Removed panel '{panel_name}' from canvas '{canvas_name}'",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def export_canvas_handler(
+    parent_dir: str,
+    canvas_name: str,
+    output_path: Optional[str] = None,
+    format: Optional[str] = None,
+    dpi: int = 300,
+) -> dict:
+    """
+    Export canvas to file.
+
+    Parameters
+    ----------
+    parent_dir : str
+        Parent directory
+    canvas_name : str
+        Canvas name
+    output_path : str, optional
+        Output file path
+    format : str, optional
+        Output format (png, pdf, svg)
+    dpi : int
+        Output DPI
+
+    Returns
+    -------
+    dict
+        Success status and output path
+    """
+    try:
+        from pathlib import Path
+
+        import scitex.canvas as canvas_module
+
+        # Build output path if not provided
+        if output_path is None:
+            canvas_path = canvas_module.get_canvas_path(parent_dir, canvas_name)
+            fmt = format or "png"
+            output_path = str(Path(canvas_path) / "exports" / f"{canvas_name}.{fmt}")
+
+        loop = asyncio.get_event_loop()
+        result_path = await loop.run_in_executor(
+            None,
+            lambda: canvas_module.export_canvas(
+                parent_dir,
+                canvas_name,
+                output_path,
+            ),
+        )
+
+        return {
+            "success": True,
+            "canvas_name": canvas_name,
+            "output_path": str(result_path) if result_path else output_path,
+            "format": format or Path(output_path).suffix.lstrip("."),
+            "dpi": dpi,
+            "message": f"Exported canvas to {output_path}",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def list_canvases_handler(parent_dir: str) -> dict:
+    """
+    List all canvases in a directory.
+
+    Parameters
+    ----------
+    parent_dir : str
+        Directory to search
+
+    Returns
+    -------
+    dict
+        Success status and canvas list
+    """
+    try:
+        import scitex.canvas as canvas_module
+
+        loop = asyncio.get_event_loop()
+        canvases = await loop.run_in_executor(
+            None,
+            lambda: canvas_module.list_canvases(parent_dir),
+        )
+
+        return {
+            "success": True,
+            "parent_dir": parent_dir,
+            "count": len(canvases) if canvases else 0,
+            "canvases": canvases or [],
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def canvas_exists_handler(
+    parent_dir: str,
+    canvas_name: str,
+) -> dict:
+    """
+    Check if a canvas exists.
+
+    Parameters
+    ----------
+    parent_dir : str
+        Parent directory
+    canvas_name : str
+        Canvas name
+
+    Returns
+    -------
+    dict
+        Success status and existence flag
+    """
+    try:
+        import scitex.canvas as canvas_module
+
+        exists = canvas_module.canvas_exists(parent_dir, canvas_name)
+
+        return {
+            "success": True,
+            "canvas_name": canvas_name,
+            "exists": exists,
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+__all__ = [
+    "create_canvas_handler",
+    "add_panel_handler",
+    "list_panels_handler",
+    "remove_panel_handler",
+    "export_canvas_handler",
+    "list_canvases_handler",
+    "canvas_exists_handler",
+]
+
+# EOF