### Install vpype with all features

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install vpype with all optional features using pipx. This command installs the full package, including the viewer.

```bash
pipx install "vpype[all]"
```

--------------------------------

### Install vpype with Pipx

Source: https://github.com/abey79/vpype/blob/master/docs/index.md

Installs vpype and all optional dependencies using pipx. Ensure pipx is installed and configured.

```bash
$ pipx install "vpype[all]"
```

--------------------------------

### Verify Plugin Installation

Source: https://github.com/abey79/vpype/blob/master/docs/plugins.md

Run 'vpype --help' to confirm that your newly installed plug-in is recognized and listed under the 'Plugins' section.

```bash
$ vpype --help
```

--------------------------------

### Command File Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Shows how to convert a nested pipeline into a command file for cleaner command-line execution.

```bash
# command_file.vpy - example command file
begin
  grid --offset 8cm 8cm 2 3
    begin
      grid --offset 2cm 2cm 3 3
      random --count 20 --area 1cm 1cm
      frame
    end
  frame --offset 0.3cm
end
show
```

--------------------------------

### Install pipx and vpype on Raspberry Pi

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install pipx and then vpype on Raspberry Pi. This is for the CLI-only version and should be favored when possible.

```bash
sudo apt-get install pipx
```

```bash
pipx ensurepath
```

```bash
pipx install vpype
```

```bash
vpype --version
```

--------------------------------

### Install Poetry using install script

Source: https://github.com/abey79/vpype/blob/master/docs/contributing.md

Use this command to install Poetry, the dependency management tool for vpype, via a shell script.

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

--------------------------------

### Clone vpype and install dependencies

Source: https://github.com/abey79/vpype/blob/master/docs/contributing.md

Clone the vpype repository and install all project dependencies, including development and documentation extras, using Poetry.

```bash
git clone https://github.com/abey79/vpype
cd vpype
poetry install -E all --with docs
```

--------------------------------

### vpype Command Pipeline Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Demonstrates how to chain vpype commands together in a pipeline. Options and arguments are specified for each command.

```bash
$ vpype command1 [--option X [...]] [ARG [...]] command2 [--option X [...]] [ARG [...]] ...
```

--------------------------------

### Install pipx

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install pipx, a tool for installing Python applications in isolated environments. Ensure pipx is properly installed by checking its version.

```bash
python3 -m pip install pipx
```

```bash
python3 -m pipx ensurepath
```

```bash
pipx --version
```

```bash
1.2.0
```

--------------------------------

### Display Command Options

Source: https://github.com/abey79/vpype/blob/master/README.md

Shows examples of the `show` command with options for units, coloring, pen-up trajectories, and layer visibility.

```bash
vpype show
```

--------------------------------

### Interactive Grid Layout Example

Source: https://github.com/abey79/vpype/blob/master/README.md

An interactive version of the grid layout example that prompts the user for parameters like input files, grid dimensions, and output path. This uses the -I flag to run a script.

```bash
$ vpype -I examples/grid.vpy
```

--------------------------------

### Install pipx on Windows

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install pipx on Windows using the python interpreter. Ensure pipx and installed software are available in the terminal.

```bat
python -m pip install --user pipx
```

```bat
pipx ensurepath
```

--------------------------------

### Example vpype Pipeline

Source: https://github.com/abey79/vpype/blob/master/docs/index.md

Demonstrates a typical vpype command sequence for reading, scaling, sorting, and writing vector graphics.

```bash
$ vpype read input.svg scale 2 2 linesort write output.svg
```

--------------------------------

### Install pipx on Linux

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install pipx on Debian/Ubuntu systems using apt-get. Ensure the path variable is properly set for pipx.

```bash
sudo apt-get install pipx
```

```bash
pipx ensurepath
```

--------------------------------

### Layout Command

Source: https://github.com/abey79/vpype/blob/master/README.md

Example of using the `layout` command for centering and fitting geometries to margins.

```bash
vpype layout
```

--------------------------------

### Verify vpype installation

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Check if vpype is installed and functional by verifying its version and displaying random lines.

```bash
vpype --version
```

```bash
vpype random show
```

--------------------------------

### Install vpype classic viewer on Raspberry Pi

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install vpype with the classic viewer on Raspberry Pi. This command is for expert users and may require specific system-level dependencies.

