Skip to main content

Convert Vega-Lite chart specifications to SVG, PNG, or Vega

Project description

Overview

vl-convert-python is a dependency-free Python package for converting Vega-Lite chart specifications into static images (SVG or PNG) or Vega chart specifications.

Since an Altair chart can generate Vega-Lite, this package can be used to easily create static images from Altair charts.

Try it out on Binder!
Binder

Installation

vl-convert-python can be installed using pip with

$ pip install vl-convert-python

Usage

The vl-convert-python package provides a series of conversion functions under the vl_convert module.

Convert Vega-Lite to SVG, PNG, and Vega

The vegalite_to_svg and vegalite_to_png functions can be used to convert Vega-Lite specifications to static SVG and PNG images respectively. The vegalite_to_vega function can be used to convert a Vega-Lite specification to a Vega specification.

import vl_convert as vlc
import json

vl_spec = r"""
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {"url": "https://raw.githubusercontent.com/vega/vega-datasets/next/data/movies.json"},
  "mark": "circle",
  "encoding": {
    "x": {
      "bin": {"maxbins": 10},
      "field": "IMDB Rating"
    },
    "y": {
      "bin": {"maxbins": 10},
      "field": "Rotten Tomatoes Rating"
    },
    "size": {"aggregate": "count"}
  }
}
"""

# Create SVG image string and then write to a file
svg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)
with open("chart.svg", "wt") as f:
    f.write(svg_str)

# Create PNG image data and then write to a file
png_data = vlc.vegalite_to_png(vl_spec=vl_spec, scale=2)
with open("chart.png", "wb") as f:
    f.write(png_data)

# Create low-level Vega representation of chart and write to file
vg_spec = vlc.vegalite_to_vega(vl_spec)
with open("chart.vg.json", "wt") as f:
    json.dump(vg_spec, f)

Convert Altair Chart to SVG, PNG, and Vega

The Altair visualization library provides a Pythonic API for generating Vega-Lite visualizations. As such, vl-convert-python can be used to convert Altair charts to PNG, SVG, or Vega. The vegalite_* functions support an optional vl_version argument that can be used to specify the particular version of the Vega-Lite JavaScript library to use. Version 4.2 of the Altair package uses Vega-Lite version 4.17, so this is the version that should be specified when converting Altair charts.

import altair as alt
from vega_datasets import data
import vl_convert as vlc
import json

source = data.barley()

chart = alt.Chart(source).mark_bar().encode(
    x='sum(yield)',
    y='variety',
    color='site'
)

# Create SVG image string and then write to a file
svg_str = vlc.vegalite_to_svg(chart.to_json(), vl_version="4.17")
with open("altair_chart.svg", "wt") as f:
    f.write(svg_str)

# Create PNG image data and then write to a file
png_data = vlc.vegalite_to_png(chart.to_json(), vl_version="4.17", scale=2)
with open("altair_chart.png", "wb") as f:
    f.write(png_data)

# Create low-level Vega representation of chart and write to file
vg_spec = vlc.vegalite_to_vega(chart.to_json(), vl_version="4.17")
with open("altair_chart.vg.json", "wt") as f:
    json.dump(vg_spec, f)

How it works

This crate uses PyO3 to wrap the vl-convert-rs Rust crate as a Python library. The vl-convert-rs crate is a self-contained Rust library for converting Vega-Lite visualization specifications into various formats. The conversions are performed using the Vega-Lite and Vega JavaScript libraries running in a v8 JavaScript runtime provided by the deno_runtime crate. Font metrics and SVG-to-PNG conversions are provided by the resvg crate.

Of note, vl-convert-python is fully self-contained and has no dependency on an external web browser or Node.js runtime.

Development setup

Create development conda environment

$ conda create -n vl-convert-dev -c conda-forge python=3.10 deno maturin altair pytest black black-jupyter scikit-image

Activate environment and pip install remaining dependencies

$ conda activate vl-convert-dev
$ pip install pypdfium2

Change to Python package directory

$ cd vl-convert-python

Build Rust python package with maturin in develop mode

$ maturin develop --release

Run tests

$ pytest tests

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vl_convert_python-1.5.0.tar.gz (4.8 MB view details)

Uploaded Source

Built Distributions

vl_convert_python-1.5.0-cp37-abi3-win_amd64.whl (28.8 MB view details)

Uploaded CPython 3.7+ Windows x86-64

vl_convert_python-1.5.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (29.5 MB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ x86-64

vl_convert_python-1.5.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (28.6 MB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ ARM64

vl_convert_python-1.5.0-cp37-abi3-macosx_11_0_arm64.whl (26.5 MB view details)

Uploaded CPython 3.7+ macOS 11.0+ ARM64

File details

Details for the file vl_convert_python-1.5.0.tar.gz.

File metadata

  • Download URL: vl_convert_python-1.5.0.tar.gz
  • Upload date:
  • Size: 4.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: maturin/1.6.0

File hashes

Hashes for vl_convert_python-1.5.0.tar.gz
Algorithm Hash digest
SHA256 ba1e13a84f5a3d1af393d0d32aa19c4268db573d5f5c799bce8a5dc0468b1899
MD5 024662b9d9e9b394066cfed0aee61e20
BLAKE2b-256 9a2ccb7f0d69d9bbd7769262444c1c6760820de0309fad2f8d2b92acf73cd632

See more details on using hashes here.

File details

Details for the file vl_convert_python-1.5.0-cp37-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for vl_convert_python-1.5.0-cp37-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 6d493952f568c85a445c2e515371a61f7ff2d09f5585e915abceec3efcd5826b
MD5 6cdbf163a8252e149ee35d18f50d9fb4
BLAKE2b-256 01d99ae3de0bbd8d48ca7dcbe6c2087c794e04038e87f23ba5412a740c616949

See more details on using hashes here.

File details

Details for the file vl_convert_python-1.5.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-1.5.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 889a403781e08a77e22370a6cac25e1c0720042dbaa7d006a5dcc3bf015e7587
MD5 4750a3894a0da2f28e58953ab9d79b81
BLAKE2b-256 4af4c9c711f6fc18838cea552875faa2c41bbc451fd37e400240f076775bbb74

See more details on using hashes here.

File details

Details for the file vl_convert_python-1.5.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for vl_convert_python-1.5.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0244666476817c1f772d26286485c24ce2218fafd9b4f1913a6ef21857083531
MD5 16ba14b7c50b84bb2529ec41e4fde668
BLAKE2b-256 58fd96bf010819e8c1ebeb181e0a25d3bfcc0f1d2b649134dea7b2599ea139f0

See more details on using hashes here.

File details

Details for the file vl_convert_python-1.5.0-cp37-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for vl_convert_python-1.5.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 fba51e437a09aa0fb04e1931a4b851231053aeb14715a3653e272c829aac1dc4
MD5 1b726d54e4e6cd06c4762d2574f4702e
BLAKE2b-256 bdb48d324ab1338278c741e0c940999bbad58cefa4b38e5443b983044203a957

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page