VlConvert#

VlConvert converts Vega-Lite and Vega chart specifications to a variety of static and interactive formats including SVG, PNG, PDF, HTML, and more. It also converts Vega-Lite to Vega.

It runs the official Vega and Vega-Lite JavaScript libraries in an embedded Deno runtime, so it does not require a browser or Node.js installation. It bundles these libraries and their dependencies so access to an online CDN is not required for it to operate. Network requests occur only for remote data, images, fonts, or plugins that the input spec or configuration references.

How it works#

VlConvert’s core is a Rust library, and the project additionally provides Python, CLI, and HTTP server interfaces to the same conversion functionality. See Architecture for how the components fit together.

Example#

Use the interface tabs and format selector below to view example code snippets for converting a Vega-Lite specification to a variety of output formats.

stacked_bar_h.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
  },
  "mark": "bar",
  "encoding": {
    "x": {"aggregate": "sum", "field": "yield"},
    "y": {"field": "variety"},
    "color": {"field": "site"}
  }
}
src/main.rs#
use vl_convert_rs::{anyhow, VlConverter, VlOpts, VlVersion};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let spec = std::fs::read_to_string("stacked_bar_h.vl.json")?;
    let converter = VlConverter::new();
    let output = converter
        .vegalite_to_svg(
            spec,
            VlOpts {
                vl_version: VlVersion::v6_4,
                ..Default::default()
            },
            Default::default(),
        )
        .await?;
    std::fs::write("stacked_bar_h.svg", output.svg)?;
    Ok(())
}
Cargo.toml#
[package]
name = "vl-convert-example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
vl-convert-rs = "=2.0.0-rc7"
main.py#
from pathlib import Path

import vl_convert as vlc

spec = Path("stacked_bar_h.vl.json").read_text(encoding="utf-8")
svg = vlc.vegalite_to_svg(spec, vl_version="6.4")
Path("stacked_bar_h.svg").write_text(svg, encoding="utf-8")
pyproject.toml#
[project]
name = "vl-convert-example"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["vl-convert-python==2.0.0rc7"]

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Perform the conversion:

$ vl-convert vl2svg \
>   --input stacked_bar_h.vl.json \
>   --output stacked_bar_h.svg \
>   --vl-version 6.4

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Start the server in one terminal:

$ vl-convert serve --port 3000

Save this request body:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "aggregate": "sum",
        "field": "yield"
      },
      "y": {
        "field": "variety"
      },
      "color": {
        "field": "site"
      }
    }
  },
  "vl_version": "6.4"
}

Send the request from a second terminal:

$ curl http://127.0.0.1:3000/vegalite/svg \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output stacked_bar_h.svg
src/main.rs#
use vl_convert_rs::{anyhow, PngOpts, VlConverter, VlOpts, VlVersion};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let spec = std::fs::read_to_string("stacked_bar_h.vl.json")?;
    let converter = VlConverter::new();
    let output = converter
        .vegalite_to_png(
            spec,
            VlOpts {
                vl_version: VlVersion::v6_4,
                ..Default::default()
            },
            PngOpts {
                scale: Some(2.0),
                ..Default::default()
            },
        )
        .await?;
    std::fs::write("stacked_bar_h.png", output.data)?;
    Ok(())
}
Cargo.toml#
[package]
name = "vl-convert-example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
vl-convert-rs = "=2.0.0-rc7"
main.py#
from pathlib import Path

import vl_convert as vlc

spec = Path("stacked_bar_h.vl.json").read_text(encoding="utf-8")
png = vlc.vegalite_to_png(spec, vl_version="6.4", scale=2)
Path("stacked_bar_h.png").write_bytes(png)
pyproject.toml#
[project]
name = "vl-convert-example"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["vl-convert-python==2.0.0rc7"]

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Perform the conversion:

$ vl-convert vl2png \
>   --input stacked_bar_h.vl.json \
>   --output stacked_bar_h.png \
>   --vl-version 6.4 \
>   --scale 2

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Start the server in one terminal:

$ vl-convert serve --port 3000

Save this request body:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "aggregate": "sum",
        "field": "yield"
      },
      "y": {
        "field": "variety"
      },
      "color": {
        "field": "site"
      }
    }
  },
  "vl_version": "6.4",
  "scale": 2
}

Send the request from a second terminal:

