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

scitex/vis/README.md

@@ -1,18 +1,28 @@
 <!-- ---
-!-- Timestamp: 2025-11-22 10:37:48
+!-- Timestamp: 2025-12-08
 !-- Author: ywatanabe
 !-- File: /home/ywatanabe/proj/scitex-code/src/scitex/vis/README.md
 !-- --- -->
 
-# scitex.vis - Structured Visualization for Publication Figures
+# scitex.vis - Canvas-Based Figure Composition
 
-**JSON-based figure specifications for reproducible, publication-quality visualizations**
+**Compose publication-quality figures from multiple panels**
+
+Schema Version: 2.0.0
 
 ---
 
 ## Overview
 
-`scitex.vis` is the visualization pillar of the SciTeX ecosystem, providing a structured approach to creating publication-quality figures through JSON specifications. It bridges the gap between data and final figures by treating visualization as structured data.
+`scitex.vis` provides canvas-based composition of publication figures. A **canvas** represents a complete paper figure (e.g., "Figure 1") that can contain multiple **panels** (A, B, C...).
+
+### Terminology
+
+| Term | Meaning | Example |
+|------|---------|---------|
+| **Canvas** | Paper figure workspace | "Figure 1" in a publication |
+| **Panel** | Single component on canvas | Panel A, B, C... |
+| **Figure** | Reserved for matplotlib's `fig` object | `stx.plt` output |
 
 ### The SciTeX Ecosystem
 
@@ -20,736 +30,357 @@
 scitex/
 ├── scholar/    → Literature & metadata management
 ├── writer/     → Document generation (LaTeX/manuscripts)
-└── vis/        → Visualization & figures (this module)
+├── plt/        → Plotting (matplotlib wrapper, outputs PNG+JSON+CSV)
+└── vis/        → Canvas composition (this module)
 ```
 
-### Why scitex.vis?
-
-Traditional plotting workflows have several pain points:
-- **Not version-controllable**: Figures are binary blobs
-- **Not reproducible**: Code scattered across notebooks, hard to recreate exact output
-- **Not collaborative**: Hard to edit someone else's plotting code
-- **Not structured**: No standard way to represent figure specifications
-
-`scitex.vis` solves these by:
-- ✅ **JSON-based**: Figures as structured, version-controllable text
-- ✅ **Reproducible**: One JSON → One figure, guaranteed
-- ✅ **Collaborative**: Easy to edit, review, and share specifications
-- ✅ **Structured**: Standard schema for all figure types
-- ✅ **Publication-ready**: Built-in templates for Nature, Science, etc.
-
 ---
 
 ## Quick Start
 
-### Basic Usage
+### Create and Compose a Canvas
 
 ```python
 import scitex as stx
