Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/abey79/vpype
The Swiss-Army-knife command-line tool for plotter vector graphics.
https://github.com/abey79/vpype
generative-art hacktoberfest hacktoberfest2020 multi-layer-svg pen-plotters plotter-art plotters python-3 python3 svg svg-files vector-graphics vpype
Last synced: 1 day ago
JSON representation
The Swiss-Army-knife command-line tool for plotter vector graphics.
- Host: GitHub
- URL: https://github.com/abey79/vpype
- Owner: abey79
- License: mit
- Created: 2019-11-11T10:01:25.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-21T15:05:11.000Z (4 months ago)
- Last Synced: 2024-10-29T15:47:10.252Z (4 months ago)
- Topics: generative-art, hacktoberfest, hacktoberfest2020, multi-layer-svg, pen-plotters, plotter-art, plotters, python-3, python3, svg, svg-files, vector-graphics, vpype
- Language: Python
- Homepage: https://vpype.readthedocs.io/
- Size: 16.6 MB
- Stars: 699
- Watchers: 8
- Forks: 61
- Open Issues: 65
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.rst
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# _vpype_
[](https://pypi.org/project/vpype/)
[](https://www.python.org)
[](https://pepy.tech/project/vpype)
[](https://vpype.readthedocs.io/en/latest/license.html)
[](https://codecov.io/gh/abey79/vpype)
[](https://sonarcloud.io/dashboard?id=abey79_vpype)
[](https://vpype.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/psf/black)
_vpype_ is the Swiss-Army-knife command-line tool for plotter vector graphics.
#### Contents
* [What _vpype_ is?](#what-vpype-is)
* [How does it work?](#how-does-it-work)
* [Examples](#examples)
* [What _vpype_ isn't?](#what-vpype-isnt)
* [Installation](#installation)
* [Documentation](#documentation)
* [Feature overview](#feature-overview)
* [General](#general)
* [Input/Output](#inputoutput)
* [Layout and transforms](#layout-and-transforms)
* [Plotting optimization](#plotting-optimization)
* [Generation](#generation)
* [Extensibility and API](#extensibility-and-api)
* [Plug-ins](#plug-ins)
* [Contributing](#contributing)
* [License](#license)
## What _vpype_ is?
_vpype_ is the Swiss-Army-knife command-line tool for plotter vector graphics. Here is what it can do:
- **layout** existing vector files with precise control on position, scale and page format;
- **optimize** existing SVG files for faster and cleaner plots;
- create **HPGL output** for vintage plotters;
- create **generative artwork** from scratch through built-in commands or [plug-ins](#plug-ins);
- create, modify and process **multi-layer vector files** for multi-colour plots;
- and much more...
_vpype_ is highly **extensible** through plug-ins that can greatly extend its capabilities. For example, plug-ins
already exists for plotting [pixel art](https://github.com/abey79/vpype-pixelart),
[half-toning with hatches](https://github.com/abey79/hatched), and much more. See below for a
[list of existing plug-ins](#plug-ins).
_vpype_ is also a [well documented](https://vpype.readthedocs.io/en/latest/api.html) **Python library**
useful to create generative art and tools for plotters. It includes data structures, utility and I/O functions, as well as
a hardware-accelerated flexible viewer for vector graphics. For example, the plotter generative art environment
[vsketch](https://github.com/abey79/vsketch) is built upon _vpype_.
Check the [documentation](https://vpype.readthedocs.io/en/latest/) for a more thorough introduction to _vpype_.
## How does it work?
_vpype_ works by building so-called _pipelines_ of _commands_, where each command's output is fed to the next command's input.
Some commands load geometries into the pipeline (e.g. the [`read`](https://vpype.readthedocs.io/en/latest/reference.html#read)
command which loads geometries from a SVG file). Other commands modify these geometries, e.g. by cropping
them ([`crop`](https://vpype.readthedocs.io/en/latest/reference.html#crop)) or reordering them to minimize pen-up
travels ([`linesort`](https://vpype.readthedocs.io/en/latest/reference.html#linesort)). Finally, some other commands
just read the geometries in the pipeline for display purposes ([`show`](https://vpype.readthedocs.io/en/latest/reference.html#show))
or output to file ([`write`](https://vpype.readthedocs.io/en/latest/reference.html#write)).
Pipeline are defined using the _vpype_'s CLI (command-line interface) in a terminal by typing `vpype` followed by the
list of commands, each with their optional parameters and their arguments:
This pipeline uses five commands (in bold):
- [`read`](https://vpype.readthedocs.io/en/latest/reference.html#read) loads geometries from a SVG file.
- [`linemerge`](https://vpype.readthedocs.io/en/latest/reference.html#linemerge) merges paths whose extremities are close to each other (within the provided tolerance).
- [`linesort`](https://vpype.readthedocs.io/en/latest/reference.html#linesort) reorder paths such as to minimise the pen-up travel.
- [`crop`](https://vpype.readthedocs.io/en/latest/reference.html#crop), well, crops.
- [`write`](https://vpype.readthedocs.io/en/latest/reference.html#write) export the resulting geometries to a SVG file.
There are many more commands available in *vpype*, see the [overview](#feature-overview) below.
Some commands have arguments, which are always required (in italic). For example, a file path must be provided to the
[`read`](https://vpype.readthedocs.io/en/latest/reference.html#read) command and dimensions must be provided to the [`crop`](https://vpype.readthedocs.io/en/latest/reference.html#crop) commands. A command may also have options which are, well,
optional. In this example, `--page-size a4` means that the [`write`](https://vpype.readthedocs.io/en/latest/reference.html#write) command will generate a A4-sized SVG (otherwise it
would have the same size as _in.svg_). Likewise, because `--center` is used, the [`write`](https://vpype.readthedocs.io/en/latest/reference.html#write) command will center geometries
on the page before saving the SVG (otherwise the geometries would have been left at their original location).
## Examples
**Note**: The following examples are laid out over multiple lines using end-of-line escaping (`\`). This is done to highlight the various commands of which the pipeline is made and would typically not be done in real-world use.
Load an SVG file, scale it to a specific size, and export it centered on an A4-sized, ready-to-plot SVG file:
```bash
$ vpype \
read input.svg \
layout --fit-to-margins 2cm a4 \
write output.svg
```
Optimize paths to reduce plotting time (merge connected lines, sort them to minimize pen-up distance, randomize closed paths' seam, and reduce the number of nodes):
```bash
$ vpype \
read input.svg \
linemerge --tolerance 0.1mm \
linesort \
reloop \
linesimplify \
write output.svg
```
Load a SVG and display it in *vpype*'s viewer, which enable close inspection of the layer and path structure):
```bash
$ vpype \
read input.svg \
show
```
Load several SVG files and save them as a single, multi-layer SVG file (e.g. for multicolored drawings):
```bash
$ vpype \
forfile "*.svg" \
read --layer %_i% %_path% \
end \
write output.svg
```
Export a SVG to HPGL for vintage plotters:
```bash
$ vpype \
read input.svg \
layout --fit-to-margins 2cm --landscape a4 \
write --device hp7475a output.hpgl
```
Draw the layer name on a SVG (this example uses [property substitution](https://vpype.readthedocs.io/en/latest/fundamentals.html#property-substitution)):
```bash
$ vpype \
read input.svg \
text --layer 1 "{vp_name}" \
write output.svg
```
Merge multiple SVG files in a grid layout (this example uses [expression substitution](https://vpype.readthedocs.io/en/latest/fundamentals.html#expression-substitution)):
```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
```
An interactive version of the previous example is available in `examples/grid.vpy`. It makes use of `input()` expressions to ask parameters from the user:
```bash
$ vpype -I examples/grid.vpy
Files [*.svg]?
Number of columns [3]? 4
Column width [10cm]?
Row height [10cm]? 15cm
Margin [0.5cm]?
Output path [output.svg]?
```
Split a SVG into one file per layer:
```bash
$ vpype \
read input.svg \
forlayer \
write "output_%_name or _lid%.svg" \
end
```
More examples and recipes are available in the [cookbook](https://vpype.readthedocs.io/en/latest/cookbook.html).
## What _vpype_ isn't?
_vpype_ caters to plotter generative art and does not aim to be a general purpose (think
Illustrator/InkScape) vector graphic tools. One of the main reason for this is the fact _vpype_ converts everything
curvy (circles, bezier curves, etc.) to lines made of small segments. _vpype_ does import metadata such stroke and fill color, stroke width, etc., it only makes partial use of them and does not aim to maintain a full consistency with the SVG specification. These design choices make _vpype_'s rich feature set possible, but limits its use for, e.g., printed media.
## Installation
Detailed installation instructions are available in the [latest documentation](https://vpype.readthedocs.io/en/latest/install.html).
TL;DR:
- Python 3.13 is recommended, but *vpype* is also compatible with Python 3.11 and 3.12.
- *vpype* is published on the [Python Package Index](https://pypi.org) and can be installed using [pipx](https://pypa.github.io/pipx/):
```bash
pipx install "vpype[all]"
```
- A Windows installer is available [here](https://github.com/abey79/vpype/releases), but plug-ins cannot be installed
when using this method).
- A CLI-only version of *vpype* can be installed using the following command:
```bash
pipx install vpype
```
This version does not include the [`show`](https://vpype.readthedocs.io/en/latest/reference.html#show) command but does not require some of the dependencies which are more difficult or impossible to install on some platforms (such as matplotlib, PySide6, and ModernGL).
## Documentation
The _vpype_ CLI includes its own, detailed documentation:
```bash
vpype --help # general help and command list
vpype COMMAND --help # help for a specific command
```
In addition, the [online documentation](https://vpype.readthedocs.io/en/latest/) provides extensive background
information on the fundamentals behind _vpype_, a cookbook covering most common tasks, the _vpype_ API documentation,
and much more.
## Feature overview
#### General
- Easy to use **CLI** interface with integrated help (`vpype --help`and `vpype COMMAND --help`) and support for arbitrary units (e.g. `vpype read input.svg translate 3cm 2in`).
- First-class **multi-layer support** with global or per-layer processing (e.g. `vpype COMMANDNAME --layer 1,3`) and optionally-probabilistic layer edition commands ([`lmove`](https://vpype.readthedocs.io/en/latest/reference.html#lmove), [`lcopy`](https://vpype.readthedocs.io/en/latest/reference.html#lcopy), [`ldelete`](https://vpype.readthedocs.io/en/latest/reference.html#ldelete), [`lswap`](https://vpype.readthedocs.io/en/latest/reference.html#lswap), [`lreverse`](https://vpype.readthedocs.io/en/latest/reference.html#lreverse)).
- Support for **per-layer and global properties**, which acts as metadata and is used by multiple commands and plug-ins.
- Support for [**property**](https://vpype.readthedocs.io/en/latest/fundamentals.html#property-substitution) and [**expression substitution**](https://vpype.readthedocs.io/en/latest/fundamentals.html#expression-substitution) in CLI user input.
- Support for complex, **per-layer** processing ([`perlayer`](https://vpype.readthedocs.io/en/latest/reference.html#perlayer)).
- Powerful hardware-accelerated **display** command with adjustable units, optional per-line coloring, optional pen-up trajectories display and per-layer visibility control ([`show`](https://vpype.readthedocs.io/en/latest/reference.html#show)).
- Geometry **statistics** extraction ([`stat`](https://vpype.readthedocs.io/en/latest/reference.html#stat)).
- Support for **command history** recording (`vpype -H [...]`)
- Support for **RNG seed** configuration for generative plug-ins (`vpype -s 37 [...]`).
#### Input/Output
- Single- and multi-layer **SVG input** with adjustable precision, parallel processing for large SVGs, and supports percent or missing width/height ([`read`](https://vpype.readthedocs.io/en/latest/reference.html#read)).
- Support for **SVG output** with fine layout control (page size and orientation, centering), layer support with custom layer names, optional display of pen-up trajectories, various option for coloring ([`write`](https://vpype.readthedocs.io/en/latest/reference.html#write)).
- Support for **HPGL output** config-based generation of HPGL code with fine layout control (page size and orientation, centering).
- Support for pattern-based **file collection** processing ([`forfile`](https://vpype.readthedocs.io/en/latest/reference.html#forfile)).
#### Layout and transforms
- Easy and flexible **layout** command for centring and fitting to margin with selectable le horizontal and vertical alignment
([`layout`](https://vpype.readthedocs.io/en/latest/reference.html#layout)).
- **Page rotation** command ([`pagerotate`](https://vpype.readthedocs.io/en/latest/reference.html#pagerotate)).
- Powerful **transform** commands for scaling, translating, skewing and rotating geometries ([`scale`](https://vpype.readthedocs.io/en/latest/reference.html#scale), [`translate`](https://vpype.readthedocs.io/en/latest/reference.html#translate), [`skew`](https://vpype.readthedocs.io/en/latest/reference.html#skew), [`rotate`](https://vpype.readthedocs.io/en/latest/reference.html#rotate)).
- Support for **scaling** and **cropping** to arbitrary dimensions ([`scaleto`](https://vpype.readthedocs.io/en/latest/reference.html#scaleto), [`crop`](https://vpype.readthedocs.io/en/latest/reference.html#crop)).
- Support for **trimming** geometries by an arbitrary amount ([`trim`](https://vpype.readthedocs.io/en/latest/reference.html#trim)).
- Arbitrary **page size** definition ([`pagesize`](https://vpype.readthedocs.io/en/latest/reference.html#pagesize)).
#### Metadata
- Adjust layer **color**, **alpha**, **pen width** and **name** ([`color`](https://vpype.readthedocs.io/en/latest/reference.html#color), [`alpha`](https://vpype.readthedocs.io/en/latest/reference.html#alpha), [`penwidth`](https://vpype.readthedocs.io/en/latest/reference.html#penwidth), [`name`](https://vpype.readthedocs.io/en/latest/reference.html#name)).
- Apply provided or fully customisable **pen configurations** ([`pens`](https://vpype.readthedocs.io/en/latest/reference.html#pens)).
- Manipulate global and per-layer **properties** ([`propset`](https://vpype.readthedocs.io/en/latest/reference.html#propset), [`propget`](https://vpype.readthedocs.io/en/latest/reference.html#propget), [`proplist`](https://vpype.readthedocs.io/en/latest/reference.html#proplist), [`propdel`](https://vpype.readthedocs.io/en/latest/reference.html#propdel), [`propclear`](https://vpype.readthedocs.io/en/latest/reference.html#propclear)).
#### Plotting optimization
- **Line merging** with optional path reversal and configurable merging threshold ([`linemerge`](https://vpype.readthedocs.io/en/latest/reference.html#linemerge)).
- **Line sorting** with optional path reversal ([`linesort`](https://vpype.readthedocs.io/en/latest/reference.html#linesort)).
- **Line simplification** with adjustable accuracy ([`linesimplify`](https://vpype.readthedocs.io/en/latest/reference.html#linesimplify)).
- Closed paths' **seam location randomization**, to reduce the visibility of pen-up/pen-down artifacts ([`reloop`](https://vpype.readthedocs.io/en/latest/reference.html#reloop)).
- Support for generating **multiple passes** on each line ([`multipass`](https://vpype.readthedocs.io/en/latest/reference.html#multipass)).
#### Filters
- Support for **filtering** by line lengths or closed-ness ([`filter`](https://vpype.readthedocs.io/en/latest/reference.html#filter)).
- **Squiggle** filter for shaky-hand or liquid-like styling ([`squiggles`](https://vpype.readthedocs.io/en/latest/reference.html#squiggles))
- Support for **splitting** all lines to their constituent segments ([`splitall`](https://vpype.readthedocs.io/en/latest/reference.html#splitall)).
- Support for **reversing** order of paths within their layers ([`reverse`](https://vpype.readthedocs.io/en/latest/reference.html#reverse)).
- Support for **splitting** layers by drawing distance ([`splitdist`](https://vpype.readthedocs.io/en/latest/reference.html#splitdist))
#### Generation
- Generation of arbitrary **primitives** including lines, rectangles, circles, ellipses and arcs ([`line`](https://vpype.readthedocs.io/en/latest/reference.html#line), [`rect`](https://vpype.readthedocs.io/en/latest/reference.html#rect), [`circle`](https://vpype.readthedocs.io/en/latest/reference.html#circle), [`ellipse`](https://vpype.readthedocs.io/en/latest/reference.html#ellipse), [`arc`](https://vpype.readthedocs.io/en/latest/reference.html#arc)).
- Generation of **text** using bundled Hershey fonts ([`text`](https://vpype.readthedocs.io/en/latest/reference.html#text))
- Generation of grid-like layouts ([`grid`](https://vpype.readthedocs.io/en/latest/reference.html#grid)).
- Generation of a **frame** around the geometries ([`frame`](https://vpype.readthedocs.io/en/latest/reference.html#frame)).
- Generation of random lines for debug/learning purposes ([`random`](https://vpype.readthedocs.io/en/latest/reference.html#random))
#### Extensibility and API
- First-class support for **plug-in** extensions (e.g [vpype-text](https://github.com/abey79/vpype-text), [hatched](https://github.com/abey79/hatched), [occult](https://github.com/LoicGoulefert/occult)).
- Support for **script-based** generation ([`script`](https://vpype.readthedocs.io/en/latest/reference.html#script)).
- Powerful and [well-documented](https://vpype.readthedocs.io/en/latest/api.html) **API** for plug-ins and other plotter generative art projects.
## Plug-ins
Here is a list of known vpype plug-ins (please make a pull request if yours is missing):
- [vsketch](https://github.com/abey79/vsketch): *vsketch* is complete framework for plotter generative artists implemented using *vpype*'s API
- [vpype-perspective](https://github.com/abey79/vpype-perspective): put your art in perspective
- [vpype-pixelart](https://github.com/abey79/vpype-pixelart): plot pixel art
- [hatched](https://github.com/abey79/hatched): half-toning with hatches
- [vpype-flow-imager](https://github.com/serycjon/vpype-flow-imager): convert images to flow-line-based designs
- [occult](https://github.com/LoicGoulefert/occult): perform hidden line removal
- [deduplicate](https://github.com/LoicGoulefert/deduplicate): remove duplicate lines
- [vpype-explorations](https://github.com/abey79/vpype-explorations): my personal grab bag of experiments and utilities
- [vpype-gcode](https://github.com/tatarize/vpype-gcode/): flexible export command for gcode and other text-based format
- [vpype-dxf](https://github.com/tatarize/vpype-dxf/): read dxf files
- [vpype-embroidery](https://github.com/EmbroidePy/vpype-embroidery): various embroidery-related utilities, including read from/write to most embroidery formats
- [vpype-vectrace](https://github.com/tatarize/vpype-vectrace): create outlines from images with vector tracing
- [vpype-ttf](https://github.com/johnbentcope/vpype-ttf): create text outlines using TTF fonts
## Contributing
Contributions to this project are welcome and do not necessarily require software development skills! Check the
[Contributing section](https://vpype.readthedocs.io/en/latest/contributing.html) of the documentation for more
information.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.