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"}}
      }
    }
  ]
}

Send the normal JSON request body to POST /vegalite/scenegraph or POST /vega/scenegraph. The response is JSON unless the Accept header asks for MessagePack. Save this Vega-Lite body as request.json:

request.json
{
  "spec": {
    "$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"
      }
    }
  }
}
$ curl http://127.0.0.1:3000/vegalite/scenegraph \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output scenegraph.json

For the Vega and MessagePack combination, save this body as request.json:

request.json
{
  "spec": {
    "$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"
            }
          }
        }
      }
    ]
  }
}
$ curl http://127.0.0.1:3000/vega/scenegraph \
>   -H 'Content-Type: application/json' \
>   -H 'Accept: application/msgpack' \
>   --data-binary @request.json \
>   --output scenegraph.msgpack

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