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

scitex/vis/io/__init__.py

@@ -1,36 +1,99 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
 # File: ./src/scitex/vis/io/__init__.py
 """
-I/O functions for figure JSON specifications.
+I/O operations for scitex.vis canvas management.
 
-Provides convenient wrappers around scitex.io for loading and
-saving figure JSONs with validation and project structure support.
+Canvas Architecture:
+    project/scitex/vis/canvases/{canvas_name}.canvas/
+        ├── canvas.json     # Layout, panels, composition settings
+        ├── panels/         # Panel directories
+        │   ├── panel_a/    # scitex type (PNG + JSON + CSV)
+        │   └── panel_b/    # image type (PNG/JPG/SVG only)
+        └── exports/        # Composed outputs (PNG, PDF, SVG)
+
+The .canvas extension makes directories self-documenting, portable, and detectable.
+
+Schema Version: 2.0.0
 """
 
-from .load import (
-    load_figure_json,
-    load_figure_json_from_project,
-    load_figure_model,
-    list_figures_in_project,
+from .directory import (
+    SCHEMA_VERSION,
+    CANVAS_EXTENSION,
+    ensure_canvas_directory,
+    get_canvas_directory_path,
+    list_canvas_directories,
+    delete_canvas_directory,
+    canvas_directory_exists,
+)
+
+from .canvas import (
+    save_canvas_json,
+    load_canvas_json,
+    update_canvas_json,
+    get_canvas_schema_version,
+)
+
+from .panel import (
+    add_panel_from_scitex,
+    add_panel_from_image,
+    remove_panel,
+    update_panel,
+    list_panels,
+    get_panel,
+    reorder_panels,
+)
+
+from .data import (
+    HashMismatchError,
+    compute_file_hash,
+    verify_data_hash,
+    verify_all_data_hashes,
+    update_data_hash,
+    list_data_files,
 )
 
-from .save import (
-    save_figure_json,
-    save_figure_json_to_project,
-    save_figure_model,
+from .export import (
+    export_canvas_to_file,
+    export_canvas_to_multiple_formats,
+    list_canvas_exports,
 )
 
 __all__ = [
-    # Load
-    "load_figure_json",
-    "load_figure_json_from_project",
-    "load_figure_model",
-    "list_figures_in_project",
-    # Save
-    "save_figure_json",
-    "save_figure_json_to_project",
-    "save_figure_model",
+    # Schema
+    "SCHEMA_VERSION",
+    "CANVAS_EXTENSION",
+    # Directory operations
+    "ensure_canvas_directory",
+    "get_canvas_directory_path",
+    "list_canvas_directories",
+    "delete_canvas_directory",
+    "canvas_directory_exists",
+    # Canvas operations
+    "save_canvas_json",
+    "load_canvas_json",
+    "update_canvas_json",
+    "get_canvas_schema_version",
+    # Panel operations
+    "add_panel_from_scitex",
+    "add_panel_from_image",
+    "remove_panel",
+    "update_panel",
+    "list_panels",
+    "get_panel",
+    "reorder_panels",
+    # Data operations
+    "HashMismatchError",
+    "compute_file_hash",
+    "verify_data_hash",
+    "verify_all_data_hashes",
+    "update_data_hash",
+    "list_data_files",
+    # Export operations
+    "export_canvas_to_file",
+    "export_canvas_to_multiple_formats",
+    "list_canvas_exports",
 ]
 
 # EOF

scitex/vis/io/canvas.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
+# File: ./src/scitex/vis/io/canvas.py
+"""
+Canvas JSON operations for scitex.vis.
+
+Handles saving, loading, and updating canvas.json files.
+"""
+
+from pathlib import Path
+from typing import Dict, Any, Union, Optional
+from datetime import datetime
+import json
+
+from .directory import get_canvas_directory_path, SCHEMA_VERSION
+
+
+def _get_empty_canvas_template(canvas_name: str) -> Dict[str, Any]:
+    """
+    Get empty canvas.json template.
+
+    Parameters
+    ----------
+    canvas_name : str
+        Name of the canvas
+
+    Returns
+    -------
+    Dict[str, Any]
+        Empty canvas template with schema version
+    """
+    now = datetime.utcnow().isoformat() + "Z"
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "canvas_name": canvas_name,
+        "size": {
+            "width_mm": 180,
+            "height_mm": 240,
+        },
+        "background": {
+            "color": "#ffffff",
+            "grid": False,
+        },
+        "panels": [],
+        "annotations": [],
+        "title": {
+            "text": "",
+            "position": {"x_mm": 90, "y_mm": 5},
+            "fontsize": 14,
+        },
+        "data_files": [],
+        "metadata": {
+            "created_at": now,
+            "updated_at": now,
+            "author": "",
+            "description": "",
+        },
+        "manual_overrides": {},
+    }
+
+
+def save_canvas_json(
+    project_dir: Union[str, Path],
+    canvas_name: str,
+    canvas_json: Dict[str, Any],
+) -> Path:
+    """
+    Save canvas specification to canvas.json.
+
+    Parameters
+    ----------
+    project_dir : str or Path
+        Project root directory
+    canvas_name : str
+        Descriptive canvas name
+    canvas_json : Dict[str, Any]
+        Canvas specification dictionary
+
+    Returns
+    -------
+    Path
+        Path to saved canvas.json file
+    """
+    canvas_dir = get_canvas_directory_path(project_dir, canvas_name)
+    json_path = canvas_dir / "canvas.json"
+
+    # Ensure directory exists
+    canvas_dir.mkdir(parents=True, exist_ok=True)
+
+    # Update metadata timestamp
+    if "metadata" not in canvas_json:
+        canvas_json["metadata"] = {}
+    canvas_json["metadata"]["updated_at"] = datetime.utcnow().isoformat() + "Z"
+
+    # Ensure schema version is set
+    if "schema_version" not in canvas_json:
+        canvas_json["schema_version"] = SCHEMA_VERSION
+
+    with open(json_path, "w") as f:
+        json.dump(canvas_json, f, indent=2)
+
+    return json_path
+
+
+def load_canvas_json(
+    project_dir: Union[str, Path],
+    canvas_name: str,
+    verify_data_hashes: bool = True,
+) -> Dict[str, Any]:
+    """
+    Load canvas specification from canvas.json.
+
+    Parameters
+    ----------
+    project_dir : str or Path
+        Project root directory
+    canvas_name : str
+        Descriptive canvas name
+    verify_data_hashes : bool, optional
+        If True, verify all data file hashes (default: True)
+
+    Returns
+    -------
+    Dict[str, Any]
+        Canvas specification dictionary
+
+    Raises
+    ------
+    FileNotFoundError
+        If canvas.json does not exist
+    HashMismatchError
+        If verify_data_hashes=True and any data file hash doesn't match
+    """
+    canvas_dir = get_canvas_directory_path(project_dir, canvas_name)
+    json_path = canvas_dir / "canvas.json"
+
+    if not json_path.exists():
+        raise FileNotFoundError(f"Canvas not found: {json_path}")
+
+    with open(json_path, "r") as f:
+        canvas_json = json.load(f)
+
+    # Verify data hashes if requested
+    if verify_data_hashes and canvas_json.get("data_files"):
+        from .data import verify_all_data_hashes
+        hash_results = verify_all_data_hashes(project_dir, canvas_name)
+        invalid_files = [f for f, valid in hash_results.items() if not valid]
+        if invalid_files:
+            from .data import HashMismatchError
+            raise HashMismatchError(
+                f"Data file hash mismatch for: {', '.join(invalid_files)}"
+            )
+
+    return canvas_json
+
+
+def update_canvas_json(
+    project_dir: Union[str, Path],
+    canvas_name: str,
+    updates: Dict[str, Any],
+) -> Path:
+    """
+    Partial update of canvas.json (merge with existing).
+
+    Parameters
+    ----------
+    project_dir : str or Path
+        Project root directory
+    canvas_name : str
+        Descriptive canvas name
+    updates : Dict[str, Any]
+        Dictionary of updates to merge
+
+    Returns
+    -------
+    Path
+        Path to updated canvas.json file
+    """
+    # Load existing
+    canvas_json = load_canvas_json(project_dir, canvas_name, verify_data_hashes=False)
+
+    # Deep merge updates
+    _deep_merge(canvas_json, updates)
+
+    # Save back
+    return save_canvas_json(project_dir, canvas_name, canvas_json)
+
+
+def _deep_merge(base: Dict, updates: Dict) -> None:
+    """Deep merge updates into base dictionary (in-place)."""
+    for key, value in updates.items():
+        if key in base and isinstance(base[key], dict) and isinstance(value, dict):
+            _deep_merge(base[key], value)
+        else:
+            base[key] = value
+
+
+def get_canvas_schema_version(
+    project_dir: Union[str, Path],
+    canvas_name: str,
+) -> Optional[str]:
+    """
+    Get schema version of a canvas.
+
+    Parameters
+    ----------
+    project_dir : str or Path
+        Project root directory
+    canvas_name : str
+        Descriptive canvas name
+
+    Returns
+    -------
+    Optional[str]
+        Schema version string or None if not found
+    """
+    try:
+        canvas_json = load_canvas_json(project_dir, canvas_name, verify_data_hashes=False)
+        return canvas_json.get("schema_version")
+    except FileNotFoundError:
+        return None
+
+
+# EOF

scitex/vis/io/data.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
+# File: ./src/scitex/vis/io/data.py
+"""
+Data operations for scitex.vis.
+
+Handles SHA256 hash computation and verification for data integrity.
+"""
+
+from pathlib import Path
+from typing import Dict, Union
+import hashlib
+
+
+class HashMismatchError(Exception):
+    """Raised when a data file hash doesn't match expected value."""
+    pass
+
+
+def compute_file_hash(filepath: Union[str, Path]) -> str:
+    """
+    Compute SHA256 hash of a file.
+
+    Parameters
+    ----------
+    filepath : str or Path
+        Path to file
+
+    Returns
+    -------
+    str
+        Hash string in format "sha256:{hex_digest}"
+    """
+    filepath = Path(filepath)
+
+    if not filepath.exists():
+        raise FileNotFoundError(f"File not found: {filepath}")
+
+    sha256_hash = hashlib.sha256()
+
+    with open(filepath, "rb") as f:
+        # Read in chunks for large files
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256_hash.update(chunk)
+
+    return f"sha256:{sha256_hash.hexdigest()}"
+
+
+def verify_data_hash(
+    filepath: Union[str, Path],
+    expected_hash: str,
+) -> bool:
+    """
+    Verify file hash against expected value.
+
+    Parameters
+    ----------
+    filepath : str or Path
+        Path to file
+    expected_hash : str
+        Expected hash string (format: "sha256:{hex_digest}")
+
+    Returns
+    -------
+    bool
+        True if hash matches, False otherwise
+    """
+    try:
+        actual_hash = compute_file_hash(filepath)
+        return actual_hash == expected_hash
+    except FileNotFoundError:
+        return False
+
+
+def verify_all_data_hashes(
+    project_dir: Union[str, Path],
+    canvas_name: str,
+) -> Dict[str, bool]:
+    """
+    Verify hashes of all data files in a canvas.
+
+    Parameters
+    ----------
+    project_dir : str or Path
+        Project root directory
+    canvas_name : str
+        Canvas name
+
+    Returns
+    -------
+    Dict[str, bool]
+        Dictionary mapping file paths to validation results
+    """
+    from .directory import get_canvas_directory_path
+    from .canvas import load_canvas_json
+
+    canvas_dir = get_canvas_directory_path(project_dir, canvas_name)
+
+    # Load canvas.json without hash verification to avoid recursion
+    json_path = canvas_dir / "canvas.json"
+    if not json_path.exists():
+        return {}
+
+    import json
+    with open(json_path, "r") as f:
+        canvas_json = json.load(f)
+
+    results = {}
+    for data_file in canvas_json.get("data_files", []):
+        rel_path = data_file.get("path", "")
+        expected_hash = data_file.get("hash", "")
+
+        if rel_path and expected_hash:
+            filepath = canvas_dir / rel_path
+            results[rel_path] = verify_data_hash(filepath, expected_hash)
+
+    return results
+
+
+def update_data_hash(
+    project_dir: Union[str, Path],
+    canvas_name: str,
+    rel_path: str,
+) -> str:
+    """
+    Update hash for a data file in canvas.json.
+
+    Parameters
+    ----------
+    project_dir : str or Path
+        Project root directory
+    canvas_name : str
+        Canvas name
+    rel_path : str
+        Relative path to data file within canvas directory
+
+    Returns
+    -------
+    str
+        New hash value
+    """
+    from .directory import get_canvas_directory_path
+    from .canvas import load_canvas_json, save_canvas_json
+
+    canvas_dir = get_canvas_directory_path(project_dir, canvas_name)
+    filepath = canvas_dir / rel_path
+
+    new_hash = compute_file_hash(filepath)
+
+    canvas_json = load_canvas_json(project_dir, canvas_name, verify_data_hashes=False)
+
+    # Update or add data file entry
+    found = False
+    for data_file in canvas_json.get("data_files", []):
+        if data_file.get("path") == rel_path:
+            data_file["hash"] = new_hash
+            found = True
+            break
+
+    if not found:
+        if "data_files" not in canvas_json:
+            canvas_json["data_files"] = []
+        canvas_json["data_files"].append({
+            "path": rel_path,
+            "hash": new_hash,
+        })
+
+    save_canvas_json(project_dir, canvas_name, canvas_json)
+
+    return new_hash
+
+
+def list_data_files(
+    project_dir: Union[str, Path],
+    canvas_name: str,
+) -> Dict[str, str]:
+    """
+    List all data files and their hashes.
+
+    Parameters
+    ----------
+    project_dir : str or Path
+        Project root directory
+    canvas_name : str
+        Canvas name
+
+    Returns
+    -------
+    Dict[str, str]
+        Dictionary mapping file paths to hash values
+    """
+    from .canvas import load_canvas_json
+
+    canvas_json = load_canvas_json(project_dir, canvas_name, verify_data_hashes=False)
+
+    return {
+        d.get("path", ""): d.get("hash", "")
+        for d in canvas_json.get("data_files", [])
+        if d.get("path")
+    }
+
+
+# EOF