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 |
|
Create an instance of the block processor class. |
|
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. |
|
Helper decorator to define generator-type commands. |
|
Helper decorator to define a global processor command. |
|
Compute a linearly interpolated version of line with segments of step length or less. |
|
Check if a line is closed. |
|
Helper decorator to define a layer processor command. |
|
Build a line from two points |
|
Compute the length of a line. |
|
Convert multiple-layer CLI argument to list of layer IDs. |
|
Marks a command as wanting to receive the current state. |
|
Read a multilayer SVG file and return its content as a |
|
Read a SVG file an return its content as a |
|
Build a rectangular path, with optional rounded angles. |
|
Change the seam of a closed path. |
|
Convert single-layer CLI argument to layer ID, accounting for the existence of a current a current target layer and dealing with default behavior. |
|
Returns True if every callables in |
|
Create a HPGL file from the |
|
Create a SVG from a |
Classes
|
|
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. |
|
Interpret value of --layer options. |
|
|
|
|
|
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
-
block_processor
(c)¶ Create an instance of the block processor class.
-
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.
-
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.
-
generator
(f)¶ Helper decorator to define generator-type commands.
Generator do not have input, have automatically a “-l, --layer” option added to them, and must return a LineCollection structure, which will be added to a new layer or an existing one depending the option.
-
global_processor
(f)¶ Helper decorator to define a global processor command.
This type of command implement a global, multi-layer processing and should be used for processors which cannot be applied layer-by-layer independently (in which case, using a
layer_processor()
is advised.No option is automatically added to global processors. In cases where the user should be able to control on which layer(s) the processing must be applied, it is advised to add a
--layer
option (with typeLayerType
) and use themultiple_to_layer_ids()
companion function (see example below)A global processor receives a
Document
as input and must return one.Example:
@click.command() @click.option( "-l", "--layer", type=vpype.LayerType(accept_multiple=True), default="all", help="Target layer(s).", ) @vpype.global_processor def my_global_processor( document: vpype.Document, layer: Union[int, List[int]] ) -> vpype.Document: '''Example global processor''' layer_ids = multiple_to_layer_ids(layer, document) for lines in document.layers_from_ids(layer_ids): # [apply some modification to lines] return document my_global_processor.help_group = "My Plugins"
-
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.
-
layer_processor
(f)¶ Helper decorator to define a layer processor command.
Layer processors implements “intra-layer” processing, i.e. they are independently called for every layer in the pipeline. A
--layer
option is automatically appended to the option to let the user control on which layer(s) the processor should be applied (by default,all
is used).Layer processors receive a
LineCollection
as input and must return one.Example:
@click.command() @vpype.layer_processor def my_processor(lines: vpype.LineCollection) -> vpype.LineCollection: '''Example layer processor''' new_lines = vpype.LineCollection() for line in lines: # [do something with line] new_lines.append(line) return lines my_processor.help_group = "My Plugins"
-
line
(x0, y0, x1, y1)¶ Build a line from two points
-
multiple_to_layer_ids
(layers, document)¶ Convert multiple-layer CLI argument to list of layer IDs.
-
pass_state
(f)¶ Marks a command as wanting to receive the current state.
-
read_multilayer_svg
(filename, 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
filename (
str
) -- path of the SVG filequantization (
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
Document
- Returns
Document
instance with the imported geometries and its page size set the the SVG dimensions
-
read_svg
(filename, 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
filename (
str
) -- path of the SVG filequantization (
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
-
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.
-
single_to_layer_id
(layer, document)¶ Convert single-layer CLI argument to layer ID, accounting for the existence of a current a current target layer and dealing with default behavior.
- Return type
- Returns
Target layer ID
-
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, 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
[float
]) -- if provided, a VS command will be generated with the corresponding valuequiet (
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='%d', show_pen_up=False, color_mode='none')¶ 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 layer_label_format, which may contain a C-style format specifier such as %d which will be replaced by the layer number.
For previsualisation purposes, pen-up trajectories can be added to the SVG and path can be colored individually (
color_mode="path"
) or layer-by-layer (color_mode="layer"
).- 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 (
str
) -- format string for layer label namingshow_pen_up (
bool
) -- add paths for the pen-up trajectoriescolor_mode (
str
) -- “none” (no formatting), “layer” (one color per layer), “path” (one color per path)
- Return type