DeepSVG: a research codebase for vector graphics as tensors

The problem DeepSVG addresses: SVG as training data, not as a file format

Most SVG tooling treats a document as markup to render. DeepSVG treats it as a sequence of geometric commands that a neural network can consume and emit. The repository states that it ships three things beyond the paper: training code to reproduce the Hierarchical Generative Network, a library for deep learning with SVG data with export to differentiable PyTorch tensors, and the SVG-Icons8 dataset. The intended audience is therefore narrow. It is a researcher or graduate student who wants to train or fine-tune a generative model over icon or font outlines, or someone doing gradient-based shape optimisation who needs an SVG representation that participates in autograd. If you want to convert a folder of SVGs to PNG at scale, this is the wrong repository, and the README never claims otherwise. The interesting part is the middle layer. Converting SVG to tensors is the unglamorous step that stops most people from training on vector data at all, because paths are variable-length, use many command types, and carry absolute and relative coordinates. DeepSVG's answer is to normalise everything into a small command subset and pad it into fixed-shape tensors.

How the representation works: command reduction, simplification, then tensors

The library's stated features are parsing of SVG files, conversion of basic shapes and commands to the subset m/l/c/z, path simplification using Ramer-Douglas-Peucker and the Philip J. Schneider algorithm, data augmentation by translation, scaling and rotation, conversion to PyTorch tensor format, and draw utilities including control-point visualisation and GIF export. That list is the architecture in miniature. Parsing produces a scene graph of shapes; the shape layer reduces everything to move, line, cubic Bezier and close commands so the network sees one vocabulary instead of the full SVG command set; simplification cuts the number of control points, which directly controls sequence length; augmentation happens in the same geometric space before tensor conversion. The README's example shows the intended order of operations: load an SVG, call normalize(), then simplify_heuristic(), then chain zoom, translate and rotate before draw(). Normalisation matters because a generative model trained on icons should not have to relearn that the same dolphin can sit at any scale or origin. The paper title describes the network as hierarchical, which matches the structure of SVG itself: a document contains groups, groups contain paths, paths contain commands. The repository does not spell out the network internals in the README, so anything beyond that grouping hierarchy has to come from the arXiv paper rather than the code listing.

Getting it running: conda, cairo, and the dataset download

The installation path in the README is explicit. Clone the repository, then create a Python 3.7 conda environment:

conda create -n deepsvg python=3.7 conda activate deepsvg pip install -r requirements.txt

CairoSVG has its own system requirements, and the README points at its documentation rather than restating it, giving two examples: sudo apt-get install libcairo2-dev on Ubuntu and brew install cairo libffi on macOS. The tested environments listed are Ubuntu 18.04 with CUDA 10.1, and macOS 10.13.6 with CUDA 10.1 and PyTorch installed from source. That is a 2020 configuration. Python 3.7 and CUDA 10.1 are both old enough that a modern machine will likely need a different PyTorch build, and the README does not describe how to do that. The dataset step is cd dataset/ followed by bash download.sh, with a manual fallback: icons_meta.csv at 9 MB and icons_tensor.zip at 3 GB, both hosted on Google Drive. The 3 GB archive holds 100k icons already converted to pre-augmented PyTorch tensors, which the README says enables easy reproduction of the paper's work. For fonts, the repository recommends following SVG-VAE's instructions and also releases a smaller demo set through bash download_fonts.sh.

Training on your own SVGs: the preprocess script and three config keys

The part most likely to be reused is the custom-data path, and it is documented concretely. The SVGDataset dataloader accepts raw SVGs, and the README advises preprocessing before training for better I/O performance rather than setting already_preprocessed to False and doing it on the fly. The preprocessing command is:

python -m dataset.preprocess --data_folder dataset/svgs/ --output_folder dataset/svgs_simplified/ --output_meta_file dataset/svg_meta.csv

The README says this runs in a multi-threaded way and produces a metadata file used for filtering during training. Then three configuration values change:

cfg.dataloader_module = "deepsvg.svg_dataset" cfg.data_dir = "./dataset/svgs_simplified/" cfg.meta_filepath = "./dataset/svg_meta.csv"

That is the whole custom-dataset story as presented. There is no description of the config file format, no list of training hyperparameters, and no command for launching a training run in the README text supplied. Anyone planning to train from scratch should expect to read the paper and the notebook code to fill that gap. The preprocess step is also where the m/l/c/z reduction gets applied to your own artwork, which is the point at which fidelity loss becomes your problem rather than the authors'.

The differentiable tensor layer and what the notebook actually demonstrates

