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-0.14.0.tar.gz (3.8 MB view details)

Uploaded Source

Built Distributions

vl_convert_python-0.14.0-cp37-abi3-win_amd64.whl (25.5 MB view details)

Uploaded CPython 3.7+ Windows x86-64

vl_convert_python-0.14.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (25.5 MB view details)

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

vl_convert_python-0.14.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (24.9 MB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ ARM64

vl_convert_python-0.14.0-cp37-abi3-macosx_11_0_arm64.whl (23.4 MB view details)

Uploaded CPython 3.7+ macOS 11.0+ ARM64

vl_convert_python-0.14.0-cp37-abi3-macosx_10_7_x86_64.whl (24.5 MB view details)

Uploaded CPython 3.7+ macOS 10.7+ x86-64

File details

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

File metadata

File hashes

Hashes for vl_convert_python-0.14.0.tar.gz
Algorithm Hash digest
SHA256 8d3d63d7c8e446cb2e9bf2209513b3c608805152acdf50275a6f430fa18d6613
MD5 964ece4c11b8de7bd6bb43e1d7306def
BLAKE2b-256 6f44f7db9dfe6287ff94750a3962ae9e1cf9b185f97f54c265017ea662a05e99

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-0.14.0-cp37-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 b971bc56e5975dfaa4f43b03f59864ccdc566d822b780e111d13e3b32f019c39
MD5 112dd606b0066495ab21d52f541713e8
BLAKE2b-256 915cc11e8ae9fd234af2aa442c3a99b0d369c790820c89623ee4c30e4bcfc67f

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-0.14.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b0319723121785efb03d295949d46e4a0f4795afcea7aafb99d1e880b53d6b22
MD5 c745b71bc91d5d07f98b122aa9258a5d
BLAKE2b-256 d179af36e4d6873682820d0abebf043d593ae63ad89e1c55df52e84389b476f7

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-0.14.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 5dcccdba6929b50179a3e702bf3e95dd31cfb9a98b7162c75a275865e320de98
MD5 e6c21a96b306e306eae7927fe78cd9c9
BLAKE2b-256 500d031a77f85aa03222f5883f9c119fcffeccea0164a1ac86317dc5e71ad443

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-0.14.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9122ebca0a8fe54492019b395acca618595fc7b2f1d09a0e77cd0fbcd471b1a8
MD5 083eb4079c9f861411294c0ad2921d64
BLAKE2b-256 6d0a3a7de8dfe3ee3fda429e6642a2f379ec51504ec9027deaf30942a902f19d

See more details on using hashes here.

File details

Details for the file vl_convert_python-0.14.0-cp37-abi3-macosx_10_7_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-0.14.0-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm Hash digest
SHA256 a93b8151871d4bc9efc2a7961395859411803f70ad32694e3b906d781233a921
MD5 e8f1bb7775c839f77e2f3bdd13a73f92
BLAKE2b-256 ea556d8513c386a01bb2d7e1429c505d35f1cdbad953f7c98a0fbc7b6222f077

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