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:

  • 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]...]...

  -v, --verbose
  -I, --include PATH  Load commands from a command file.
  --help              Show this message and exit.



    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

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.