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!

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

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é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.

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

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

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 objects

  • edge_pathTrue 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 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 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

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

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

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

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

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 objects

  • edge_pathTrue 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

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

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 objects

  • distance – 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 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

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
  • pathPath objects

  • g1_tol – tolerance for G1 continuity check

Returns

BSpline and lists of Vec3

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

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

Parameters
  • paths – iterable of Path objects

  • extrusion – 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 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.bbox(paths: Iterable[Path]) → BoundingBox

Returns the BoundingBox for the given paths.

Parameters
  • paths – iterable of Path objects

  • flatten – 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 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- ond z-size values

  • uniformTrue 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.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.

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.

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 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
  • pathPath 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: 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.

Parameters
  • pathPath 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

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

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

The Path Class

class ezdxf.path.Path
start

Path start point, resetting the start point of an empty path is possible.

end

Path end point.

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 z-axis 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è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.

clone()Path

Returns a new copy of Path with shared immutable data.

reversed()Path

Returns a new Path with reversed segments and control vertices.

clockwise()Path

Returns new Path in clockwise orientation.

counter_clockwise()Path

Returns new Path in counter-clockwise orientation.

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