Hatching

This module provides rendering support for hatch patterns as used in Hatch and MPolygon entities.

High Level Functions

ezdxf.render.hatching.hatch_entity(polygon: DXFPolygon, filter_text_boxes=True, jiggle_origin: bool = True) → Iterator[tuple[Vec3, Vec3]]

Yields the hatch pattern of the given HATCH or MPOLYGON entity as 3D lines. Each line is a pair of Vec3 instances as start- and end vertex, points are represented as lines of zero length, which means the start vertex is equal to the end vertex.

The function yields nothing if polygon has a solid- or gradient filling or does not have a usable pattern assigned.

Parameters:

  • polygon – Hatch or MPolygon entity

  • filter_text_boxes – ignore text boxes if True

  • jiggle_origin – move pattern line origins a small amount to avoid intersections in corner points which causes errors in patterns

ezdxf.render.hatching.hatch_polygons(baseline: HatchBaseLine, polygons: Sequence[Sequence[Vec2]], terminate: Callable[[], bool] | None = None) → Iterator[Line]

Yields all pattern lines for all hatch lines generated by the given HatchBaseLine, intersecting the given 2D polygons as Line instances. The polygons should represent a single entity with or without holes, the order of the polygons and their winding orientation (cw or ccw) is not important. Entities which do not intersect or overlap should be handled separately!

Each polygon is a sequence of Vec2 instances, they are treated as closed polygons even if the last vertex is not equal to the first vertex.

The hole detection is done by a simple inside/outside counting algorithm and far from perfect, but is able to handle ordinary polygons well.

The terminate function WILL BE CALLED PERIODICALLY AND should return True to terminate execution. This can be used to implement a timeout, which can be required if using a very small hatching distance, especially if you get the data from untrusted sources.

Parameters:

  • baseline – HatchBaseLine

  • polygons – multiple sequences of Vec2 instances of a single entity, the order of exterior- and hole paths and the winding orientation (cw or ccw) of paths is not important

  • terminate – callback function which is called periodically and should return True to terminate the hatching function

ezdxf.render.hatching.hatch_paths(baseline: HatchBaseLine, paths: Sequence[Path], terminate: Callable[[], bool] | None = None) → Iterator[Line]

Yields all pattern lines for all hatch lines generated by the given HatchBaseLine, intersecting the given 2D Path instances as Line instances. The paths are handled as projected into the xy-plane the z-axis of path vertices will be ignored if present.

Same as the hatch_polygons() function, but for Path instances instead of polygons build of vertices. This function does not flatten the paths into vertices, instead the real intersections of the Bézier curves and the hatch lines are calculated.

For more information see the docs of the hatch_polygons() function.

Parameters:

  • baseline – HatchBaseLine

  • paths – sequence of Path instances of a single entity, the order of exterior- and hole paths and the winding orientation (cw or ccw) of the paths is not important

  • terminate – callback function which is called periodically and should return True to terminate the hatching function

Classes

class ezdxf.render.hatching.HatchBaseLine(origin: Vec2, direction: Vec2, offset: Vec2, line_pattern: list[float] | None = None, min_hatch_line_distance=MIN_HATCH_LINE_DISTANCE)

A hatch baseline defines the source line for hatching a geometry. A complete hatch pattern of a DXF entity can consist of one or more hatch baselines.

Parameters:

  • origin – the origin of the hatch line as Vec2 instance

  • direction – the hatch line direction as Vec2 instance, must not (0, 0)

  • offset – the offset of the hatch line origin to the next or to the previous hatch line

  • line_pattern – line pattern as sequence of floats, see also PatternRenderer

  • min_hatch_line_distance – minimum hatch line distance to render, raises an DenseHatchingLinesError exception if the distance between hatch lines is smaller than this value

Raises:
hatch_line(distance: float) → HatchLine

Returns the HatchLine at the given signed distance.

pattern_renderer(distance: float) → PatternRenderer

Returns the PatternRenderer for the given signed distance.

signed_distance(point: Vec2) → float

Returns the signed normal distance of the given point from this hatch baseline.

class ezdxf.render.hatching.HatchLine(origin: Vec2, direction: Vec2, distance: float)

Represents a single hatch line.

Parameters:

  • origin – the origin of the hatch line as Vec2 instance

  • direction – the hatch line direction as Vec2 instance, must not (0, 0)

  • distance – the normal distance to the base hatch line as float

