Home

Awesome

banner

vpype

PyPI python Downloads license Test codecov Sonarcloud Status Documentation Status Code style: Black

vpype is the Swiss-Army-knife command-line tool for plotter vector graphics.

Contents

What vpype is?

vpype is the Swiss-Army-knife command-line tool for plotter vector graphics. Here is what it can do:

vpype is highly extensible through plug-ins that can greatly extend its capabilities. For example, plug-ins already exists for plotting pixel art, half-toning with hatches, and much more. See below for a list of existing plug-ins.

vpype is also a well documented Python library useful to create generative art and tools for plotters. It includes data structures, utility and I/O functions, as well as a hardware-accelerated flexible viewer for vector graphics. For example, the plotter generative art environment vsketch is built upon vpype.

Check the documentation for a more thorough introduction to vpype.

How does it work?

vpype works by building so-called pipelines of commands, where each command's output is fed to the next command's input. Some commands load geometries into the pipeline (e.g. the read command which loads geometries from a SVG file). Other commands modify these geometries, e.g. by cropping them (crop) or reordering them to minimize pen-up travels (linesort). Finally, some other commands just read the geometries in the pipeline for display purposes (show) or output to file (write).

Pipeline are defined using the vpype's CLI (command-line interface) in a terminal by typing vpype followed by the list of commands, each with their optional parameters and their arguments:

command line

This pipeline uses five commands (in bold):

There are many more commands available in vpype, see the overview below.

Some commands have arguments, which are always required (in italic). For example, a file path must be provided to the read command and dimensions must be provided to the crop commands. A command may also have options which are, well, optional. In this example, --page-size a4 means that the write command will generate a A4-sized SVG (otherwise it would have the same size as in.svg). Likewise, because --center is used, the write command will center geometries on the page before saving the SVG (otherwise the geometries would have been left at their original location).

Examples

Note: The following examples are laid out over multiple lines using end-of-line escaping (\). This is done to highlight the various commands of which the pipeline is made and would typically not be done in real-world use.

Load an SVG file, scale it to a specific size, and export it centered on an A4-sized, ready-to-plot SVG file:

$ vpype \
  read input.svg \
  layout --fit-to-margins 2cm a4 \
  write output.svg

Optimize paths to reduce plotting time (merge connected lines, sort them to minimize pen-up distance, randomize closed paths' seam, and reduce the number of nodes):

$ vpype \
  read input.svg \
  linemerge --tolerance 0.1mm \
  linesort \
  reloop \
  linesimplify \
  write output.svg

Load a SVG and display it in vpype's viewer, which enable close inspection of the layer and path structure):

$ vpype \
  read input.svg \
  show

Load several SVG files and save them as a single, multi-layer SVG file (e.g. for multicolored drawings):

$ vpype \
  forfile "*.svg" \
    read --layer %_i% %_path% \
  end \
  write output.svg

Export a SVG to HPGL for vintage plotters:

$ vpype \
  read input.svg \
  layout --fit-to-margins 2cm --landscape a4 \
  write --device hp7475a output.hpgl

Draw the layer name on a SVG (this example uses property substitution):

$ vpype \
    read input.svg \
    text --layer 1 "{vp_name}" \
    write output.svg

Merge multiple SVG files in a grid layout (this example uses expression substitution):

$ vpype \
    eval "files=glob('*.svg')" \
    eval "cols=3; rows=ceil(len(files)/cols)" \
    grid -o 10cm 10cm "%cols%" "%rows%" \
        read --no-fail "%files[_i] if _i < len(files) else ''%" \
        layout -m 0.5cm 10x10cm \
    end \
    write combined_on_a_grid.svg

An interactive version of the previous example is available in examples/grid.vpy. It makes use of input() expressions to ask parameters from the user:

$ vpype -I examples/grid.vpy
Files [*.svg]?
Number of columns [3]? 4
Column width [10cm]?
Row height [10cm]? 15cm
Margin [0.5cm]?
Output path [output.svg]?

Split a SVG into one file per layer:

$ vpype \
    read input.svg \
    forlayer \
      write "output_%_name or _lid%.svg" \
    end

More examples and recipes are available in the cookbook.

What vpype isn't?

vpype caters to plotter generative art and does not aim to be a general purpose (think Illustrator/InkScape) vector graphic tools. One of the main reason for this is the fact vpype converts everything curvy (circles, bezier curves, etc.) to lines made of small segments. vpype does import metadata such stroke and fill color, stroke width, etc., it only makes partial use of them and does not aim to maintain a full consistency with the SVG specification. These design choices make vpype's rich feature set possible, but limits its use for, e.g., printed media.

Installation

Detailed installation instructions are available in the latest documentation.

TL;DR:

Documentation

The vpype CLI includes its own, detailed documentation:

vpype --help          # general help and command list
vpype COMMAND --help  # help for a specific command

In addition, the online documentation provides extensive background information on the fundamentals behind vpype, a cookbook covering most common tasks, the vpype API documentation, and much more.

Feature overview

General

Input/Output

Layout and transforms

Metadata

Plotting optimization

Filters

Generation

Extensibility and API

Plug-ins

Here is a list of known vpype plug-ins (please make a pull request if yours is missing):

Contributing

Contributions to this project are welcome and do not necessarily require software development skills! Check the Contributing section of the documentation for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.