vpype

vpype provides a command-line interface for processing plotter geometries. It supports arbitrary units (e.g., cm, in) and integrated help via --help.

Key CLI features include:

• Layer Control: Use --layer 1,3 to apply commands to specific layers.
• History: Record command history using the -H flag.
• Reproducibility: Set a Random Number Generator (RNG) seed using the -s flag for generative plugins.
• Property Substitution: Use properties and expression substitution in CLI inputs.

vpype --help
# Example with units and layers
vpype read input.svg translate 3cm 2in --layer 1
# Example with RNG seed
vpype -s 37 read input.svg ...

In vpype, you perform tasks by composing "pipelines" of "commands". Geometries flow through the pipeline, being passed from one command to the next, starting from the first command and ending with the last.

A pipeline is constructed by providing the first command name followed by its options and arguments, then the next command name and its arguments, and so on.

To see a list of all available commands, use the --help flag on the core vpype command. To see help for a specific command, use the --help flag after that command name.

# General pipeline structure
$ vpype command1 [options] [args] command2 [options] [args] ...

# List all available commands
$ vpype --help

# Get help for a specific command
$ vpype circle --help

vpype treats layers as first-class citizens, allowing for both global and per-layer processing. You can manipulate layer properties (metadata) and visual attributes using the following commands:

Layer Manipulation:

• lmove, lcopy, ldelete, lswap, lreverse: Optionally-probabilistic layer edition commands.
• perlayer: Perform complex, per-layer processing.

Metadata and Visuals:

• color: Adjust layer color.
• alpha: Adjust layer alpha.
• penwidth: Adjust pen width.
• name: Change layer name.
• pens: Apply custom pen configurations.
• propset, propget, proplist, propdel, propclear: Manipulate global and per-layer properties.

There are two primary ways to layout geometries in vpype:

1. Pipeline Commands (Preferred): Use commands like layout, scale, scaleto, and translate. These modify the pipeline itself and their effects can be previewed using the show command.
2. Write Options: The write command offers --page-size <size> and --center options. These only affect the output file and do not change the pipeline state. Their effects cannot be previewed with show even if show is called before write.

# Example: Layout to A4 landscape using pipeline commands
$ vpype read input.svg layout --landscape a4 write output.svg

# Example: Layout to A4 landscape using write options (does not affect pipeline state)
$ vpype read input.svg write --page-size a4 --landscape --center output.svg

Expressions in a single vpype pipeline share the same scope. A variable defined in one expression (or via the eval command) is available to all subsequent expressions in that pipeline. This allows you to compute complex values once and reuse them throughout the workflow.

Example

In this pipeline, m is defined as a margin, and w/h are calculated from the page size. These variables are then reused in both crop and rect commands.

$ vpype \
    read input.svg \
    eval "m=2*cm; w,h=prop.vp_page_size; w-=2*m;h-=2*m" \
    crop "%m%" "%m%" "%w%" "%h%" \
    rect "%m%" "%m%" "%w%" "%h%" \
    write output.svg

$ vpype \
    read input.svg \
    eval "m=2*cm; w,h=prop.vp_page_size; w-=2*m;h-=2*m" \
    crop "%m%" "%m%" "%m%" "%w%" "%h%" \
    rect "%m%" "%m%" "%w%" "%h%" \
    write output.svg

A block is a portion of the pipeline that starts with an optional begin command, followed by a block processor command, and ends with an end command.

Commands placed between the block processor and the end command are called nested commands (or the nested pipeline). The block processor executes this nested pipeline one or more times and combines the results into the main pipeline.

For example, a grid block processor executes its nested pipeline once for every cell in the grid, translating the resulting geometries to the appropriate cell position before merging them back into the outer pipeline.

$ vpype begin grid -o 2cm 2cm 2 2 circle 1cm 1cm 8mm line 1cm 2mm 1cm 18mm end show

Global processors are executed exactly once per pipeline and apply to all layers simultaneously. This is distinct from layer processors, which run once for every layer.

Common Global Processors:

• write: Uses all layers to generate a multi-layer SVG file.
• layout: Considers all layers when arranging geometries on a page.
• lmove / lcopy: Layer operations that affect multiple layers at once.

Generators add new geometries to a target layer without affecting existing content in other layers.

By default, a generator targets the layer used by the previous generator in the pipeline, or layer 1 if it is the first generator. You can explicitly set the target layer using the --layer option. Using --layer new creates a new, empty layer with the lowest possible identifier.

Common Generators:

• line: Draws a line between points.
• circle: Generates a circle with center (X, Y) and radius R.
• rect: Generates a rectangle (with optional rounded corners).
• ellipse: Generates an ellipse.
• arc: Generates a circular arc.
• frame: Generates a single-line frame around existing geometries.

# Draw a line on layer 3, then a circle on layer 3
$ vpype line --layer 3 0 0 1cm 1cm circle 0.5cm 0.5cm 0.3cm

Geometries in vpype are organized into a collection of layers, where each layer contains a collection of paths.

Layers

Layers are primarily used for multicolored plots. Each layer typically represents a specific pen or color. Layers are identified by non-zero, positive integers (e.g., 1, 2, 3).

Paths and Polylines

Paths are stored as "polylines"—sequences of 2D points connected by straight segments. vpype does not support curved paths natively; instead, it approximates curves (like circles or Bezier paths) using many small linear segments. This process is controlled by a parameter called quantization.

Note: Approximating curves with polylines can increase file size. If files become too large, use the -q (quantization) option to tune segment length or use the linesimplify command to reduce point density.

vpype operates using a pipeline model. You define a sequence of commands in a terminal, where the output of one command is automatically fed as the input to the next.

Commands generally fall into three categories:

1. Loading commands: Bring geometries into the pipeline (e.g., read).
2. Transformation commands: Modify the geometries (e.g., crop, linemerge, linesort, reloop, linesimplify).
3. Output/Display commands: Read the geometries for final use (e.g., write to save to a file, or show to view in the interactive viewer).

Each command can take arguments (which are usually required, like a file path) and options (which are optional, like --page-size or --center).

In vpype, properties are metadata attached to either the entire pipeline (global properties) or to specific layers (layer properties). They provide information about geometries, such as color, pen width, or names. Properties can have arbitrary names and values (integers, floats, colors, etc.).

Commands in the pipeline are responsible for creating, modifying, or deleting these properties. For example, read creates properties from an input SVG, and write uses certain properties to format the output file.