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.

Hint

A Path can not represent a point. A Path with only a start point yields no vertices!

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.

Empty-Path: Contains only a start point, the length of the path is 0 and the methods Path.approximate(), Path.flattening() and Path.control_vertices() do not yield any vertices.
Single-Path: The Path object contains only one path without gaps, the property Path.has_sub_paths is False and the method Path.sub_paths() yields only this one path.
Multi-Path: The Path object contains more than one path, the property Path.has_sub_paths is True and the method Path.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 methods Path.has_clockwise_orientation(), Path.clockwise() and Path.counter_clockwise() raise a TypeError 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

Parameters:	entity – DXF entity segments – minimal count of cubic Bézier-curves for elliptical arcs like CIRCLE, ARC, ELLIPSE, BULGE see `Path.add_ellipse()` level – subdivide level for SPLINE approximation, see `Path.add_spline()`
Raises:	TypeError – for unsupported DXF types

ezdxf.path.from_hatch(hatch: ezdxf.entities.polygon.DXFPolygon, offset: ezdxf.math._vector.Vec3 = Vec3(0.0, 0.0, 0.0)) → Iterator[ezdxf.path.path.Path]¶: Yield all HATCH/MPOLYGON boundary paths as separated Path objects in WCS coordinates.

ezdxf.path.from_vertices(vertices: Iterable[Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]], close=False) → ezdxf.path.path.Path¶: Returns a Path object from the given vertices.

ezdxf.path.from_matplotlib_path(mpath, curves=True) → Iterator[ezdxf.path.path.Path]¶: Yields multiple Path objects from a Matplotlib Path (TextPath) object. (requires Matplotlib)

ezdxf.path.multi_path_from_matplotlib_path(mpath, curves=True) → ezdxf.path.path.Path¶: Returns a Path object from a Matplotlib Path (TextPath) object. (requires Matplotlib). Returns a multi-path object if necessary.

ezdxf.path.from_qpainter_path(qpath) → Iterator[ezdxf.path.path.Path]¶: Yields multiple Path objects from a QPainterPath. (requires Qt bindings)

