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

scitex/vis/__init__.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: ./src/scitex/vis/__init__.py
+"""
+SciTeX Visualization Module (scitex.vis)
+
+A structured approach to creating publication-quality figures through JSON specifications.
+This module completes the SciTeX ecosystem as the third pillar alongside scholar and writer.
+
+Architecture:
+- model: JSON data models (FigureModel, AxesModel, PlotModel, etc.)
+- backend: JSON → matplotlib rendering engine
+- io: Load/save figure JSON with project structure support
+- utils: Validation and publication format templates
+
+Quick Start:
+-----------
+>>> import scitex as stx
+>>>
+>>> # Using a template
+>>> fig_json = stx.vis.utils.get_template("nature_single", height_mm=100)
+>>> fig_json["axes"] = [...]  # Add axes configurations
+>>>
+>>> # Save the spec
+>>> stx.vis.io.save_figure_json(fig_json, "figure.json")
+>>>
+>>> # Render to matplotlib
+>>> fig, axes = stx.vis.backend.build_figure_from_json(fig_json)
+>>>
+>>> # Export to image
+>>> stx.vis.backend.export_figure(fig_json, "figure.png", dpi=300)
+
+With Project Structure:
+----------------------
+>>> # Save to project
+>>> stx.vis.io.save_figure_json_to_project(
+...     project_dir="/path/to/project",
+...     figure_id="fig-001",
+...     fig_json=fig_json
+... )
+>>>
+>>> # Load from project
+>>> loaded = stx.vis.io.load_figure_json_from_project(
+...     project_dir="/path/to/project",
+...     figure_id="fig-001"
+... )
+>>>
+>>> # Export from project
+>>> stx.vis.backend.export_figure(loaded, "output/fig-001.png")
+"""
+
+# Import submodules
+from . import model
+from . import backend
+from . import io
+from . import utils
+from . import editor
+
+# Convenient top-level imports for common use cases
+from .model import FigureModel, AxesModel, PlotModel, GuideModel, AnnotationModel
+
+from .backend import (
+    build_figure_from_json,
+    export_figure,
+    export_figure_from_file,
+    export_multiple_formats,
+)
+
+from .io import (
+    load_figure_json,
+    save_figure_json,
+    load_figure_json_from_project,
+    save_figure_json_to_project,
+)
+
+from .utils import (
+    get_template,
+    list_templates,
+    NATURE_SINGLE_COLUMN_MM,
+    NATURE_DOUBLE_COLUMN_MM,
+)
+
+from .editor import edit
+
+__all__ = [
+    # Submodules
+    "model",
+    "backend",
+    "io",
+    "utils",
+    "editor",
+    # Editor
+    "edit",
+    # Models
+    "FigureModel",
+    "AxesModel",
+    "PlotModel",
+    "GuideModel",
+    "AnnotationModel",
+    # Backend
+    "build_figure_from_json",
+    "export_figure",
+    "export_figure_from_file",
+    "export_multiple_formats",
+    # I/O
+    "load_figure_json",
+    "save_figure_json",
+    "load_figure_json_from_project",
+    "save_figure_json_to_project",
+    # Utils
+    "get_template",
+    "list_templates",
+    "NATURE_SINGLE_COLUMN_MM",
+    "NATURE_DOUBLE_COLUMN_MM",
+]
+
+# EOF

scitex/vis/backend/__init__.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: ./src/scitex/vis/backend/__init__.py
+"""
+Backend for rendering figure JSON to matplotlib figures.
+
+This module bridges the gap between JSON specifications and
+actual matplotlib figures using scitex.plt.
+"""
+
+from .parser import (
+    parse_figure_json,
+    parse_axes_json,
+    parse_plot_json,
+    parse_guide_json,
+    parse_annotation_json,
+    validate_figure_json,
+)
+
+from .render import (
+    render_figure,
+    render_axes,
+    render_plot,
+    render_guide,
+    render_annotation,
+    build_figure_from_json,
+)
+
+from .export import (
+    export_figure,
+    export_figure_from_file,
+    export_multiple_formats,
+)
+
+__all__ = [
+    # Parser
+    "parse_figure_json",
+    "parse_axes_json",
+    "parse_plot_json",
+    "parse_guide_json",
+    "parse_annotation_json",
+    "validate_figure_json",
+    # Renderer
+    "render_figure",
+    "render_axes",
+    "render_plot",
+    "render_guide",
+    "render_annotation",
+    "build_figure_from_json",
+    # Exporter
+    "export_figure",
+    "export_figure_from_file",
+    "export_multiple_formats",
+]
+
+# EOF

