Plug-ins#
Why?#
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
vpype-ttf: create text outlines with TTF fonts
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
How?#
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.
...
The cookiecutter project includes a single generator command with the @vpype_cli.generator
decorator:
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.layer_processor
and @vpype_cli.global_processor
decorators. Check the API reference for more information.
Getting help#
This being a rather young project, documentation may be missing and/or rough around the edges. The author is available for support on Drawingbots’s Discord server.