Package: vpype
vpypevpypeis the Swiss-Army-knife command-line tool for plotter vector graphics.ContentsWhatvpypeis?How does it work?ExamplesWhatvpypeisn't?InstallationDocumentationFeature overviewGeneralInput/OutputLayout and transformsPlotting optimizationGenerationExtensibility and APIPlug-insContributingLicenseWhatvpypeis?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 alist of existing plug-ins.vpypeis also awell documentedPython libraryuseful 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 environmentvsketchis 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. thereadcommand 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 thereadcommand 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).ExamplesNote: 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-margins2cma4\writeoutput.svgOptimize 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--tolerance0.1mm\linesort\reloop\linesimplify\writeoutput.svgLoad a SVG and display it invpype's viewer, which enable close inspection of the layer and path structure):$vpype\readinput.svg\showLoad 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\writeoutput.svgExport a SVG to HPGL for vintage plotters:$vpype\readinput.svg\layout--fit-to-margins2cm--landscapea4\write--devicehp7475aoutput.hpglDraw the layer name on a SVG (this example usesproperty substitution):$vpype\readinput.svg\text--layer1"{vp_name}"\writeoutput.svgMerge 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-o10cm10cm"%cols%""%rows%"\read--no-fail"%files[_i] if _i < len(files) else ''%"\layout-m0.5cm10x10cm\end\writecombined_on_a_grid.svgAn interactive version of the previous example is available inexamples/grid.vpy. It makes use ofinput()expressions to ask parameters from the user:$vpype-Iexamples/grid.vpy
Files[*.svg]?
Numberofcolumns[3]?4Columnwidth[10cm]?
Rowheight[10cm]?15cm
Margin[0.5cm]?
Outputpath[output.svg]?Split a SVG into one file per layer:$vpype\readinput.svg\forlayer\write"output_%_name or _lid%.svg"\endMore 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.InstallationDetailed 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:pipxinstall"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:pipxinstallvpypeThis 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).DocumentationThevpypeCLI includes its own, detailed documentation:vpype--help# general help and command listvpypeCOMMAND--help# help for a specific commandIn addition, theonline documentationprovides extensive background
information on the fundamentals behindvpype, a cookbook covering most common tasks, thevpypeAPI documentation,
and much more.Feature overviewGeneralEasy 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/OutputSingle- 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 transformsEasy 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).MetadataAdjust 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 optimizationLine 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).FiltersSupport 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)GenerationGeneration 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 APIFirst-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-insHere 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 APIvpype-perspective: put your art in perspectivevpype-pixelart: plot pixel arthatched: half-toning with hatchesvpype-flow-imager: convert images to flow-line-based designsoccult: perform hidden line removaldeduplicate: remove duplicate linesvpype-explorations: my personal grab bag of experiments and utilitiesvpype-gcode: flexible export command for gcode and other text-based formatvpype-dxf: read dxf filesvpype-embroidery: various embroidery-related utilities, including read from/write to most embroidery formatsvpype-vectrace: create outlines from images with vector tracingvpype-ttf: create text outlines using TTF fontsContributingContributions to this project are welcome and do not necessarily require software development skills! Check theContributing sectionof the documentation for more
information.LicenseThis project is licensed under the MIT License - see theLICENSEfile for details.