$ curl http://127.0.0.1:3000/vegalite/png \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output stacked_bar_h.png
src/main.rs#
use vl_convert_rs::{anyhow, JpegOpts, VlConverter, VlOpts, VlVersion};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let spec = std::fs::read_to_string("stacked_bar_h.vl.json")?;
    let converter = VlConverter::new();
    let output = converter
        .vegalite_to_jpeg(
            spec,
            VlOpts {
                vl_version: VlVersion::v6_4,
                ..Default::default()
            },
            JpegOpts {
                scale: Some(2.0),
                quality: Some(90),
            },
        )
        .await?;
    std::fs::write("stacked_bar_h.jpg", output.data)?;
    Ok(())
}
Cargo.toml#
[package]
name = "vl-convert-example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
vl-convert-rs = "=2.0.0-rc7"
main.py#
from pathlib import Path

import vl_convert as vlc

spec = Path("stacked_bar_h.vl.json").read_text(encoding="utf-8")
jpeg = vlc.vegalite_to_jpeg(
    spec,
    vl_version="6.4",
    scale=2,
    quality=90,
)
Path("stacked_bar_h.jpg").write_bytes(jpeg)
pyproject.toml#
[project]
name = "vl-convert-example"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["vl-convert-python==2.0.0rc7"]

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Perform the conversion:

$ vl-convert vl2jpeg \
>   --input stacked_bar_h.vl.json \
>   --output stacked_bar_h.jpg \
>   --vl-version 6.4 \
>   --scale 2 \
>   --quality 90

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Start the server in one terminal:

$ vl-convert serve --port 3000

Save this request body:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "aggregate": "sum",
        "field": "yield"
      },
      "y": {
        "field": "variety"
      },
      "color": {
        "field": "site"
      }
    }
  },
  "vl_version": "6.4",
  "scale": 2,
  "quality": 90
}

Send the request from a second terminal:

$ curl http://127.0.0.1:3000/vegalite/jpeg \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output stacked_bar_h.jpg
src/main.rs#
use vl_convert_rs::{anyhow, VlConverter, VlOpts, VlVersion};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let spec = std::fs::read_to_string("stacked_bar_h.vl.json")?;
    let converter = VlConverter::new();
    let output = converter
        .vegalite_to_pdf(
            spec,
            VlOpts {
                vl_version: VlVersion::v6_4,
                ..Default::default()
            },
            Default::default(),
        )
        .await?;
    std::fs::write("stacked_bar_h.pdf", output.data)?;
    Ok(())
}
Cargo.toml#
[package]
name = "vl-convert-example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
vl-convert-rs = "=2.0.0-rc7"
main.py#
from pathlib import Path

import vl_convert as vlc

spec = Path("stacked_bar_h.vl.json").read_text(encoding="utf-8")
pdf = vlc.vegalite_to_pdf(spec, vl_version="6.4")
Path("stacked_bar_h.pdf").write_bytes(pdf)
pyproject.toml#
[project]
name = "vl-convert-example"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["vl-convert-python==2.0.0rc7"]

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Perform the conversion:

$ vl-convert vl2pdf \
>   --input stacked_bar_h.vl.json \
>   --output stacked_bar_h.pdf \
>   --vl-version 6.4

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Start the server in one terminal:

$ vl-convert serve --port 3000

Save this request body:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "aggregate": "sum",
        "field": "yield"
      },
      "y": {
        "field": "variety"
      },
      "color": {
        "field": "site"
      }
    }
  },
  "vl_version": "6.4"
}

Send the request from a second terminal:

$ curl http://127.0.0.1:3000/vegalite/pdf \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output stacked_bar_h.pdf
src/main.rs#
use vl_convert_rs::{
    anyhow, HtmlOpts, Renderer, VlConverter, VlOpts, VlVersion,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let spec = std::fs::read_to_string("stacked_bar_h.vl.json")?;
    let converter = VlConverter::new();
    let output = converter
        .vegalite_to_html(
            spec,
            VlOpts {
                vl_version: VlVersion::v6_4,
                ..Default::default()
            },
            HtmlOpts {
                bundle: true,
                renderer: Renderer::Svg,
            },
        )
        .await?;
    std::fs::write("stacked_bar_h.html", output.html)?;
    Ok(())
}
Cargo.toml#
[package]
name = "vl-convert-example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
vl-convert-rs = "=2.0.0-rc7"
main.py#
from pathlib import Path

import vl_convert as vlc

