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

scitex/fig/__init__.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
+# File: ./src/scitex/vis/__init__.py
+"""
+SciTeX Visualization Module (scitex.fig)
+
+Canvas-based composition of publication-quality figures.
+
+Terminology:
+- Canvas: A paper figure workspace (e.g., "Figure 1" in publication)
+- Panel: A single component on canvas (stx.plt output or image)
+- Figure: Reserved for matplotlib's fig object (see scitex.plt)
+
+Quick Start:
+-----------
+>>> import scitex as stx
+>>>
+>>> # 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")
+>>>
+>>> # Save with stx.io (auto-exports PNG/PDF/SVG)
+>>> canvas = stx.io.load("/output/fig1.canvas")
+>>> stx.io.save(canvas, "/output/fig1_copy.canvas")
+
+Directory Structure:
+-------------------
+{parent_dir}/{canvas_name}.canvas/
+    ├── canvas.json     # Layout, panels, composition
+    ├── panels/         # Panel directories
+    └── exports/        # canvas.png, canvas.pdf, canvas.svg
+"""
+
+# Submodules for advanced use
+from . import io
+from . import model
+from . import backend
+from . import utils
+from . import editor
+
+# Canvas class
+from .canvas import Canvas
+
+# =============================================================================
+# 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 export_canvas_to_file as export_canvas
+
+# Data integrity
+from .io import verify_all_data_hashes as verify_data
+
+# Editor
+from .editor import edit
+
+
+# =============================================================================
+# Convenience wrapper for add_panel
+# =============================================================================
+def add_panel(
+    parent_dir,
+    canvas_name,
+    panel_name,
+    source,
+    position=(0, 0),
+    size=(50, 50),
+    label="",
+    bundle=False,
+    **kwargs,
+):
+    """
+    Add a panel to canvas (auto-detects scitex vs image type).
+
+    Parameters
+    ----------
+    parent_dir : str or Path
+        Parent directory containing canvas
+    canvas_name : str
+        Canvas name
+    panel_name : str
+        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
+    label : str
+        Panel label (A, B, C...)
+    bundle : bool
+        If True, copy files. If False (default), use symlinks.
+    **kwargs
+        Additional panel properties (rotation_deg, opacity, flip_h, etc.)
+    """
+    from pathlib import Path
+
+    source = Path(source)
+    panel_properties = {
+        "position": {"x_mm": position[0], "y_mm": position[1]},
+        "size": {"width_mm": size[0], "height_mm": size[1]},
+        **kwargs,
+    }
+    if label:
+        panel_properties["label"] = {"text": label, "position": "top-left"}
+
+    # Check if scitex output (has .json/.csv siblings)
+    json_sibling = source.parent / f"{source.stem}.json"
+    if json_sibling.exists():
+        return add_panel_from_scitex(
+            project_dir=parent_dir,
+            canvas_name=canvas_name,
+            panel_name=panel_name,
+            source_png=source,
+            panel_properties=panel_properties,
+            bundle=bundle,
+        )
+    else:
+        return add_panel_from_image(
+            project_dir=parent_dir,
+            canvas_name=canvas_name,
+            panel_name=panel_name,
+            source_image=source,
+            panel_properties=panel_properties,
+            bundle=bundle,
+        )
+
+
+# =============================================================================
+# .figz Bundle Support
+# =============================================================================
+
+def save_figz(
+    panels,
+    path,
+    spec=None,
+    as_zip=None,
+):
+    """
+    Save panels as a .figz 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"}
+    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
+    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).
+
+    Returns
+    -------
+    Path
+        Path to saved bundle.
+
+    Examples
+    --------
+    >>> import scitex.fig as sfig
+    >>> panels = {
+    ...     "A": "timecourse.pltz.d",
+    ...     "B": "barplot.pltz.d"
+    ... }
+    >>> sfig.save_figz(panels, "Figure1.figz")    # Creates ZIP
+    >>> sfig.save_figz(panels, "Figure1.figz.d")  # Creates directory
+    """
+    from pathlib import Path
+    import shutil
+    from scitex.io._bundle import save_bundle, BundleType
+
+    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")
+
+    # Auto-generate spec if not provided
+    if spec is None:
+        spec = _generate_figure_spec(panels)
+
+    # Build bundle data - pass source paths directly for file copying
+    bundle_data = {
+        '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():
+            # Store source path for direct copying
+            bundle_data['plots'][panel_id] = str(pltz_path)
+
+    return save_bundle(bundle_data, p, bundle_type=BundleType.FIGZ, as_zip=as_zip)
+
+
+def load_figz(path):
+    """
+    Load a .figz bundle.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .figz bundle (directory or ZIP).
+
+    Returns
+    -------
+    dict
+        Figure data with:
+        - 'spec': Figure specification
+        - 'panels': Dict mapping panel IDs to {'spec': ..., 'data': ...}
+
+    Examples
+    --------
+    >>> figure = scitex.fig.load_figz("Figure1.figz.d")
+    >>> print(figure['spec']['figure']['title'])
+    >>> panel_a = figure['panels']['A']
+    >>> print(panel_a['spec'], panel_a['data'])
+    """
+    from scitex.io._bundle import load_bundle
+
+    bundle = load_bundle(path)
+
+    if bundle['type'] != 'figz':
+        raise ValueError(f"Not a .figz bundle: {path}")
+
+    result = {
+        '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'),
+        }
+
+    return result
+
+
+def _generate_figure_spec(panels):
+    """Generate figure.json spec from 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',
+            },
+        },
+        'panels': [],
+    }
+
+    # Auto-layout panels
+    panel_ids = sorted(panels.keys())
+    n_panels = len(panel_ids)
+
+    if n_panels == 0:
+        return spec
+
+    # Simple grid layout
+    cols = min(n_panels, 2)
+    rows = (n_panels + cols - 1) // cols
+
+    panel_w = 80
+    panel_h = 50
+    margin = 5
+
+    for i, panel_id in enumerate(panel_ids):
+        row = i // cols
+        col = i % cols
+
+        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},
+        })
+
+    return spec
+
+
+__all__ = [
+    # Canvas class
+    "Canvas",
+    # Submodules (advanced)
+    "io",
+    "model",
+    "backend",
+    "utils",
+    "editor",
+    # Canvas operations
+    "create_canvas",
+    "get_canvas_path",
+    "canvas_exists",
+    "list_canvases",
+    "delete_canvas",
+    # Panel operations
+    "add_panel",
+    "update_panel",
+    "remove_panel",
+    "list_panels",
+    # Export
+    "export_canvas",
+    # Data integrity
+    "verify_data",
+    # Editor
+    "edit",
+    # .figz bundle
+    "save_figz",
+    "load_figz",
+]
+
+# EOF

scitex/{vis → fig}/backend/_parser.py

@@ -161,7 +161,7 @@ def validate_figure_json(fig_json: Dict[str, Any]) -> bool:
 
     Examples
     --------
-    >>> from scitex.vis.backend import validate_figure_json
+    >>> from scitex.fig.backend import validate_figure_json
     >>> fig_json = {"width_mm": 180, "height_mm": 120, "axes": []}
     >>> validate_figure_json(fig_json)
     True

scitex/{vis → fig}/canvas.py

@@ -3,7 +3,7 @@
 # Timestamp: 2025-12-08
 # File: ./src/scitex/vis/canvas.py
 """