```bash
vpype [...] show --classic
```

--------------------------------

### Get general help and command list

Source: https://github.com/abey79/vpype/blob/master/README.md

Displays general help information and a list of available commands for the vpype CLI.

```bash
vpype --help
```

--------------------------------

### Install Poetry using pipx

Source: https://github.com/abey79/vpype/blob/master/docs/contributing.md

Alternative method to install Poetry using pipx, a tool for installing and running Python applications in isolated environments.

```bash
pipx install poetry
```

--------------------------------

### vpype Block Structure Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Illustrates the structure of a vpype block, including begin, block processor, nested commands, and end.

```none
                                           command              command
                                    ┌─────────┴────────┐┌──────────┴──────────┐

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

        └──┬──┘└─────────┬─────────┘└────────────────────┬────────────────────┘└─┬─┘
         block         block                           nested                  block
         start       processor                        pipeline                  end

```

--------------------------------

### Referencing Other Command Files

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Shows an example of a command file that includes another command file.

```bash
# Example command file
begin
  grid --offset 1cm 1cm 2 2
  -I sub_command.vpy
end
show
```

--------------------------------

### Install vpype Plugin in Editable Mode

Source: https://github.com/abey79/vpype/blob/master/docs/plugins.md

After navigating to your plug-in directory, set up a virtual environment and install the plug-in using pip with the --editable flag. This allows for live code changes to be reflected immediately.

```bash
$ cd my-vpype-plugin/
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install --upgrade pip
$ pip install --editable .
```

--------------------------------

### Getting Help

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Display the help message for vpype or a specific command using the -h or --help option.

```shell
vpype -h
```

--------------------------------

### Create vpype Plugin Project

Source: https://github.com/abey79/vpype/blob/master/docs/plugins.md

Use this command to initialize a new vpype plug-in project with a Cookiecutter template. Ensure you have Cookiecutter installed.

```bash
$ cookiecutter gh:abey79/cookiecutter-vpype-plugin
```

--------------------------------

### Displaying Version Information

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Show the installed vpype version and exit using the --version option.

```shell
vpype --version
```

--------------------------------

### Nested Blocks Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Demonstrates a complex pipeline composition using nested 'grid', 'random', and 'frame' commands.

```bash
$ vpype \
    grid --offset 8cm 8cm 2 3 \
      grid --offset 2cm 2cm 3 3 \
        random --count 20 --area 1cm 1cm \
        frame \
      end \
      frame --offset 0.3cm \
    end \
    layout a4 \
    show
```

--------------------------------

### Install CLI-only vpype

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install a CLI-only version of vpype without optional dependencies like matplotlib or PySide6. This is useful when viewer dependencies are difficult to install.

```bash
pipx install vpype
```

--------------------------------

### vpype Repeat Command Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Creates four layers, each populated with random lines, using the repeat block processor.

```bash
$ vpype repeat 4 random -l new -a 10cm 10cm -n 30 \
    end pens cmyk show

```

--------------------------------

### Get help for a specific vpype command

Source: https://github.com/abey79/vpype/blob/master/README.md

Displays detailed help information for a specific vpype command.

```bash
vpype COMMAND --help
```

--------------------------------

### Check Python Version

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Verify that the installed Python interpreter is properly installed. Expected output is similar to 'Python 3.13.2'.

```bash
python3 --version
```

```bash
Python 3.13.2
```

--------------------------------

### vpype Layer Management Examples

Source: https://github.com/abey79/vpype/wiki/Layers

Demonstrates different ways to specify layer IDs for commands. If a layer ID does not exist, it is created. 'new' creates a new layer with the lowest unused ID. If no --layer option is provided, the last target layer is used, or a new layer with ID 1 is created if none exists.

```bash
vpype random --layer 1 show
vpype random --layer new show
vpype random show
```

```bash
vpype random --layer 1 frame show
```

```bash
vpype random --layer 1 frame --layer 2 show
vpype random --layer 1 frame --layer new show
```

--------------------------------

### Property Substitution Formatting Examples

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Illustrates various formatting options for property substitution, including precision, padding, and color component extraction. Refer to Python's string.format() documentation for full details.

