Thanks to the CLI library which underlies vpype (Click), writing plug-ins is easy and makes it a compelling option for your next plotter project. Plug-ins directly benefit from vpype’s facilities, such as SVG export, line optimization and sorting, scaling and pagination, etc. Plug-ins also benefit from the Click-inherited facilities to easily create compelling CLI interfaces to parametrize your plug-in.
Here are a few existing plug-ins to illustrate the possibilities:
vpype-perspective: put your art in perspective
vpype-gcode: flexible export to gcode or any other text-based format
vpype-embroidery: convert to/from common embroidery file formats
vpype-dxf: read from DXF
vpype-vectrace: trace from bitmap images
occult: perform hidden line removal with closed geometry
deduplicate: remove overlapping lines
vpype-flow-imager: convert image to flow field line art
vpype-pixelart: easy pixel art plotting
(original art by Reddit user u/_NoMansDream)
hatched: convert images to hatched patterns
The easiest way to start a plug-in project is to use the Cookiecutter template for vpype plug-ins. You will first need to install
cookiecutter command (see the website for more info). Then, run the following command:
$ cookiecutter gh:abey79/cookiecutter-vpype-plugin
Cookiecutter will ask you a few questions and create a project structure automatically. To make it operational, the plug-in and its dependencies (including vpype itself) must be installed in a local virtual environment:
$ cd my-vpype-plugin/ $ python3 -m venv venv $ source venv/bin/activate $ pip install --upgrade pip $ pip install --editable .
Note the use of the
--editable flag when installing the plug-in. With this flag, the actual code in the plug-in project is used for the plug-in, which means you can freely edit the source of the plug-in and it is automatically used the next time vpype is run.
Let’s check that that everything works as expected:
$ vpype --help Usage: vpype [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]... Options: -v, --verbose -I, --include PATH Load commands from a command file. --help Show this message and exit. Commands: ... Plugins: my-vpype-plugin Insert documentation here. ...
import click import vpype as vp import vpype_cli @click.command() @vpype_cli.generator def my_vpype_plugin(): """Insert documentation here. """ lc = vp.LineCollection() return lc my_vpype_plugin.help_group = "Plugins"
Generator commands must return a
vpype.LineCollection instance. Plug-in can also contain layer processor or global processor command, respectively using the
@vpype_cli.global_processor decorators. Check the API reference for more information.