intersect_line(a: Vec2, b: Vec2, dist_a: float, dist_b: float) → Intersection

Returns the Intersection of this hatch line and the line defined by the points a and b. The arguments dist_a and dist_b are the signed normal distances of the points a and b from the hatch baseline. The normal distances from the baseline are easy to calculate by the HatchBaseLine.signed_distance() method and allow a fast intersection calculation by a simple point interpolation.

Parameters:

  • a – start point of the line as Vec2 instance

  • b – end point of the line as Vec2 instance

  • dist_a – normal distance of point a to the hatch baseline as float

  • dist_b – normal distance of point b to the hatch baseline as float

intersect_cubic_bezier_curve(curve: Bezier4P) → Sequence[Intersection]

Returns 0 to 3 Intersection points of this hatch line with a cubic Bèzier curve.

Parameters:

curve – the cubic Bèzier curve as ezdxf.math.Bezier4P instance

class ezdxf.render.hatching.PatternRenderer(hatch_line: HatchLine, pattern: Sequence[float])

The hatch pattern of a DXF entity has one or more HatchBaseLine instances with an origin, direction, offset and line pattern. The PatternRenderer for a certain distance from the baseline has to be acquired from the HatchBaseLine by the pattern_renderer() method.

The origin of the hatch line is the starting point of the line pattern. The offset defines the origin of the adjacent hatch line and doesn’t have to be orthogonal to the hatch line direction.

Line Pattern

The line pattern is a sequence of floats, where a value > 0.0 is a dash, a value < 0.0 is a gap and value of 0.0 is a point.

Parameters:

  • hatch_line – HatchLine

  • pattern – the line pattern as sequence of float values

render(start: Vec2, end: Vec2) → Iterator[tuple[Vec2, Vec2]]

Yields the pattern lines as pairs of Vec2 instances from the start- to the end point on the hatch line. For points the start- and end point are the same Vec2 instance and can be tested by the is operator.

The start- and end points should be located collinear at the hatch line of this instance, otherwise the points a projected onto this hatch line.

class ezdxf.render.hatching.Intersection(type: IntersectionType = IntersectionType.NONE, p0: Vec2 = Vec2(nan, nan), p1: Vec2 = Vec2(nan, nan))

Represents an intersection.

type

intersection type as IntersectionType instance

p0

(first) intersection point as Vec2 instance

p1

second intersection point as Vec2 instance, only if type is COLLINEAR

class ezdxf.render.hatching.IntersectionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
NONE

no intersection

REGULAR

regular intersection point at a polygon edge or a Bèzier curve

START

intersection point at the start vertex of a polygon edge

END

intersection point at the end vertex of a polygon edge

COLLINEAR

intersection is collinear to a polygon edge

class ezdxf.render.hatching.Line(start: 'Vec2', end: 'Vec2', distance: 'float')
start

start point as Vec2 instance

end

end point as Vec2 instance

distance

signed normal distance to the HatchBaseLine

Helper Functions

ezdxf.render.hatching.hatch_boundary_paths(polygon: DXFPolygon, filter_text_boxes=True) → list[Path]

Returns the hatch boundary paths as ezdxf.path.Path instances of HATCH and MPOLYGON entities. Ignores text boxes if argument filter_text_boxes is True.

ezdxf.render.hatching.hatch_line_distances(point_distances: Sequence[float], normal_distance: float) → list[float]

Returns all hatch line distances in the range of the given point distances.

ezdxf.render.hatching.pattern_baselines(polygon: DXFPolygon, min_hatch_line_distance: float = MIN_HATCH_LINE_DISTANCE, *, jiggle_origin: bool = False) → Iterator[HatchBaseLine]

Yields the hatch pattern baselines of HATCH and MPOLYGON entities as HatchBaseLine instances. Set jiggle_origin to True to move pattern line origins a small amount to avoid intersections in corner points which causes errors in patterns.

Exceptions

class ezdxf.render.hatching.HatchingError

Base exception class of the hatching module.

class ezdxf.render.hatching.HatchLineDirectionError

Hatching direction is undefined or a (0, 0) vector.

class ezdxf.render.hatching.DenseHatchingLinesError

Very small hatching distance which creates too many hatching lines.