```none
{vp_pen_width}          -> 2.5
{vp_pen_width:.3f}      -> 2.500
{vp_pen_width:06.2f}    -> 002.50
{vp_page_size}          -> (793.7007874015749, 1122.5196850393702)
{vp_page_size[0]:.2f}   -> 793.70
{vp_color}              -> #ff0000
{vp_color.red}          -> 255
{vp_color.red:#02x}     -> 0xff
```

--------------------------------

### Install system dependencies on Raspberry Pi

Source: https://github.com/abey79/vpype/blob/master/docs/install.md

Install system-level Python packages commonly used by vpype on Raspberry Pi. These include shapely, numpy, and scipy.

```bash
sudo apt-get install python3-shapely python3-numpy python3-scipy
```

--------------------------------

### SVG Input

Source: https://github.com/abey79/vpype/blob/master/README.md

Example of reading SVG files, with support for multi-layer and adjustable precision.

```bash
vpype read input.svg
```

--------------------------------

### Layer Manipulation Commands

Source: https://github.com/abey79/vpype/blob/master/README.md

Examples of commands for managing layers, including selection, moving, copying, deleting, and reversing.

```bash
vpype COMMANDNAME --layer 1,3
```

```bash
vpype lmove --layer 1,3
```

```bash
vpype lcopy --layer 1,3
```

```bash
vpype ldelete --layer 1,3
```

```bash
vpype lswap --layer 1,3
```

```bash
vpype lreverse --layer 1,3
```

--------------------------------

### begin

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Marks the start of a block. A begin command must be followed by a block processor command (e.g. grid or repeat), which indicates how the block is processed. Blocks must be ended by a end command. Blocks can be nested.

