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.

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() 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, 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) → Iterator[Path]

Yield all HATCH boundary paths as separated Path objects.

New in version 0.16.

Changed in version 17.1: Attaches the boundary state to each path as ezdxf.lldxf.const.BoundaryPathState.

ezdxf.path.from_vertices(vertices: Iterable[Union[Sequence[float], Vec2, Vec3]], close=False) → Path

Returns a Path object from the given vertices.

ezdxf.path.from_matplotlib_path(mpath, curves=True) → Iterator[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) → Iterator[Path]

Yields multiple Path objects from a QPainterPath. (requires Qt bindings)

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 Qt bindings)

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_hatches(layout: Layout, 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

New in version 0.16.

ezdxf.path.render_lines(layout: Layout, 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

New in version 0.16.

ezdxf.path.render_lwpolylines(layout: Layout, 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

New in version 0.16.

ezdxf.path.render_mpolygons(layout: Layout, 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

New in version 0.17.

ezdxf.path.render_polylines2d(layout: Layout, 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

New in version 0.16.

ezdxf.path.render_polylines3d(layout: Layout, 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

New in version 0.16.

ezdxf.path.render_splines_and_polylines(layout: Layout, 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

New in version 0.16.

Entity Maker

Functions to create DXF entities from paths.

ezdxf.path.to_hatches(paths: Iterable[Path], *, edge_path: bool = True, distance: float = 0.01, segments: int = 4, g1_tol: float = 0.0001, extrusion: Union[Sequence[float], Vec2, Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[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

New in version 0.16.

ezdxf.path.to_lines(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs=None) → Iterator[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_lwpolylines(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Union[Sequence[float], Vec2, Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[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_mpolygons(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Union[Sequence[float], Vec2, Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[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

New in version 0.17.

ezdxf.path.to_polylines2d(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, extrusion: Union[Sequence[float], Vec2, Vec3] = Vec3(0.0, 0.0, 1.0), dxfattribs=None) → Iterator[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_polylines3d(paths: Iterable[Path], *, distance: float = 0.01, segments: int = 4, dxfattribs=None) → Iterator[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_splines_and_polylines(paths: Iterable[Path], *, g1_tol: float = 0.0001, dxfattribs=None) → Iterator[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 = 0.0001) → Iterator[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 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: Union[Sequence[float], Vec2, 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!

New in version 0.16.

ezdxf.path.to_qpainter_path(paths: Iterable[Path], extrusion: Union[Sequence[float], Vec2, 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!

New in version 0.16.

Utility Functions

ezdxf.path.add_bezier3p(path: Path, curves: Iterable[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.

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]) → 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.

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, 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: Path, spline: 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 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

  • 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[Path], *, fast=False) → 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.

Changed in version 0.18: Uses a new algorithm to determine exact Bézier curve bounding boxes. Added argument fast and removed the arguments flatten and segments.

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

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

Parameters

  • points – coordinates of the line segments

  • length – chamfer length

New in version 0.18.

ezdxf.path.chamfer2(points: Sequence[Vec3], a: float, b: float) → 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

New in version 0.18.

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

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

Parameters

  • points – coordinates of the line segments

  • radius – fillet radius

New in version 0.18.

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: Path, b: Path, *, rel_tol=1e-09, abs_tol=1e-12) → bool

Returns True if the control vertices of given paths are close.

New in version 0.16.5.

ezdxf.path.lines_to_curve3(path: Path) → Path

Replaces all lines by quadratic Bézier curves. Returns a new Path instance.

ezdxf.path.lines_to_curve4(path: Path) → Path

Replaces all lines by cubic Bézier curves. Returns a new Path instance.

ezdxf.path.polygonal_fillet(points: Sequence[Vec3], radius: float, count: int = 32) → 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

New in version 0.18.

ezdxf.path.single_paths(paths: Iterable[Path]) → Iterable[Path]

Yields all given paths and their sub-paths as single path objects.

New in version 0.17.

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.

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[Path], max_flattening_distance: float = 0.01) → Iterator[Sequence[Vec2]]

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

New in version 0.18.1.

Basic Shapes

ezdxf.path.elliptic_transformation(center: Union[Sequence[float], Vec2, Vec3] = (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.gear(count: int, top_width: float, bottom_width: float, height: float, outside_radius: float, transform: Optional[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

ezdxf.path.helix(radius: float, pitch: float, turns: float, ccw=True, segments: int = 4) → 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

New in version 0.18.

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

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 end: ezdxf.math._vector.Vec3

Path end point.

property has_curves: bool

Returns True if the path has any curve segments.

property has_lines: bool

Returns True if the path has any line 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.

property is_closed: bool

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

property start: ezdxf.math._vector.Vec3

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

property user_data: Any

Attach arbitrary user data to a Path object. The user data is copied by reference, no deep copy is applied therefore a mutable state is shared between copies.

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

New in version 0.17.

approximate(segments: int = 20) → Iterator[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() → Path

Returns new Path in clockwise orientation.

Raises

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

clone() → 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.

New in version 0.17.

control_vertices() → List[Vec3]

Yields all path control vertices in consecutive order.

counter_clockwise() → 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], Vec2, Vec3], ctrl: Union[Sequence[float], Vec2, 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], Vec2, Vec3], ctrl1: Union[Sequence[float], Vec2, Vec3], ctrl2: Union[Sequence[float], Vec2, 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: 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).

New in version 0.17.

flattening(distance: float, segments: int = 16) → Iterator[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], Vec2, Vec3]) → None

Add a line from actual path end point to location.

move_to(location: Union[Sequence[float], Vec2, 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.

New in version 0.17.

reversed() → Path

Returns a new Path with reversed segments and control vertices.

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

transform(m: Matrix44) → Path

Returns a new transformed path.

Parameters

m – transformation matrix of type Matrix44