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-text: generate plottable text with Hershey fonts (based on axi)
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 generator()
decorator:
import click
from vpype import LineCollection, generator
@click.command()
@generator
def my_vpype_plugin():
"""Insert documentation here.
"""
lc = LineCollection()
return lc
my_vpype_plugin.help_group = "Plugins"
Generator commands must return a LineCollection
instance. Plug-in can also contain layer processor or global processor command, respectively using the layer_processor()
and 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.