vpype

This module contains vpype core and its API.

Functions

arc

Build an elliptical arc path.

as_vector

Return a view of a complex line array that behaves as an Nx2 real array

circle

Build a circular path.

convert_angle

Convert an angle optionally expressed as a string with unit to degrees.

convert_length

Convert a length optionally expressed as a string with unit to px value.

convert_page_size

Converts a string with page size to dimension in pixels.

crop

Crop a polyline to a rectangular area.

crop_half_plane

Crop a path at a axis-aligned location.

ellipse

Build an elliptical path.

format_length

Convert a length in pixel to a string representation with the provided unit or unit system.

interpolate

Compute a linearly interpolated version of line with segments of step length or less.

is_closed

Check if a line is closed.

line

Build a line from two points

line_length

Compute the length of a line.

read_multilayer_svg

Read a multilayer SVG file and return its content as a Document instance retaining the SVG's layer structure and its dimension.

read_svg

Read an SVG file and return its content as a LineCollection instance.

read_svg_by_attributes

Read an SVG file by sorting geometries by unique combination of provided attributes.

rect

Build a rectangular path, with optional rounded angles.

reloop

Change the seam of a closed path.

squiggles

Apply a squiggle filter to a LineCollection.

text_block

Create a wrapped block of text using the provided width.

text_line

Create a line of text.

union

