Path¶
This module implements a geometric Path
, supported by several render
backends, with the goal to create such paths from DXF entities like LWPOLYLINE,
POLYLINE or HATCH and send them to the render backend,
see ezdxf.addons.drawing
.
Minimum common interface:
- matplotlib: PathPatch
matplotlib.path.Path() codes:
MOVETO
LINETO
CURVE3 - quadratic Bèzier-curve
CURVE4 - cubic Bèzier-curve
- PyQt: QPainterPath
moveTo()
lineTo()
quadTo() - quadratic Bèzier-curve (converted to a cubic Bèzier-curve)
cubicTo() - cubic Bèzier-curve
- PyCairo: Context
move_to()
line_to()
no support for quadratic Bèzier-curve
curve_to() - cubic Bèzier-curve
- SVG: SVG-Path
“M” - absolute move to
“L” - absolute line to
“Q” - absolute quadratic Bèzier-curve
“C” - absolute cubic Bèzier-curve
ARC and ELLIPSE entities are approximated by multiple cubic Bézier-curves, which are close enough for display rendering. Non-rational SPLINES of 3rd degree can be represented exact as multiple cubic Bézier-curves, other B-splines will be approximated. The XLINE and the RAY entities are not supported, because of their infinite nature.
This Path
class is a full featured 3D object, although the backends
only support 2D paths.
Changed in version 0.16: Refactored the module ezdxf.render.path
into the subpackage
ezdxf.path
.
The usability of the Path
class expanded by the introduction
of the reverse conversion from Path
to DXF entities (LWPOLYLINE,
POLYLINE, LINE), and many other tools in ezdxf v0.16.
To emphasize this new usability, the Path
class has got its own
subpackage ezdxf.path
.
New in version 0.17: Added the Path.move_to()
command and Multi-Path support.
- Empty-Path¶
Contains only a start point, the length of the path is 0 and the methods
Path.approximate()
,Path.flattening()
andPath.control_vertices()
do not yield any vertices.- Single-Path¶
The
Path
object contains only one path without gaps, the propertyPath.has_sub_paths
isFalse
and the methodPath.sub_paths()
yields only this one path.- Multi-Path¶
The
Path
object contains more than one path, the propertyPath.has_sub_paths
isTrue
and the methodPath.sub_paths()
yields all paths within this object as single-path objects. It is not possible to detect the orientation of a multi-path object, therefore the methodsPath.has_clockwise_orientation()
,Path.clockwise()
andPath.counter_clockwise()
raise aTypeError
exception.
Warning
Always import from the top level ezdxf.path
, never from the
sub-modules
Factory Functions¶
Functions to create Path
objects from other objects.
- ezdxf.path.make_path(entity: DXFEntity) → Path¶
Factory function to create a single
Path
object from a DXF entity. Supported DXF types:LINE
CIRCLE
ARC
ELLIPSE
SPLINE and HELIX
LWPOLYLINE
2D and 3D POLYLINE
SOLID, TRACE, 3DFACE
IMAGE, WIPEOUT clipping path
VIEWPORT clipping path
HATCH as Multi-Path object, new in v0.17
- Parameters
entity – DXF entity
segments – minimal count of cubic Bézier-curves for elliptical arcs like CIRCLE, ARC, ELLIPSE, see
Path.add_ellipse()
level – subdivide level for SPLINE approximation, see
Path.add_spline()
- Raises
TypeError – for unsupported DXF types
New in version 0.16.
Changed in version 0.17: support for HATCH as Multi-Path object
- ezdxf.path.from_hatch(hatch: Hatch) → Iterable[Path]¶
Yield all HATCH boundary paths as separated
Path
objects.New in version 0.16.
- ezdxf.path.from_vertices(vertices: Iterable[Vertex], close=False) → Path¶
Returns a
Path
object from the given vertices.
- ezdxf.path.from_matplotlib_path(mpath, curves=True) → Iterable[Path]¶
Yields multiple
Path
objects from a Matplotlib Path (TextPath) object. (requires Matplotlib)New in version 0.16.
- ezdxf.path.multi_path_from_matplotlib_path(mpath, curves=True) → Path¶
Returns a
Path
object from a Matplotlib Path (TextPath) object. (requires Matplotlib). Returns a multi-path object if necessary.New in version 0.17.
- ezdxf.path.from_qpainter_path(qpath) → Iterable[Path]¶
Yields multiple
Path
objects from a QPainterPath. (requires PyQt5)New in version 0.16.
- ezdxf.path.multi_path_from_qpainter_path(qpath) → Path¶
Returns a
Path
objects from a QPainterPath. Returns a multi-path object if necessary. (requires PyQt5)New in version 0.17.
Render Functions¶
Functions to create DXF entities from paths and add them to the modelspace, a paperspace layout or a block definition.
- ezdxf.path.render_lwpolylines(layout: Layout, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → EntityQuery¶
Render the given paths into layout as
LWPolyline
entities. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.- Parameters
layout – the modelspace, a paperspace layout or a block definition
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
extrusion – extrusion vector for all paths
dxfattribs – additional DXF attribs
- Returns
created entities in an
EntityQuery
object
New in version 0.16.
- ezdxf.path.render_polylines2d(layout: Layout, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → EntityQuery¶
Render the given paths into layout as 2D
Polyline
entities. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector.The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.- Parameters
layout – the modelspace, a paperspace layout or a block definition
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
extrusion – extrusion vector for all paths
dxfattribs – additional DXF attribs
- Returns
created entities in an
EntityQuery
object
New in version 0.16.
- ezdxf.path.render_hatches(layout: Layout, paths: Iterable[Path], *, edge_path=True, distance: float = 0.01, segments: int = 4, g1_tol: float = 1e-4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → EntityQuery¶
Render the given paths into layout as
Hatch
entities. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.- Parameters
layout – the modelspace, a paperspace layout or a block definition
paths – iterable of
Path
objectsedge_path –
True
for edge paths build of LINE and SPLINE edges,False
for only LWPOLYLINE paths as boundary pathsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve to flatten polyline paths
g1_tol – tolerance for G1 continuity check to separate SPLINE edges
extrusion – extrusion vector for all paths
dxfattribs – additional DXF attribs
- Returns
created entities in an
EntityQuery
object
New in version 0.16.
- ezdxf.path.render_mpolygons(layout: Layout, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → EntityQuery¶
Render the given paths into layout as
MPolygon
entities. The MPOLYGON entity supports only polyline boundary paths. All curves will be approximated.The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.
- Parameters
layout – the modelspace, a paperspace layout or a block definition
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve to flatten polyline paths
extrusion – extrusion vector for all paths
dxfattribs – additional DXF attribs
- Returns
created entities in an
EntityQuery
object
New in version 0.17.
- ezdxf.path.render_polylines3d(layout: Layout, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs: Dict = None) → EntityQuery¶
Render the given paths into layout as 3D
Polyline
entities.- Parameters
layout – the modelspace, a paperspace layout or a block definition
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
dxfattribs – additional DXF attribs
- Returns
created entities in an
EntityQuery
object
New in version 0.16.
- ezdxf.path.render_lines(layout: Layout, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs: Dict = None) → EntityQuery¶
Render the given paths into layout as
Line
entities.- Parameters
layout – the modelspace, a paperspace layout or a block definition
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
dxfattribs – additional DXF attribs
- Returns
created entities in an
EntityQuery
object
New in version 0.16.
- ezdxf.path.render_splines_and_polylines(layout: Layout, paths: Iterable[Path], *, g1_tol: float = 1e-4, dxfattribs: Dict = None) → EntityQuery¶
Render the given paths into layout as
Spline
and 3DPolyline
entities.- Parameters
layout – the modelspace, a paperspace layout or a block definition
paths – iterable of
Path
objectsg1_tol – tolerance for G1 continuity check
dxfattribs – additional DXF attribs
- Returns
created entities in an
EntityQuery
object
New in version 0.16.
Entity Maker¶
Functions to create DXF entities from paths.
- ezdxf.path.to_lwpolylines(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → Iterable[LWPolyline]¶
Convert the given paths into
LWPolyline
entities. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.- Parameters
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
extrusion – extrusion vector for all paths
dxfattribs – additional DXF attribs
- Returns
iterable of
LWPolyline
objects
New in version 0.16.
- ezdxf.path.to_polylines2d(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → Iterable[Polyline]¶
Convert the given paths into 2D
Polyline
entities. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.- Parameters
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
extrusion – extrusion vector for all paths
dxfattribs – additional DXF attribs
- Returns
iterable of 2D
Polyline
objects
New in version 0.16.
- ezdxf.path.to_hatches(paths: Iterable[Path], *, edge_path: True, distance: float = 0.01, segments: int = 4, g1_tol: float = 1e-4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → Iterable[Hatch]¶
Convert the given paths into
Hatch
entities. Uses LWPOLYLINE paths for boundaries without curves and edge paths, build of LINE and SPLINE edges, as boundary paths for boundaries including curves. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.- Parameters
paths – iterable of
Path
objectsedge_path –
True
for edge paths build of LINE and SPLINE edges,False
for only LWPOLYLINE paths as boundary pathsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve to flatten LWPOLYLINE paths
g1_tol – tolerance for G1 continuity check to separate SPLINE edges
extrusion – extrusion vector to all paths
dxfattribs – additional DXF attribs
- Returns
iterable of
Hatch
objects
New in version 0.16.
- ezdxf.path.to_mpolygons(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Vertex = (0, 0, 1), dxfattribs: Dict = None) → Iterable[MPolygon]¶
Convert the given paths into
MPolygon
entities. In contrast to HATCH, MPOLYGON supports only polyline boundary paths. All curves will be approximated.The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. The plane elevation is the distance from the WCS origin to the start point of the first path.
- Parameters
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve to flatten LWPOLYLINE paths
extrusion – extrusion vector to all paths
dxfattribs – additional DXF attribs
- Returns
iterable of
MPolygon
objects
New in version 0.17.
- ezdxf.path.to_polylines3d(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs: Dict = None) → Iterable[Polyline]¶
Convert the given paths into 3D
Polyline
entities.- Parameters
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
dxfattribs – additional DXF attribs
- Returns
iterable of 3D
Polyline
objects
New in version 0.16.
- ezdxf.path.to_lines(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs: Dict = None) → Iterable[Line]¶
Convert the given paths into
Line
entities.- Parameters
paths – iterable of
Path
objectsdistance – maximum distance, see
Path.flattening()
segments – minimum segment count per Bézier curve
dxfattribs – additional DXF attribs
- Returns
iterable of
Line
objects
New in version 0.16.
- ezdxf.path.to_splines_and_polylines(paths: Iterable[Path], *, g1_tol: float = 1e-4, dxfattribs: Dict = None) → Iterable[Union[Spline, Polyline]]¶
Convert the given paths into
Spline
and 3DPolyline
entities.- Parameters
paths – iterable of
Path
objectsg1_tol – tolerance for G1 continuity check
dxfattribs – additional DXF attribs
- Returns
iterable of
Line
objects
New in version 0.16.
Tool Maker¶
Functions to create construction tools.
- ezdxf.path.to_bsplines_and_vertices(path: Path, g1_tol: float = 1e-4) → Iterable[Union[BSpline, List[Vec3]]]¶
Convert a
Path
object into multiple cubic B-splines and polylines as lists of vertices. Breaks adjacent Bèzier without G1 continuity into separated B-splines.- Parameters
path –
Path
objectsg1_tol – tolerance for G1 continuity check
- Returns
New in version 0.16.
- ezdxf.path.to_matplotlib_path(paths: Iterable[Path], extrusion=(0, 0, 1)) → matplotlib.path.Path¶
Convert the given paths into a single
matplotlib.path.Path
object. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector.The default extrusion vector is the WCS z-axis. The MatplotlibPath
is a 2D object with OCS coordinates and the z-elevation is lost. (requires Matplotlib)- Parameters
paths – iterable of
Path
objectsextrusion – extrusion vector for all paths
- Returns
matplotlib Path in OCS!
New in version 0.16.
- ezdxf.path.to_qpainter_path(paths: Iterable[Path], extrusion=(0, 0, 1)) → PyQt5.QtGui.QPainterPath¶
Convert the given paths into a
PyQt5.QtGui.QPainterPath
object. The extrusion vector is applied to all paths, all vertices are projected onto the plane normal to this extrusion vector. The default extrusion vector is the WCS z-axis. TheQPainterPath
is a 2D object with OCS coordinates and the z-elevation is lost. (requires PyQt5)- Parameters
paths – iterable of
Path
objectsextrusion – extrusion vector for all paths
- Returns
QPainterPath in OCS!
New in version 0.16.
Utility Functions¶
- ezdxf.path.transform_paths(paths: Iterable[Path], m: Matrix44) → List[Path]¶
Transform multiple
Path
objects at once by transformation matrix m. Returns a list of the transformedPath
objects.
- ezdxf.path.transform_paths_to_ocs(paths: Iterable[Path], ocs: OCS) → List[Path]¶
Transform multiple
Path
objects at once from WCS to OCS. Returns a list of the transformedPath
objects.
- ezdxf.path.bbox(paths: Iterable[Path]) → BoundingBox¶
Returns the
BoundingBox
for the given paths.- Parameters
paths – iterable of
Path
objectsflatten – value != 0 for bounding box calculation from the flattened path and value == 0 for bounding box from the control vertices. Default value is 0.01 as max flattening distance.
segments – minimal segment count for flattening
- ezdxf.path.fit_paths_into_box(paths: Iterable[Path], size: Tuple[float, float, float], uniform=True, source_box: BoundingBox = None) → List[Path]¶
Scale the given paths to fit into a box of the given size, so that all path vertices are inside this borders. If source_box is
None
the default source bounding box is calculated from the control points of the paths.Note: if the target size has a z-size of 0, the paths are projected into the xy-plane, same is true for the x-size, projects into the yz-plane and the y-size, projects into and xz-plane.
- Parameters
paths – iterable of
Path
objectssize – target box size as tuple of x-, y- ond z-size values
uniform –
True
for uniform scalingsource_box – pass precalculated source bounding box, or
None
to calculate the default source bounding box from the control vertices
- ezdxf.path.add_bezier3p(path: Path, curves: Iterable[Bezier3P])¶
Add multiple quadratic Bèzier-curves to the given path.
Auto-detect the connection point to the given path, if neither the start- nor the end point of the curves is close to the path end point, a line from the path end point to the start point of the first curve will be added automatically.
Changed in version 0.16.2: add linear Bézier curve segments as LINE_TO commands
- ezdxf.path.add_bezier4p(path: Path, curves: Iterable[Bezier4P])¶
Add multiple cubic Bèzier-curves to the given path.
Auto-detect the connection point to the given path, if neither the start- nor the end point of the curves is close to the path end point, a line from the path end point to the start point of the first curve will be added automatically.
Changed in version 0.16.2: add linear Bézier curve segments as LINE_TO commands
- ezdxf.path.add_ellipse(path: Path, ellipse: ConstructionEllipse, segments=1)¶
Add an elliptical arc as multiple cubic Bèzier-curves to the given path, use
from_arc()
constructor of classConstructionEllipse
to add circular arcs.Auto-detect the connection point to the given path, if neither the start- nor the end point of the ellipse is close to the path end point, a line from the path end point to the ellipse start point will be added automatically (see
add_bezier4p()
).By default the start of an empty path is set to the start point of the ellipse, setting argument reset to
False
prevents this behavior.- Parameters
path –
Path
objectellipse – ellipse parameters as
ConstructionEllipse
objectsegments – count of Bèzier-curve segments, at least one segment for each quarter (pi/2),
1
for as few as possible.reset – set start point to start of ellipse if path is empty
- ezdxf.path.add_spline(path: Path, spline: BSpline, level=4)¶
Add a B-spline as multiple cubic Bèzier-curves.
Non-rational B-splines of 3rd degree gets a perfect conversion to cubic bezier curves with a minimal count of curve segments, all other B-spline require much more curve segments for approximation.
Auto-detect the connection point to the given path, if neither the start- nor the end point of the B-spline is close to the path end point, a line from the path end point to the start point of the B-spline will be added automatically. (see
add_bezier4p()
).By default the start of an empty path is set to the start point of the spline, setting argument reset to
False
prevents this behavior.
- ezdxf.path.to_multi_path(paths: Iterable[Path]) → Path¶
Returns a multi-path object from all given paths and their sub-paths. Ignores paths without any commands (empty paths).
New in version 0.17.
Basic Shapes¶
- ezdxf.path.unit_circle(start_angle: float = 0, end_angle: float = 2π, segments: int = 1, transform: Matrix44 = None) → Path¶
Returns an unit circle as a
Path
object, with the center at (0, 0, 0) and the radius of 1 drawing unit.The arc spans from the start- to the end angle in counter clockwise orientation. The end angle has to be greater than the start angle and the angle span has to be greater than 0.
- Parameters
start_angle – start angle in radians
end_angle – end angle in radians (end_angle > start_angle!)
segments – count of Bèzier-curve segments, default is one segment for each arc quarter (π/2)
transform – transformation Matrix applied to the unit circle
- ezdxf.path.wedge(start_angle: float, end_angle: float, segments: int = 1, transform: Matrix44 = None) → Path¶
Returns a wedge as a
Path
object, with the center at (0, 0, 0) and the radius of 1 drawing unit.The arc spans from the start- to the end angle in counter clockwise orientation. The end angle has to be greater than the start angle and the angle span has to be greater than 0.
- Parameters
start_angle – start angle in radians
end_angle – end angle in radians (end_angle > start_angle!)
segments – count of Bèzier-curve segments, default is one segment for each arc quarter (π/2)
transform – transformation Matrix applied to the wedge
- ezdxf.path.elliptic_transformation(center: Vertex = (0, 0, 0), radius: float = 1, ratio: float = 1, rotation: float = 0) → Matrix44¶
Returns the transformation matrix to transform an unit circle into an arbitrary circular- or elliptic arc.
Example how to create an ellipse with an major axis length of 3, a minor axis length 1.5 and rotated about 90°:
m = elliptic_transformation(radius=3, ratio=0.5, rotation=math.pi / 2) ellipse = shapes.unit_circle(transform=m)
- Parameters
center – curve center in WCS
radius – radius of the major axis in drawing units
ratio – ratio of minor axis to major axis
rotation – rotation angle about the z-axis in radians
- ezdxf.path.rect(width: float = 1, height: float = 1, transform: Matrix44 = None) → Path¶
Returns a closed rectangle as a
Path
object, with the center at (0, 0, 0) and the given width and height in drawing units.- Parameters
width – width of the rectangle in drawing units, width > 0
height – height of the rectangle in drawing units, height > 0
transform – transformation Matrix applied to the rectangle
- ezdxf.path.ngon(count: int, length: float = None, radius: float = 1.0, transform: Matrix44 = None) → Path¶
Returns a regular polygon a
Path
object, with the center at (0, 0, 0). The polygon size is determined by the edge length or the circum radius argument. If both are given length has higher priority. Default size is a radius of 1. The ngon starts with the first vertex is on the x-axis! The base geometry is created by functionezdxf.render.forms.ngon()
.- Parameters
count – count of polygon corners >= 3
length – length of polygon side
radius – circum radius, default is 1
transform – transformation Matrix applied to the ngon
- ezdxf.path.star(count: int, r1: float, r2: float, transform: Matrix44 = None) → Path¶
Returns a star shape as a
Path
object, with the center at (0, 0, 0).Argument count defines the count of star spikes, r1 defines the radius of the “outer” vertices and r2 defines the radius of the “inner” vertices, but this does not mean that r1 has to be greater than r2. The star shape starts with the first vertex is on the x-axis! The base geometry is created by function
ezdxf.render.forms.star()
.- Parameters
count – spike count >= 3
r1 – radius 1
r2 – radius 2
transform – transformation Matrix applied to the star
- ezdxf.path.gear(count: int, top_width: float, bottom_width: float, height: float, outside_radius: float, transform: Matrix44 = None) → Path¶
Returns a gear (cogwheel) shape as a
Path
object, with the center at (0, 0, 0). The base geometry is created by functionezdxf.render.forms.gear()
.Warning
This function does not create correct gears for mechanical engineering!
- Parameters
count – teeth count >= 3
top_width – teeth width at outside radius
bottom_width – teeth width at base radius
height – teeth height; base radius = outside radius - height
outside_radius – outside radius
transform – transformation Matrix applied to the gear shape
The text2path
add-on provides additional functions to
create paths from text strings and DXF text entities.
The Path Class¶
- class ezdxf.path.Path¶
- property start: ezdxf.math._vector.Vec3¶
Path
start point, resetting the start point of an empty path is possible.
- property is_closed: bool¶
Returns
True
if the start point is close to the end point.
- property has_lines: bool¶
Returns
True
if the path has any line segments.
- property has_curves: bool¶
Returns
True
if the path has any curve segments.
- property has_sub_paths: bool¶
Returns
True
if the path is a Multi-Path object which contains multiple sub-paths.New in version 0.17.
- sub_paths() → Iterable[Path]¶
Yield sub-path as Single-Path objects.
It is safe to call
sub_paths()
on any path-type: Single-Path, Multi-Path and Empty-Path.New in version 0.17.
- control_vertices()¶
Yields all path control vertices in consecutive order.
- has_clockwise_orientation() → bool¶
Returns
True
if 2D path has clockwise orientation, ignores z-axis of all control vertices.- Raises
TypeError – can’t detect orientation of a Multi-Path object
- line_to(location: Vec3)¶
Add a line from actual path end point to location.
- move_to(location: Vec3)¶
Start a new sub-path at location. This creates a gap between the current end-point and the start-point of the new sub-path. This converts the instance into a Multi-Path object.
If the
move_to()
command is the first command, the start point of the path will be reset to location.New in version 0.17.
- curve3_to(location: Vec3, ctrl: Vec3)¶
Add a quadratic Bèzier-curve from actual path end point to location, ctrl is the control point for the quadratic Bèzier-curve.
- curve4_to(location: Vec3, ctrl1: Vec3, ctrl2: Vec3)¶
Add a cubic Bèzier-curve from actual path end point to location, ctrl1 and ctrl2 are the control points for the cubic Bèzier-curve.
- close() → None¶
Close path by adding a line segment from the end point to the start point.
- close_sub_path() → None¶
Close last sub-path by adding a line segment from the end point to the start point of the last sub-path. Behaves like
close()
for Single-Path instances.New in version 0.17.
- clockwise() → Path¶
Returns new
Path
in clockwise orientation.- Raises
TypeError – can’t detect orientation of a Multi-Path object
- counter_clockwise() → Path¶
Returns new
Path
in counter-clockwise orientation.- Raises
TypeError – can’t detect orientation of a Multi-Path object
- transform(m: Matrix44) → Path¶
Returns a new transformed path.
- Parameters
m – transformation matrix of type
Matrix44
- approximate(segments: int = 20) → Iterable[Vec3]¶
Approximate path by vertices, segments is the count of approximation segments for each Bézier curve.
Does not yield any vertices for empty paths, where only a start point is present!
Approximation of Multi-Path objects is possible, but gaps are indistinguishable from line segments.
- flattening(distance: float, segments: int = 16) → Iterable[Vec3]¶
Approximate path by vertices and use adaptive recursive flattening to approximate Bèzier curves. The argument segments is the minimum count of approximation segments for each curve, if the distance from the center of the approximation segment to the curve is bigger than distance the segment will be subdivided.
Does not yield any vertices for empty paths, where only a start point is present!
Flattening of Multi-Path objects is possible, but gaps are indistinguishable from line segments.
- Parameters
distance – maximum distance from the center of the curve to the center of the line segment between two approximation points to determine if a segment should be subdivided.
segments – minimum segment count per Bézier curve
- append_path(path: Path)¶
Append another path to this path. Adds a
self.line_to(path.start)
if the end of this path != the start of appended path.New in version 0.17.
- extend_multi_path(path: Path)¶
Extend the path by another path. The source path is automatically a Multi-Path object, even if the previous end point matches the start point of the appended path. Ignores paths without any commands (empty paths).
New in version 0.17.
- all_lines_to_curve3() → None¶
Inline conversion of all LINE_TO commands into CURVE3_TO commands.
- all_lines_to_curve4() → None¶
Inline conversion of all LINE_TO commands into CURVE4_TO commands.