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èziercurve
CURVE4  cubic Bèziercurve
 PyQt: QPainterPath
moveTo()
lineTo()
quadTo()  quadratic Bèziercurve (converted to a cubic Bèziercurve)
cubicTo()  cubic Bèziercurve
 PyCairo: Context
move_to()
line_to()
no support for quadratic Bèziercurve
curve_to()  cubic Bèziercurve
 SVG: SVGPath
“M”  absolute move to
“L”  absolute line to
“Q”  absolute quadratic Bèziercurve
“C”  absolute cubic Bèziercurve
ARC and ELLIPSE entities are approximated by multiple cubic Béziercurves, which are close enough for display rendering. Nonrational SPLINES of 3rd degree can be represented exact as multiple cubic Béziercurves, other Bsplines 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
.
Warning
Always import from the top level ezdxf.path
, never from the
submodules
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
The HATCH entity consist of multiple boundary paths and is not convertible into a single
Path
object and therefore not supported by this function. Parameters
entity – DXF entity
segments – minimal count of cubic Béziercurves 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.

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.
from_qpainter_path
(qpath) → Iterable[Path]¶ Yields multiple
Path
objects from a QPainterPath. (requires PyQt5)New in version 0.16.
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 zaxis. 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 zaxis. 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 = 1e4, 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 zaxis. 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 LWPOLYLINE 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_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 = 1e4, 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 zaxis. 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 zaxis. 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 = 1e4, 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 zaxis. 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_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 = 1e4, 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 = 1e4) → Iterable[Union[BSpline, List[Vec3]]]¶ Convert a
Path
object into multiple cubic Bsplines and polylines as lists of vertices. Breaks adjacent Bèzier without G1 continuity into separated Bsplines. 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 zaxis. The MatplotlibPath
is a 2D object with OCS coordinates and the zelevation 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 zaxis. TheQPainterPath
is a 2D object with OCS coordinates and the zelevation 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
and value == 0 for bounding box from the control vertices. (path) –
value is 0.01 as max flattening distance. (Default) –
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 zsize of 0, the paths are projected into the xyplane, same is true for the xsize, projects into the yzplane and the ysize, projects into and xzplane.
 Parameters
paths – iterable of
Path
objectssize – target box size as tuple of x, y ond zsize 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èziercurves to the given path.
Autodetect 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.

ezdxf.path.
add_bezier4p
(path: Path, curves: Iterable[Bezier4P])¶ Add multiple cubic Bèziercurves to the given path.
Autodetect 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.

ezdxf.path.
add_ellipse
(path: Path, ellipse: ConstructionEllipse, segments=1)¶ Add an elliptical arc as multiple cubic Bèziercurves to the given path, use
from_arc()
constructor of classConstructionEllipse
to add circular arcs.Autodetect 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èziercurve 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 Bspline as multiple cubic Bèziercurves.
Nonrational Bsplines of 3rd degree gets a perfect conversion to cubic bezier curves with a minimal count of curve segments, all other Bspline require much more curve segments for approximation.
Autodetect the connection point to the given path, if neither the start nor the end point of the Bspline is close to the path end point, a line from the path end point to the start point of the Bspline 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.
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èziercurve 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èziercurve 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 zaxis 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 xaxis! 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 xaxis! 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
addon provides additional functions to
create paths from text strings and DXF text entities.
The Path Class¶

class
ezdxf.path.
Path
¶ 

is_closed
¶ Returns
True
if the start point is close to the end point.

has_lines
¶ Returns
True
if the path has any line segments.

has_curves
¶ Returns
True
if the path has any curve segments.

control_vertices
()¶ Yields all path control vertices in consecutive order.

has_clockwise_orientation
() → bool¶ Returns
True
if 2D path has clockwise orientation, ignores zaxis of all control vertices.

line_to
(location: Vec3)¶ Add a line from actual path end point to location.

curve3_to
(location: Vec3, ctrl: Vec3)¶ Add a quadratic Bèziercurve from actual path end point to location, ctrl is the control point for the quadratic Bèziercurve.

curve4_to
(location: Vec3, ctrl1: Vec3, ctrl2: Vec3)¶ Add a cubic Bèziercurve from actual path end point to location, ctrl1 and ctrl2 are the control points for the cubic Bèziercurve.

close
() → None¶ Close path by adding a line segment from the end point to the start point.

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!

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!
 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
