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. |
|
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 a SVG file an return its content as a |
|
Read a 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 a HPGL file from the |
|
Create a 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.cKDTree 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, y, rw, rh, start, stop, quantization=0.1)
Build an elliptical arc path. Zero angles refer to east of unit circle and positive values extend counter-clockwise.
- Parameters
x (
float
) -- center X coordinatey (
float
) -- center Y coordinaterw (
float
) -- ellipse half-widthrh (
float
) -- ellipse half-height (use the same value asrw
for a circular arc)start (
float
) -- start angle (degree)stop (
float
) -- stop angle (degree)quantization (
float
) -- maximum length of linear segment
- Return type
ndarray
- Returns
arc path
- as_vector(a)
Return a view of a complex line array that behaves as an Nx2 real array
- circle(x, y, radius, quantization=0.1)
Build a circular path.
- convert_angle(value)
Convert an angle optionally expressed as a string with unit to degrees.
- Parameters
- Return type
- Returns
converted angle in degree
- Raises
ValueError --
- convert_length(value)
Convert a length optionally expressed as a string with unit to px value.
- Parameters
- Return type
- Returns
converted value
- Raises
ValueError --
- convert_page_size(value)
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, x1, y1, x2, y2)
Crop a polyline to a rectangular area.
- Parameters
- Return type
List
[ndarray
]- Returns
list of lines resulting of the crop (emtpy if x1 > x2 or y1 > y2)
- crop_half_plane(line, loc, axis, keep_smaller)
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
- Return type
List
[ndarray
]- Returns
list of paths
- ellipse(x, y, w, h, quantization=0.1)
Build an elliptical path.
- interpolate(line, step)
Compute a linearly interpolated version of line with segments of step length or less.
- Parameters
line (
ndarray
) -- 1D array of complexstep (
float
) -- maximum length of interpolated segment
- Return type
ndarray
- Returns
interpolated 1D array of complex
- is_closed(line, tolerance)
Check if a line is closed.
- line(x0, y0, x1, y1)
Build a line from two points
- read_multilayer_svg(file, quantization, crop=True, simplify=False, parallel=False, default_width=1000, default_height=1000)
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. Labels are stripped of non-numeric characters and the remaining is used as layer ID. Lacking numeric characters, the appearing order is used. If the label is 0, its 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.
- Parameters
file (
Union
[str
,TextIO
]) -- path of the SVG file or stream objectquantization (
float
) -- maximum size of segment used to approximate curved geometriescrop (
bool
) -- crop the geometries to the SVG boundariessimplify (
bool
) -- run Shapely’s simplify on loaded geometryparallel (
bool
) -- enable multiprocessing (only recommended forsimplify=True
and SVG with many curves)default_width (
float
) -- default width if not provided by SVG or if a percent width is provideddefault_height (
float
) -- default height if not provided by SVG or if a percent height is provided
- Return type
- Returns
Document
instance with the imported geometries and its page size set the the SVG dimensions
- read_svg(file, quantization, crop=True, simplify=False, parallel=False, default_width=1000, default_height=1000)
Read a SVG file an 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.
- Parameters
file (
Union
[str
,TextIO
]) -- path of the SVG file or stream objectquantization (
float
) -- maximum size of segment used to approximate curved geometriescrop (
bool
) -- crop the geometries to the SVG boundariessimplify (
bool
) -- run Shapely’s simplify on loaded geometryparallel (
bool
) -- enable multiprocessing (only recommended forsimplify=True
and SVG with many curves)default_width (
float
) -- default width if not provided by SVG or if a percent width is provideddefault_height (
float
) -- default height if not provided by SVG or if a percent height is provided
- Return type
- Returns
tuple containing a
LineCollection
with the imported geometries as well as the width and height of the SVG
- read_svg_by_attributes(file, attributes, quantization, crop=True, simplify=False, parallel=False, default_width=1000, default_height=1000)
Read a 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.
- Parameters
file (
Union
[str
,TextIO
]) -- path of the SVG file or stream objectattributes (
Iterable
[str
]) -- attributes by which the object should be sortedquantization (
float
) -- maximum size of segment used to approximate curved geometriescrop (
bool
) -- crop the geometries to the SVG boundariessimplify (
bool
) -- run Shapely’s simplify on loaded geometryparallel (
bool
) -- enable multiprocessing (only recommended forsimplify=True
and SVG with many curves)default_width (
float
) -- default width if not provided by SVG or if a percent width is provideddefault_height (
float
) -- default height if not provided by SVG or if a percent height is provided
- Return type
- Returns
Document
instance with the imported geometries and its page size set the the SVG dimensions
- rect(x, y, width, height, tl=0, tr=0, br=0, bl=0, quantization=0.1)
Build a rectangular path, with optional rounded angles.
- Parameters
x (
float
) -- top-left corner X coordinatey (
float
) -- top-left corner Y coordinatewidth (
float
) -- rectangle widthheight (
float
) -- rectangle heighttl (
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
- Return type
ndarray
- Returns
rectangular path
- reloop(line, loc=None)
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.
- squiggles(lines, ampl, period, quantization)
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 linesampl (
float
) -- squiggle amplitude (px)period (
float
) -- squiggle period (px)quantization (
float
) -- quantization (px)
- Return type
- Returns
filtered lines
- text_block(paragraph, width, font_name='futural', size=18.0, align='left', line_spacing=1, justify=False)
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 layoutfont_name -- the name of the font to use (see
FONT_NAMES
)width (
float
) -- the width of the blocksize (
float
) -- the font sizealign (
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)
- Return type
- text_line(txt, font_name='futural', size=18.0, align='left', spacing=0.0)
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, keys)
Returns True if every callables in
keys
return True (similar toall()
. This function is typically used withLineCollection.filter()
.
- write_hpgl(output, document, page_size, landscape, center, device, velocity, absolute=False, quiet=False)
Create a 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 writtendocument (
Document
) -- geometries to be writtenpage_size (
str
) -- page size string (it must be configured for the selected device)landscape (
bool
) -- if True, the geometries are generated in landscape orientationcenter (
bool
) -- center geometries on page before exportdevice (
Optional
[str
]) -- name of the device to use (the corresponding config must exists). If not provided, a default device must be configured, which will be used.velocity (
Optional
[int
]) -- if provided, a VS command will be generated with the corresponding valueabsolute (
bool
) -- if True, only use absolute coordinatesquiet (
bool
) -- if True, do not print the plotter/paper info strings
- Return type
- write_svg(output, document, page_size=None, center=False, source_string='', layer_label_format=None, show_pen_up=False, color_mode='default', use_svg_metadata=False)
Create a 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 writtendocument (
Document
) -- geometries to be writtenpage_size (
Optional
[Tuple
[float
,float
]]) -- if provided, overrides document.page_sizecenter (
bool
) -- center geometries on page before exportsource_string (
str
) -- value of the source metadatalayer_label_format (
Optional
[str
]) -- format string for layer label namingshow_pen_up (
bool
) -- add paths for the pen-up trajectoriescolor_mode (
str
) -- “default” (system property), “none” (no formatting), “layer” (one color per layer), “path” (one color per path)use_svg_metadata (
bool
) -- applysvg_
-prefixed properties as SVG attributes
- Return type