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

Uploaded Source

Built Distributions

vl_convert_python-1.2.1-cp37-abi3-win_amd64.whl (26.6 MB view details)

Uploaded CPython 3.7+ Windows x86-64

vl_convert_python-1.2.1-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (27.6 MB view details)

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

vl_convert_python-1.2.1-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (26.8 MB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ ARM64

vl_convert_python-1.2.1-cp37-abi3-macosx_11_0_arm64.whl (25.4 MB view details)

Uploaded CPython 3.7+ macOS 11.0+ ARM64

vl_convert_python-1.2.1-cp37-abi3-macosx_10_12_x86_64.whl (26.3 MB view details)

Uploaded CPython 3.7+ macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for vl_convert_python-1.2.1.tar.gz
Algorithm Hash digest
SHA256 8cde0690434b6ece26df0206bb7dfc76c9b3cea73d7085a1ced59ccb3526a1c6
MD5 be4470f1be036693190b3764f8a599b9
BLAKE2b-256 9cb07e8e8d005a2971c1ecb5dd0eb7e257f939ca2fff0d22b1eb5fd8511594d3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.2.1-cp37-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 cca66f4800b691029eb079eeb0639e88ff2c6180367c89757c75c7e9998d6478
MD5 e55e02002795c5c56ac8377341787cbc
BLAKE2b-256 2df1a495e80a1bf9a4268216ba5b756663aadc43e6c0225d52ae13b24ea096fc

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.2.1-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 52f9785e127daa662b114b0f1d9b689f26c779c907df6c13a0632451e2f47778
MD5 de02b86826ac908c8da359453ea4c523
BLAKE2b-256 58ff333d604a4d23546a32ee7d984cbfd13425917de7e48419a768dc1d178140

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.2.1-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e74a963ec36811e8a7903c19d49914c4caad03b118fac218cbbc041c4399407e
MD5 9606011aa998e77942a9e7fc84fe1d99
BLAKE2b-256 9d5ef8694637a6affa59c3d8767d9a04ca494c8c7da811747db9cf8c592e57c1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.2.1-cp37-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 15163ba71e528f1a1a7f46918098865ef620e8a5134b7d00fc14ac8e79b5fea1
MD5 1199be64e3319e7a060cd0521e4d6fa9
BLAKE2b-256 74ff3033b8898ba80cf464739bc3cd0780ebe38cf69949d0388dd3ecc004e61f

See more details on using hashes here.

File details

Details for the file vl_convert_python-1.2.1-cp37-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for vl_convert_python-1.2.1-cp37-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 7a0c4a32e08701e4ee3e6c0150b4105fb3a7f9edfc139335b2b4b28ce8cc5d15
MD5 e4da54e703ae7b68346471df96d5c514
BLAKE2b-256 37946cedd40754708984bbf753f8877dee0579793a85ebb6a70f1fd28219b6ad

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