scitex/vis/backend/export.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: ./src/scitex/vis/backend/export.py
+"""Export figure models to image files via scitex.io."""
+
+from pathlib import Path
+from typing import Dict, Any, Optional, Union
+
+from .render import build_figure_from_json
+
+
+def export_figure(
+    fig_json: Dict[str, Any],
+    output_path: Union[str, Path],
+    fmt: Optional[str] = None,
+    dpi: int = 300,
+    auto_crop: bool = False,
+    **kwargs,
+) -> Path:
+    """
+    Export figure JSON to image file.
+
+    Parameters
+    ----------
+    fig_json : Dict[str, Any]
+        Figure JSON specification
+    output_path : str or Path
+        Output file path
+    fmt : str, optional
+        Output format ("png", "pdf", "svg", etc.)
+        If None, inferred from output_path extension
+    dpi : int, optional
+        Resolution in dots per inch (default: 300)
+    auto_crop : bool, optional
+        Automatically crop whitespace (default: False)
+    **kwargs
+        Additional keyword arguments passed to scitex.io.save()
+
+    Returns
+    -------
+    Path
+        Path to the saved file
+
+    Examples
+    --------
+    >>> fig_json = {"width_mm": 180, "height_mm": 120, ...}
+    >>> export_figure(fig_json, "output.png", dpi=300)
+    PosixPath('output.png')
+
+    >>> # Auto-crop for publication
+    >>> export_figure(fig_json, "figure.pdf", auto_crop=True)
+    PosixPath('figure.pdf')
+    """
+    import scitex as stx
+
+    output_path = Path(output_path)
+
+    # Build figure from JSON
+    fig, axes = build_figure_from_json(fig_json)
+
+    # Save using scitex.io
+    save_kwargs = {"dpi": dpi, "auto_crop": auto_crop}
+    save_kwargs.update(kwargs)
+
+    if fmt:
+        save_kwargs["fmt"] = fmt
+
+    stx.io.save(fig, output_path, **save_kwargs)
+
+    return output_path
+
+
+def export_figure_from_file(
+    json_path: Union[str, Path],
+    output_path: Union[str, Path],
+    **kwargs,
+) -> Path:
+    """
+    Export figure from JSON file to image file.
+
+    Parameters
+    ----------
+    json_path : str or Path
+        Path to figure JSON file
+    output_path : str or Path
+        Output image file path
+    **kwargs
+        Additional keyword arguments passed to export_figure()
+
+    Returns
+    -------
+    Path
+        Path to the saved file
+
+    Examples
+    --------
+    >>> export_figure_from_file("figure.json", "figure.png")
+    PosixPath('figure.png')
+    """
+    import scitex as stx
+
+    json_path = Path(json_path)
+
+    # Load JSON
+    fig_json = stx.io.load(json_path)
+
+    # Export
+    return export_figure(fig_json, output_path, **kwargs)
+
+
+def export_multiple_formats(
+    fig_json: Dict[str, Any],
+    output_dir: Union[str, Path],
+    base_name: str,
+    formats: list = None,
+    **kwargs,
+) -> Dict[str, Path]:
+    """
+    Export figure to multiple formats.
+
+    Parameters
+    ----------
+    fig_json : Dict[str, Any]
+        Figure JSON specification
+    output_dir : str or Path
+        Output directory
+    base_name : str
+        Base filename (without extension)
+    formats : list, optional
+        List of formats (default: ["png", "pdf", "svg"])
+    **kwargs
+        Additional keyword arguments passed to export_figure()
+
+    Returns
+    -------
+    Dict[str, Path]
+        Dictionary mapping format to output path
+
+    Examples
+    --------
+    >>> fig_json = {...}
+    >>> paths = export_multiple_formats(
+    ...     fig_json,
+    ...     "output",
+    ...     "figure-01",
+    ...     formats=["png", "pdf"]
+    ... )
+    >>> paths
+    {'png': PosixPath('output/figure-01.png'),
+     'pdf': PosixPath('output/figure-01.pdf')}
+    """
+    if formats is None:
+        formats = ["png", "pdf", "svg"]
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    results = {}
+    for fmt in formats:
+        output_path = output_dir / f"{base_name}.{fmt}"
+        results[fmt] = export_figure(fig_json, output_path, fmt=fmt, **kwargs)
+
+    return results
+
+
+# EOF