The README describes differentiable operations on SVGTensor, comparing the idea to PyTorch3D, and states that this enables deforming a circle to match an arbitrary target via gradient descent. It also notes that using a lower number of Bezier commands in the initial circle produces what it calls artistic approximations of the target. That is a shape-fitting demo, not a generative model, and it is the clearest example of why the tensor conversion exists as a separate library rather than being buried inside the training script. The walkthrough lives in notebooks/svglib.ipynb, which the README calls a walk-trough of deepsvg.svglib. The sample code shows a fluent chain: SVG.load_svg("docs/imgs/dolphin.svg").normalize(), then simplify_heuristic(), then zoom(0.75).translate(Point(0, 5)).rotate(Angle(15)), then draw(). Animation is a single call, icon.animate(), which writes a GIF. Two caveats follow from the material. First, the notebook is the documentation; the README gives a taste and defers the rest, so API stability is whatever the notebook and source happen to show. Second, the repository is described as Jupyter Notebook as its primary language, which tells you where the executable examples live and where the maintenance attention has gone.

Where DeepSVG breaks down: simplification, licensing, and the missing dataset source

Three limitations are visible without running anything. The first is geometric fidelity. Path simplification via Ramer-Douglas-Peucker and Schneider is lossy by design, and the m/l/c/z conversion discards command types that the network does not model. For icons this is usually acceptable. For maps, technical drawings, or typography with hinting, the reduced representation may not be. The second is the dataset licence boundary. The pre-converted icons_tensor archive is what the repository ships, but the README states that for full flexibility and more research freedom it recommends downloading the original SVG icons from icons8, which requires a paid plan, and that instructions to download the dataset from source are coming soon. So the reproducible artefact is the tensor dump, and the provenance of the underlying icons is a commercial one. The MIT licence on the code does not settle what you may do with the data; that is a separate question and not one to answer from a repository badge. The third is operational: no releases are listed, no homepage is declared, and the last push date is well after the paper, which suggests occasional maintenance rather than active development. There is no inference server, no CLI for batch generation, and no versioned API surface.

The real alternative: SVG-VAE and what changes in the approach

The README itself points to SVG-VAE, specifically the Magenta implementation, as the recommended source for the font dataset. The two projects solve an overlapping problem with different modelling assumptions. SVG-VAE is the earlier work that DeepSVG positions itself against, and the naming in the topics list (svg-vae alongside autoencoder and transformer) reflects that lineage. The difference that matters for adoption is structural: DeepSVG's stated contribution is a hierarchical generative network, meaning it models the grouping of paths inside a document rather than treating the drawing as one flat command sequence. That hierarchy is what the paper claims enables animation between vector graphics, which is the demo the project page and the one-minute video show. If you only need to autoencode and interpolate flat icon outlines, the older approach is simpler and the ecosystem around Magenta is larger. If you need the grouping structure preserved so that parts of a drawing can move independently, that is the specific gap DeepSVG claims to fill. The trade-off is that you inherit a research codebase with a notebook as its front door, rather than a library with a release cadence.

Maintenance, upgrades, and what to check before you depend on it

The upgrade cost here is mostly environmental. Pinning Python 3.7 and CUDA 10.1 from the tested-environments list means a new machine will need a dependency resolution pass that the README does not document, and CairoSVG is a system-level dependency that fails at import time rather than install time if libcairo2-dev or cairo and libffi are missing. The dataset is a 3 GB download from Google Drive links, which is a fragile distribution channel for a reproducibility artefact; if those links rot, the pre-augmented tensors are gone and the recommended fallback is a paid icons8 plan. On licensing, the repository is MIT, which is permissive for the code, but the icons and fonts come from elsewhere and the README's own wording about a paid plan should be read as a signal that the data has its own terms. Nothing here is legal advice; read the licence file and the upstream data terms yourself. The practical position is that DeepSVG is worth adopting as a component, the svglib conversion and simplification layer, while treating the training code as a paper companion that you fork rather than track.

Editorial conclusion

Adopt DeepSVG if you are reproducing the paper, training an icon or font generative model from the shipped SVG-Icons8 tensors, or you need a differentiable SVG-to-tensor layer for shape optimisation. Do not adopt it if you want a maintained inference service, a stable API, or a path from raw designer SVGs to production output without preprocessing work. Before committing, verify three things: that libcairo2-dev or cairo and libffi resolve on your platform, that the 3 GB icons_tensor.zip download completes from the Google Drive links, and that your own SVG corpus survives the m/l/c/z conversion in dataset/preprocess.py without losing the shapes you care about.

Official sources

1. alexandre01/deepsvg on GitHub
2. Issues
3. License: MIT
4. README