Returns True if every callables in keys return True (similar to all().

write_hpgl

Create an HPGL file from the Document instance.

write_svg

Create an SVG from a Document instance.

Classes

Color([red, green, blue, alpha])

Simple, immutable, hashable color class with flexible construction.

ConfigManager()

Helper class to handle vpype's TOML configuration files.

Document([line_collection, metadata, page_size])

This class is the core data model of vpype and represent the data that is passed from one command to the other.

LineCollection([lines, metadata])

LineCollection encapsulate a list of piecewise linear lines (or paths).

LineIndex(lines[, reverse])

Wrapper to scipy.spatial.KDTree to facilitate systematic processing of a line collection.

PaperConfig(name, y_axis_up, ...)

Data class containing configuration for a give plotter type/paper size combinations.

PlotterConfig(name, paper_configs, ...[, info])

Data class containing configuration for a given plotter type.

_MetadataMixin([metadata])

Functions

arc(x: float, y: float, rw: float, rh: float, start: float, stop: float, quantization: float = 0.1) ndarray

Build an elliptical arc path. Zero angles refer to east of unit circle and positive values extend counter-clockwise.

Parameters:
  • x (float) -- center X coordinate

  • y (float) -- center Y coordinate

  • rw (float) -- ellipse half-width

  • rh (float) -- ellipse half-height (use the same value as rw for a circular arc)

  • start (float) -- start angle (degree)

  • stop (float) -- stop angle (degree)

  • quantization (float) -- maximum length of linear segment

Returns:

arc path

Return type:

ndarray

as_vector(a: ndarray)

Return a view of a complex line array that behaves as an Nx2 real array

Parameters:

a (ndarray)

circle(x: float, y: float, radius: float, quantization: float = 0.1) ndarray

Build a circular path.

Parameters:
  • x (float) -- center X coordinate

  • y (float) -- center Y coordinate

  • radius (float) -- circle radius

  • quantization (float) -- maximum length of linear segment

Returns:

circular path

Return type:

ndarray

convert_angle(value: str | float) float

Convert an angle optionally expressed as a string with unit to degrees.

Parameters:

value (str | float) -- angle to convert

Returns:

converted angle in degree

Raises:

ValueError --

Return type:

float

convert_length(value: str | float) float

Convert a length optionally expressed as a string with unit to px value.

Parameters:

value (str | float) -- value to convert

Returns:

converted value

Raises:

ValueError --

Return type:

float

convert_page_size(value: str) tuple[float, float]

Converts a string with page size to dimension in pixels.

The input can be either a known page size (see vpype write --help for a list) or a page size descriptor in the form of “WxH” where both W and H can have units.

Examples

Using a know page size:

>>> import vpype
>>> vpype.convert_page_size("a3")
(1122.5196850393702, 1587.4015748031497)

Using page size descriptor (no units, pixels are assumed):

>>> vpype.convert_page_size("100x200")
(100.0, 200.0)

Using page size descriptor (explicit units):

>>> vpype.convert_page_size("1inx2in")
(96.0, 192.0)
Parameters:

value (str) -- page size descriptor

Returns:

the page size in CSS pixels

Return type:

tuple[float, float]

crop(line: ndarray, x1: float, y1: float, x2: float, y2: float) list[ndarray]

Crop a polyline to a rectangular area.

Parameters:
  • line (ndarray) -- line to crop

  • x1 (float) -- left coordinate of the crop area

  • y1 (float) -- bottom coordinate of the crop area

  • x2 (float) -- right coordinate of the crop area

  • y2 (float) -- top coordinate of the crop area

Returns:

list of lines resulting of the crop (emtpy if x1 > x2 or y1 > y2)

Return type:

list[ndarray]

crop_half_plane(line: ndarray, loc: float, axis: int, keep_smaller: bool) list[ndarray]

Crop a path at a axis-aligned location.

The path is cut at location x=loc for axis=0, and y=loc for axis=1. The argument keep_smaller controls which part of the path is discarded.

Parameters:
  • line (ndarray) -- path to crop

  • loc (float) -- coordinate at which the cut is made

  • axis (int) -- 0 for a cut along x axis, 1 for y axis

  • keep_smaller (bool) -- if True, parts of line with coordinates smaller or equal than loc are kept, and the reverse otherwise

Returns:

list of paths

Return type:

list[ndarray]

ellipse(x: float, y: float, w: float, h: float, quantization: float = 0.1) ndarray

Build an elliptical path.

Parameters:
  • x (float) -- center X coordinate

  • y (float) -- center Y coordinate

  • w (float) -- half width of the ellipse

  • h (float) -- half height of the ellipse

  • quantization (float) -- maximum length of linear segment

Returns:

elliptical path

Return type:

ndarray

format_length(value: float, unit: str, full_precision: bool = True) str

Convert a length in pixel to a string representation with the provided unit or unit system.

The representation is for display only and

Parameters:
  • value (float) -- the value to convert (in pixels)

  • unit (str) -- unit (from vpype.UNITS) or unit system (from vp.UNIT_SYSTEMS)

  • full_precision (bool) -- if False, the return string will use a limited precision best suited for informative display

Returns:

a string representation of the length

Return type:

str

interpolate(line: ndarray, step: float) ndarray

Compute a linearly interpolated version of line with segments of step length or less.

Parameters:
  • line (ndarray) -- 1D array of complex

  • step (float) -- maximum length of interpolated segment

Returns:

interpolated 1D array of complex

Return type:

ndarray

is_closed(line: ndarray, tolerance: float) bool

Check if a line is closed.

Parameters:
  • line (ndarray) -- the line to test

  • tolerance (float) -- max distance between starting and ending point to consider a path is_closed

Returns:

True if line is is_closed

Return type:

bool

line(x0: float, y0: float, x1: float, y1: float) ndarray

Build a line from two points

Parameters:
  • x0 (float) -- line start X coordinate

  • y0 (float) -- line start Y coordinate

  • x1 (float) -- line end X coordinate

  • y1 (float) -- line end Y coordinate

Returns:

line path

Return type:

ndarray

line_length(line: ndarray) float

Compute the length of a line.

Parameters:

line (ndarray)

Return type:

float

read_multilayer_svg(file: str | TextIO, quantization: float, crop: bool = True, simplify: bool = False, parallel: bool = False, default_width: float | None = None, default_height: float | None = None) Document

Read a multilayer SVG file and return its content as a Document instance retaining the SVG’s layer structure and its dimension.

Each top-level group is considered a layer. All non-group, top-level elements are imported in layer 1.

Groups are matched to layer ID according their inkscape:label attribute, their id attribute or their appearing order, in that order of priority. The first contiguous group of digits in the label is used as layer ID. Lacking numeric characters, the appearing order is used. If the label is 0, it is changed to 1.

All curved geometries are chopped in segments no longer than the value of quantization. Optionally, the geometries are simplified using Shapely, using the value of quantization as tolerance.

The page size is set based on the width and height attributes of the <svg> tag. If these attributes are missing or expressed in percent, svgelements attempts to use the viewBox attribute instead, or reverts to a 1000x1000px page size. This behaviour can be overridden by providing values for the default_width and default_height arguments.

Parameters:
  • file (str | TextIO) -- path of the SVG file or stream object

  • quantization (float) -- maximum size of segment used to approximate curved geometries

  • crop (bool) -- crop the geometries to the SVG boundaries

  • simplify (bool) -- run Shapely’s simplify on loaded geometry

  • parallel (bool) -- enable multiprocessing (only recommended for simplify=True and SVG with many curves)

  • default_width (float | None) -- default width if not provided by SVG or if a percent width is provided

  • default_height (float | None) -- default height if not provided by SVG or if a percent height is provided

Returns:

Document instance with the imported geometries and its page size set the SVG dimensions

Return type:

Document

read_svg(file: str | TextIO, quantization: float, crop: bool = True, simplify: bool = False, parallel: bool = False, default_width: float | None = None, default_height: float | None = None) tuple[LineCollection, float, float]

Read an SVG file and return its content as a LineCollection instance.

All curved geometries are chopped in segments no longer than the value of quantization. Optionally, the geometries are simplified using Shapely, using the value of quantization as tolerance.

The page size is set based on the width and height attributes of the <svg> tag. If these attributes are missing or expressed in percent, svgelements attempts to use the viewBox attribute instead, or reverts to a 1000x1000px page size. This behaviour can be overridden by providing values for the default_width and default_height arguments.

Parameters:
  • file (str | TextIO) -- path of the SVG file or stream object

  • quantization (float) -- maximum size of segment used to approximate curved geometries

  • crop (bool) -- crop the geometries to the SVG boundaries

  • simplify (bool) -- run Shapely’s simplify on loaded geometry

  • parallel (bool) -- enable multiprocessing (only recommended for simplify=True and SVG with many curves)

  • default_width (float | None) -- default width if not provided by SVG or if a percent width is provided

  • default_height (float | None) -- default height if not provided by SVG or if a percent height is provided

Returns:

tuple containing a LineCollection with the imported geometries as well as the width and height of the SVG

Return type:

tuple[LineCollection, float, float]

read_svg_by_attributes(file: str | TextIO, attributes: Iterable[str], quantization: float, crop: bool = True, simplify: bool = False, parallel: bool = False, default_width: float | None = None, default_height: float | None = None) Document

Read an SVG file by sorting geometries by unique combination of provided attributes.

All curved geometries are chopped in segments no longer than the value of quantization. Optionally, the geometries are simplified using Shapely, using the value of quantization as tolerance.

The page size is set based on the width and height attributes of the <svg> tag. If these attributes are missing or expressed in percent, svgelements attempts to use the viewBox attribute instead, or reverts to a 1000x1000px page size. This behaviour can be overridden by providing values for the default_width and default_height arguments.

Parameters:
  • file (str | TextIO) -- path of the SVG file or stream object

  • attributes (Iterable[str]) -- attributes by which the object should be sorted

  • quantization (float) -- maximum size of segment used to approximate curved geometries

  • crop (bool) -- crop the geometries to the SVG boundaries

  • simplify (bool) -- run Shapely’s simplify on loaded geometry

  • parallel (bool) -- enable multiprocessing (only recommended for simplify=True and SVG with many curves)

  • default_width (float | None) -- default width if not provided by SVG or if a percent width is provided

  • default_height (float | None) -- default height if not provided by SVG or if a percent height is provided

Returns:

Document instance with the imported geometries and its page size set the SVG dimensions

Return type:

Document

rect(x: float, y: float, width: float, height: float, tl: float = 0, tr: float = 0, br: float = 0, bl: float = 0, quantization: float = 0.1) ndarray

Build a rectangular path, with optional rounded angles.

Parameters:
  • x (float) -- top-left corner X coordinate

  • y (float) -- top-left corner Y coordinate

  • width (float) -- rectangle width

  • height (float) -- rectangle height

  • tl (float) -- top-left corner radius (0 if not provided)

  • tr (float) -- top-right corner radius (0 if not provided)

  • br (float) -- bottom-right corner radius (0 if not provided)

  • bl (float) -- bottom-left corner radius (0 if not provided)

  • quantization (float) -- maximum size of segments approximating round corners

Returns:

rectangular path

Return type:

ndarray

reloop(line: ndarray, loc: int | None = None) ndarray

Change the seam of a closed path. Closed-ness is not checked. Beginning and end points are averaged to compute a new point. A new seam location can be provided or will be chosen randomly.

Parameters:
  • line (ndarray) -- path to reloop

  • loc (int | None) -- new seam location

Returns:

re-seamed path

Return type:

ndarray

squiggles(lines: LineCollection, ampl: float, period: float, quantization: float) LineCollection

Apply a squiggle filter to a LineCollection.

This filter first densely resample the input lines (based on the quantization parameter), and then applies a 2D-Perlin-noise-based displacement to all points.

For small values of amplitude (~2px) and period (~12px), this filter gives a “shaky-hand” style to the lines. Larger values of amplitude (~60px) and period (~400px) result in a a smoother, liquid-like effect.

Parameters:
  • lines (LineCollection) -- input lines

  • ampl (float) -- squiggle amplitude (px)

  • period (float) -- squiggle period (px)

  • quantization (float) -- quantization (px)

Returns:

filtered lines

Return type:

LineCollection

text_block(paragraph: str, width: float, font_name='futural', size: float = 18.0, align: str = 'left', line_spacing: float = 1, justify=False, hyphenate=None) LineCollection

Create a wrapped block of text using the provided width.

The text block starts at (0, 0) and extends right and down. The parameters affects how the text is rendered.

Parameters:
  • paragraph (str) -- the text to layout

  • font_name -- the name of the font to use (see FONT_NAMES)

  • width (float) -- the width of the block

  • size (float) -- the font size

  • align (str) -- text horizontal alignment ("left", "right", or "center", default: left alignment)

  • line_spacing (float) -- line spacing (default: 1.0)

  • justify -- should the text be justified (default: False)

  • hyphenate -- wrapped text is hyphenated with the given language (en, etc., default: None)

Return type:

LineCollection

text_line(txt: str, font_name='futural', size: float = 18.0, align: str = 'left', spacing: float = 0.0) LineCollection

Create a line of text.

The text block starts at (0, 0) and extends either right, left, or both, depending on the align argument.

Parameters:
  • txt (str) -- the text to layout

  • font_name -- the name of the font to use (see FONT_NAMES)

  • size (float) -- the font size

  • align (str) -- text horizontal alignment ("left", "right", or "center", default: left alignment)

  • spacing (float) -- additional spacing added after each character

Return type:

LineCollection

union(line: ndarray, keys: list[Callable[[ndarray], bool]]) bool

Returns True if every callables in keys return True (similar to all(). This function is typically used with LineCollection.filter().

Parameters:
  • line (ndarray) -- line to test

  • keys (list[Callable[[ndarray], bool]]) -- list of callables

Returns:

True if every callables return True

Return type:

bool

write_hpgl(output: TextIO, document: Document, page_size: str, landscape: bool, center: bool, device: str | None, velocity: int | None, absolute: bool = False, quiet: bool = False) None

Create an HPGL file from the Document instance.

The device/page_size combination must be defined in the built-in or user-provided config files or an exception will be raised.

By default, no translation is applied on the geometry. If center=True, geometries are moved to the center of the page.

No scaling or rotation is applied to geometries.

Parameters:
  • output (TextIO) -- text-mode IO stream where SVG code will be written

  • document (Document) -- geometries to be written

  • page_size (str) -- page size string (it must be configured for the selected device)

  • landscape (bool) -- if True, the geometries are generated in landscape orientation

  • center (bool) -- center geometries on page before export

  • device (str | None) -- name of the device to use (the corresponding config must exist). If not provided, a default device must be configured, which will be used.

  • velocity (int | None) -- if provided, a VS command will be generated with the corresponding value

  • absolute (bool) -- if True, only use absolute coordinates

  • quiet (bool) -- if True, do not print the plotter/paper info strings

Return type:

None

write_svg(output: TextIO, document: Document, page_size: tuple[float, float] | None = None, center: bool = False, source_string: str = '', layer_label_format: str | None = None, show_pen_up: bool = False, color_mode: str = 'default', use_svg_metadata: bool = False, set_date: bool = True) None

Create an SVG from a Document instance.

If no page size is provided (or (0, 0) is passed), the SVG generated has bounds tightly fitted around the geometries. Otherwise, the provided size (in pixel) is used. The width and height is capped to a minimum of 1 pixel.

By default, no translation is applied on the geometry. If center=True, geometries are moved to the center of the page.

No scaling or rotation is applied to geometries.

Layers are named after the vp_name system property if it exists, or with their layer ID otherwise. This can be overridden with the layer_label_format parameter, which may contain a C-style format specifier such as %d which will be replaced by the layer number.

Optionally, metadata properties prefixed with svg_ (typically extracted from an input SVG with the read command) may be used as group attributes with use_svg_metadata=True.

The color of the layer is determined by the color_mode parameter.

  • "default": use vp_color system property and reverts to the default coloring scheme

  • "none": no formatting (black)

  • "layer": one color per layer based on the default coloring scheme

  • "path": one color per path based on the default coloring scheme

The pen width is set to the vp_pen_width system property if it exists.

For previsualisation purposes, pen-up trajectories can be added to the SVG using the show pen_up argument.

Parameters:
  • output (TextIO) -- text-mode IO stream where SVG code will be written

  • document (Document) -- geometries to be written

  • page_size (tuple[float, float] | None) -- if provided, overrides document.page_size

  • center (bool) -- center geometries on page before export

  • source_string (str) -- value of the source metadata

  • layer_label_format (str | None) -- format string for layer label naming

  • show_pen_up (bool) -- add paths for the pen-up trajectories

  • color_mode (str) -- “default” (system property), “none” (no formatting), “layer” (one color per layer), “path” (one color per path)

  • use_svg_metadata (bool) -- apply svg_-prefixed properties as SVG attributes

  • set_date (bool) -- controls whether the current date and time is set in the SVG’s metadata (disabling it is useful for auto-generated SVG under VCS)

Return type:

None