```APIDOC
## begin

### Description
Marks the start of a block.

A begin command must be followed by a block processor command (e.g. grid or repeat),
which indicates how the block is processed. Blocks must be ended by a end command.
Blocks can be nested.

### Method
POST

### Endpoint
/begin

### Parameters
No parameters available.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

--------------------------------

### Property Manipulation Commands

Source: https://github.com/abey79/vpype/blob/master/README.md

Commands for setting, getting, listing, deleting, and clearing properties.

```bash
vpype propset key value --layer 1
```

```bash
vpype propget key --layer 1
```

```bash
vpype proplist --layer 1
```

```bash
vpype propdel key --layer 1
```

```bash
vpype propclear --layer 1
```

--------------------------------

### vpype CLI Usage

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Basic structure for invoking vpype commands with options and arguments. Use this as a starting point for all vpype operations.

```shell
vpype [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
```

--------------------------------

### Begin a block with begin command

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

The `begin` command marks the start of a block, which must be followed by a block processor command and ended with an `end` command. Blocks can be nested.

```shell
begin [OPTIONS]
```

--------------------------------

### Custom Pen Configuration Example

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Define custom pen configurations in a TOML file to associate names, colors, and pen widths with specific layers. The 'layer_id' is mandatory for each layer definition.

```toml
[pen_config.my_pen_config]  # my_pen_config is this pen configuration's name
layers = [
    # for each layer, a layer_id must be provided, but name, color and
    # pen_width are optional
    { layer_id = 1, name = "black layer", color = "black", pen_width = "0.15mm" },

    # any valid CSS color string and length unit may be used
    { layer_id = 2, name = "red layer", color = "#e00", pen_width = "0.05in" },

    # any attribute may be omitted, except layer_id
    { layer_id = 4, color = "#00de00" },

    # etc. (a pen configuration may have an arbitrary number of layers defined)
]

```

--------------------------------

### vpype Layer Processors Examples

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Layer processors operate on a layer-by-layer basis. The --layer option can specify single or multiple layers, or 'all'. If omitted, all layers are processed.

```bash
$ vpype [...] crop --layer 1 0 0 10cm 10cm      # crop layer 1 only
```

```bash
$ vpype [...] crop --layer 1,2,4 0 0 10cm 10cm  # crop layers 1, 2 and 4
```

```bash
$ vpype [...] crop --layer all 0 0 10cm 10cm    # crop all layers
```

```bash
$ vpype [...] crop 0 0 10cm 10cm                # crop all layers
```

--------------------------------

### Python Dictionary Example for Layer Merging

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

This Python dictionary illustrates how layer names are mapped to destination layer IDs during the merging process.

```python
names = {
   'cyan': 100,
   'magenta': 101,
   'yellow': 102,
   'black': 103
}
```

--------------------------------

### vpype Filter Layer Example

Source: https://github.com/abey79/vpype/wiki/Layers

Applies a scale filter to a specific layer. The '-a' option specifies dimensions, and '--layer 2' targets the second layer for scaling. If the specified layer does not exist, the command has no effect.

```bash
vpype random -a 10cm 10cm frame --layer 2 scale --layer 2 1.05 1.05 show
```

--------------------------------

### vpype Generators Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Generators add new geometries to a target layer. Use --layer TARGET to specify the layer, or --layer new for a new empty layer.

```bash
$ vpype line --layer 3 0 0 1cm 1cm circle 0.5cm 0.5cm 0.3cm
```

--------------------------------

### Example vpype Generator Plugin Command

Source: https://github.com/abey79/vpype/blob/master/docs/plugins.md

This Python code defines a simple generator command for a vpype plug-in. Generator commands must return a vpype.LineCollection instance. Ensure necessary imports are included.

```python
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"
```

--------------------------------

### Loading Command Files

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Illustrates how to load a command file using the -I or --include option.

```bash
$ vpype -I command_file.vpy
```

--------------------------------

### vpype Alternative Units Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

vpype understands various CSS units (cm, ft, in, inch, km, m, mi, mm, pc, pt, px, yd). This command also generates a 1-inch-radius circle.

```bash
$ vpype circle 0 0 1in
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/abey79/vpype/blob/master/README.md

Demonstrates basic command-line interface usage with integrated help and support for arbitrary units.

```bash
vpype --help
```

```bash
vpype COMMAND --help
```

```bash
vpype read input.svg translate 3cm 2in
```

--------------------------------

### vpype Core Command Help

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Displays the usage and available options for the core vpype command, including global options like verbose and include path.

```bash
$ vpype --help
Usage: vpype [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options:
  -v, --verbose
  -I, --include PATH  Load commands from a command file.
  -H, --history       Record this command in a `vpype_history.txt` in the
                      current directory.
  -s, --seed INTEGER  Specify the RNG seed.
  --help              Show this message and exit.
    ...
```

--------------------------------

### vpype Circle Command Help

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Shows the usage and options for the 'circle' command, including parameters for position, radius, and quantization.

```bash
$ vpype circle --help
Usage: vpype circle [OPTIONS] X Y R

  Generate lines approximating a circle.

  The circle is centered on (X, Y) and has a radius of R.

Options:
  -q, --quantization LENGTH  Maximum length of segments approximating the
                             circle.
  -l, --layer LAYER          Target layer or 'new'.
  --help                     Show this message and exit.
```

--------------------------------

### vpype Angle Units Examples

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Angles are interpreted as degrees by default, but alternative units like deg, rad, grad, and turn can be specified. These examples all rotate a rectangle by 45 degrees.

```bash
$ vpype rect 0 0 50 100 rotate 45
```

```bash
$ vpype rect 0 0 50 100 rotate 50grad
```

```bash
$ vpype rect 0 0 50 100 rotate 0.125turn
```

```bash
$ vpype rect 0 0 50 100 rotate 0.785398rad
```

--------------------------------

### vpype Grid Command Help

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Displays help information for the vpype grid command, detailing its usage and options for creating grid layouts.

```bash
$ vpype grid --help
Usage: vpype grid [OPTIONS] NX NY

  Creates a NX by NY grid of geometry

  The number of column and row must always be specified. By default, 10mm
  offsets are used in both directions. Use the "--offset" option to override
  these values.

  [...]

```

--------------------------------

### Run vpype help command with Poetry

Source: https://github.com/abey79/vpype/blob/master/docs/contributing.md

Execute the vpype command-line interface with the --help flag using Poetry's run command to manage the virtual environment.

```bash
poetry run vpype --help
```

--------------------------------

### End a block with end command

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

The `end` command marks the end of a block started with the `begin` command.

```shell
end [OPTIONS]
```

--------------------------------

### Mixing Arguments and Command Files

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Demonstrates combining regular command-line arguments with command file inclusions.

```bash
$ vpype -I generate_lines.vpy write -p a4 -c output.svg
```

--------------------------------

### Bump Project Version (Pre-release)

Source: https://github.com/abey79/vpype/blob/master/RELEASE.md

Use this command to set the project to a pre-release version. This is typically done after a stable release to prepare for the next one.

```shell
poetry version preminor
```

--------------------------------

### Print human-readable statistics

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Prints human-readable statistics on the current geometries. No specific setup is required beyond having geometries loaded.

```shell
stat [OPTIONS]
```

--------------------------------

### Import with quantization and simplification

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Imports geometries with specified quantization for segment length and enables line simplification for curved elements.

```shell
vpype read --quantization 0.01mm --simplify input_file.svg [...]
```

--------------------------------

### vpype Default Unit Example

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

The default unit in vpype is the CSS pixel (1/96th of an inch). This command generates a 1-inch-radius circle.

```bash
$ vpype circle 0 0 96
```

--------------------------------

### Write a previsualization SVG with pen-up paths and colored paths

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Creates an SVG file for previsualization, including pen-up trajectories and distinct colors for each path to aid in visualizing line optimization. This is useful for debugging and analysis.

```bash
vpype [...] write --pen-up --color-mode path output.svg
```

--------------------------------

### vpype example of single-line conditional statement

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Demonstrates that single-line conditional statements in vpype expressions evaluate to None, even if the condition is met.

```bash
$ vpype text "%if True: 'hello'%" show
```

--------------------------------

### Read files with pathlib.Path in vpype

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Use pathlib.Path objects directly with commands like 'read'. The '_path' variable from 'forfile' is an example of such an object.

```bash
$ vpype \
    forfile "*.svg" \
      read --layer %_i+1% %_path% \
    end \
    write output.svg
```

--------------------------------

### Activate Poetry shell and run vpype

Source: https://github.com/abey79/vpype/blob/master/docs/contributing.md

Activate the virtual environment managed by Poetry to directly execute vpype commands, such as displaying help information.

```bash
poetry shell
vpype --help
```

--------------------------------

### Loading Custom Configuration Files

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Specify a custom TOML configuration file using the -c or --config option. vpype automatically loads .vpype.toml from the user directory if it exists, but this option allows for project-specific configurations.

```shell
vpype -c my_plotter_config.toml read input.svg write -d my_plotter output.hpgl
```

--------------------------------

### Using vpype convert_length() Function

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Converts string representations of lengths into numerical pixel values. For example, '4in' is converted to its equivalent in pixels.

```python
print(convert_length('4in'))
```

--------------------------------

### Transform Commands

Source: https://github.com/abey79/vpype/blob/master/README.md

Demonstrates various transform commands for scaling, translating, skewing, and rotating geometries.

```bash
vpype scale 2
```

```bash
vpype translate 10mm 5mm
```

```bash
vpype skew x 10
```

```bash
vpype rotate 45
```

--------------------------------

### Create a grid of circles on different layers

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Creates a 2x3 grid of circles, with each circle placed on a new layer. This demonstrates layer management within a grid.

```shell
vpype begin grid -o 3cm 3cm 2 3 circle --layer new 0 0 1cm end show
```

--------------------------------

### Showing Geometries

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

The 'show' command displays the current geometry in a graphical user interface. This is useful for visualizing the results of vpype operations.

```shell
vpype random show
```

--------------------------------

### vpype Commands

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

List of available commands for vpype, with brief descriptions.

```APIDOC
## vpype Commands

### alpha

Set the opacity of one or more layers.

### arc

Generate lines approximating a circular arc.

### begin

Marks the start of a block.

### circle

Generate lines approximating a circle.

### circlecrop

Crop to a circular area.

### color

Set the color for one or more layers.

### crop

Crop the geometries.

### ellipse

Generate lines approximating an ellipse.

### end

Marks the end of a block.

### eval

Evaluate an expression.

### filter

Filter paths according to specified criteria.

### forfile

Iterate over a file list.

### forlayer

Iterate over each layer.

### frame

Add a single-line frame around the geometry.

### grid

Creates a NX by NY grid of geometry.

### layout

Layout the geometries on the provided page.

### lcopy

Copy the content of one or more layer(s).

### ldelete

Delete one or more layers.

### line

Generate a single line.

### linemerge

Merge lines whose endings and starts are close.

### lineshuffle

Randomizes the line order within a layer.

### linesimplify

Reduce the number of segments in the geometry.

### linesort

Sort lines to minimize the pen-up travel.

### lmove

Move the content of one or more layer(s).

### lreverse

Reverse the path order within one or more layers.

### lswap

Swap the content between two layers.

### multipass

Add multiple passes to each line.

### name

Set the name for one or more layers.

### pagerotate

Rotate the page by 90 degrees.

### pagesize

Change the current page size.

### pens

Apply a pen configuration.

### penwidth

Set the pen width for one or more layers.

### propclear

Remove all global or layer properties.

### propdel

Remove a global or layer property.

### propget

Print the value of a global or layer property.

### proplist

Print a list of the existing global or layer properties.

### propset

Set the value of a global or layer property.

### random

Generate random lines.

### read

Extract geometries from an SVG file.

### rect

Generate a rectangle, with optional rounded corners.

### reloop

Randomize the seam location of closed paths.

### repeat

Repeat geometries N times.

### reverse

Reverse order of lines.

### rotate

Rotate the geometries (clockwise positive).

### scale

Scale the geometries by a factor.

### scaleto

Scale the geometries to given dimensions.

### script

Call an external python script to generate geometries.

### show

Display the geometry in a graphical user interface.

### skew

Skew the geometries.

### snap

Snap all points to a grid with a specified resolution.

### splitall

Split all paths into their constituent segments.

### splitdist

Split layers by drawing distance.

### squiggles

Apply a squiggle filter to the geometries.

### stat

Print human-readable statistics on the geometries.

```

--------------------------------

### List Global or Layer Properties

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Use 'proplist' to display existing global or layer properties and their values. Similar to 'propget', use --global or --layer to specify the target.

```shell
vpype pagesize a4 proplist -g
```

--------------------------------

### Merge Overlapping Lines

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Merges lines whose start and end points are close or overlapping. By default, considers strokes in both directions. Tolerance for merging and disabling stroke reversal can be configured.

```shell
linemerge [OPTIONS]
```

--------------------------------

### Scaling and Cropping

Source: https://github.com/abey79/vpype/blob/master/README.md

Commands for scaling to arbitrary dimensions and cropping geometries.

```bash
vpype scaleto 100mm 50mm
```

```bash
vpype crop 10mm 10mm 100mm 100mm
```

--------------------------------

### Applying Custom Pen Configuration

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Use the 'pens' command with the name of your custom pen configuration to apply the defined styles to layers.

```bash
$ vpype [...] pens my_pen_config [...]
```

--------------------------------

### Apply pen configuration

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Applies pen configurations (names, colors, widths) to layers. Configurations must be defined in a config file. Layers not in the configuration are unaffected.

```shell
pens [OPTIONS] CONF
```

--------------------------------

### Merge SVGs in a Grid Layout

Source: https://github.com/abey79/vpype/blob/master/README.md

Merges multiple SVG files into a grid layout. This example uses expression substitution for file globbing, grid dimensions, and reading files. It also includes layout adjustments.

```bash
$ vpype \
    eval "files=glob('*.svg')" \
    eval "cols=3; rows=ceil(len(files)/cols)" \
    grid -o 10cm 10cm "%cols%" "%rows%" \
        read --no-fail "%files[_i] if _i < len(files) else ''%" \
        layout -m 0.5cm 10x10cm \
    end \
    write combined_on_a_grid.svg
```

--------------------------------

### vpype Read Multiple Files (Rejected)

Source: https://github.com/abey79/vpype/wiki/Layers

Shows a rejected alternative for the 'read' command where multiple file paths could be provided as arguments, each loading into a separate layer. This approach has issues when 'read' is not the first command in the pipeline.

```bash
vpype read layer1.svg layer2.svg layer3.svg show
```

--------------------------------

### Get Global or Layer Property Value

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Use 'propget' to retrieve the value of a global or layer property. Specify the target with --global or --layer. For layers, you can target specific IDs, a comma-separated list, or 'all'.

```shell
vpype […] pens cmyk propget --layer all vp_color […]
```

--------------------------------

### Merge Layers by Name from Multiple Files

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Use this pipeline to load multiple SVG files and merge layers with the same name into a single output file. It assigns new layer IDs starting from 100 to avoid conflicts.

```bash
$ vpype \
    eval "names={};n=100" \
    forfile "*.svg" \
        read %_path% \
        forlayer \
            eval "%if _name not in names: names[_name] = n; n = n+1%" \
            lmove %_lid% "%names[_name]%" \
        end \
    end \
    write combined.svg
```

--------------------------------

### vpype Block Processor with Multilayer (Rejected)

Source: https://github.com/abey79/vpype/wiki/Layers

Demonstrates a rejected alternative for block processors using a '--multilayer' option to send each iteration to a new layer. This was rejected due to potential conflicts with existing --layer options.

```bash
vpype begin repeat -n 10 --multilayer random end show
```

--------------------------------

### Pen Configurations

Source: https://github.com/abey79/vpype/blob/master/README.md

Applying predefined or custom pen configurations using the `pens` command.

```bash
vpype pens "default"
```

--------------------------------

### Batch Process SVGs with GNU Parallel

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Use this command to process all SVG files in the current directory with a vpype pipeline. The `--plus` option enables string replacement for output file naming. Ensure GNU Parallel is installed.

```bash
$ parallel --plus vpype read {} linemerge linesort write {/.svg/_processed.svg} ::: *.svg
```

--------------------------------

### vpype Command with Custom Configuration File

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Use the --config option to specify a custom configuration file when invoking vpype. This option must be provided on each invocation.

```bash
(vpype_venv) $ vpype --config my_config_file.toml [...]
```

--------------------------------

### Per-Layer Processing

Source: https://github.com/abey79/vpype/blob/master/README.md

Illustrates how to perform operations on specific layers using the `perlayer` command.

```bash
vpype perlayer COMMANDNAME --layer 1,3
```

--------------------------------

### Load, Scale, and Export SVG

Source: https://github.com/abey79/vpype/blob/master/README.md

Use this to load an SVG, scale it to a specific size, and export it centered on an A4-sized SVG file.

```bash
$ vpype \
  read input.svg \
  layout --fit-to-margins 2cm a4 \
  write output.svg
```

--------------------------------

### Page Size Definition

Source: https://github.com/abey79/vpype/blob/master/README.md

Setting an arbitrary page size using the `pagesize` command.

```bash
vpype pagesize 210mm 297mm
```

--------------------------------

### Specify custom page size for layout

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Demonstrates specifying custom page dimensions for the layout command. Units can be mixed and matched.

```shell
layout 11x14in
```

```shell
layout 1024x768
```

```shell
layout 13.5inx4cm
```

--------------------------------

### Command History and RNG Seed

Source: https://github.com/abey79/vpype/blob/master/README.md

Demonstrates how to record command history and configure the RNG seed for generative plugins.

```bash
vpype -H [...]
```

```bash
vpype -s 37 [...]
```

--------------------------------

### Interactive SVG Grid Layout Command File

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

A command file for vpype that interactively prompts the user for parameters like file patterns, grid dimensions, and output path, using sensible defaults. It utilizes functions like glob(), convert_length(), and input() for dynamic pipeline configuration.

```bash
# Content of file grid.vpy
# Ask user for some information, using sensible defaults.
eval "files=glob(input('Files [*.svg]? ') or '*.svg')"    # glob() creates a list of file based on a pattern
eval "cols=int(input('Number of columns [3]? ') or 3)"
eval "rows=ceil(len(files)/cols)"  # the number of rows depends on the number of files
eval "col_width=convert_length(input('Column width [10cm]? ') or '10cm')"  # convert_length() converts string like '3cm' to pixels
eval "row_height=convert_length(input('Row height [10cm]? ') or '10cm')"
eval "margin=convert_length(input('Margin [0.5cm]? ') or '0.5cm')"
eval "output_path=input('Output path [output.svg]? ') or 'output.svg'"

# Create a grid with provided parameters.
grid -o %col_width% %row_height% %cols% %rows%

    # Read the `_i`-th file. The last row may be incomplete so we use an empty path and `--no-fail`.
    read --no-fail "%files[_i] if _i < len(files) else ''%"

    # Layout the file in the cell.
    layout -m %margin% %col_width%x%row_height%
end

# wWrite the output file.
write "%output_path%"
```

--------------------------------

### Scale SVG to 5x5cm and Layout to A5

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Reads an SVG, scales it to a 5x5cm square using scaleto, centers it on an A5 page, and writes to a new SVG.

```bash
$ vpype read input.svg scaleto 5cm 5cm layout a5 write output.svg
```

--------------------------------

### Convert SVG to HPGL with manual page size and orientation

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Manually specify the page size and orientation (e.g., A4 landscape) using `--page-size` and `--landscape` options when automatic inference fails or is not desired.

```bash
$ vpype read input.svg write --device hp7475a --page-size a4 --landscape output.hpgl
```

--------------------------------

### Including Command Files

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Load commands from a specified file using the -I or --include option. This is useful for organizing complex command sequences or reusing them across projects.

```shell
vpype read input.svg -I my_post_processing.vpy write.output.svg
```

--------------------------------

### Custom vpype Configuration File Location

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Place your custom TOML configuration file at the root of your user directory for automatic loading by vpype. The file name should be '.vpype.toml'.

```bash
# Windows:
# C:\Users\username\.vpype.toml
# Mac:
# /Users/username/.vpype.toml
# Linux:
# /home/username/.vpype.toml

```

--------------------------------

### vpype Read Multiple Files with --to-layer (Rejected)

Source: https://github.com/abey79/vpype/wiki/Layers

Presents a rejected alternative for the 'read' command using '--to-layer' options to specify target layers for multiple input files. While addressing some issues of the previous alternative, it is considered verbose and less elegant for simple cases.

```bash
vpype --to-layer 1 layer1.svg --to-layer 2 layer2.svg --to-layer 3 layer3.svg show
```

--------------------------------

### Snap Points to Grid with snap

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Moves all points of all paths to the nearest grid point with a specified pitch. Deduplicates sequential points on the same grid point. Paths with less than 2 points after snapping are discarded.

```shell
vpype […] snap 3mm […]
```

--------------------------------

### Using eval for Expression Evaluation

Source: https://github.com/abey79/vpype/blob/master/docs/fundamentals.md

Demonstrates the use of the 'eval' command to evaluate an expression and assign it to a variable for later use.

```bash
$ vpype eval "%txt='hello world'%" text %txt% show
```

--------------------------------

### proplist - List Properties

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Lists existing global or layer properties and their current values. Requires either --global or --layer option.

```APIDOC
## GET /proplist

### Description
Lists existing global or layer properties and their values.

### Method
GET (implicitly, as it's a command-line tool action)

### Endpoint
N/A (Command-line tool)

### Parameters
#### Query Parameters
- **--global** (flag) - Optional - Use to list global properties.
- **--layer** (string) - Optional - Target layer(s). Can be a single ID, comma-separated list, or 'all'.

### Request Example
```shell
vpype pagesize a4 proplist -g
```

### Response
#### Success Response (200)
- **properties** (object) - A dictionary of property names and their values.

#### Response Example
```json
{
  "properties": {
    "page_width": "210mm",
    "page_height": "297mm"
  }
}
```
```

--------------------------------

### Create Preview SVG with Paths Colored by Layer

Source: https://github.com/abey79/vpype/blob/master/docs/cookbook.md

Use this command to generate an SVG where paths are colored by layer, useful for visualizing the output of operations like linemerge.

```bash
$ vpype read input.svg linemerge write --color-mode path output.svg
```

--------------------------------

### vpype Global Options

Source: https://github.com/abey79/vpype/blob/master/docs/reference.md

Global options that can be used with the vpype command.

```APIDOC
## vpype Global Options

### Description

Execute the sequence of commands passed in argument. vpype's commands or plug-ins may rely on a random number generator (RNG). By default, vpype's RNG is seeded with the current time. The seed can instead be set to a specific value (using the --seed option) when reproducible behaviour is needed.

### Usage

```shell
vpype [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
```

### Options

- **--version**
  Show the version and exit.

- **-h, --help**
  Show this message and exit.

- **-v, --verbose**
  Increase verbosity level (can be used multiple times for higher verbosity).

- **-I, --include <include>**
  Load commands from a command file.

- **-H, --history**
  Record this command in a vpype_history.txt file in the current directory.

- **-s, --seed <seed>**
  Specify the RNG seed for reproducible behavior.

- **-c, --config <config>**
  Load an additional configuration file.

```

--------------------------------

### Layer Metadata Commands

Source: https://github.com/abey79/vpype/blob/master/README.md

Commands for adjusting layer color, alpha, pen width, and name.

```bash
vpype color red --layer 1
```

```bash
vpype alpha 0.5 --layer 1
```

```bash
vpype penwidth 0.1mm --layer 1
```

```bash
vpype name "My Layer" --layer 1
```