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.
- 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 asLine
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 importantterminate – 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 2DPath
instances asLine
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 forPath
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 importantterminate – 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
instancedirection – 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:
HatchLineDirectionError – hatch baseline has no direction, (0, 0) vector
DenseHatchingLinesError – hatching lines are too narrow
- pattern_renderer(distance: float) PatternRenderer ¶
Returns the
PatternRenderer
for the given signed distance.
- class ezdxf.render.hatching.HatchLine(origin: Vec2, direction: Vec2, distance: float)¶
Represents a single hatch line.
- Parameters:
- 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 theHatchBaseLine.signed_distance()
method and allow a fast intersection calculation by a simple point interpolation.
- 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. ThePatternRenderer
for a certain distance from the baseline has to be acquired from theHatchBaseLine
by thepattern_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 sameVec2
instance and can be tested by theis
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
- class ezdxf.render.hatching.IntersectionType(value, names=_not_given, *values, 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
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 isTrue
.
- 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 toTrue
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.