Document Format

Naming

• Document: the canonical plot data/config payload.
• Session: document + additional UI view state for the editor.

Document example (version: "1.0")

{
  "version": "1.0",
  "figure_title": "Whole Figure Title",
  "figure_title_fontsize": 16,
  "figure_title_position": { "x": 0.5, "y": 0.98 },
  "grid": { "rows": 2, "cols": 1, "share_x": true, "share_y": false },
  "subplots": [
    {
      "id": "subplot-main",
      "title": "Transmission",
      "x_label": "Frequency (GHz)",
      "y_label": "Transmission (a.u.)",
      "title_fontsize": 12,
      "label_fontsize": 10,
      "x_label_position": { "x": 0.5, "y": -0.08 },
      "y_label_position": { "x": -0.08, "y": 0.5 },
      "x_scale": "linear",
      "y_scale": "linear",
      "x_lim": [4.7, 5.3],
      "y_lim": [0.0, 1.05],
      "grid": false,
      "legend": { "visible": true, "x": 0.04, "y": 0.96, "framealpha": 0.9 },
      "layout": { "row": 0, "col": 0, "row_span": 1, "col_span": 1 }
    },
    {
      "id": "subplot-2",
      "title": "Residuals",
      "x_label": "Frequency (GHz)",
      "y_label": "Residual",
      "title_fontsize": 12,
      "label_fontsize": 10,
      "x_scale": "linear",
      "y_scale": "linear",
      "grid": false,
      "layout": { "row": 1, "col": 0, "row_span": 1, "col_span": 1 }
    }
  ],
  "datasets": [
    {
      "id": "ds-line-1",
      "name": "Signal",
      "columns": [
        { "id": "col-x", "name": "x", "kind": "raw", "role": "x", "values": [0, 1, 2] },
        { "id": "col-y", "name": "y", "kind": "raw", "role": "y", "values": [0.0, 1.1, 2.1] }
      ]
    }
  ],
  "layers": [
    {
      "id": "layer-line-1",
      "dataset_id": "ds-line-1",
      "y_column_id": "col-y",
      "subplot_id": "subplot-main",
      "label": "Signal",
      "visible": true,
      "style": { "color": "#005f73", "linewidth": 2.0, "marker": "o" }
    }
  ],
  "axes": {
    "title": "Transmission",
    "x_label": "Frequency (GHz)",
    "y_label": "Transmission (a.u.)",
    "x_lim": [4.7, 5.3],
    "y_lim": [0.0, 1.05],
    "grid": false,
    "legend": { "visible": true, "x": 0.04, "y": 0.96, "framealpha": 0.9 }
  },
  "annotations": [
    {
      "id": "ann-text-1",
      "type": "text",
      "subplot_id": "subplot-main",
      "text": "Peak",
      "x": 5.0,
      "y": 0.92,
      "color": "#111111",
      "fontsize": 10
    },
    {
      "id": "ann-vline-1",
      "type": "vline",
      "subplot_id": "subplot-main",
      "x": 5.0,
      "position_mode": "fit_param",
      "fit_binding": { "fit_id": "fit-1", "parameter": "x0", "scale": 1.0, "offset": 0.0 },
      "color": "#bb3e03",
      "linewidth": 1.5,
      "linestyle": "--"
    }
  ],
  "fits": [
    {
      "id": "fit-1",
      "dataset_id": "ds-line-1",
      "y_column_id": "col-y",
      "subplot_id": "subplot-main",
      "model": "custom",
      "label": "Lorentz Peak Fit",
      "enabled": true,
      "custom_function": "def lorentz(x, a, x0, gamma, offset):\n    return offset + a / (1 + ((x - x0) / gamma) ** 2)"
    }
  ]
}

Key document fields

• figure_title, figure_title_fontsize, figure_title_position: figure-level suptitle state
• grid: subplot grid shape and axis-sharing flags
• subplots: canonical subplot definitions; layers, fits, and annotations bind to these via subplot_id
• axes: compatibility mirror of the active/primary subplot axes
• annotations: supports text, arrow, hline, and vline
• fits: fit specs used by the web app; fit-derived annotations can bind to these by fit_id

Line annotation binding

hline and vline annotations support two positioning modes:

• manual: use the numeric x or y value directly
• fit_param: resolve the position from a fit parameter using fit_binding

Example:

{
  "id": "ann-vline-1",
  "type": "vline",
  "subplot_id": "subplot-main",
  "x": 5.0,
  "position_mode": "fit_param",
  "fit_binding": {
    "fit_id": "fit-1",
    "parameter": "x0",
    "scale": 1.0,
    "offset": 0.0
  }
}

If the fit is unavailable, the stored numeric x / y value acts as the fallback.

Session envelope example

{
  "session_version": "1.0",
  "saved_at": "2026-03-21T18:00:00Z",
  "document": { "...": "document payload" },
  "view": {
    "figure_width_cm": 15.24,
    "figure_height_cm": 10.16,
    "dpi": 150.0,
    "selected_fit_id": "",
    "active_subplot_id": "subplot-main",
    "annotation_position_mode": "data",
    "show_edit_overlays": true,
    "export_format": "png",
    "include_export_edit_remark": true
  }
}

Versioning

• pontink package is independently versioned (1.0.0 currently).
• The pont.ink document/session JSON schema version is currently 1.0.
• axes is still present for compatibility, but new editors should treat subplots + grid as the canonical figure layout model.