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:

  • hatched: convert images to hatched patterns

    https://i.imgur.com/QLlBpNU.png https://i.imgur.com/fRIrPV2.jpg

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.