ezdxf.path.multi_path_from_qpainter_path(qpath) → ezdxf.path.path.Path¶: Returns a Path objects from a QPainterPath. Returns a multi-path object if necessary. (requires Qt bindings)

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_hatches(layout: GenericLayoutType, paths: Iterable[Path], *, edge_path: bool = True, distance: float = 0.01, segments: int = 4, g1_tol: float = 0.0001, extrusion: UVec = Vec3(0.0, 0.0, 1.0), dxfattribs=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 objects
edge_path – True for edge paths build of LINE and SPLINE edges, False for only LWPOLYLINE paths as boundary paths
distance – 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

ezdxf.path.render_lines(layout: GenericLayoutType, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs=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` objects distance – maximum distance, see `Path.flattening()` segments – minimum segment count per Bézier curve dxfattribs – additional DXF attribs
Returns:	created entities in an `EntityQuery` object

ezdxf.path.render_lwpolylines(layout: GenericLayoutType, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: UVec = Vec3(0.0, 0.0, 1.0), dxfattribs=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` objects distance – 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

ezdxf.path.render_mpolygons(layout: GenericLayoutType, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: UVec = Vec3(0.0, 0.0, 1.0), dxfattribs=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` objects distance – 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

ezdxf.path.render_polylines2d(layout: GenericLayoutType, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: UVec = Vec3(0.0, 0.0, 1.0), dxfattribs=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` objects distance – 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

ezdxf.path.render_polylines3d(layout: GenericLayoutType, paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs=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` objects distance – maximum distance, see `Path.flattening()` segments – minimum segment count per Bézier curve dxfattribs – additional DXF attribs
Returns:	created entities in an `EntityQuery` object

ezdxf.path.render_splines_and_polylines(layout: GenericLayoutType, paths: Iterable[Path], *, g1_tol: float = 0.0001, dxfattribs=None) → EntityQuery¶

Render the given paths into layout as Spline and 3D Polyline entities.

Parameters:	layout – the modelspace, a paperspace layout or a block definition paths – iterable of `Path` objects g1_tol – tolerance for G1 continuity check dxfattribs – additional DXF attribs
Returns:	created entities in an `EntityQuery` object

Entity Maker¶

Functions to create DXF entities from paths.

ezdxf.path.to_hatches(paths: Iterable[ezdxf.path.path.Path], *, edge_path: bool = True, distance: float = 0.01, segments: int = 4, g1_tol: float = 0.0001, extrusion: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[ezdxf.entities.hatch.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 objects
edge_path – True for edge paths build of LINE and SPLINE edges, False for only LWPOLYLINE paths as boundary paths
distance – 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

ezdxf.path.to_lines(paths: Iterable[ezdxf.path.path.Path], *, distance: float = 0.01, segments: int = 4, dxfattribs=None) → Iterator[ezdxf.entities.line.Line]¶

Convert the given paths into Line entities.

Parameters:	paths – iterable of `Path` objects distance – maximum distance, see `Path.flattening()` segments – minimum segment count per Bézier curve dxfattribs – additional DXF attribs
Returns:	iterable of `Line` objects

ezdxf.path.to_lwpolylines(paths: Iterable[ezdxf.path.path.Path], *, distance: float = 0.01, segments: int = 4, extrusion: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[ezdxf.entities.lwpolyline.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` objects distance – 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

ezdxf.path.to_mpolygons(paths: Iterable[ezdxf.path.path.Path], *, distance: float = 0.01, segments: int = 4, extrusion: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[ezdxf.entities.mpolygon.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` objects distance – 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

ezdxf.path.to_polylines2d(paths: Iterable[ezdxf.path.path.Path], *, distance: float = 0.01, segments: int = 4, extrusion: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[ezdxf.entities.polyline.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` objects distance – 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

ezdxf.path.to_polylines3d(paths: Iterable[ezdxf.path.path.Path], *, distance: float = 0.01, segments: int = 4, dxfattribs=None) → Iterator[ezdxf.entities.polyline.Polyline]¶

Convert the given paths into 3D Polyline entities.

Parameters:	paths – iterable of `Path` objects distance – maximum distance, see `Path.flattening()` segments – minimum segment count per Bézier curve dxfattribs – additional DXF attribs
Returns:	iterable of 3D `Polyline` objects

ezdxf.path.to_splines_and_polylines(paths: Iterable[ezdxf.path.path.Path], *, g1_tol: float = 0.0001, dxfattribs=None) → Iterator[Union[ezdxf.entities.spline.Spline, ezdxf.entities.polyline.Polyline]]¶

Convert the given paths into Spline and 3D Polyline entities.

Parameters:	paths – iterable of `Path` objects g1_tol – tolerance for G1 continuity check dxfattribs – additional DXF attribs
Returns:	iterable of `Line` objects

Tool Maker¶

Functions to create construction tools.

ezdxf.path.to_bsplines_and_vertices(path: ezdxf.path.path.Path, g1_tol: float = 0.0001) → Iterator[Union[ezdxf.math.bspline.BSpline, List[ezdxf.math._vector.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` objects g1_tol – tolerance for G1 continuity check
Returns:	`BSpline` and lists of `Vec3`

ezdxf.path.to_matplotlib_path(paths: Iterable[ezdxf.path.path.Path], extrusion: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = Vec3(0.0, 0.0, 1.0))¶

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 Matplotlib Path is a 2D object with OCS coordinates and the z-elevation is lost. (requires Matplotlib)

Parameters:	paths – iterable of `Path` objects extrusion – extrusion vector for all paths
Returns:	matplotlib Path in OCS!

ezdxf.path.to_qpainter_path(paths: Iterable[ezdxf.path.path.Path], extrusion: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = Vec3(0.0, 0.0, 1.0))¶

Convert the given paths into a 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. The QPainterPath is a 2D object with OCS coordinates and the z-elevation is lost. (requires Qt bindings)

Parameters:	paths – iterable of `Path` objects extrusion – extrusion vector for all paths
Returns:	QPainterPath in OCS!

Utility Functions¶

ezdxf.path.add_bezier3p(path: ezdxf.path.path.Path, curves: Iterable[ezdxf.math._bezier3p.Bezier3P]) → None¶

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.

ezdxf.path.add_bezier4p(path: ezdxf.path.path.Path, curves: Iterable[ezdxf.math._bezier4p.Bezier4P]) → None¶

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.

ezdxf.path.add_ellipse(path: ezdxf.path.path.Path, ellipse: ezdxf.math.ellipse.ConstructionEllipse, segments=1, reset=True) → None¶

Add an elliptical arc as multiple cubic Bèzier-curves to the given path, use from_arc() constructor of class ConstructionEllipse 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` object ellipse – ellipse parameters as `ConstructionEllipse` object segments – 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: ezdxf.path.path.Path, spline: ezdxf.math.bspline.BSpline, level=4, reset=True) → None¶

Add a B-spline as multiple cubic Bèzier-curves.

Non-rational B-splines of 3rd degree gets a perfect conversion to cubic Bézier 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.

Parameters:	path – `Path` object spline – B-spline parameters as `BSpline` object level – subdivision level of approximation segments reset – set start point to start of spline if path is empty

ezdxf.path.bbox(paths: Iterable[ezdxf.path.path.Path], *, fast=False) → ezdxf.math.bbox.BoundingBox¶

Returns the BoundingBox for the given paths.

Parameters:	paths – iterable of `Path` objects fast – calculates the precise bounding box of Bèzier curves if `False`, otherwise uses the control points of Bézier curves to determine their bounding box.

ezdxf.path.chamfer(points: Sequence[ezdxf.math._vector.Vec3], length: float) → ezdxf.path.path.Path¶

Returns a Path with chamfers of given length between straight line segments.

Parameters:	points – coordinates of the line segments length – chamfer length

ezdxf.path.chamfer2(points: Sequence[ezdxf.math._vector.Vec3], a: float, b: float) → ezdxf.path.path.Path¶

Returns a Path with chamfers at the given distances a and b from the segment points between straight line segments.

Parameters:	points – coordinates of the line segments a – distance of the chamfer start point to the segment point b – distance of the chamfer end point to the segment point

ezdxf.path.fillet(points: Sequence[ezdxf.math._vector.Vec3], radius: float) → ezdxf.path.path.Path¶

Returns a Path with circular fillets of given radius between straight line segments.

Parameters:	points – coordinates of the line segments radius – fillet radius

ezdxf.path.fit_paths_into_box(paths: Iterable[Path], size: tuple[float, float, float], uniform: bool = True, source_box: Optional[BoundingBox] = None) → list[Path]¶

Scale the given paths to fit into a box of the given size, so that all path vertices are inside these 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` objects size – target box size as tuple of x-, y- and z-size values uniform – `True` for uniform scaling source_box – pass precalculated source bounding box, or `None` to calculate the default source bounding box from the control vertices

ezdxf.path.have_close_control_vertices(a: ezdxf.path.path.Path, b: ezdxf.path.path.Path, *, rel_tol=1e-09, abs_tol=1e-12) → bool¶: Returns True if the control vertices of given paths are close.

ezdxf.path.lines_to_curve3(path: ezdxf.path.path.Path) → ezdxf.path.path.Path¶: Replaces all lines by quadratic Bézier curves. Returns a new Path instance.

ezdxf.path.lines_to_curve4(path: ezdxf.path.path.Path) → ezdxf.path.path.Path¶: Replaces all lines by cubic Bézier curves. Returns a new Path instance.

ezdxf.path.polygonal_fillet(points: Sequence[ezdxf.math._vector.Vec3], radius: float, count: int = 32) → ezdxf.path.path.Path¶

Returns a Path with polygonal fillets of given radius between straight line segments. The count argument defines the vertex count of the fillet for a full circle.

Parameters:	points – coordinates of the line segments radius – fillet radius count – polygon vertex count for a full circle, minimum is 4

ezdxf.path.single_paths(paths: Iterable[ezdxf.path.path.Path]) → Iterable[ezdxf.path.path.Path]¶: Yields all given paths and their sub-paths as single path objects.

ezdxf.path.to_multi_path(paths: Iterable[ezdxf.path.path.Path]) → ezdxf.path.path.Path¶: Returns a multi-path object from all given paths and their sub-paths. Ignores paths without any commands (empty paths).

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 transformed Path objects.

Parameters:	paths – iterable of `Path` objects m – transformation matrix of type `Matrix44`

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 transformed Path objects.

Parameters:	paths – iterable of `Path` objects ocs – OCS transformation of type `OCS`

ezdxf.path.triangulate(paths: Iterable[ezdxf.path.path.Path], max_sagitta: float = 0.01, min_segments: int = 16) → Iterator[Sequence[ezdxf.math._vector.Vec2]]¶

Tessellate nested 2D paths into triangle-faces. For 3D paths the projection onto the xy-plane will be triangulated.

Parameters:	paths – iterable of nested Path instances max_sagitta – 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. min_segments – minimum segment count per Bézier curve

Basic Shapes¶

ezdxf.path.elliptic_transformation(center: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = (0, 0, 0), radius: float = 1, ratio: float = 1, rotation: float = 0) → ezdxf.math._matrix44.Matrix44¶

Returns the transformation matrix to transform a unit circle into an arbitrary circular- or elliptic arc.

Example how to create an ellipse with a 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.gear(count: int, top_width: float, bottom_width: float, height: float, outside_radius: float, transform: Optional[ezdxf.math._matrix44.Matrix44] = None) → ezdxf.path.path.Path¶

Returns a gear (cogwheel) shape as a Path object, with the center at (0, 0, 0). The base geometry is created by function ezdxf.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

ezdxf.path.helix(radius: float, pitch: float, turns: float, ccw=True, segments: int = 4) → ezdxf.path.path.Path¶

Returns a helix as a Path object. The center of the helix is always (0, 0, 0), a positive pitch value creates a helix along the +z-axis, a negative value along the -z-axis.

Parameters:	radius – helix radius pitch – the height of one complete helix turn turns – count of turns ccw – creates a counter-clockwise turning (right-handed) helix if `True` segments – cubic Bezier segments per turn

ezdxf.path.ngon(count: int, length: Optional[float] = None, radius: float = 1.0, transform: Optional[ezdxf.math._matrix44.Matrix44] = None) → ezdxf.path.path.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 function ezdxf.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.rect(width: float = 1, height: float = 1, transform: Optional[ezdxf.math._matrix44.Matrix44] = None) → ezdxf.path.path.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.star(count: int, r1: float, r2: float, transform: Optional[ezdxf.math._matrix44.Matrix44] = None) → ezdxf.path.path.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.unit_circle(start_angle: float = 0, end_angle: float = 6.283185307179586, segments: int = 1, transform: Optional[ezdxf.math._matrix44.Matrix44] = None) → ezdxf.path.path.Path¶

Returns a 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: Optional[ezdxf.math._matrix44.Matrix44] = None) → ezdxf.path.path.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

The text2path add-on provides additional functions to create paths from text strings and DXF text entities.

The Path Class¶

class ezdxf.path.Path¶

append_path(path: ezdxf.path.path.Path) → None¶: Append another path to this path. Adds a self.line_to(path.start) if the end of this path != the start of appended path.

approximate(segments: int = 20) → Iterator[ezdxf.math._vector.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.

clockwise() → ezdxf.path.path.Path¶

Returns new Path in clockwise orientation.

Raises:	`TypeError` – can’t detect orientation of a Multi-Path object

clone() → ezdxf.path.path.Path¶: Returns a new copy of Path with shared immutable data.

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.

control_vertices() → list[Vec3]¶: Yields all path control vertices in consecutive order.

counter_clockwise() → ezdxf.path.path.Path¶

Returns new Path in counter-clockwise orientation.

Raises:	`TypeError` – can’t detect orientation of a Multi-Path object

curve3_to(location: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3], ctrl: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]) → None¶: 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: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3], ctrl1: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3], ctrl2: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]) → None¶: 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.

extend_multi_path(path: ezdxf.path.path.Path) → None¶: 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).

flattening(distance: float, segments: int = 16) → Iterator[ezdxf.math._vector.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

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: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]) → None¶: Add a line from actual path end point to location.

move_to(location: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]) → None¶

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.

reversed() → ezdxf.path.path.Path¶: Returns a new Path with reversed segments and control vertices.

sub_paths() → Iterator[ezdxf.path.path.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.

transform(m: ezdxf.math._matrix44.Matrix44) → ezdxf.path.path.Path¶

Returns a new transformed path.

Parameters:	m – transformation matrix of type `Matrix44`