-Canvas class for scitex.vis.
+Canvas class for scitex.fig.
 
 Provides object-oriented interface to canvas operations.
 """

scitex/{vis → fig}/editor/__init__.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-# File: ./src/scitex/vis/editor/__init__.py
+# Timestamp: "2025-12-14 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fig/editor/__init__.py
+
 """
 SciTeX Visual Editor Module
 
@@ -13,11 +15,12 @@ Supports multiple backends with graceful degradation:
   - mpl: Minimal matplotlib (always works)
 """
 
-from ._edit import edit, save_manual_overrides
+from .edit import edit, save_manual_overrides
 
 __all__ = [
     "edit",
     "save_manual_overrides",
 ]
 
+
 # EOF

scitex/{vis → fig}/editor/_dearpygui_editor.py

@@ -1901,7 +1901,7 @@ class DearPyGuiEditor:
     def _save_manual(self, sender=None, app_data=None, user_data=None):
         """Save current overrides to .manual.json."""
         import dearpygui.dearpygui as dpg
-        from ._edit import save_manual_overrides
+        from .edit import save_manual_overrides
 
         try:
             self._collect_overrides(dpg)

scitex/{vis → fig}/editor/_defaults.py

@@ -3,6 +3,8 @@
 # File: ./src/scitex/vis/editor/_defaults.py
 """Default style settings for SciTeX visual editor."""
 
+from scitex.plt.styles import get_default_dpi, get_preview_dpi
+
 
 def get_scitex_defaults():
     """
@@ -36,7 +38,7 @@ def get_scitex_defaults():
         "grid_linewidth": 0.6,
         "grid_alpha": 0.3,
         # Figure settings