-import numpy as np
-
-# 1. Create figure using publication template
-fig_json = stx.vis.get_template("nature_single", height_mm=100)
-
-# 2. Define your plot
-x = np.linspace(0, 2*np.pi, 100)
-y = np.sin(x)
-
-fig_json["axes"] = [{
-    "row": 0,
-    "col": 0,
-    "xlabel": "Time (s)",
-    "ylabel": "Amplitude",
-    "title": "Sine Wave",
-    "plots": [{
-        "plot_type": "line",
-        "data": {"x": x.tolist(), "y": y.tolist()},
-        "color": "blue",
-        "linewidth": 2,
-        "label": "sin(x)"
-    }],
-    "grid": True,
-    "legend": True
-}]
-
-# 3. Save the specification
-stx.vis.save_figure_json(fig_json, "figure.json")
-
-# 4. Render to matplotlib
-fig, axes = stx.vis.build_figure_from_json(fig_json)
-
-# 5. Export to image
-stx.vis.export_figure(fig_json, "figure.png", dpi=300)
-```
-
-### Project-Based Workflow
 
-```python
-# Save to project structure: project/scitex/vis/figs/fig-001.json
-stx.vis.save_figure_json_to_project(
+# 1. Create a canvas
+stx.vis.ensure_canvas_directory(
     project_dir="/path/to/project",
-    figure_id="fig-001",
-    fig_json=fig_json
+    canvas_name="fig1_results"
 )
 
-# Load from project
-fig_json = stx.vis.load_figure_json_from_project(
+# 2. Add panels from stx.plt outputs
+stx.vis.add_panel_from_scitex(
     project_dir="/path/to/project",
-    figure_id="fig-001"
+    canvas_name="fig1_results",
+    panel_name="panel_a",
+    source_png="./output/timeseries.png",
+    panel_properties={
+        "position": {"x_mm": 10, "y_mm": 10},
+        "size": {"width_mm": 80, "height_mm": 60},
+        "label": {"text": "A"}
+    }
 )
 
-# Export directly
-stx.vis.export_figure(fig_json, "output/fig-001.png", dpi=300)
-```
-
----
-
-## Architecture
+# 3. Add an image panel
+stx.vis.add_panel_from_image(
+    project_dir="/path/to/project",
+    canvas_name="fig1_results",
+    panel_name="panel_b",
+    source_image="./external/diagram.png",
+    panel_properties={
+        "position": {"x_mm": 100, "y_mm": 10},
+        "size": {"width_mm": 70, "height_mm": 60},
+        "label": {"text": "B"}
+    }
+)
 
-```
-scitex.vis/
-├── model/              # JSON data models
-│   ├── FigureModel     # Top-level figure specification
-│   ├── AxesModel       # Subplot configuration
-│   ├── PlotModel       # Individual plot (line, scatter, etc.)
-│   ├── GuideModel      # Reference lines, spans
-│   └── AnnotationModel # Text, arrows, shapes
-│
-├── backend/            # Rendering engine
-│   ├── parser.py       # JSON → Python objects
-│   ├── render.py       # Objects → matplotlib figures
-│   └── export.py       # Export to PNG/PDF/SVG
-│
-├── io/                 # Load/save operations
-│   ├── load.py         # Load figure JSONs
-│   └── save.py         # Save figure JSONs
-│
-└── utils/              # Utilities
-    ├── validate.py     # JSON validation
-    └── defaults.py     # Publication templates
+# 4. Export composed canvas
+stx.vis.export_canvas_to_file(
+    project_dir="/path/to/project",
+    canvas_name="fig1_results",
+    output_format="png"
+)
 ```
 
 ---
 
-## Publication Templates
-
-### Available Templates
-
-```python
-# List all templates
-templates = stx.vis.list_templates()
-# ['nature_single', 'nature_double', 'science_single', 'a4', 'square', 'presentation']
-
-# Get template dimensions
-for name in templates:
-    template = stx.vis.get_template(name)
-    print(f"{name}: {template['width_mm']} × {template['height_mm']} mm")
-```
-
-### Template Dimensions
-
-| Template | Width (mm) | Use Case |
-|----------|------------|----------|
-| `nature_single` | 89 | Nature single column |
-| `nature_double` | 183 | Nature double column |
-| `science_single` | 84 | Science single column |
-| `a4` | 180 | A4 document figures |
-| `square` | 120 | Square aspect ratio |
-| `presentation` | 254 | Presentation slides (16:9) |
-
-### Creating Custom Templates
-
-```python
-# Start with a template
-fig_json = stx.vis.get_template("nature_single")
+## Directory Structure
 
-# Customize dimensions
-fig_json["height_mm"] = 120
-fig_json["nrows"] = 2
-fig_json["ncols"] = 1
+Canvas directories use `.canvas` extension for portability and distinguishability:
 
-# Or create from scratch
-fig_json = {
-    "width_mm": 180,
-    "height_mm": 120,
-    "nrows": 1,
-    "ncols": 1,
-    "dpi": 300,
-    "axes": []
-}
 ```
-
----
-
-## Figure JSON Schema
-
-### Minimal Example
-
-```json
-{
-  "width_mm": 89,
-  "height_mm": 100,
-  "nrows": 1,
-  "ncols": 1,
-  "axes": [
-    {
-      "row": 0,
-      "col": 0,
-      "xlabel": "X",
-      "ylabel": "Y",
-      "plots": [
-        {
-          "plot_type": "line",
-          "data": {"x": [0, 1, 2], "y": [0, 1, 4]},
-          "color": "blue"
-        }
-      ]
-    }
-  ]
-}
+project/scitex/vis/canvases/
+└── fig1_results.canvas/          # .canvas extension for bundle
+    ├── canvas.json               # Layout, panels, composition
+    ├── panels/
+    │   ├── panel_a/              # type: scitex (full stx.plt output)
+    │   │   ├── panel.json
+    │   │   ├── panel.csv
+    │   │   └── panel.png
+    │   └── panel_b/              # type: image (static)
+    │       └── panel.png
+    └── exports/
+        ├── canvas.png            # Final composed output
+        ├── canvas.pdf
+        └── canvas.svg
 ```
 
-### Complete Example
-
-```json
-{
-  "width_mm": 183,
-  "height_mm": 120,
-  "nrows": 1,
-  "ncols": 2,
-  "dpi": 300,
-  "facecolor": "white",
-  "suptitle": "Figure 1: Example Results",
-  "suptitle_fontsize": 12,
-  "axes": [
-    {
-      "row": 0,
-      "col": 0,
-      "xlabel": "Time (s)",
-      "ylabel": "Amplitude",
-      "title": "Experimental Data",
-      "xlim": [0, 10],
-      "ylim": [-1, 1],
-      "grid": true,
-      "legend": true,
-      "plots": [
-        {
-          "plot_type": "line",
-          "data": {"x": [...], "y": [...]},
-          "color": "blue",
-          "linewidth": 2,
-          "label": "Measurement"
-        },
-        {
-          "plot_type": "scatter",
-          "data": {"x": [...], "y": [...]},
-          "color": "red",
-          "alpha": 0.6,
-          "label": "Control"
-        }
-      ],
-      "guides": [
-        {
-          "guide_type": "axhline",
-          "y": 0,
-          "color": "gray",
-          "linestyle": "--"
-        }
-      ],
-      "annotations": [
-        {
-          "annotation_type": "text",
-          "text": "Peak",
-          "x": 5,
-          "y": 0.8,
-          "fontsize": 10
-        }
-      ]
-    }
-  ]
-}
-```
+The `.canvas` extension makes directories self-documenting, portable, and detectable by `scitex.io`.
 
 ---
 
-## Plot Types
-
-### Supported Plot Types
-
-| Plot Type | Description | Required Data Fields |
-|-----------|-------------|---------------------|
-| `line` | Line plot | `x`, `y` |
-| `scatter` | Scatter plot | `x`, `y` |
-| `errorbar` | Error bars | `x`, `y`, optional `xerr`, `yerr` |
-| `bar` | Bar chart | `x`, `height` (or `y`) |
-| `barh` | Horizontal bar chart | `y`, `width` (or `x`) |
-| `hist` | Histogram | `x`, optional `bins` |
-| `fill_between` | Filled area | `x`, `y1`, `y2` |
-| `heatmap` | Heatmap | `z` (or `img`) |
-| `imshow` | Image display | `img` (or `z`) |
-| `contour` | Contour lines | `x`, `y`, `z` |
-| `contourf` | Filled contours | `x`, `y`, `z` |
+## Panel Types
 
-### Examples
+| Type | Contents | Editable | Re-renderable |
+|------|----------|----------|---------------|
+| `scitex` | PNG + JSON + CSV | Full (data, style) | Yes |
+| `image` | PNG/JPG/SVG only | Position/size/transform | No |
 
-#### Line Plot
+### Panel Properties
 
 ```python
-{
-  "plot_type": "line",
-  "data": {"x": [0, 1, 2, 3], "y": [0, 1, 4, 9]},
-  "color": "blue",
-  "linewidth": 2,
-  "linestyle": "-",
-  "marker": "o",
-  "label": "Quadratic"
-}
-```
+panel_properties = {
+    # Position and size (required)
+    "position": {"x_mm": 10, "y_mm": 10},
+    "size": {"width_mm": 70, "height_mm": 50},
+
+    # Transform
+    "z_index": 0,           # Stacking order
+    "rotation_deg": 0,      # Rotation (clockwise)
+    "opacity": 1.0,         # 0.0 - 1.0
+    "flip_h": False,        # Horizontal flip
+    "flip_v": False,        # Vertical flip
+    "visible": True,
+
+    # Clip (crop)
+    "clip": {
+        "enabled": False,
+        "x_mm": 0, "y_mm": 0,
+        "width_mm": None, "height_mm": None
+    },
 
-#### Scatter Plot
+    # Label (A, B, C...)
+    "label": {
+        "text": "A",
+        "position": "top-left",
+        "fontsize": 12,
+        "fontweight": "bold"
+    },
 
-```python
-{
-  "plot_type": "scatter",
-  "data": {"x": [...], "y": [...]},
-  "color": "red",
-  "alpha": 0.6,
-  "markersize": 50,
-  "label": "Data points"
+    # Border
+    "border": {
+        "visible": False,
+        "color": "#000000",
+        "width_mm": 0.2
+    }
 }
 ```
 
-#### Error Bar Plot
-
-```python
-{
-  "plot_type": "errorbar",
-  "data": {"x": [...], "y": [...]},
-  "yerr": [...],  # Can be scalar or array
-  "capsize": 5,
-  "color": "green",
-  "label": "Mean ± SD"
-}
-```
+---
 
-#### Heatmap
+## canvas.json Schema
 
-```python
+```json
 {
-  "plot_type": "heatmap",
-  "data": {"z": [[...], [...], [...]]},  # 2D array
-  "cmap": "viridis",
-  "vmin": 0,
-  "vmax": 1
-}
-```
-
----
+  "schema_version": "2.0.0",
+  "canvas_name": "fig1_results",
 
-## Multi-Subplot Figures
+  "size": {
+    "width_mm": 180,
+    "height_mm": 240
+  },
 
-### Creating Subplots
+  "background": {
+    "color": "#ffffff",
+    "grid": false
+  },
 
-```python
-# 2×2 subplot layout
-fig_json = stx.vis.get_template("nature_double", height_mm=160)
-fig_json["nrows"] = 2
-fig_json["ncols"] = 2
-
-# Define each subplot
-fig_json["axes"] = [
-    # Top-left (row=0, col=0)
-    {
-        "row": 0,
-        "col": 0,
-        "title": "Plot A",
-        "plots": [...]
-    },
-    # Top-right (row=0, col=1)
+  "panels": [
     {
-        "row": 0,
-        "col": 1,
-        "title": "Plot B",
-        "plots": [...]
+      "name": "panel_a",
+      "type": "scitex",
+      "position": {"x_mm": 10, "y_mm": 10},
+      "size": {"width_mm": 80, "height_mm": 60},
+      "z_index": 0,
+      "label": {"text": "A", "position": "top-left"}
     },
-    # Bottom-left (row=1, col=0)
     {
-        "row": 1,
-        "col": 0,
-        "title": "Plot C",
-        "plots": [...]
-    },
-    # Bottom-right (row=1, col=1)
-    {
-        "row": 1,
-        "col": 1,
-        "title": "Plot D",
-        "plots": [...]
+      "name": "panel_b",
+      "type": "image",
+      "source": "panel.png",
+      "position": {"x_mm": 100, "y_mm": 10},
+      "size": {"width_mm": 70, "height_mm": 60},
+      "label": {"text": "B"}
     }
-]
-```
-
----
+  ],
 
-## Guides and Annotations
-
-### Reference Lines and Spans
-
-```python
-# Horizontal line
-{
-  "guide_type": "axhline",
-  "y": 0,
-  "color": "gray",
-  "linestyle": "--",
-  "linewidth": 1
-}
+  "annotations": [
+    {"type": "text", "content": "p < 0.05", "position": {"x_mm": 50, "y_mm": 80}}
+  ],
 
-# Vertical line
-{
-  "guide_type": "axvline",
-  "x": 5,
-  "color": "red",
-  "alpha": 0.5
-}
-
-# Horizontal span (shaded region)
-{
-  "guide_type": "axhspan",
-  "ymin": -0.5,
-  "ymax": 0.5,
-  "color": "yellow",
-  "alpha": 0.3
-}
-
-# Vertical span
-{
-  "guide_type": "axvspan",
-  "xmin": 2,
-  "xmax": 4,
-  "color": "blue",
-  "alpha": 0.2
-}
-```
+  "data_files": [
+    {"path": "panels/panel_a/panel.csv", "hash": "sha256:abc123..."}
+  ],
 
-### Text Annotations
-
-```python
-# Simple text
-{
-  "annotation_type": "text",
-  "text": "Important point",
-  "x": 5,
-  "y": 10,
-  "fontsize": 12,
-  "color": "red",
-  "ha": "center",  # horizontal alignment
-  "va": "bottom"   # vertical alignment
-}
-
-# Annotate with arrow
-{
-  "annotation_type": "annotate",
-  "text": "Peak value",
-  "x": 5,           # Point to annotate
-  "y": 10,
-  "xytext": [6, 12], # Text position
-  "arrowprops": {
-    "arrowstyle": "->",
-    "color": "black",
-    "lw": 1.5
+  "metadata": {
+    "created_at": "2025-12-08T12:00:00Z",
+    "updated_at": "2025-12-08T15:30:00Z"
   }
 }
 ```
 
 ---
 
-## Advanced Usage
+## API Reference
 
-### Using Models Directly
+### Directory Operations
 
 ```python
-from scitex.vis.model import FigureModel, AxesModel, PlotModel
-
-# Create models programmatically
-fig_model = FigureModel(
-    width_mm=stx.vis.NATURE_SINGLE_COLUMN_MM,
-    height_mm=100,
-    nrows=1,
-    ncols=1
-)
-
-axes_model = AxesModel(
-    row=0,
-    col=0,
-    xlabel="Time",
-    ylabel="Signal"
-)
+# Create canvas directory structure
+canvas_dir = stx.vis.ensure_canvas_directory(project_dir, canvas_name)
 
-plot_model = PlotModel(
-    plot_type="line",
-    data={"x": [0, 1, 2], "y": [0, 1, 4]},
-    color="blue"
-)
+# Get canvas path
+path = stx.vis.get_canvas_directory_path(project_dir, canvas_name)
 
-# Build hierarchy
-axes_model.add_plot(plot_model.to_dict())
-fig_model.add_axes(axes_model.to_dict())
+# List all canvases
+canvases = stx.vis.list_canvas_directories(project_dir)
 
-# Validate
-fig_model.validate()
+# Check existence
+exists = stx.vis.canvas_directory_exists(project_dir, canvas_name)
 
-# Convert to JSON and render
-fig_json = fig_model.to_dict()
-fig, axes = stx.vis.build_figure_from_json(fig_json)
+# Delete canvas
+deleted = stx.vis.delete_canvas_directory(project_dir, canvas_name)
 ```
 
-### Validation
+### Canvas Operations
 
 ```python
-from scitex.vis.backend import validate_figure_json
+# Save canvas.json
+stx.vis.save_canvas_json(project_dir, canvas_name, canvas_json)
 
-try:
-    validate_figure_json(fig_json)
-    print("✓ Valid figure JSON")
-except ValueError as e:
-    print(f"✗ Invalid: {e}")
-```
+# Load canvas.json (with hash verification)
+canvas_json = stx.vis.load_canvas_json(project_dir, canvas_name)
 
-### Export Multiple Formats
+# Partial update
+stx.vis.update_canvas_json(project_dir, canvas_name, {"size": {"width_mm": 200}})
 
-```python
-# Export to PNG, PDF, and SVG simultaneously
-paths = stx.vis.backend.export_multiple_formats(
-    fig_json=fig_json,
-    output_dir="output",
-    base_name="figure-01",
-    formats=["png", "pdf", "svg"],
-    dpi=300,
-    auto_crop=True
-)
-
-# Returns: {'png': Path(...), 'pdf': Path(...), 'svg': Path(...)}
+# Get schema version
+version = stx.vis.get_canvas_schema_version(project_dir, canvas_name)
 ```
 
----
-
-## Integration with scitex.plt
-
-`scitex.vis` uses `scitex.plt` as its rendering backend, which means:
-
-1. **All figures maintain mm-exact dimensions**
-2. **Automatic metadata embedding** (creation time, dimensions, etc.)
-3. **Consistent styling** across all figures
-4. **High-quality output** optimized for publications
+### Panel Operations
 
 ```python
-# This renders through scitex.plt
-fig, axes = stx.vis.build_figure_from_json(fig_json)
+# Add panel from stx.plt output
+stx.vis.add_panel_from_scitex(
+    project_dir, canvas_name, panel_name,
+    source_png="plot.png",
+    panel_properties={...}
+)
 
-# You get a FigWrapper with all scitex.plt features
-print(type(fig))  # <class 'scitex.plt._subplots._FigWrapper.FigWrapper'>
+# Add panel from image
+stx.vis.add_panel_from_image(
+    project_dir, canvas_name, panel_name,
+    source_image="image.png",
+    panel_properties={...}
+)
 
-# Axes are AxisWrapper objects
-print(type(axes[0]))  # <class 'scitex.plt._subplots._AxesWrapper.AxisWrapper'>
-```
+# Update panel properties
+stx.vis.update_panel(project_dir, canvas_name, panel_name, {"opacity": 0.8})
 
----
+# Remove panel
+stx.vis.remove_panel(project_dir, canvas_name, panel_name)
 
-## API Reference
+# List panels
+panels = stx.vis.list_panels(project_dir, canvas_name)
 
-### Top-Level Functions
+# Get single panel
+panel = stx.vis.get_panel(project_dir, canvas_name, panel_name)
 
-```python
-# Templates
-stx.vis.get_template(name, **kwargs) -> Dict
-stx.vis.list_templates() -> List[str]
-
-# Build & Export
-stx.vis.build_figure_from_json(fig_json) -> (fig, axes)
-stx.vis.export_figure(fig_json, output_path, fmt=None, dpi=300, **kwargs) -> Path
-stx.vis.export_figure_from_file(json_path, output_path, **kwargs) -> Path
-
-# I/O
-stx.vis.load_figure_json(path, validate=True) -> Dict
-stx.vis.save_figure_json(fig_json, path) -> Path
-stx.vis.load_figure_json_from_project(project_dir, figure_id) -> Dict
-stx.vis.save_figure_json_to_project(project_dir, figure_id, fig_json) -> Path
-
-# Models
-stx.vis.FigureModel
-stx.vis.AxesModel
-stx.vis.PlotModel
-stx.vis.GuideModel
-stx.vis.AnnotationModel
-
-# Constants
-stx.vis.NATURE_SINGLE_COLUMN_MM  # 89
-stx.vis.NATURE_DOUBLE_COLUMN_MM  # 183
+# Reorder panels (z-index)
+stx.vis.reorder_panels(project_dir, canvas_name, ["panel_b", "panel_a"])
 ```
 
-### Backend Module
+### Data Operations (Hash Verification)
 
 ```python
-from scitex.vis import backend
+# Compute file hash
+hash_str = stx.vis.compute_file_hash(filepath)  # "sha256:abc123..."
 
-# Parsing
-backend.parse_figure_json(fig_json) -> FigureModel
-backend.validate_figure_json(fig_json) -> bool
+# Verify hash
+is_valid = stx.vis.verify_data_hash(filepath, expected_hash)
 
-# Rendering
-backend.render_figure(fig_model) -> (fig, axes)
-backend.build_figure_from_json(fig_json) -> (fig, axes)
-
-# Export
-backend.export_figure(fig_json, output_path, **kwargs) -> Path
-backend.export_multiple_formats(fig_json, output_dir, base_name, formats) -> Dict
+# Verify all data files in canvas
+results = stx.vis.verify_all_data_hashes(project_dir, canvas_name)
+# {"panels/panel_a/panel.csv": True, ...}
 ```
 
-### IO Module
+### Export Operations
 
 ```python
-from scitex.vis import io
-
-# Load
-io.load_figure_json(path) -> Dict
-io.load_figure_json_from_project(project_dir, figure_id) -> Dict
-io.load_figure_model(path) -> FigureModel
-io.list_figures_in_project(project_dir) -> List[str]
-
-# Save
-io.save_figure_json(fig_json, path) -> Path
-io.save_figure_json_to_project(project_dir, figure_id, fig_json) -> Path
-io.save_figure_model(fig_model, path) -> Path
-```
+# Export to single format
+export_path = stx.vis.export_canvas_to_file(
+    project_dir, canvas_name,
+    output_format="png",  # png, pdf, svg
+    dpi=300
+)
 
-### Utils Module
+# Export to multiple formats
+paths = stx.vis.export_canvas_to_multiple_formats(
+    project_dir, canvas_name,
+    formats=["png", "pdf", "svg"]
+)
 
-```python
-from scitex.vis import utils
-
-# Templates
-utils.get_nature_single_column(height_mm=89, nrows=1, ncols=1) -> Dict
-utils.get_nature_double_column(height_mm=120, nrows=1, ncols=1) -> Dict
-utils.get_science_single_column(height_mm=84, nrows=1, ncols=1) -> Dict
-utils.get_a4_figure(width_mm=180, height_mm=120) -> Dict
-utils.get_square_figure(size_mm=120) -> Dict
-utils.get_presentation_slide(aspect_ratio="16:9") -> Dict
-
-# Validation
-utils.validate_json_structure(fig_json) -> bool
-utils.validate_plot_data(plot_data) -> bool
-utils.check_schema_version(fig_json) -> str
-
-# Constants
-utils.NATURE_SINGLE_COLUMN_MM
-utils.NATURE_DOUBLE_COLUMN_MM
-utils.SCIENCE_SINGLE_COLUMN_MM
-utils.A4_WIDTH_MM
-utils.A4_HEIGHT_MM
+# List existing exports
+exports = stx.vis.list_canvas_exports(project_dir, canvas_name)
 ```
 
 ---
 
-## Project Structure
+## Integration with stx.plt
 
-When using project-based workflows, figures are organized as:
+`stx.plt` outputs (PNG + JSON + CSV) can be directly added as panels:
 
+```python
+# 1. Create figures with stx.plt
+fig, ax = stx.plt.subplots()
+ax.plot(x, y)
+stx.io.save(fig, "./output/timeseries.png")
+# Creates: timeseries.png, timeseries.json, timeseries.csv
+
+# 2. Add to canvas as panel
+stx.vis.add_panel_from_scitex(
+    project_dir, canvas_name, "panel_a",
+    source_png="./output/timeseries.png"  # Auto-finds .json and .csv
+)
 ```
-project/
-└── scitex/
-    └── vis/
-        ├── figs/           # Figure JSON specifications
-        │   ├── fig-001.json
-        │   ├── fig-002.json
-        │   └── ...
-        └── export/         # Exported images (optional)
-            ├── fig-001.png
-            ├── fig-002.pdf
-            └── ...
-```
-
-This structure:
-- ✅ **Version controllable**: JSON files track with your code
-- ✅ **Organized**: Clear separation of specs and outputs
-- ✅ **Collaborative**: Easy to review and edit
-- ✅ **Reproducible**: One JSON → One figure
-
----
-
-## Comparison with Other Tools
-
-| Feature | scitex.vis | Matplotlib | Plotly | Seaborn |
-|---------|-----------|-----------|--------|---------|
-| JSON-based specs | ✅ | ❌ | ✅ | ❌ |
-| Version controllable | ✅ | ❌ | Partial | ❌ |
-| Publication templates | ✅ | ❌ | ❌ | ❌ |
-| mm-exact dimensions | ✅ | ❌ | ❌ | ❌ |
-| Metadata embedding | ✅ | ❌ | ❌ | ❌ |
-| Project structure | ✅ | ❌ | ❌ | ❌ |
-| Backend flexibility | ✅ | N/A | ❌ | Depends on mpl |
 
 ---
 
-## Future Enhancements
-
-Planned features for future versions:
-
-- [ ] **Interactive editing**: Web UI for figure JSON editing
-- [ ] **AI figure generation**: LLM-based figure creation from descriptions
-- [ ] **Figure diff/merge**: Git-friendly figure comparison
-- [ ] **Style inheritance**: Template inheritance and composition
-- [ ] **Figure collections**: Multi-figure documents
-- [ ] **Backend plugins**: Support for alternative renderers
-- [ ] **Automatic layouts**: Smart subplot arrangement
-- [ ] **3D plots**: Support for 3D visualizations
-
----
-
-## Contributing
-
-When contributing to `scitex.vis`:
-
-1. **Models**: Extend models in `model/` for new features
-2. **Renderers**: Add plot types in `backend/render.py`
-3. **Templates**: Add publication formats in `utils/defaults.py`
-4. **Validation**: Update validators in `utils/validate.py`
-
----
+## Examples
 
-## License
+See `examples/vis/` for complete examples:
 
-Part of the SciTeX project. See main LICENSE file.
+- `demo_canvas.py` - Canvas composition workflow
+- `demo_vis_editor.py` - Interactive editor usage
+- `demo_vis_module.py` - Legacy JSON-based workflow
 
 ---
 
 ## Related Documentation
 
+- [CANVAS_ARCHITECTURE.md](./docs/CANVAS_ARCHITECTURE.md) - Full architecture details
 - [scitex.plt](../plt/README.md) - Plotting backend
-- [scitex.io](../io/README.md) - I/O operations
-- [scitex.scholar](../scholar/README.md) - Literature management
-- [scitex.writer](../writer/README.md) - Document generation
+- [FIGURE_ARCHITECTURE.md](../plt/docs/FIGURE_ARCHITECTURE.md) - Figure output format
 
 ---
 
-## Examples
+## Integration with stx.io
 
-See `examples/demo_vis_module.py` for comprehensive examples including:
-- Basic figure creation
-- Multi-subplot layouts
-- Project workflows
-- Model validation
-- Template usage
+Canvas directories (`.canvas`) are first-class citizens in the scitex I/O system:
 
-Run the demo:
-```bash
-python examples/demo_vis_module.py
+```python
+# Save canvas to a portable directory
+stx.io.save(canvas_dict, "/path/to/fig1_results.canvas")
+
+# Load canvas from directory
+canvas = stx.io.load("/path/to/fig1_results.canvas")
+
+# Access canvas properties
+print(canvas["canvas_name"])
+print(canvas["panels"])
 ```
 
 ---
 
-**Made with ❤️ by the SciTeX team**
+## Constants
 
-*Completing the SciTeX ecosystem: scholar → writer → vis*
+```python
+stx.vis.SCHEMA_VERSION          # "2.0.0"
+stx.vis.CANVAS_EXTENSION        # ".canvas"
+stx.vis.NATURE_SINGLE_COLUMN_MM # 89
+stx.vis.NATURE_DOUBLE_COLUMN_MM # 183
+```
 
-<!-- EOF -->
+<!-- EOF -->