vpype¶
This module contains vpype core and its API.
Functions
Build an elliptical arc path. |
|
Return a view of a complex line array that behaves as an Nx2 real array |
|
Build a circular path. |
|
Convert an angle optionally expressed as a string with unit to degrees. |
|
Convert a length optionally expressed as a string with unit to px value. |
|
Converts a string with page size to dimension in pixels. |
|
Crop a polyline to a rectangular area. |
|
Crop a path at a axis-aligned location. |
|
Build an elliptical path. |
|
Convert a length in pixel to a string representation with the provided unit or unit system. |
|
Compute a linearly interpolated version of line with segments of step length or less. |
|
Check if a line is closed. |
|
Build a line from two points |
|
Compute the length of a line. |
|
Read a multilayer SVG file and return its content as a |
|
Read an SVG file and return its content as a |
|
Read an SVG file by sorting geometries by unique combination of provided attributes. |
|
Build a rectangular path, with optional rounded angles. |
|
Change the seam of a closed path. |
|
Apply a squiggle filter to a |
|
Create a wrapped block of text using the provided width. |
|
Create a line of text. |
|
Returns True if every callables in |
|
Create an HPGL file from the |
|
Create an SVG from a |
Classes
|
Simple, immutable, hashable color class with flexible construction. |
Helper class to handle vpype's TOML configuration files. |
|
|
This class is the core data model of vpype and represent the data that is passed from one command to the other. |
|
|
|
Wrapper to scipy.spatial.KDTree to facilitate systematic processing of a line collection. |
|
Data class containing configuration for a give plotter type/paper size combinations. |
|
Data class containing configuration for a given plotter type. |
|
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.
- convert_angle(value: str | float) float ¶
Convert an angle optionally expressed as a string with unit to degrees.
- Parameters:
- Returns:
converted angle in degree
- Raises:
ValueError --
- Return type:
- convert_length(value: str | float) float ¶
Convert a length optionally expressed as a string with unit to px value.
- Parameters:
- Returns:
converted value
- Raises:
ValueError --
- Return type:
- 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)
- crop(line: ndarray, x1: float, y1: float, x2: float, y2: float) list[ndarray] ¶
Crop a polyline to a rectangular area.
- Parameters:
- 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:
- 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.
- 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:
- Returns:
a string representation of the length
- Return type:
- 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
- line_length(line: ndarray) float ¶
Compute the length of a line.
- Parameters:
line (ndarray)
- Return type:
- 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
andheight
attributes of the<svg>
tag. If these attributes are missing or expressed in percent,svgelements
attempts to use theviewBox
attribute instead, or reverts to a 1000x1000px page size. This behaviour can be overridden by providing values for thedefault_width
anddefault_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:
- 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
andheight
attributes of the<svg>
tag. If these attributes are missing or expressed in percent,svgelements
attempts to use theviewBox
attribute instead, or reverts to a 1000x1000px page size. This behaviour can be overridden by providing values for thedefault_width
anddefault_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:
- 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
andheight
attributes of the<svg>
tag. If these attributes are missing or expressed in percent,svgelements
attempts to use theviewBox
attribute instead, or reverts to a 1000x1000px page size. This behaviour can be overridden by providing values for thedefault_width
anddefault_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:
- 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:
- 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:
- 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:
- Return type:
- union(line: ndarray, keys: list[Callable[[ndarray], bool]]) bool ¶
Returns True if every callables in
keys
return True (similar toall()
. This function is typically used withLineCollection.filter()
.
- 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 withuse_svg_metadata=True
.The color of the layer is determined by the
color_mode
parameter."default"
: usevp_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 attributesset_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