spec = Path("stacked_bar_h.vl.json").read_text(encoding="utf-8")
html = vlc.vegalite_to_html(
    spec,
    vl_version="6.4",
    bundle=True,
    renderer="svg",
)
Path("stacked_bar_h.html").write_text(html, encoding="utf-8")
pyproject.toml#
[project]
name = "vl-convert-example"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["vl-convert-python==2.0.0rc7"]

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Perform the conversion:

$ vl-convert vl2html \
>   --input stacked_bar_h.vl.json \
>   --output stacked_bar_h.html \
>   --vl-version 6.4 \
>   --bundle \
>   --renderer svg

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Start the server in one terminal:

$ vl-convert serve --port 3000

Save this request body:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "aggregate": "sum",
        "field": "yield"
      },
      "y": {
        "field": "variety"
      },
      "color": {
        "field": "site"
      }
    }
  },
  "vl_version": "6.4",
  "bundle": true,
  "renderer": "svg"
}

Send the request from a second terminal:

$ curl http://127.0.0.1:3000/vegalite/html \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output stacked_bar_h.html
src/main.rs#
use vl_convert_rs::{anyhow, VlConverter, VlOpts, VlVersion};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let spec = std::fs::read_to_string("stacked_bar_h.vl.json")?;
    let converter = VlConverter::new();
    let output = converter
        .vegalite_to_vega(
            spec,
            VlOpts {
                vl_version: VlVersion::v6_4,
                ..Default::default()
            },
        )
        .await?;
    let vega = serde_json::to_string_pretty(&output.spec)?;
    std::fs::write("stacked_bar_h.vg.json", vega)?;
    Ok(())
}
Cargo.toml#
[package]
name = "vl-convert-example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
vl-convert-rs = "=2.0.0-rc7"
main.py#
import json
from pathlib import Path

import vl_convert as vlc

spec = Path("stacked_bar_h.vl.json").read_text(encoding="utf-8")
vega = vlc.vegalite_to_vega(spec, vl_version="6.4")
Path("stacked_bar_h.vg.json").write_text(
    json.dumps(vega, indent=2) + "\n",
    encoding="utf-8",
)
pyproject.toml#
[project]
name = "vl-convert-example"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["vl-convert-python==2.0.0rc7"]

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Perform the conversion:

$ vl-convert vl2vg \
>   --input stacked_bar_h.vl.json \
>   --output stacked_bar_h.vg.json \
>   --vl-version 6.4 \
>   --pretty

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Start the server in one terminal:

$ vl-convert serve --port 3000

Save this request body:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "aggregate": "sum",
        "field": "yield"
      },
      "y": {
        "field": "variety"
      },
      "color": {
        "field": "site"
      }
    }
  },
  "vl_version": "6.4"
}

Send the request from a second terminal:

$ curl http://127.0.0.1:3000/vegalite/vega \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output stacked_bar_h.vg.json
src/main.rs#
use vl_convert_rs::{anyhow, vegalite_to_url, UrlOpts};

fn main() -> anyhow::Result<()> {
    let spec = std::fs::read_to_string("stacked_bar_h.vl.json")?;
    let url = vegalite_to_url(spec, UrlOpts::default())?;
    println!("{url}");
    Ok(())
}
Cargo.toml#
[package]
name = "vl-convert-example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
vl-convert-rs = "=2.0.0-rc7"
main.py#
from pathlib import Path

import vl_convert as vlc

spec = Path("stacked_bar_h.vl.json").read_text(encoding="utf-8")
url = vlc.vegalite_to_url(spec)
print(url)
pyproject.toml#
[project]
name = "vl-convert-example"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["vl-convert-python==2.0.0rc7"]

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Perform the conversion:

$ vl-convert vl2url --input stacked_bar_h.vl.json

Download a prebuilt executable, or build it with Cargo:

$ cargo install vl-convert \
>   --version '=2.0.0-rc7' \
>   --locked

Start the server in one terminal:

$ vl-convert serve --port 3000

Save this request body:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json"
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "aggregate": "sum",
        "field": "yield"
      },
      "y": {
        "field": "variety"
      },
      "color": {
        "field": "site"
      }
    }
  }
}

Send the request from a second terminal:

