Evaluated Scenegraph Output#

A Vega scenegraph is the evaluated tree of groups, marks, and text with their computed positions and styles. It holds layout results rather than chart instructions. Use it when another system needs to inspect rendered marks or drive a custom renderer. Use SVG, PNG, JPEG, or PDF for ordinary image export.

The scenegraph is available as JSON or as MessagePack, a compact binary encoding of the same structure.

The examples use the Vega-Lite specification from Quick Start and the direct Vega specification from Converting from Vega:

chart.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "values": [
      {"category": "A", "value": 28},
      {"category": "B", "value": 55},
      {"category": "C", "value": 43},
      {"category": "D", "value": 91},
      {"category": "E", "value": 81}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}
chart.vg.json
{
  "$schema": "https://vega.github.io/schema/vega/v6.json",
  "width": 300,
  "height": 180,
  "padding": 5,
  "data": [
    {
      "name": "table",
      "values": [
        {"category": "A", "value": 28},
        {"category": "B", "value": 55},
        {"category": "C", "value": 43},
        {"category": "D", "value": 91},
        {"category": "E", "value": 81}
      ]
    }
  ],
  "scales": [
    {
      "name": "xscale",
      "type": "band",
      "domain": {"data": "table", "field": "category"},
      "range": "width",
      "padding": 0.1
    },
    {
      "name": "yscale",
      "domain": {"data": "table", "field": "value"},
      "nice": true,
      "range": "height"
    }
  ],
  "axes": [
    {"orient": "bottom", "scale": "xscale"},
    {"orient": "left", "scale": "yscale"}
  ],
  "marks": [
    {
      "type": "rect",
      "from": {"data": "table"},
      "encode": {
        "enter": {
          "x": {"scale": "xscale", "field": "category"},
          "width": {"scale": "xscale", "band": 1},
          "y": {"scale": "yscale", "field": "value"},
          "y2": {"scale": "yscale", "value": 0}
        },
        "update": {"fill": {"value": "#4c78a8"}}
      }
    }
  ]
}
import json
from pathlib import Path

import vl_convert as vlc

vl_spec = Path("chart.vl.json").read_text(encoding="utf-8")
vg_spec = Path("chart.vg.json").read_text(encoding="utf-8")
scenegraph = vlc.vegalite_to_scenegraph(vl_spec)
scenegraph_msgpack = vlc.vega_to_scenegraph(vg_spec, format="msgpack")
Path("scenegraph.json").write_text(
    json.dumps(scenegraph, indent=2),
    encoding="utf-8",
)
Path("scenegraph.msgpack").write_bytes(scenegraph_msgpack)

The default result is a dictionary. The MessagePack result is bytes. Use vega_to_scenegraph() for an already compiled Vega specification.

The scenegraph follows Vega’s internal representation and may change when Vega changes its layout or mark implementation.