vpype

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

Contents

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

Whatvpypeis?

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

• layoutexisting vector files with precise control on position, scale and page format;
• optimizeexisting SVG files for faster and cleaner plots;
• createHPGL outputfor vintage plotters;
• creategenerative artworkfrom scratch through built-in commands orplug-ins;
• create, modify and processmulti-layer vector filesfor multi-colour plots;
• and much more...

vpypeis highlyextensiblethrough plug-ins that can greatly extend its capabilities. For example, plug-ins already exists for plottingpixel art, half-toning with hatches,and much more. See below for a list of existing plug-ins.

vpypeis also awell documentedPython 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 vsketchis built uponvpype.

Check thedocumentationfor a more thorough introduction tovpype.

How does it work?

vpypeworks by building so-calledpipelinesofcommands,where each command's output is fed to the next command's input. Some commands load geometries into the pipeline (e.g. theread 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 thevpype's CLI (command-line interface) in a terminal by typingvpypefollowed by the list of commands, each with their optional parameters and their arguments:

This pipeline uses five commands (in bold):

• readloads geometries from a SVG file.
• linemergemerges paths whose extremities are close to each other (within the provided tolerance).
• linesortreorder paths such as to minimise the pen-up travel.
• crop,well, crops.
• writeexport the resulting geometries to a SVG file.

There are many more commands available invpype,see theoverviewbelow.

Some commands have arguments, which are always required (in italic). For example, a file path must be provided to the readcommand and dimensions must be provided to thecropcommands. A command may also have options which are, well, optional. In this example,--page-size a4means that thewritecommand will generate a A4-sized SVG (otherwise it would have the same size asin.svg). Likewise, because--centeris used, thewritecommand 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 \
readinput.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 \
readinput.svg \
linemerge --tolerance 0.1mm \
linesort \
reloop \
linesimplify \
write output.svg

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

$ vpype \
readinput.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 \
readinput.svg \
layout --fit-to-margins 2cm --landscape a4 \
write --device hp7475a output.hpgl

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

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

Merge multiple SVG files in a grid layout (this example usesexpression 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 inexamples/grid.vpy.It makes use ofinput()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 \
readinput.svg \
forlayer \
write"output_%_name or _lid%.svg"\
end

More examples and recipes are available in thecookbook.

Whatvpypeisn't?

vpypecaters 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 factvpypeconverts everything curvy (circles, bezier curves, etc.) to lines made of small segments.vpypedoes 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 makevpype's rich feature set possible, but limits its use for, e.g., printed media.

Installation

Detailed installation instructions are available in thelatest documentation.

TL;DR:

• Python 3.12 is recommended, butvpypeis also compatible with Python 3.10 and 3.11.
• vpypeis published on thePython Package Indexand can be installed usingpipx:

  pipx install"vpype[all]"

• A Windows installer is availablehere,but plug-ins cannot be installed when using this method).
• A CLI-only version ofvpypecan be installed using the following command:

  pipx install vpype

  This version does not include theshowcommand but does not require some of the dependencies which are more difficult or impossible to install on some platforms (such as matplotlib, PySide6, and ModernGL).

Documentation

ThevpypeCLI includes its own, detailed documentation:

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

In addition, theonline documentationprovides extensive background information on the fundamentals behindvpype,a cookbook covering most common tasks, thevpypeAPI documentation, and much more.

Feature overview

General

• Easy to useCLIinterface with integrated help (vpype --helpandvpype COMMAND --help) and support for arbitrary units (e.g.vpype read input.svg translate 3cm 2in).
• First-classmulti-layer supportwith global or per-layer processing (e.g.vpype COMMANDNAME --layer 1,3) and optionally-probabilistic layer edition commands (lmove,lcopy,ldelete,lswap,lreverse).
• Support forper-layer and global properties,which acts as metadata and is used by multiple commands and plug-ins.
• Support forpropertyandexpression substitutionin CLI user input.
• Support for complex,per-layerprocessing (perlayer).
• Powerful hardware-accelerateddisplaycommand with adjustable units, optional per-line coloring, optional pen-up trajectories display and per-layer visibility control (show).
• Geometrystatisticsextraction (stat).
• Support forcommand historyrecording (vpype -H [...])
• Support forRNG seedconfiguration for generative plug-ins (vpype -s 37 [...]).

Input/Output

• Single- and multi-layerSVG inputwith adjustable precision, parallel processing for large SVGs, and supports percent or missing width/height (read).
• Support forSVG outputwith 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 forHPGL outputconfig-based generation of HPGL code with fine layout control (page size and orientation, centering).
• Support for pattern-basedfile collectionprocessing (forfile).

Layout and transforms

• Easy and flexiblelayoutcommand for centring and fitting to margin with selectable le horizontal and vertical alignment (layout).
• Page rotationcommand (pagerotate).
• Powerfultransformcommands for scaling, translating, skewing and rotating geometries (scale,translate,skew,rotate).
• Support forscalingandcroppingto arbitrary dimensions (scaleto,crop).
• Support fortrimminggeometries by an arbitrary amount (trim).
• Arbitrarypage sizedefinition (pagesize).

Metadata

• Adjust layercolor,Alpha,pen widthandname(color,Alpha,penwidth,name).
• Apply provided or fully customisablepen configurations(pens).
• Manipulate global and per-layerproperties(propset,propget,proplist,propdel,propclear).

Plotting optimization

• Line mergingwith optional path reversal and configurable merging threshold (linemerge).
• Line sortingwith optional path reversal (linesort).
• Line simplificationwith adjustable accuracy (linesimplify).
• Closed paths'seam location randomization,to reduce the visibility of pen-up/pen-down artifacts (reloop).
• Support for generatingmultiple passeson each line (multipass).

Filters

• Support forfilteringby line lengths or closed-ness (filter).
• Squigglefilter for shaky-hand or liquid-like styling (squiggles)
• Support forsplittingall lines to their constituent segments (splitall).
• Support forreversingorder of paths within their layers (reverse).
• Support forsplittinglayers by drawing distance (splitdist)

Generation

• Generation of arbitraryprimitivesincluding lines, rectangles, circles, ellipses and arcs (line,rect,circle,ellipse,arc).
• Generation oftextusing bundled Hershey fonts (text)
• Generation of grid-like layouts (grid).
• Generation of aframearound the geometries (frame).
• Generation of random lines for debug/learning purposes (random)

Extensibility and API

• First-class support forplug-inextensions (e.gvpype-text,hatched,occult).
• Support forscript-basedgeneration (script).
• Powerful andwell-documentedAPIfor 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:vsketchis complete framework for plotter generative artists implemented usingvpype's API
• vpype-perspective:put your art in perspective
• 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
• deduplicate:remove duplicate lines
• 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
• vpype-ttf:create text outlines using TTF fonts

Contributing

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

License

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