$ curl http://127.0.0.1:3000/vegalite/url \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json
Horizontal stacked bar chart of barley yield by variety and site
{
  "$schema": "https://vega.github.io/schema/vega/v6.json",
  "background": "white",
  "padding": 5,
  "width": 300,
  "style": "cell",
  "data": [
    {
      "name": "source_0",
      "url": "https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/barley.json",
      "format": {
        "type": "json"
      },
      "transform": [
        {
          "type": "aggregate",
          "groupby": [
            "variety",
            "site"
          ],
          "ops": [
            "sum"
          ],
          "fields": [
            "yield"
          ],
          "as": [
            "sum_yield"
          ]
        },
        {
          "type": "stack",
          "groupby": [
            "variety"
          ],
          "field": "sum_yield",
          "sort": {
            "field": [
              "site"
            ],
            "order": [
              "ascending"
            ]
          },
          "as": [
            "sum_yield_start",
            "sum_yield_end"
          ],
          "offset": "zero"
        },
        {
          "type": "filter",
          "expr": "isValid(datum[\"sum_yield\"]) && isFinite(+datum[\"sum_yield\"])"
        }
      ]
    }
  ],
  "signals": [
    {
      "name": "y_step",
      "value": 20
    },
    {
      "name": "height",
      "update": "bandspace(domain('y').length, 0.1, 0.05) * y_step"
    }
  ],
  "marks": [
    {
      "name": "marks",
      "type": "rect",
      "style": [
        "bar"
      ],
      "from": {
        "data": "source_0"
      },
      "encode": {
        "update": {
          "fill": {
            "scale": "color",
            "field": "site"
          },
          "ariaRoleDescription": {
            "value": "bar"
          },
          "description": {
            "signal": "\"Sum of yield: \" + (format(datum[\"sum_yield\"], \"\")) + \"; variety: \" + (isValid(datum[\"variety\"]) ? isArray(datum[\"variety\"]) ? join(datum[\"variety\"], ' ') : datum[\"variety\"] : \"\"+datum[\"variety\"]) + \"; site: \" + (isValid(datum[\"site\"]) ? isArray(datum[\"site\"]) ? join(datum[\"site\"], ' ') : datum[\"site\"] : \"\"+datum[\"site\"])"
          },
          "x": {
            "scale": "x",
            "field": "sum_yield_end"
          },
          "x2": {
            "scale": "x",
            "field": "sum_yield_start"
          },
          "y": {
            "scale": "y",
            "field": "variety"
          },
          "height": {
            "signal": "max(0.25, bandwidth('y'))"
          }
        }
      }
    }
  ],
  "scales": [
    {
      "name": "x",
      "type": "linear",
      "domain": {
        "data": "source_0",
        "fields": [
          "sum_yield_start",
          "sum_yield_end"
        ]
      },
      "range": [
        0,
        {
          "signal": "width"
        }
      ],
      "nice": true,
      "zero": true
    },
    {
      "name": "y",
      "type": "band",
      "domain": {
        "data": "source_0",
        "field": "variety",
        "sort": true
      },
      "range": {
        "step": {
          "signal": "y_step"
        }
      },
      "paddingInner": 0.1,
      "paddingOuter": 0.05
    },
    {
      "name": "color",
      "type": "ordinal",
      "domain": {
        "data": "source_0",
        "field": "site",
        "sort": true
      },
      "range": "category"
    }
  ],
  "axes": [
    {
      "scale": "x",
      "orient": "bottom",
      "gridScale": "y",
      "grid": true,
      "tickCount": {
        "signal": "ceil(width/40)"
      },
      "domain": false,
      "labels": false,
      "aria": false,
      "maxExtent": 0,
      "minExtent": 0,
      "ticks": false,
      "zindex": 0
    },
    {
      "scale": "x",
      "orient": "bottom",
      "grid": false,
      "title": "Sum of yield",
      "labelFlush": true,
      "labelOverlap": true,
      "tickCount": {
        "signal": "ceil(width/40)"
      },
      "zindex": 0
    },
    {
      "scale": "y",
      "orient": "left",
      "grid": false,
      "title": "variety",
      "zindex": 0
    }
  ],
  "legends": [
    {
      "fill": "color",
      "symbolType": "square",
      "title": "site"
    }
  ]
}

Choose an Interface#

All four VlConvert interfaces share one conversion engine, so a chart renders the same way from each of them given the same configuration and environment. Each interface has specialized documentation.

Rust

Embed vl-convert-rs directly in Rust applications.

Rust
Python

Use vl-convert-python from Python applications and Altair workflows.

Python
CLI

Run vl-convert from scripts, shells, and build pipelines.

CLI
Server

Run vl-convert serve as an HTTP rendering worker.

Server