vpype

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

Contents

• What vpype is?
• How does it work?
• Examples
• What vpype isn't?
• Installation
• Documentation
• Feature overview
  • General
  • Input/Output
  • Layout and transforms
  • Plotting optimization
  • Generation
  • Extensibility and API
• Plug-ins
• Contributing
• License

What vpype is?

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

• layout existing vector files with precise control on position, scale and page format;
• optimize existing SVG files for faster and cleaner plots;
• create HPGL output for vintage plotters;
• create generative artwork from scratch through built-in commands or plug-ins;
• create, modify and process multi-layer vector files for multi-colour plots;
• and much more...

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:

This pipeline uses five commands (in bold):

• read loads geometries from a SVG file.
• linemerge merges paths whose extremities are close to each other (within the provided tolerance).
• linesort reorder paths such as to minimise the pen-up travel.
• crop, well, crops.
• write export the resulting geometries to a SVG file.

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: although it is not required, commands are separated by multiple spaces for clarity in the following examples.

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  scaleto 10cm 10cm  write --page-size a4 --center output.svg

Optimize paths to reduce plotting time (merge connected lines and sort them to minimize pen-up distance):

vpype  read input.svg  linemerge --tolerance 0.1mm  linesort  write output.svg

Visualize the path structure of large SVG files, showing whether lines are properly joined or not thanks to a colorful display:

vpype  read input.svg  show --colorful

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

vpype  read -l 1 input1.svg  read -l 2 input2.svg  write output.svg

Create arbitrarily-sized, grid-like designs like this page's top banner:

vpype  begin  grid -o 1cm 1cm 10 13  script alien_letter.py  scaleto 0.5cm 0.5cm  end  show

Export to HPGL for vintage plotters:

vpype  read input.svg  write --device hp7475a --page-size a4 --landscape --center output.hpgl

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 also dismisses the stroke and fill properties (color, line width, etc.) of the imported graphics. These design choices make possible vpype's rich feature set, but makes its use for, e.g., printed media limited.

Installation

For Windows, an installer is available here (note: plug-ins cannot be installed when using this installation method).

For other platforms, and when plug-ins are required, vpype can be installed from the Python Package Index using the following command:

pip install vpype

Python must previously be installed. Python version 3.9.1 or later is recommended to use vpype, although it is also compatible with Python 3.6 and later.

For Linux, install Python with your OS's default package manager. For macOS, Python is best installed from either MacPorts or Homebrew. For Windows, use the official installer.

Check the documentation for more details, in particular on how to use a virtual environment (recommended).

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

• Easy to use CLI interface with integrated help (vpype --helpand vpype COMMAND --help) and support for arbitrary units (e.g. vpype read input.svg translate 3cm 2in).
• First-class multi-layer support with global or per-layer processing (e.g. vpype COMMANDNAME --layer 1,3) and optionally-probabilistic layer edition commands (lmove, lcopy, ldelete).
• Powerful hardware-accelerated display command with adjustable units, optional per-line coloring, optional pen-up trajectories display and per-layer visibility control (show).
• Geometry statistics extraction (stat).
• Support for command history recording (vpype -H [...])
• Support for RNG seed configuration for generative plug-ins (vpype -s 37 [...]).

Input/Output

• Single- and multi-layer SVG input with adjustable precision, parallel processing for large SVGs, and supports percent or missing width/height (read).
• Support for SVG output with fine layout control (page size and orientation, centering), layer support with custom layer names, optional display of pen-up trajectories, various option for coloring (write).
• Support for HPGL output config-based generation of HPGL code with fine layout control (page size and orientation, centering).

Layout and transforms

• Easy and flexible layout command for centring and fitting to margin with selectable le horizontal and vertical alignment (layout).
• Powerful transform commands for scaling, translating, skewing and rotating geometries (scale, translate, skew, rotate).
• Support for scaling and cropping to arbitrary dimensions (scaleto, crop).
• Support for trimming geometries by an arbitrary amount (trim).
• Arbitrary page size definition (pagesize).

Plotting optimization

• Line merging with optional path reversal and configurable merging threshold (linemerge).
• Line sorting with optional path reversal (linesort).
• Line simplification with adjustable accuracy (linesimplify).
• Closed paths' seam location randomization, to reduce the visibility of pen-up/pen-down artifacts (reloop).
• Support for generating multiple passes on each line (multipass).

Filters

• Support for filtering by line lengths or closed-ness (filter).
• Squiggle filter for shaky-hand or liquid-like styling (squiggles)
• Support for splitting all lines to their constituent segments (splitall).
• Support for reversing order of paths within their layers (reverse).

Generation

• Generation of arbitrary primitives including lines, rectangles, circles, ellipses and arcs (line, rect, circle, ellipse, arc).
• Generation of text using bundled Hershey fonts (text)
• Generation of grid-like layouts (grid).
• Generation of a frame around the geometries (frame).
• Generation of random lines for debug/learning purposes (random)

Extensibility and API

• First-class support for plug-in extensions (e.g vpype-text, hatched, occult).
• Support for script-based generation (script).
• Powerful and well-documented API for plug-ins and other plotter generative art projects.

Plug-ins

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

• vsketch: vsketch is complete framework for plotter generative artists implemented using vpype's API
• vpype-pixelart: plot pixel art
• hatched: half-toning with hatches
• vpype-flow-imager: convert images to flow-line-based designs
• occult: perform hidden line removal
• vpype-explorations: my personal grab bag of experiments and utilities
• vpype-gcode: flexible export command for gcode and other text-based format
• vpype-dxf: read dxf files
• vpype-embroidery: various embroidery-related utilities, including read from/write to most embroidery formats
• vpype-vectrace: create outlines from images with vector tracing

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.