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

scitex/io/_load.py

@@ -48,6 +48,98 @@ from ._load_modules._zarr import _load_zarr
 from ._load_modules._canvas import _load_canvas
 
 
+def _load_bundle(lpath, verbose=False, **kwargs):
+    """Load a .pltz, .figz, or .statsz bundle.
+
+    Parameters
+    ----------
+    lpath : str or Path
+        Path to the bundle (directory or ZIP).
+    verbose : bool
+        If True, print verbose output.
+    **kwargs
+        Additional arguments.
+
+    Returns
+    -------
+    For .pltz bundles:
+        tuple: (fig, ax, data) where fig is reconstructed figure,
+               ax is the axes, data is DataFrame or None.
+    For .figz bundles:
+        dict: Figure data with 'spec' and 'panels'.
+    For .statsz bundles:
+        dict: Stats data with 'spec' and 'comparisons'.
+    """
+    from ._bundle import load_bundle, BundleType
+
+    bundle = load_bundle(lpath)
+    bundle_type = bundle.get('type')
+
+    if bundle_type == BundleType.PLTZ:
+        # Return (fig, ax, data) tuple for .pltz bundles
+        # Note: We return the spec and data, not a reconstructed figure
+        # as matplotlib figures cannot be perfectly serialized/deserialized
+        import matplotlib.pyplot as plt
+        from pathlib import Path
+
+        p = Path(lpath)
+        bundle_dir = p
+
+        # Handle ZIP extraction
+        if not p.is_dir():
+            import tempfile
+            import zipfile
+            temp_dir = Path(tempfile.mkdtemp())
+            with zipfile.ZipFile(p, 'r') as zf:
+                zf.extractall(temp_dir)
+            bundle_dir = temp_dir
+
+        # Find PNG file - layered format stores in exports/
+        basename = bundle.get('basename', 'plot')
+        png_path = bundle_dir / "exports" / f"{basename}.png"
+        if not png_path.exists():
+            # Fallback to root level (legacy format)
+            png_path = bundle_dir / f"{basename}.png"
+
+        # Load the PNG as a figure
+        if png_path.exists():
+            img = plt.imread(str(png_path))
+            fig, ax = plt.subplots()
+            ax.imshow(img)
+            ax.axis('off')
+
+            # Attach metadata from spec
+            spec = bundle.get('spec', {})
+            if spec:
+                # Handle both layered and legacy spec formats
+                axes_list = spec.get('axes', [])
+                if axes_list and isinstance(axes_list, list):
+                    for key, val in axes_list[0].items():
+                        setattr(ax, f'_scitex_{key}', val)
+                # Theme from style (layered) or spec (legacy)
+                style = bundle.get('style', {})
+                theme = style.get('theme', {}) if style else spec.get('theme', {})
+                if theme:
+                    fig._scitex_theme = theme.get('mode')
+
+            # Data from bundle (merged in load_layered_pltz_bundle)
+            data = bundle.get('data')
+            return fig, ax, data
+        else:
+            # No PNG, return spec and data
+            return bundle.get('spec'), None, bundle.get('data')
+
+    elif bundle_type == BundleType.FIGZ:
+        # Return figure dict for .figz bundles
+        return bundle
+
+    elif bundle_type == BundleType.STATSZ:
+        # Return stats dict for .statsz bundles
+        return bundle
+
+    return bundle
+
+
 def load(
     lpath: Union[str, Path],
     ext: str = None,
@@ -157,6 +249,12 @@ def load(
     if lpath.endswith(".canvas"):
         return _load_canvas(lpath, verbose=verbose, **kwargs)
 
+    # Handle bundle formats (.pltz, .figz, .statsz and their .d variants)
+    bundle_extensions = (".figz", ".pltz", ".statsz")
+    for bext in bundle_extensions:
+        if lpath.endswith(bext) or lpath.endswith(f"{bext}.d"):
+            return _load_bundle(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/_H5Explorer.py

@@ -11,7 +11,6 @@ __DIR__ = os.path.dirname(__FILE__)
 
 import random
 import time
-import warnings
 
 # Time-stamp: "2025-06-13 21:00:00 (ywatanabe)"
 
@@ -22,6 +21,10 @@ from typing import Any, Dict, List, Optional
 import h5py
 import numpy as np
 
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
 
 class H5Explorer:
     """Interactive HDF5 file explorer.
@@ -262,7 +265,7 @@ def explore_h5(filepath: str) -> None:
         explorer.explore()
         explorer.close()
     else:
-        warnings.warn(f"Warning: File does not exist: {filepath}")
+        logger.warning(f"File does not exist: {filepath}")
 
 
 def has_h5_key(h5_path, key, max_retries=3, action_on_corrupted="delete"):

scitex/io/_load_modules/_canvas.py

@@ -3,7 +3,7 @@
 # Timestamp: 2025-12-08
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_load_modules/_canvas.py
 """
-Load canvas directory (.canvas) for scitex.vis.
+Load canvas directory (.canvas) for scitex.fig.
 
 Canvas directories are portable figure bundles containing:
     - canvas.json: Layout, panels, composition settings
@@ -100,7 +100,7 @@ def _load_canvas(
     # Return Canvas object by default
     if not as_dict:
         try:
-            from scitex.vis.canvas import Canvas
+            from scitex.fig.canvas import Canvas
 
             canvas_obj = Canvas.from_dict(canvas_dict)
             # Store reference to original directory for copying

scitex/io/_load_modules/_image.py

@@ -3,11 +3,12 @@
 # Time-stamp: "2024-11-14 07:55:38 (ywatanabe)"
 # File: ./scitex_repo/src/scitex/io/_load_modules/_image.py
 
-import logging
 from typing import Any, Dict, Optional, Tuple, Union
 
 from PIL import Image
 
+from scitex import logging
+
 logger = logging.getLogger(__name__)
 
 
@@ -58,9 +59,7 @@ def _load_image(
 
     except Exception as e:
         # If metadata reading fails, return None
-        import warnings
-
-        warnings.warn(f"Failed to read metadata: {e}")
+        logger.warning(f"Failed to read metadata: {e}")
         return img, None
 
 

scitex/io/_load_modules/_txt.py

@@ -9,7 +9,9 @@ __FILE__ = __file__
 __DIR__ = os.path.dirname(__FILE__)
 # ----------------------------------------
 
-import warnings
+from scitex import logging
+
+logger = logging.getLogger(__name__)
 
 # # UnicodeDecodeError: 'utf-8' codec can't decode byte 0x8a in position 30173: invalid start byte
 # def _load_txt(lpath, **kwargs):
@@ -93,7 +95,7 @@ def _load_txt(lpath, strip=True, as_lines=True):
         lpath = str(lpath)
 
     if not lpath.endswith((".txt", ".log", ".event", ".py", ".sh", ".tex", ".bib")):
-        warnings.warn(f"Unexpected extension for file: {lpath}")
+        logger.warning(f"Unexpected extension for file: {lpath}")
 
     try:
         with open(lpath, "r", encoding="utf-8") as file:

scitex/io/_metadata.py

@@ -1,337 +1,47 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-# Timestamp: "2025-11-14 (ywatanabe)"
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_metadata.py
-# ----------------------------------------
+
 """
 Image and PDF metadata embedding and extraction for research reproducibility.
 
-This module provides functions to embed and extract metadata from image and PDF files.
-Metadata is stored using standard formats:
+This module re-exports from _metadata_modules for backwards compatibility.
+See _metadata_modules/ for format-specific implementations:
 - PNG: tEXt chunks
 - JPEG: EXIF ImageDescription field
+- SVG: <metadata> element with scitex namespace
 - PDF: XMP metadata (industry standard)
-
-The metadata is stored as JSON strings, allowing flexible dictionary structures.
 """
 
-import json
-import os
-from typing import Any, Dict, Optional
-
-from PIL import Image
-from PIL.PngImagePlugin import PngInfo
-
-__FILE__ = __file__
-__DIR__ = os.path.dirname(__FILE__)
-
-
-def _convert_for_json(obj: Any) -> Any:
-    """
-    Convert non-JSON-serializable objects to serializable format.
-
-    Handles FixedFloat objects from figure metadata by converting
-    them to regular floats.
-    """
-    # Handle FixedFloat (from _collect_figure_metadata)
-    if hasattr(obj, 'value') and hasattr(obj, 'precision') and hasattr(obj, '__class__') and obj.__class__.__name__ == 'FixedFloat':
-        return obj.value
-
-    # Handle dict recursively
-    if isinstance(obj, dict):
-        return {key: _convert_for_json(value) for key, value in obj.items()}
-
-    # Handle list recursively
-    if isinstance(obj, list):
-        return [_convert_for_json(item) for item in obj]
-
-    # Handle tuple
-    if isinstance(obj, tuple):
-        return [_convert_for_json(item) for item in obj]
-
-    # Handle numpy arrays
-    if hasattr(obj, "tolist"):
-        return obj.tolist()
-
-    # Default: return as-is
-    return obj
-# ----------------------------------------
-
-
-def embed_metadata(image_path: str, metadata: Dict[str, Any]) -> None:
-    """
-    Embed metadata into an existing image or PDF file.
-
-    Args:
-        image_path: Path to the image/PDF file (PNG, JPEG, or PDF)
-        metadata: Dictionary containing metadata (must be JSON serializable)
-
-    Raises:
-        ValueError: If file format is not supported or metadata is not JSON serializable
-        FileNotFoundError: If file doesn't exist
-
-    Example:
-        >>> metadata = {
-        ...     'experiment': 'seizure_prediction_001',
-        ...     'session': '2024-11-14',
-        ...     'analysis': 'PAC'
-        ... }
-        >>> embed_metadata('result.png', metadata)
-        >>> embed_metadata('result.pdf', metadata)
-    """
-    if not os.path.exists(image_path):
-        raise FileNotFoundError(f"File not found: {image_path}")
-
-    # Convert non-serializable objects (e.g., FixedFloat) to serializable format
-    metadata = _convert_for_json(metadata)
-
-    # Serialize metadata to JSON
-    try:
-        metadata_json = json.dumps(metadata, ensure_ascii=False, indent=2)
-    except (TypeError, ValueError) as e:
-        raise ValueError(f"Metadata must be JSON serializable: {e}")
-
-    # Handle PNG format
-    if image_path.lower().endswith(".png"):
-        # Open the image
-        img = Image.open(image_path)
-        # Create new PNG info with metadata
-        pnginfo = PngInfo()
-        pnginfo.add_text("scitex_metadata", metadata_json)
-
-        # Save with metadata
-        img.save(image_path, "PNG", pnginfo=pnginfo)
-
-    # Handle JPEG format
-    elif image_path.lower().endswith((".jpg", ".jpeg")):
-        # Open the image
-        img = Image.open(image_path)
-
-        try:
-            import piexif
-        except ImportError:
-            raise ImportError(
-                "piexif is required for JPEG metadata support. "
-                "Install with: pip install piexif"
-            )
-
-        # Convert to RGB if necessary (JPEG doesn't support RGBA)
-        if img.mode in ("RGBA", "LA", "P"):
-            rgb_img = Image.new("RGB", img.size, (255, 255, 255))
-            if img.mode == "P":
-                img = img.convert("RGBA")
-            if img.mode in ("RGBA", "LA"):
-                rgb_img.paste(img, mask=img.split()[-1])
-            else:
-                rgb_img.paste(img)
-            img = rgb_img
-
-        # Create EXIF dict with metadata in ImageDescription field
-        exif_dict = {
-            "0th": {piexif.ImageIFD.ImageDescription: metadata_json.encode("utf-8")},
-            "Exif": {},
-            "GPS": {},
-            "1st": {},
-        }
-
-        # Try to preserve existing EXIF data
-        try:
-            existing_exif = piexif.load(img.info.get("exif", b""))
-            # Merge with new metadata (prioritize new metadata)
-            for ifd in ["Exif", "GPS", "1st"]:
-                if ifd in existing_exif:
-                    exif_dict[ifd].update(existing_exif[ifd])
-        except:
-            pass  # If existing EXIF is corrupted, just use new metadata
-
-        exif_bytes = piexif.dump(exif_dict)
-
-        # Save with EXIF metadata (quality=100 for maximum quality)
-        img.save(
-            image_path,
-            "JPEG",
-            quality=100,
-            subsampling=0,
-            optimize=False,
-            exif=exif_bytes,
-        )
-
-    # Handle PDF format
-    elif image_path.lower().endswith(".pdf"):
-        try:
-            from pypdf import PdfReader, PdfWriter
-        except ImportError:
-            raise ImportError(
-                "pypdf is required for PDF metadata support. "
-                "Install with: pip install pypdf"
-            )
-
-        # Read existing PDF
-        reader = PdfReader(image_path)
-        writer = PdfWriter()
-
-        # Copy all pages
-        for page in reader.pages:
-            writer.add_page(page)
-
-        # Prepare metadata for PDF Info Dictionary
-        pdf_metadata = {
-            "/Title": metadata.get("title", ""),
-            "/Author": metadata.get("author", ""),
-            "/Subject": metadata_json,  # Store full JSON in Subject field
-            "/Creator": "SciTeX",
-            "/Producer": "SciTeX",
-        }
-
-        # Add metadata
-        writer.add_metadata(pdf_metadata)
-
-        # Write back to file
-        with open(image_path, "wb") as output_file:
-            writer.write(output_file)
-
-    else:
-        raise ValueError(
-            f"Unsupported file format: {image_path}. "
-            "Only PNG, JPEG, and PDF formats are supported."
-        )
-
-    # Close image if it was opened (not for PDF)
-    if image_path.lower().endswith((".png", ".jpg", ".jpeg")):
-        img.close()
-
-
-def read_metadata(image_path: str) -> Optional[Dict[str, Any]]:
-    """
-    Read metadata from an image or PDF file.
-
-    Args:
-        image_path: Path to the file (PNG, JPEG, or PDF)
-
-    Returns:
-        Dictionary containing metadata, or None if no metadata found
-
-    Raises:
-        FileNotFoundError: If file doesn't exist
-        ValueError: If file format is not supported
-
-    Example:
-        >>> metadata = read_metadata('result.png')
-        >>> print(metadata['experiment'])
-        'seizure_prediction_001'
-        >>> metadata = read_metadata('result.pdf')
-    """
-    if not os.path.exists(image_path):
-        raise FileNotFoundError(f"File not found: {image_path}")
-
-    # Don't open PDF files with PIL
-    if not image_path.lower().endswith(".pdf"):
-        img = Image.open(image_path)
-    metadata = None
-
-    try:
-        # Handle PNG format
-        if image_path.lower().endswith(".png"):
-            # Check for scitex_metadata in PNG info
-            if hasattr(img, "info") and "scitex_metadata" in img.info:
-                metadata_json = img.info["scitex_metadata"]
-                try:
-                    metadata = json.loads(metadata_json)
-                except json.JSONDecodeError:
-                    # Metadata exists but is not valid JSON
-                    metadata = {"raw": metadata_json}
-
-        # Handle JPEG format
-        elif image_path.lower().endswith((".jpg", ".jpeg")):
-            try:
-                import piexif
-
-                # Load EXIF data
-                if "exif" in img.info:
-                    exif_dict = piexif.load(img.info["exif"])
-
-                    # Try to read ImageDescription field
-                    if piexif.ImageIFD.ImageDescription in exif_dict.get("0th", {}):
-                        description = exif_dict["0th"][piexif.ImageIFD.ImageDescription]
-
-                        # Decode bytes to string
-                        if isinstance(description, bytes):
-                            description = description.decode("utf-8", errors="ignore")
-
-                        # Try to parse as JSON
-                        try:
-                            metadata = json.loads(description)
-                        except json.JSONDecodeError:
-                            # If not JSON, return as raw text
-                            metadata = {"raw": description}
-            except ImportError:
-                pass  # piexif not available, return None
-            except Exception:
-                pass  # EXIF data corrupted or not readable
-
-        # Handle PDF format
-        elif image_path.lower().endswith(".pdf"):
-            try:
-                from pypdf import PdfReader
-
-                reader = PdfReader(image_path)
-
-                # Try to read metadata from PDF Info Dictionary
-                if reader.metadata:
-                    # Check Subject field for JSON metadata
-                    if "/Subject" in reader.metadata:
-                        subject = reader.metadata["/Subject"]
-                        try:
-                            metadata = json.loads(subject)
-                        except json.JSONDecodeError:
-                            # If not JSON, create metadata dict from available fields
-                            metadata = {
-                                "title": reader.metadata.get("/Title", ""),
-                                "author": reader.metadata.get("/Author", ""),
-                                "subject": subject,
-                                "creator": reader.metadata.get("/Creator", ""),
-                            }
-            except ImportError:
-                pass  # pypdf not available, return None
-            except Exception:
-                pass  # PDF metadata corrupted or not readable
-            finally:
-                # No need to close anything for PDF
-                pass
-
-        else:
-            raise ValueError(
-                f"Unsupported file format: {image_path}. "
-                "Only PNG, JPEG, and PDF formats are supported."
-            )
-
-    finally:
-        # Only close if img was opened (not for PDF)
-        if not image_path.lower().endswith(".pdf"):
-            img.close()
-
-    return metadata
-
-
-def has_metadata(image_path: str) -> bool:
-    """
-    Check if an image file has embedded metadata.
-
-    Args:
-        image_path: Path to the image file
-
-    Returns:
-        True if metadata exists, False otherwise
-
-    Example:
-        >>> if has_metadata('result.png'):
-        ...     print(read_metadata('result.png'))
-    """
-    try:
-        metadata = read_metadata(image_path)
-        return metadata is not None
-    except:
-        return False
-
+from ._metadata_modules import (
+    embed_metadata,
+    read_metadata,
+    has_metadata,
+    embed_metadata_png,
+    embed_metadata_jpeg,
+    embed_metadata_svg,
+    embed_metadata_pdf,
+    read_metadata_png,
+    read_metadata_jpeg,
+    read_metadata_svg,
+    read_metadata_pdf,
+)
+
+# Backwards compatibility alias
+_convert_for_json = None  # Removed - use _metadata_modules._utils.convert_for_json
+
+__all__ = [
+    "embed_metadata",
+    "read_metadata",
+    "has_metadata",
+    "embed_metadata_png",
+    "embed_metadata_jpeg",
+    "embed_metadata_svg",
+    "embed_metadata_pdf",
+    "read_metadata_png",
+    "read_metadata_jpeg",
+    "read_metadata_svg",
+    "read_metadata_pdf",
+]
 
 # EOF

scitex/io/_metadata_modules/__init__.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_metadata_modules/__init__.py
+
+"""
+Image and PDF metadata embedding and extraction for research reproducibility.
+
+This module provides functions to embed and extract metadata from image and PDF files.
+Metadata is stored using standard formats:
+- PNG: tEXt chunks
+- JPEG: EXIF ImageDescription field
+- SVG: <metadata> element with scitex namespace
+- PDF: XMP metadata (industry standard)
+
+The metadata is stored as JSON strings, allowing flexible dictionary structures.
+"""
+
+from ._embed import embed_metadata
+from ._read import read_metadata
+from ._utils import has_metadata
+
+# Format-specific modules (for direct access if needed)
+from .embed_metadata_png import embed_metadata_png
+from .embed_metadata_jpeg import embed_metadata_jpeg
+from .embed_metadata_svg import embed_metadata_svg
+from .embed_metadata_pdf import embed_metadata_pdf
+from .read_metadata_png import read_metadata_png
+from .read_metadata_jpeg import read_metadata_jpeg
+from .read_metadata_svg import read_metadata_svg
+from .read_metadata_pdf import read_metadata_pdf
+
+__all__ = [
+    "embed_metadata",
+    "read_metadata",
+    "has_metadata",
+    "embed_metadata_png",
+    "embed_metadata_jpeg",
+    "embed_metadata_svg",
+    "embed_metadata_pdf",
+    "read_metadata_png",
+    "read_metadata_jpeg",
+    "read_metadata_svg",
+    "read_metadata_pdf",
+]
+
+# EOF

scitex/io/_metadata_modules/_embed.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_metadata_modules/_embed.py
+
+"""Main embed_metadata dispatcher."""
+
+import os
+from typing import Any, Dict
+
+from ._utils import serialize_metadata
+
+
+def embed_metadata(image_path: str, metadata: Dict[str, Any]) -> None:
+    """
+    Embed metadata into an existing image or PDF file.
+
+    Args:
+        image_path: Path to the image/PDF file (PNG, JPEG, SVG, or PDF)
+        metadata: Dictionary containing metadata (must be JSON serializable)
+
+    Raises:
+        ValueError: If file format is not supported or metadata is not JSON serializable
+        FileNotFoundError: If file doesn't exist
+
+    Example:
+        >>> metadata = {
+        ...     'experiment': 'seizure_prediction_001',
+        ...     'session': '2024-11-14',
+        ...     'analysis': 'PAC'
+        ... }
+        >>> embed_metadata('result.png', metadata)
+        >>> embed_metadata('result.pdf', metadata)
+    """
+    if not os.path.exists(image_path):
+        raise FileNotFoundError(f"File not found: {image_path}")
+
+    # Serialize metadata to JSON
+    metadata_json = serialize_metadata(metadata)
+
+    path_lower = image_path.lower()
+
+    # Dispatch to format-specific handlers
+    if path_lower.endswith(".png"):
+        from .embed_metadata_png import embed_metadata_png
+
+        embed_metadata_png(image_path, metadata_json)
+
+    elif path_lower.endswith((".jpg", ".jpeg")):
+        from .embed_metadata_jpeg import embed_metadata_jpeg
+
+        embed_metadata_jpeg(image_path, metadata_json)
+
+    elif path_lower.endswith(".svg"):
+        from .embed_metadata_svg import embed_metadata_svg
+
+        embed_metadata_svg(image_path, metadata_json)
+
+    elif path_lower.endswith(".pdf"):
+        from .embed_metadata_pdf import embed_metadata_pdf
+
+        embed_metadata_pdf(image_path, metadata_json, metadata)
+
+    else:
+        raise ValueError(
+            f"Unsupported file format: {image_path}. "
+            "Only PNG, JPEG, SVG, and PDF formats are supported."
+        )
+
+
+# EOF