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

Uploaded Source

Built Distributions

vl_convert_python-1.7.0-cp37-abi3-win_amd64.whl (29.8 MB view details)

Uploaded CPython 3.7+ Windows x86-64

vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (30.1 MB view details)

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

vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (29.1 MB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ ARM64

vl_convert_python-1.7.0-cp37-abi3-macosx_11_0_arm64.whl (26.9 MB view details)

Uploaded CPython 3.7+ macOS 11.0+ ARM64

vl_convert_python-1.7.0-cp37-abi3-macosx_10_12_x86_64.whl (28.2 MB view details)

Uploaded CPython 3.7+ macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: vl_convert_python-1.7.0.tar.gz
  • Upload date:
  • Size: 4.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for vl_convert_python-1.7.0.tar.gz
Algorithm Hash digest
SHA256 bc9e1f8ca0d8d3b3789c66e37cd6a8cf0a83406427d5143133346c2b5004485b
MD5 2d01dc32ee37690241dc877fa96dbc6b
BLAKE2b-256 e6f143803e91e12d4ab697eedc5e14029d1630daea0c81abc6321b96a31a7dc0

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.7.0-cp37-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 285bbadb1ce8a922c87f6e75a9544fe10a652d37bd4c1519fb93f90bab381588
MD5 9fbc2fddd0e08447cd29eb471c0bdb59
BLAKE2b-256 aee2c4a3fff3efcfeebaab554c9c4b027e875fd339da7f619b144765353a60d1

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8b50c492b640abb89a54a71e2c26f0f2d2c1cedc42030cc55bcc202670334724
MD5 8e5567f92afd481b9635d54643eb931d
BLAKE2b-256 913cc34e52138fa38eb6059cdb2c603ba1433decf4f97cb89e767c04a9605eff

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 962100d7670b9d35f9bb9745cdf590412f62f57c134b4a142340ba93a4dbddba
MD5 51f8ad165d6facbf534a95bf1399c222
BLAKE2b-256 950f139568d71fadcb1be697acd2ccd0b79bd1553ca833d4448312191cd33654

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.7.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 51f99c58b1d0d74126455ece7d41972740cb4430b8dfdf7e0908270eed5be32d
MD5 d531c3283c15e834e5a820fcb114f7e7
BLAKE2b-256 dc504b8b500f0b3c0b24ef3bec01563de412e95dbf27cfe53e403e6fa8514525

See more details on using hashes here.

Provenance

File details

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

File metadata

File hashes

Hashes for vl_convert_python-1.7.0-cp37-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 90fba4356bd621bd31e72507a55e26dd13ebe79efa784715743116109afd0d47
MD5 7bf631152edc3575cafe9509d5983a2c
BLAKE2b-256 e21cb0dc67d9e51eb9d14c35c79e033a680a92418edd12a3879bb50aade597a1

See more details on using hashes here.

Provenance

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