scitex 2.4.3__py3-none-any.whl → 2.5.0__py3-none-any.whl

scitex/__version__.py

@@ -9,6 +9,6 @@ __FILE__ = "./src/scitex/__version__.py"
 __DIR__ = os.path.dirname(__FILE__)
 # ----------------------------------------
 
-__version__ = "2.4.3"
+__version__ = "2.5.0"
 
 # EOF

scitex/io/_load.py

@@ -44,6 +44,7 @@ from ._load_modules._txt import _load_txt
 from ._load_modules._xml import _load_xml
 from ._load_modules._yaml import _load_yaml
 from ._load_modules._zarr import _load_zarr
+from ._load_modules._canvas import _load_canvas
 
 
 def load(
@@ -151,6 +152,10 @@ def load(
         if verbose:
             print(f"[DEBUG] After Path conversion: {lpath}")
 
+    # Handle .canvas directories (special case - directory not file)
+    if lpath.endswith(".canvas"):
+        return _load_canvas(lpath, verbose=verbose, **kwargs)
+
     # Check if it's a glob pattern
     if "*" in lpath or "?" in lpath or "[" in lpath:
         # Handle glob pattern

scitex/io/_load_modules/_canvas.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_load_modules/_canvas.py
+"""
+Load canvas directory (.canvas) for scitex.vis.
+
+Canvas directories are portable figure bundles containing:
+    - canvas.json: Layout, panels, composition settings
+    - panels/: Panel directories (scitex or image type)
+    - exports/: Composed outputs (PNG, PDF, SVG)
+
+Usage:
+    >>> import scitex as stx
+    >>> # Load canvas from directory
+    >>> canvas = stx.io.load("/path/to/fig1_results.canvas")
+    >>> # Access canvas properties
+    >>> print(canvas["canvas_name"])
+    >>> print(canvas["panels"])
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Union
+
+
+def _load_canvas(
+    lpath: Union[str, Path],
+    verbose: bool = False,
+    load_panels: bool = False,
+    as_dict: bool = False,
+    **kwargs,
+) -> Any:
+    """
+    Load a canvas from a .canvas directory.
+
+    Parameters
+    ----------
+    lpath : str or Path
+        Path to the .canvas directory.
+    verbose : bool, optional
+        If True, print verbose output. Default is False.
+    load_panels : bool, optional
+        If True, also load panel images as numpy arrays.
+        If False (default), only load canvas.json metadata.
+    as_dict : bool, optional
+        If True, return raw dict instead of Canvas object.
+        Default is False (returns Canvas object).
+    **kwargs
+        Additional arguments (reserved for future use).
+
+    Returns
+    -------
+    Canvas or Dict[str, Any]
+        Canvas object (default) or dictionary if as_dict=True.
+        Contains:
+        - All fields from canvas.json
+        - '_canvas_dir': Path to the canvas directory
+        - If load_panels=True, panel images are loaded into memory
+
+    Raises
+    ------
+    FileNotFoundError
+        If the .canvas directory or canvas.json doesn't exist.
+    ValueError
+        If the path doesn't appear to be a valid canvas directory.
+    """
+    lpath = Path(lpath)
+
+    # Validate path
+    if not str(lpath).endswith(".canvas"):
+        raise ValueError(
+            f"Canvas path must end with .canvas extension: {lpath}"
+        )
+
+    if not lpath.exists():
+        raise FileNotFoundError(f"Canvas directory not found: {lpath}")
+
+    if not lpath.is_dir():
+        raise ValueError(
+            f"Canvas path must be a directory: {lpath}"
+        )
+
+    json_path = lpath / "canvas.json"
+    if not json_path.exists():
+        raise FileNotFoundError(
+            f"canvas.json not found in canvas directory: {lpath}"
+        )
+
+    # Load canvas.json
+    with open(json_path, "r") as f:
+        canvas_dict = json.load(f)
+
+    # Add reference to the canvas directory
+    canvas_dict["_canvas_dir"] = str(lpath)
+
+    if verbose:
+        print(f"Loaded canvas: {canvas_dict.get('canvas_name', 'unknown')}")
+        print(f"  Schema version: {canvas_dict.get('schema_version', 'unknown')}")
+        print(f"  Panels: {len(canvas_dict.get('panels', []))}")
+
+    # Optionally load panel images
+    if load_panels:
+        _load_panel_images(lpath, canvas_dict, verbose=verbose)
+
+    # Return Canvas object by default
+    if not as_dict:
+        try:
+            from scitex.vis.canvas import Canvas
+            canvas_obj = Canvas.from_dict(canvas_dict)
+            # Store reference to original directory for copying
+            canvas_obj._canvas_dir = str(lpath)
+            return canvas_obj
+        except ImportError:
+            # Fall back to dict if Canvas class unavailable
+            pass
+
+    return canvas_dict
+
+
+def _load_panel_images(
+    canvas_dir: Path,
+    canvas_dict: Dict[str, Any],
+    verbose: bool = False,
+) -> None:
+    """
+    Load panel images into canvas_dict.
+
+    Modifies canvas_dict in place, adding '_image' key to each panel
+    containing the loaded numpy array.
+    """
+    try:
+        from PIL import Image
+        import numpy as np
+    except ImportError:
+        if verbose:
+            print("PIL/numpy not available, skipping panel image loading")
+        return
+
+    panels_dir = canvas_dir / "panels"
+
+    for panel in canvas_dict.get("panels", []):
+        panel_name = panel.get("name", "")
+        if not panel_name:
+            continue
+
+        panel_dir = panels_dir / panel_name
+        if not panel_dir.exists():
+            continue
+
+        # Try to find panel image
+        panel_type = panel.get("type", "image")
+        if panel_type == "scitex":
+            img_path = panel_dir / "panel.png"
+        else:
+            # For image type, use source filename
+            source = panel.get("source", "panel.png")
+            img_path = panel_dir / source
+
+        if img_path.exists():
+            try:
+                img = Image.open(img_path)
+                panel["_image"] = np.array(img)
+                if verbose:
+                    print(f"  Loaded panel image: {panel_name}")
+            except Exception as e:
+                if verbose:
+                    print(f"  Failed to load panel image {panel_name}: {e}")
+
+
+# EOF

scitex/io/_save.py

@@ -61,6 +61,7 @@ from ._save_modules import save_torch
 from ._save_modules import save_yaml
 from ._save_modules import save_zarr
 from ._save_modules._bibtex import save_bibtex
+from ._save_modules._canvas import save_canvas
 
 logger = logging.getLogger()
 
@@ -510,6 +511,11 @@ def _save(
     # Get file extension
     ext = _os.path.splitext(spath)[1].lower()
 
+    # Handle .canvas directories (special case - path ends with .canvas)
+    if spath.endswith(".canvas"):
+        save_canvas(obj, spath, **kwargs)
+        return
+
     # Try dispatch dictionary first for O(1) lookup
     if ext in _FILE_HANDLERS:
         # Check if handler needs special parameters
@@ -1028,6 +1034,8 @@ def _handle_image_with_csv(
 
 # Dispatch dictionary for O(1) file format lookup
 _FILE_HANDLERS = {
+    # Canvas directory format (scitex.vis)
+    ".canvas": save_canvas,
     # Excel formats
     ".xlsx": save_excel,
     ".xls": save_excel,

scitex/io/_save_modules/_canvas.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_save_modules/_canvas.py
+"""
+Save canvas directory (.canvas) for scitex.vis.
+
+Canvas directories are portable figure bundles containing:
+    - canvas.json: Layout, panels, composition settings
+    - panels/: Panel directories (scitex or image type)
+    - exports/: Composed outputs (PNG, PDF, SVG)
+
+Usage:
+    >>> import scitex as stx
+    >>> # Create canvas object
+    >>> canvas = stx.vis.Canvas(name="fig1_results")
+    >>> canvas.add_panel("panel_a", "plot.png", ...)
+    >>> # Save canvas to directory
+    >>> stx.io.save(canvas, "/path/to/fig1_results.canvas")
+    >>>
+    >>> # Or save existing canvas directory to new location
+    >>> stx.io.save(canvas_json_dict, "/path/to/new_location.canvas")
+"""
+
+import os
+import shutil
+from pathlib import Path
+from typing import Any, Dict, Union
+
+
+def save_canvas(
+    obj: Any,
+    spath: Union[str, Path],
+    **kwargs,
+) -> Path:
+    """
+    Save a canvas object or dictionary to a .canvas directory.
+
+    Parameters
+    ----------
+    obj : Any
+        Canvas object or dictionary containing canvas data.
+        Can be:
+        - Dict with canvas.json structure
+        - Canvas object with to_dict() method
+        - Path to existing .canvas directory (for copy/move)
+    spath : str or Path
+        Path where the .canvas directory should be created.
+        Must end with .canvas extension.
+    **kwargs
+        Additional arguments (reserved for future use).
+
+    Returns
+    -------
+    Path
+        Path to the created .canvas directory.
+
+    Raises
+    ------
+    ValueError
+        If path doesn't end with .canvas extension.
+    """
+    spath = Path(spath)
+
+    # Validate extension
+    if not str(spath).endswith(".canvas"):
+        raise ValueError(
+            f"Canvas path must end with .canvas extension: {spath}"
+        )
+
+    # Handle different object types
+    if isinstance(obj, (str, Path)):
+        # Source is an existing canvas directory - copy it
+        _copy_canvas_directory(Path(obj), spath)
+    elif isinstance(obj, dict):
+        # Object is a canvas JSON dictionary
+        _save_canvas_from_dict(obj, spath)
+    elif hasattr(obj, "to_dict"):
+        # Object has to_dict method (Canvas object)
+        canvas_dict = obj.to_dict()
+        # Check if this Canvas was loaded from disk (has _canvas_dir)
+        if hasattr(obj, "_canvas_dir") and obj._canvas_dir:
+            canvas_dict["_canvas_dir"] = obj._canvas_dir
+        # Pass bundle option
+        if "bundle" in kwargs:
+            canvas_dict["_bundle"] = kwargs.pop("bundle")
+        _save_canvas_from_dict(canvas_dict, spath)
+    elif hasattr(obj, "_canvas_json"):
+        # Object has internal canvas JSON (Canvas object variant)
+        _save_canvas_from_dict(obj._canvas_json, spath)
+    else:
+        raise TypeError(
+            f"Cannot save object of type {type(obj).__name__} as canvas. "
+            "Expected dict, Canvas object, or path to existing canvas."
+        )
+
+    # Export figures to exports/ directory
+    _export_canvas_figures(spath, **kwargs)
+
+    return spath
+
+
+def _export_canvas_figures(
+    canvas_dir: Path,
+    formats: list = None,
+    dpi: int = 300,
+    **kwargs,
+) -> None:
+    """
+    Export canvas figures directly to canvas directory.
+
+    Automatically exports PNG, PDF, and SVG formats.
+    """
+    if formats is None:
+        formats = ["png", "pdf", "svg"]
+
+    try:
+        from scitex.vis.io.export import _compose_and_export
+        import json
+
+        # Load canvas.json
+        json_path = canvas_dir / "canvas.json"
+        if not json_path.exists():
+            return
+
+        with open(json_path, "r") as f:
+            canvas_json = json.load(f)
+
+        # Export directly to canvas directory (no exports/ subdirectory)
+        for fmt in formats:
+            output_path = canvas_dir / f"canvas.{fmt}"
+            _compose_and_export(
+                canvas_dir=canvas_dir,
+                canvas_json=canvas_json,
+                output_path=output_path,
+                output_format=fmt,
+                dpi=dpi,
+                transparent=False,
+            )
+    except ImportError:
+        # scitex.vis not available
+        pass
+    except Exception as e:
+        # Log but don't fail save if export fails
+        import sys
+        print(f"Warning: Canvas export failed: {e}", file=sys.stderr)
+
+
+def _copy_canvas_directory(source: Path, dest: Path) -> None:
+    """Copy an existing canvas directory to a new location."""
+    if not source.exists():
+        raise FileNotFoundError(f"Source canvas directory not found: {source}")
+
+    if not (source / "canvas.json").exists():
+        raise ValueError(
+            f"Invalid canvas directory (missing canvas.json): {source}"
+        )
+
+    # Remove destination if exists
+    if dest.exists():
+        shutil.rmtree(dest)
+
+    # Copy entire directory tree
+    shutil.copytree(source, dest)
+
+
+def _save_canvas_from_dict(canvas_dict: Dict[str, Any], dest: Path) -> None:
+    """Create a canvas directory from a dictionary."""
+    import json
+
+    # Create directory structure (no exports/ - files go directly in canvas dir)
+    dest.mkdir(parents=True, exist_ok=True)
+    (dest / "panels").mkdir(exist_ok=True)
+
+    # Check if this dict was loaded from an existing canvas (has _canvas_dir)
+    source_canvas_dir = canvas_dict.get("_canvas_dir")
+
+    # Check if this dict has source files (from Canvas object)
+    source_files = canvas_dict.get("_source_files", {})
+
+    # Get bundle option
+    bundle = canvas_dict.get("_bundle", False)
+
+    # Create a clean copy of canvas_dict without internal keys for saving
+    save_dict = {k: v for k, v in canvas_dict.items() if not k.startswith("_")}
+
+    # Save canvas.json
+    json_path = dest / "canvas.json"
+    with open(json_path, "w") as f:
+        json.dump(save_dict, f, indent=2, default=str)
+
+    # If canvas_dict was loaded from an existing canvas, copy panel files
+    if source_canvas_dir:
+        _copy_panels_from_source(Path(source_canvas_dir), dest, canvas_dict)
+
+    # If canvas_dict has source files (from Canvas object), create panel dirs
+    if source_files:
+        _create_panels_from_source_files(source_files, dest, canvas_dict, bundle=bundle)
+
+    # If canvas_dict contains embedded panel data, extract it
+    _extract_embedded_panels(canvas_dict, dest)
+
+
+def _copy_panels_from_source(
+    source_canvas_dir: Path,
+    dest: Path,
+    canvas_dict: Dict[str, Any],
+) -> None:
+    """
+    Copy panel files from source canvas directory to destination.
+
+    When a canvas dict was loaded from an existing canvas directory,
+    this function copies the panel files to the new location.
+    Skips copying if source and destination are the same.
+    """
+    source_panels_dir = source_canvas_dir / "panels"
+    dest_panels_dir = dest / "panels"
+
+    if not source_panels_dir.exists():
+        return
+
+    # Skip if source and dest are the same (saving back to same location)
+    try:
+        if source_canvas_dir.resolve() == dest.resolve():
+            return
+    except (OSError, ValueError):
+        pass
+
+    for panel in canvas_dict.get("panels", []):
+        panel_name = panel.get("name", "")
+        if not panel_name:
+            continue
+
+        source_panel_dir = source_panels_dir / panel_name
+        dest_panel_dir = dest_panels_dir / panel_name
+
+        if source_panel_dir.exists() and source_panel_dir.is_dir():
+            # Copy entire panel directory (follow symlinks to get actual content)
+            if dest_panel_dir.exists():
+                shutil.rmtree(dest_panel_dir)
+            shutil.copytree(source_panel_dir, dest_panel_dir, symlinks=False)
+
+
+def _create_panels_from_source_files(
+    source_files: Dict[str, str],
+    dest: Path,
+    canvas_dict: Dict[str, Any],
+    bundle: bool = False,
+) -> None:
+    """
+    Create panel directories from source files.
+
+    When a Canvas object is saved, this creates the panel directories
+    with symlinks (default) or copies of the source files.
+
+    Parameters
+    ----------
+    source_files : Dict[str, str]
+        Mapping of panel_name -> source_file_path
+    dest : Path
+        Destination canvas directory
+    canvas_dict : Dict[str, Any]
+        Canvas dictionary (to get panel types)
+    bundle : bool
+        If True, copy files. If False (default), create symlinks.
+    """
+    dest_panels_dir = dest / "panels"
+
+    for panel in canvas_dict.get("panels", []):
+        panel_name = panel.get("name", "")
+        if not panel_name or panel_name not in source_files:
+            continue
+
+        source_path = Path(source_files[panel_name])
+        if not source_path.exists():
+            continue
+
+        panel_type = panel.get("type", "image")
+        panel_dir = dest_panels_dir / panel_name
+        panel_dir.mkdir(parents=True, exist_ok=True)
+
+        # Symlink or copy panel files
+        if panel_type == "scitex":
+            # Scitex panel: PNG, JSON, CSV
+            _link_or_copy(source_path, panel_dir / "panel.png", bundle)
+            json_sibling = source_path.parent / f"{source_path.stem}.json"
+            if json_sibling.exists():
+                _link_or_copy(json_sibling, panel_dir / "panel.json", bundle)
+            csv_sibling = source_path.parent / f"{source_path.stem}.csv"
+            if csv_sibling.exists():
+                _link_or_copy(csv_sibling, panel_dir / "panel.csv", bundle)
+        else:
+            # Image panel: just the image
+            dest_name = f"panel{source_path.suffix}"
+            _link_or_copy(source_path, panel_dir / dest_name, bundle)
+
+
+def _link_or_copy(source: Path, dest: Path, bundle: bool = False) -> None:
+    """Create relative symlink or copy file based on bundle flag."""
+    if dest.exists() or dest.is_symlink():
+        dest.unlink()
+
+    if bundle:
+        shutil.copy2(source, dest)
+    else:
+        try:
+            # Use relative symlink for portability
+            import os
+            rel_path = os.path.relpath(source.resolve(), dest.parent.resolve())
+            dest.symlink_to(rel_path)
+        except (OSError, ValueError):
+            # Fallback to copy if symlink fails
+            shutil.copy2(source, dest)
+
+
+def _extract_embedded_panels(canvas_dict: Dict[str, Any], dest: Path) -> None:
+    """
+    Extract embedded panel data from canvas dictionary.
+
+    Some Canvas objects may embed panel image data (base64) in the dict.
+    This function extracts them to the panels/ directory.
+    """
+    import base64
+
+    for panel in canvas_dict.get("panels", []):
+        panel_name = panel.get("name", "")
+        if not panel_name:
+            continue
+
+        panel_dir = dest / "panels" / panel_name
+        panel_dir.mkdir(parents=True, exist_ok=True)
+
+        # Check for embedded image data
+        if "image_data" in panel:
+            # Decode base64 image data
+            img_data = base64.b64decode(panel["image_data"])
+            img_ext = panel.get("image_ext", "png")
+            img_path = panel_dir / f"panel.{img_ext}"
+            with open(img_path, "wb") as f:
+                f.write(img_data)
+
+        # Check for embedded JSON data (scitex type panels)
+        if "panel_json" in panel:
+            import json
+            json_path = panel_dir / "panel.json"
+            with open(json_path, "w") as f:
+                json.dump(panel["panel_json"], f, indent=2, default=str)
+
+        # Check for embedded CSV data (scitex type panels)
+        if "panel_csv" in panel:
+            csv_path = panel_dir / "panel.csv"
+            with open(csv_path, "w") as f:
+                f.write(panel["panel_csv"])
+
+
+# EOF