scitex/vis/backend/parser.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: ./src/scitex/vis/backend/parser.py
+"""Parse figure JSON to Python object models."""
+
+from typing import Dict, Any
+from ..model import (
+    FigureModel,
+    AxesModel,
+    PlotModel,
+    GuideModel,
+    AnnotationModel,
+)
+
+
+def parse_figure_json(fig_json: Dict[str, Any]) -> FigureModel:
+    """
+    Parse figure JSON into FigureModel.
+
+    Parameters
+    ----------
+    fig_json : Dict[str, Any]
+        Figure JSON specification
+
+    Returns
+    -------
+    FigureModel
+        Parsed figure model
+
+    Examples
+    --------
+    >>> fig_json = {
+    ...     "width_mm": 180,
+    ...     "height_mm": 120,
+    ...     "nrows": 1,
+    ...     "ncols": 2,
+    ...     "axes": [...]
+    ... }
+    >>> fig_model = parse_figure_json(fig_json)
+    """
+    # Parse nested axes
+    axes_data = fig_json.get("axes", [])
+    parsed_axes = [parse_axes_json(ax) for ax in axes_data]
+
+    # Create FigureModel with parsed axes
+    fig_data = fig_json.copy()
+    fig_data["axes"] = [ax.to_dict() for ax in parsed_axes]
+
+    return FigureModel.from_dict(fig_data)
+
+
+def parse_axes_json(axes_json: Dict[str, Any]) -> AxesModel:
+    """
+    Parse axes JSON into AxesModel.
+
+    Parameters
+    ----------
+    axes_json : Dict[str, Any]
+        Axes JSON specification
+
+    Returns
+    -------
+    AxesModel
+        Parsed axes model
+    """
+    # Parse nested plots
+    plots_data = axes_json.get("plots", [])
+    parsed_plots = [parse_plot_json(plot) for plot in plots_data]
+
+    # Parse nested annotations
+    annotations_data = axes_json.get("annotations", [])
+    parsed_annotations = [
+        parse_annotation_json(ann) for ann in annotations_data
+    ]
+
+    # Parse nested guides
+    guides_data = axes_json.get("guides", [])
+    parsed_guides = [parse_guide_json(guide) for guide in guides_data]
+
+    # Create AxesModel with parsed children
+    ax_data = axes_json.copy()
+    ax_data["plots"] = [p.to_dict() for p in parsed_plots]
+    ax_data["annotations"] = [a.to_dict() for a in parsed_annotations]
+    ax_data["guides"] = [g.to_dict() for g in parsed_guides]
+
+    return AxesModel.from_dict(ax_data)
+
+
+def parse_plot_json(plot_json: Dict[str, Any]) -> PlotModel:
+    """
+    Parse plot JSON into PlotModel.
+
+    Parameters
+    ----------
+    plot_json : Dict[str, Any]
+        Plot JSON specification
+
+    Returns
+    -------
+    PlotModel
+        Parsed plot model
+    """
+    return PlotModel.from_dict(plot_json)
+
+
+def parse_guide_json(guide_json: Dict[str, Any]) -> GuideModel:
+    """
+    Parse guide JSON into GuideModel.
+
+    Parameters
+    ----------
+    guide_json : Dict[str, Any]
+        Guide JSON specification
+
+    Returns
+    -------
+    GuideModel
+        Parsed guide model
+    """
+    return GuideModel.from_dict(guide_json)
+
+
+def parse_annotation_json(annotation_json: Dict[str, Any]) -> AnnotationModel:
+    """
+    Parse annotation JSON into AnnotationModel.
+
+    Parameters
+    ----------
+    annotation_json : Dict[str, Any]
+        Annotation JSON specification
+
+    Returns
+    -------
+    AnnotationModel
+        Parsed annotation model
+    """
+    return AnnotationModel.from_dict(annotation_json)
+
+
+def validate_figure_json(fig_json: Dict[str, Any]) -> bool:
+    """
+    Validate figure JSON structure (single entry point for validation).
+
+    This is the recommended validation function that performs:
+    1. Basic JSON structure validation (utils.validate_json_structure)
+    2. Model parsing and validation (FigureModel.validate)
+    3. Axes layout validation (utils.validate_axes_layout)
+
+    Parameters
+    ----------
+    fig_json : Dict[str, Any]
+        Figure JSON to validate
+
+    Returns
+    -------
+    bool
+        True if valid, raises ValueError otherwise
+
+    Raises
+    ------
+    ValueError
+        If JSON structure is invalid
+
+    Examples
+    --------
+    >>> from scitex.vis.backend import validate_figure_json
+    >>> fig_json = {"width_mm": 180, "height_mm": 120, "axes": []}
+    >>> validate_figure_json(fig_json)
+    True
+    """
+    from ..utils import validate_json_structure, validate_axes_layout
+
+    # Step 1: Validate basic JSON structure
+    validate_json_structure(fig_json)
+
+    # Step 2: Parse to models and validate
+    fig_model = parse_figure_json(fig_json)
+    fig_model.validate()
+
+    # Step 3: Validate axes layout consistency
+    validate_axes_layout(
+        nrows=fig_model.nrows,
+        ncols=fig_model.ncols,
+        num_axes=len(fig_model.axes),
+    )
+
+    return True
+
+
+# EOF