# Overview
`vl-convert-python` is a dependency-free Python package for converting [Vega-Lite](https://vega.github.io/vega-lite/) chart specifications into static images (SVG or PNG) or [Vega](https://vega.github.io/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! \
[](https://mybinder.org/v2/gh/jonmmease/vl-convert/main?labpath=vl-convert-python%2Fnotebooks%2Fconvert_vegalite.ipynb)
# 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.
```python
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.
```python
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](https://pyo3.rs/) to wrap the [`vl-convert-rs`](https://crates.io/crates/vl-convert-rs) Rust crate as a Python library. The `vl-convert-rs` crate is a self-contained Rust library for converting [Vega-Lite](https://vega.github.io/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`](https://crates.io/crates/deno_runtime) crate. Font metrics and SVG-to-PNG conversions are provided by the [`resvg`](https://crates.io/crates/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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jonmmease/vl-convert",
"name": "vl-convert-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e6/f1/43803e91e12d4ab697eedc5e14029d1630daea0c81abc6321b96a31a7dc0/vl_convert_python-1.7.0.tar.gz",
"platform": null,
"description": "# Overview\n`vl-convert-python` is a dependency-free Python package for converting [Vega-Lite](https://vega.github.io/vega-lite/) chart specifications into static images (SVG or PNG) or [Vega](https://vega.github.io/vega/) chart specifications.\n\n\nSince an Altair chart can generate Vega-Lite, this package can be used to easily create static images from Altair charts.\n\nTry it out on Binder! \\\n[](https://mybinder.org/v2/gh/jonmmease/vl-convert/main?labpath=vl-convert-python%2Fnotebooks%2Fconvert_vegalite.ipynb)\n\n# Installation\n`vl-convert-python` can be installed using pip with\n\n```\n$ pip install vl-convert-python\n```\n\n# Usage\nThe `vl-convert-python` package provides a series of conversion functions under the `vl_convert` module.\n\n## Convert Vega-Lite to SVG, PNG, and Vega\nThe `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.\n\n```python\nimport vl_convert as vlc\nimport json\n\nvl_spec = r\"\"\"\n{\n \"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\",\n \"data\": {\"url\": \"https://raw.githubusercontent.com/vega/vega-datasets/next/data/movies.json\"},\n \"mark\": \"circle\",\n \"encoding\": {\n \"x\": {\n \"bin\": {\"maxbins\": 10},\n \"field\": \"IMDB Rating\"\n },\n \"y\": {\n \"bin\": {\"maxbins\": 10},\n \"field\": \"Rotten Tomatoes Rating\"\n },\n \"size\": {\"aggregate\": \"count\"}\n }\n}\n\"\"\"\n\n# Create SVG image string and then write to a file\nsvg_str = vlc.vegalite_to_svg(vl_spec=vl_spec)\nwith open(\"chart.svg\", \"wt\") as f:\n f.write(svg_str)\n\n# Create PNG image data and then write to a file\npng_data = vlc.vegalite_to_png(vl_spec=vl_spec, scale=2)\nwith open(\"chart.png\", \"wb\") as f:\n f.write(png_data)\n\n# Create low-level Vega representation of chart and write to file\nvg_spec = vlc.vegalite_to_vega(vl_spec)\nwith open(\"chart.vg.json\", \"wt\") as f:\n json.dump(vg_spec, f)\n```\n\n## Convert Altair Chart to SVG, PNG, and Vega\nThe 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.\n\n```python\nimport altair as alt\nfrom vega_datasets import data\nimport vl_convert as vlc\nimport json\n\nsource = data.barley()\n\nchart = alt.Chart(source).mark_bar().encode(\n x='sum(yield)',\n y='variety',\n color='site'\n)\n\n# Create SVG image string and then write to a file\nsvg_str = vlc.vegalite_to_svg(chart.to_json(), vl_version=\"4.17\")\nwith open(\"altair_chart.svg\", \"wt\") as f:\n f.write(svg_str)\n\n# Create PNG image data and then write to a file\npng_data = vlc.vegalite_to_png(chart.to_json(), vl_version=\"4.17\", scale=2)\nwith open(\"altair_chart.png\", \"wb\") as f:\n f.write(png_data)\n\n# Create low-level Vega representation of chart and write to file\nvg_spec = vlc.vegalite_to_vega(chart.to_json(), vl_version=\"4.17\")\nwith open(\"altair_chart.vg.json\", \"wt\") as f:\n json.dump(vg_spec, f)\n```\n# How it works\nThis crate uses [PyO3](https://pyo3.rs/) to wrap the [`vl-convert-rs`](https://crates.io/crates/vl-convert-rs) Rust crate as a Python library. The `vl-convert-rs` crate is a self-contained Rust library for converting [Vega-Lite](https://vega.github.io/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`](https://crates.io/crates/deno_runtime) crate. Font metrics and SVG-to-PNG conversions are provided by the [`resvg`](https://crates.io/crates/resvg) crate.\n\nOf note, `vl-convert-python` is fully self-contained and has no dependency on an external web browser or Node.js runtime.\n\n# Development setup\nCreate development conda environment\n```\n$ conda create -n vl-convert-dev -c conda-forge python=3.10 deno maturin altair pytest black black-jupyter scikit-image\n```\n\nActivate environment and pip install remaining dependencies\n```\n$ conda activate vl-convert-dev\n$ pip install pypdfium2\n```\n\nChange to Python package directory\n```\n$ cd vl-convert-python\n\n```\nBuild Rust python package with maturin in develop mode\n```\n$ maturin develop --release\n```\n\nRun tests\n```\n$ pytest tests\n```\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Convert Vega-Lite chart specifications to SVG, PNG, or Vega",
"version": "1.7.0",
"project_urls": {
"Homepage": "https://github.com/jonmmease/vl-convert",
"Source Code": "https://github.com/jonmmease/vl-convert"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e21cb0dc67d9e51eb9d14c35c79e033a680a92418edd12a3879bb50aade597a1",
"md5": "7bf631152edc3575cafe9509d5983a2c",
"sha256": "90fba4356bd621bd31e72507a55e26dd13ebe79efa784715743116109afd0d47"
},
"downloads": -1,
"filename": "vl_convert_python-1.7.0-cp37-abi3-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "7bf631152edc3575cafe9509d5983a2c",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 28233538,
"upload_time": "2024-10-05T14:32:44",
"upload_time_iso_8601": "2024-10-05T14:32:44.438896Z",
"url": "https://files.pythonhosted.org/packages/e2/1c/b0dc67d9e51eb9d14c35c79e033a680a92418edd12a3879bb50aade597a1/vl_convert_python-1.7.0-cp37-abi3-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dc504b8b500f0b3c0b24ef3bec01563de412e95dbf27cfe53e403e6fa8514525",
"md5": "d531c3283c15e834e5a820fcb114f7e7",
"sha256": "51f99c58b1d0d74126455ece7d41972740cb4430b8dfdf7e0908270eed5be32d"
},
"downloads": -1,
"filename": "vl_convert_python-1.7.0-cp37-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "d531c3283c15e834e5a820fcb114f7e7",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 26940338,
"upload_time": "2024-10-05T14:32:49",
"upload_time_iso_8601": "2024-10-05T14:32:49.266507Z",
"url": "https://files.pythonhosted.org/packages/dc/50/4b8b500f0b3c0b24ef3bec01563de412e95dbf27cfe53e403e6fa8514525/vl_convert_python-1.7.0-cp37-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "950f139568d71fadcb1be697acd2ccd0b79bd1553ca833d4448312191cd33654",
"md5": "51f8ad165d6facbf534a95bf1399c222",
"sha256": "962100d7670b9d35f9bb9745cdf590412f62f57c134b4a142340ba93a4dbddba"
},
"downloads": -1,
"filename": "vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "51f8ad165d6facbf534a95bf1399c222",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 29124271,
"upload_time": "2024-10-05T14:32:54",
"upload_time_iso_8601": "2024-10-05T14:32:54.189098Z",
"url": "https://files.pythonhosted.org/packages/95/0f/139568d71fadcb1be697acd2ccd0b79bd1553ca833d4448312191cd33654/vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "913cc34e52138fa38eb6059cdb2c603ba1433decf4f97cb89e767c04a9605eff",
"md5": "8e5567f92afd481b9635d54643eb931d",
"sha256": "8b50c492b640abb89a54a71e2c26f0f2d2c1cedc42030cc55bcc202670334724"
},
"downloads": -1,
"filename": "vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "8e5567f92afd481b9635d54643eb931d",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 30089941,
"upload_time": "2024-10-05T14:32:59",
"upload_time_iso_8601": "2024-10-05T14:32:59.429854Z",
"url": "https://files.pythonhosted.org/packages/91/3c/c34e52138fa38eb6059cdb2c603ba1433decf4f97cb89e767c04a9605eff/vl_convert_python-1.7.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aee2c4a3fff3efcfeebaab554c9c4b027e875fd339da7f619b144765353a60d1",
"md5": "9fbc2fddd0e08447cd29eb471c0bdb59",
"sha256": "285bbadb1ce8a922c87f6e75a9544fe10a652d37bd4c1519fb93f90bab381588"
},
"downloads": -1,
"filename": "vl_convert_python-1.7.0-cp37-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "9fbc2fddd0e08447cd29eb471c0bdb59",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 29796401,
"upload_time": "2024-10-05T14:33:04",
"upload_time_iso_8601": "2024-10-05T14:33:04.650816Z",
"url": "https://files.pythonhosted.org/packages/ae/e2/c4a3fff3efcfeebaab554c9c4b027e875fd339da7f619b144765353a60d1/vl_convert_python-1.7.0-cp37-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e6f143803e91e12d4ab697eedc5e14029d1630daea0c81abc6321b96a31a7dc0",
"md5": "2d01dc32ee37690241dc877fa96dbc6b",
"sha256": "bc9e1f8ca0d8d3b3789c66e37cd6a8cf0a83406427d5143133346c2b5004485b"
},
"downloads": -1,
"filename": "vl_convert_python-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "2d01dc32ee37690241dc877fa96dbc6b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4719466,
"upload_time": "2024-10-05T14:33:07",
"upload_time_iso_8601": "2024-10-05T14:33:07.741054Z",
"url": "https://files.pythonhosted.org/packages/e6/f1/43803e91e12d4ab697eedc5e14029d1630daea0c81abc6321b96a31a7dc0/vl_convert_python-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-05 14:33:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jonmmease",
"github_project": "vl-convert",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vl-convert-python"
}
JSON