-        "dpi": 300,  # Default DPI
+        "dpi": get_default_dpi(),  # From SCITEX_STYLE.yaml
         "fig_size": [3.15, 2.68],  # Default figure size in inches
         # Colors (SciTeX defaults)
         "facecolor": "#ffffff",  # White background
@@ -126,13 +128,23 @@ def extract_defaults_from_metadata(metadata):
     if "n_ticks" in style_mm:
         defaults["n_ticks"] = style_mm["n_ticks"]
 
-    # Dimensions from metadata
+    # Dimensions from metadata (support both old and new formats)
     dimensions = metadata.get("dimensions", {})
     if "dpi" in dimensions:
         defaults["dpi"] = dimensions["dpi"]
     if "figure_size_inch" in dimensions:
         defaults["fig_size"] = dimensions["figure_size_inch"]
 
+    # New format: size.width_mm, size.height_mm, size.dpi
+    size = metadata.get("size", {})
+    if "dpi" in size:
+        defaults["dpi"] = size["dpi"]
+    if "width_mm" in size and "height_mm" in size:
+        # Convert mm to inches
+        width_inch = size["width_mm"] / 25.4
+        height_inch = size["height_mm"] / 25.4
+        defaults["fig_size"] = [width_inch, height_inch]
+
     # Axis labels from metadata
     if "xlabel" in metadata:
         defaults["xlabel"] = metadata["xlabel"]
@@ -177,20 +189,73 @@ def extract_defaults_from_metadata(metadata):
             defaults["title"] = ax["title"]
         if "grid" in ax:
             defaults["grid"] = ax["grid"]
+        # Extract axis limits from list format
+        if "xlim" in ax:
+            defaults["xlim"] = ax["xlim"]
+        if "ylim" in ax:
+            defaults["ylim"] = ax["ylim"]
 
-    # Extract traces information
+    # Extract traces information - check multiple possible locations
     traces = metadata.get("traces", [])
+
+    # Also check axes[].lines (pltz bundle format)
+    if not traces and isinstance(axes, list) and len(axes) > 0:
+        ax = axes[0]
+        lines = ax.get("lines", [])
+        if lines:
+            traces = lines
+
+    # Also check hit_regions.color_map for trace info
+    if not traces:
+        hit_regions = metadata.get("hit_regions", {})
+        color_map = hit_regions.get("color_map", {})
+        if color_map:
+            traces = []
+            for trace_id, trace_info in color_map.items():
+                traces.append({
+                    "id": trace_id,
+                    "label": trace_info.get("label", f"Trace {trace_id}"),
+                    "type": trace_info.get("type", "line"),
+                })
+
     if traces:
         defaults["traces"] = traces
 
-    # Extract legend information
+    # Extract legend information from multiple possible locations
     legend = metadata.get("legend", {})
+
+    # Also check selectable_regions.axes[0].legend (pltz bundle format)
+    if not legend:
+        selectable = metadata.get("selectable_regions", {})
+        sel_axes = selectable.get("axes", [])
+        if sel_axes and len(sel_axes) > 0:
+            legend = sel_axes[0].get("legend", {})
+
     if legend:
         defaults["legend_visible"] = legend.get("visible", True)
         defaults["legend_frameon"] = legend.get("frameon", False)
-        loc = legend.get("loc", "best")
+        # Support both old format (loc) and new format (location)
+        loc = legend.get("location") or legend.get("loc", "best")
         # Convert numeric legend loc to string (matplotlib accepts both but GUI needs string)
         defaults["legend_loc"] = _normalize_legend_loc(loc)
+        # Extract fontsize if present
+        if "fontsize" in legend:
+            defaults["legend_fontsize"] = legend["fontsize"]
+        # Extract ncols if present
+        if "ncols" in legend:
+            defaults["legend_ncols"] = legend["ncols"]
+        # Extract title if present
+        if "title" in legend:
+            defaults["legend_title"] = legend["title"]
+
+        # Extract legend entries if present
+        entries = legend.get("entries", [])
+        if entries and not traces:
+            # Use legend entries as trace labels
+            defaults["traces"] = [
+                {"label": e.get("text", f"Trace {i}")}
+                for i, e in enumerate(entries)
+            ]
 
     return defaults
 

scitex/{vis → fig}/editor/_mpl_editor.py

@@ -228,7 +228,7 @@ class MplEditor:
 
     def _save(self, event):
         """Save to .manual.json."""
-        from ._edit import save_manual_overrides
+        from .edit import save_manual_overrides
 
         try:
             manual_path = save_manual_overrides(self.json_path, self.current_overrides)