Hatch¶
The HATCH entity (DXF Reference) fills a closed area defined by one or more boundary paths by a hatch pattern, a solid fill, or a gradient fill.
All points in OCS as (x, y) tuples (Hatch.dxf.elevation
is the
zaxis value).
There are two different hatch pattern default scaling, depending on the HEADER variable $MEASUREMENT, one for ISO measurement (m, cm, mm, …) and one for imperial measurement (in, ft, yd, …).
The default scaling for predefined hatch pattern will be chosen according this measurement setting in the HEADER section, this replicates the behavior of BricsCAD and other CAD applications. Ezdxf uses the ISO pattern definitions as a base line and scales this pattern down by factor 1/25.6 for imperial measurement usage. The pattern scaling is independent from the drawing units of the document defined by the HEADER variable $INSUNITS.
See also
Subclass of  ezdxf.entities.DXFGraphic 
DXF type  'HATCH' 
Factory function  ezdxf.layouts.BaseLayout.add_hatch() 
Inherited DXF attributes  Common graphical DXF attributes 
Required DXF version  DXF R2000 ('AC1015' ) 
Boundary paths classes
Path manager: BoundaryPaths
Pattern and gradient classes
Pattern
PatternLine
Gradien

class
ezdxf.entities.
Hatch
¶ 
dxf.
pattern_name
¶ Pattern name as string

dxf.
solid_fill
¶ 1 solid fill, use method Hatch.set_solid_fill()
0 pattern fill, use method Hatch.set_pattern_fill()

dxf.
associative
¶ 1 associative hatch 0 not associative hatch Associations are not managed by ezdxf.

dxf.
hatch_style
¶ 0 normal 1 outer 2 ignore (search AutoCAD help for more information)

dxf.
pattern_type
¶ 0 user 1 predefined 2 custom

dxf.
pattern_angle
¶ The actual pattern rotation angle in degrees (float). Changing this value does not rotate the pattern, use
set_pattern_angle()
for this task.

dxf.
pattern_scale
¶ The actual pattern scale factor (float). Changing this value does not scale the pattern use
set_pattern_scale()
for this task.

dxf.
pattern_double
¶ 1 = double pattern size else 0. (int)

dxf.
n_seed_points
¶ Count of seed points (use
get_seed_points()
)

paths
¶ BoundaryPaths
object.

seeds
¶ A list of seed points as (x, y) tuples.

set_pattern_definition
(lines: Sequence[T_co], factor: float = 1, angle: float = 0) → None¶ Setup pattern definition by a list of definition lines and the definition line is a 4tuple (angle, base_point, offset, dash_length_items). The pattern definition should be designed for a pattern scale factor of 1 and a pattern rotation angle of 0.
 angle: line angle in degrees
 basepoint: (x, y) tuple
 offset: (dx, dy) tuple
 dash_length_items: list of dash items (item > 0 is a line, item < 0 is a gap and item == 0.0 is a point)
Parameters:  lines – list of definition lines
 factor – pattern scale factor
 angle – rotation angle in degrees

set_pattern_scale
(scale: float) → None¶ Sets the pattern scale factor and scales the pattern definition.
The method always starts from the original base scale, the
set_pattern_scale(1)
call resets the pattern scale to the original appearance as defined by the pattern designer, but only if the pattern attributedxf.pattern_scale
represents the actual scale, it cannot restore the original pattern scale from the pattern definition itself.Parameters: scale – pattern scale factor

set_pattern_angle
(angle: float) → None¶ Sets the pattern rotation angle and rotates the pattern definition.
The method always starts from the original base rotation of 0, the
set_pattern_angle(0)
call resets the pattern rotation angle to the original appearance as defined by the pattern designer, but only if the pattern attributedxf.pattern_angle
represents the actual pattern rotation, it cannot restore the original rotation angle from the pattern definition itself.Parameters: angle – pattern rotation angle in degrees

set_solid_fill
(color: int = 7, style: int = 1, rgb: Optional[RGB] = None)¶ Set the solid fill mode and removes all gradient and pattern fill related data.
Parameters:  color – AutoCAD Color Index (ACI), (0 = BYBLOCK; 256 = BYLAYER)
 style – hatch style (0 = normal; 1 = outer; 2 = ignore)
 rgb – true color value as (r, g, b)tuple  has higher priority than color. True color support requires DXF R2000.

set_pattern_fill
(name: str, color: int = 7, angle: float = 0.0, scale: float = 1.0, double: int = 0, style: int = 1, pattern_type: int = 1, definition=None) → None¶ Sets the pattern fill mode and removes all gradient related data.
The pattern definition should be designed for a scale factor 1 and a rotation angle of 0 degrees. The predefined hatch pattern like “ANSI33” are scaled according to the HEADER variable $MEASUREMENT for ISO measurement (m, cm, … ), or imperial units (in, ft, …), this replicates the behavior of BricsCAD.
Parameters:  name – pattern name as string
 color – pattern color as AutoCAD Color Index (ACI)
 angle – pattern rotation angle in degrees
 scale – pattern scale factor
 double – double size flag
 style – hatch style (0 = normal; 1 = outer; 2 = ignore)
 pattern_type – pattern type (0 = userdefined; 1 = predefined; 2 = custom)
 definition – list of definition lines and a definition line is a
4tuple [angle, base_point, offset, dash_length_items],
see
set_pattern_definition()

set_gradient
(color1: Tuple[int, int, int] = (0, 0, 0), color2: Tuple[int, int, int] = (255, 255, 255), rotation: float = 0.0, centered: float = 0.0, one_color: int = 0, tint: float = 0.0, name: str = 'LINEAR') → None¶ Sets the gradient fill mode and removes all pattern fill related data, requires DXF R2004 or newer. A gradient filled hatch is also a solid filled hatch.
Valid gradient type names are:
 “LINEAR”
 “CYLINDER”
 “INVCYLINDER”
 “SPHERICAL”
 “INVSPHERICAL”
 “HEMISPHERICAL”
 “INVHEMISPHERICAL”
 “CURVED”
 “INVCURVED”
Parameters:  color1 – (r, g, b)tuple for first color, rgb values as int in the range [0, 255]
 color2 – (r, g, b)tuple for second color, rgb values as int in the range [0, 255]
 rotation – rotation angle in degrees
 centered – determines whether the gradient is centered or not
 one_color – 1 for gradient from color1 to tinted color1
 tint – determines the tinted target color1 for a one color gradient. (valid range 0.0 to 1.0)
 name – name of gradient type, default “LINEAR”

set_seed_points
(points: Iterable[tuple[float, float]]) → None¶ Set seed points, points is an iterable of (x, y)tuples. I don’t know why there can be more than one seed point. All points in OCS (
Hatch.dxf.elevation
is the Z value)

transform
(m: Matrix44) → Hatch¶ Transform entity by transformation matrix m inplace.

associate
(path: AbstractBoundaryPath, entities: Iterable[DXFEntity])¶ Set association from hatch boundary path to DXF geometry entities.
A HATCH entity can be associative to a base geometry, this association is not maintained nor verified by ezdxf, so if you modify the base geometry the geometry of the boundary path is not updated and no verification is done to check if the associated geometry matches the boundary path, this opens many possibilities to create invalid DXF files: USE WITH CARE!

remove_association
()¶ Remove associated path elements.

Boundary Paths¶
The hatch entity is build by different path types, these are the
filter flags for the Hatch.dxf.hatch_style
:
 EXTERNAL: defines the outer boundary of the hatch
 OUTERMOST: defines the first tier of inner hatch boundaries
 DEFAULT: default boundary path
As you will learn in the next sections, these are more the recommended usage type for the flags, but the fill algorithm doesn’t care much about that, for instance an OUTERMOST path doesn’t have to be inside the EXTERNAL path.
Island Detection¶
In general the island detection algorithm works always from outside to inside
and alternates filled and unfilled areas. The area between then 1st and the 2nd
boundary is filled, the area between the 2nd and the 3rd boundary is unfilled
and so on. The different hatch styles defined by the Hatch.dxf.hatch_style
attribute are created by filtering some boundary path types.
Hatch Style¶
 HATCH_STYLE_IGNORE: Ignores all paths except the paths marked as EXTERNAL, if there are more than one path marked as EXTERNAL, they are filled in NESTED style. Creates no hatch if no path is marked as EXTERNAL.
 HATCH_STYLE_OUTERMOST: Ignores all paths marked as DEFAULT, remaining EXTERNAL and OUTERMOST paths are filled in NESTED style. Creates no hatch if no path is marked as EXTERNAL or OUTERMOST.
 HATCH_STYLE_NESTED: Use all existing paths.
Hatch Boundary Classes¶

class
ezdxf.entities.
BoundaryPaths
¶ Defines the borders of the hatch, a hatch can consist of more than one path.

paths
¶ List of all boundary paths. Contains
PolylinePath
andEdgePath
objects. (read/write)

external_paths
() → Iterable[ezdxf.entities.boundary_paths.AbstractBoundaryPath]¶ Iterable of external paths, could be empty.

outermost_paths
() → Iterable[ezdxf.entities.boundary_paths.AbstractBoundaryPath]¶ Iterable of outermost paths, could be empty.

default_paths
() → Iterable[ezdxf.entities.boundary_paths.AbstractBoundaryPath]¶ Iterable of default paths, could be empty.

rendering_paths
(hatch_style: int = 0) → Iterable[ezdxf.entities.boundary_paths.AbstractBoundaryPath]¶ Iterable of paths to process for rendering, filters unused boundary paths according to the given hatch style:
 NESTED: use all boundary paths
 OUTERMOST: use EXTERNAL and OUTERMOST boundary paths
 IGNORE: ignore all paths except EXTERNAL boundary paths
Yields paths in order of EXTERNAL, OUTERMOST and DEFAULT.

add_polyline_path
(path_vertices: Iterable[tuple[float, ...]], is_closed: bool = True, flags: int = 1) → PolylinePath¶ Create and add a new
PolylinePath
object.Parameters:  path_vertices – iterable of polyline vertices as (x, y) or (x, y, bulge)tuples.
 is_closed – 1 for a closed polyline else 0
 flags – external(1) or outermost(16) or default (0)

add_edge_path
(flags: int = 1) → ezdxf.entities.boundary_paths.EdgePath¶ Create and add a new
EdgePath
object.Parameters: flags – external(1) or outermost(16) or default (0)

polyline_to_edge_paths
(just_with_bulge=True) → None¶ Convert polyline paths including bulge values to line and arc edges.
Parameters: just_with_bulge – convert only polyline paths including bulge values if True

edge_to_polyline_paths
(distance: float, segments: int = 16)¶ Convert all edge paths to simple polyline paths without bulges.
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 curve

arc_edges_to_ellipse_edges
() → None¶ Convert all arc edges to ellipse edges.

ellipse_edges_to_spline_edges
(num: int = 32) → None¶ Convert all ellipse edges to spline edges (approximation).
Parameters: num – count of control points for a full ellipse, partial ellipses have proportional fewer control points but at least 3.

spline_edges_to_line_edges
(factor: int = 8) → None¶ Convert all spline edges to line edges (approximation).
Parameters: factor – count of approximation segments = count of control points x factor

all_to_spline_edges
(num: int = 64) → None¶ Convert all bulge, arc and ellipse edges to spline edges (approximation).
Parameters: num – count of control points for a full circle/ellipse, partial circles/ellipses have proportional fewer control points but at least 3.

all_to_line_edges
(num: int = 64, spline_factor: int = 8) → None¶ Convert all bulge, arc and ellipse edges to spline edges and approximate this splines by line edges.
Parameters:  num – count of control points for a full circle/ellipse, partial circles/ellipses have proportional fewer control points but at least 3.
 spline_factor – count of spline approximation segments = count of control points x spline_factor

clear
() → None¶ Remove all boundary paths.


class
ezdxf.entities.
PolylinePath
¶ A polyline as hatch boundary path.

type
¶ Path type as
BoundaryPathType.POLYLINE
enum

path_type_flags
¶ (bit coded flags)
0 default 1 external 2 polyline, will be set by ezdxf 16 outermost My interpretation of the
path_type_flags
, see also Tutorial for Hatch: external: path is part of the hatch outer border
 outermost: path is completely inside of one or more external paths
 default: path is completely inside of one or more outermost paths
If there are troubles with AutoCAD, maybe the hatch entity has the
Hatch.dxf.pixel_size
attribute set  delete itdel hatch.dxf.pixel_size
and maybe the problem is solved. Ezdxf does not use theHatch.dxf.pixel_size
attribute, but it can occur in DXF files created by other applications.

is_closed
¶ True
if polyline path is closed.

vertices
¶ List of path vertices as (x, y, bulge)tuples. (read/write)

source_boundary_objects
¶ List of handles of the associated DXF entities for associative hatches. There is no support for associative hatches by ezdxf, you have to do it all by yourself. (read/write)

set_vertices
(vertices: Iterable[Sequence[float]], is_closed: bool = True) → None¶ Set new vertices as new polyline path, a vertex has to be a (x, y) or a (x, y, bulge)tuple.

clear
() → None¶ Removes all vertices and all handles to associated DXF objects (
source_boundary_objects
).


class
ezdxf.entities.
EdgePath
¶ Boundary path build by edges. There are four different edge types:
LineEdge
,ArcEdge
,EllipseEdge
ofSplineEdge
. Make sure there are no gaps between edges and the edge path must be closed to be recognized as path. AutoCAD is very picky in this regard. Ezdxf performs no checks on gaps between the edges and does not prevent creating open loops.Note
ArcEdge
andEllipseEdge
are ALWAYS represented in counterclockwise orientation, even if an clockwise oriented edge is required to build a closed loop. To add a clockwise oriented curve swap start and end angles and set the ccw flag to False and ezdxf will export a correct clockwise orientated curve.
type
¶ Path type as
BoundaryPathType.EDGE
enum

path_type_flags
¶ (bit coded flags)
0 default 1 external 16 outermost

edges
¶ List of boundary edges of type
LineEdge
,ArcEdge
,EllipseEdge
ofSplineEdge

source_boundary_objects
¶ Required for associative hatches, list of handles to the associated DXF entities.

clear
() → None¶ Delete all edges.

add_line
(start: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3], end: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]) → LineEdge¶ Add a
LineEdge
from start to end.Parameters:  start – start point of line, (x, y)tuple
 end – end point of line, (x, y)tuple

add_arc
(center: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3], radius: float = 1.0, start_angle: float = 0.0, end_angle: float = 360.0, ccw: bool = True) → ArcEdge¶ Add an
ArcEdge
.Adding Clockwise Oriented Arcs:
Clockwise oriented
ArcEdge
objects are sometimes necessary to build closed loops, but theArcEdge
objects are always represented in counterclockwise orientation. To add a clockwise orientedArcEdge
you have to swap the start and end angle and set the ccw flag toFalse
, e.g. to add a clockwise orientedArcEdge
from 180 to 90 degree, add theArcEdge
in counterclockwise orientation with swapped angles:edge_path.add_arc(center, radius, start_angle=90, end_angle=180, ccw=False)
Parameters:  center – center point of arc, (x, y)tuple
 radius – radius of circle
 start_angle – start angle of arc in degrees (end_angle for a clockwise oriented arc)
 end_angle – end angle of arc in degrees (start_angle for a clockwise oriented arc)
 ccw –
True
for counter clockwiseFalse
for clockwise orientation

add_ellipse
(center: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3], major_axis: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = (1.0, 0.0), ratio: float = 1.0, start_angle: float = 0.0, end_angle: float = 360.0, ccw: bool = True) → ezdxf.entities.boundary_paths.EllipseEdge¶ Add an
EllipseEdge
.Adding Clockwise Oriented Ellipses:
Clockwise oriented
EllipseEdge
objects are sometimes necessary to build closed loops, but theEllipseEdge
objects are always represented in counterclockwise orientation. To add a clockwise orientedEllipseEdge
you have to swap the start and end angle and set the ccw flag toFalse
, e.g. to add a clockwise orientedEllipseEdge
from 180 to 90 degree, add theEllipseEdge
in counterclockwise orientation with swapped angles:edge_path.add_ellipse(center, major_axis, ratio, start_angle=90, end_angle=180, ccw=False)
Parameters:  center – center point of ellipse, (x, y)tuple
 major_axis – vector of major axis as (x, y)tuple
 ratio – ratio of minor axis to major axis as float
 start_angle – start angle of ellipse in degrees (end_angle for a clockwise oriented ellipse)
 end_angle – end angle of ellipse in degrees (start_angle for a clockwise oriented ellipse)
 ccw –
True
for counter clockwiseFalse
for clockwise orientation

add_spline
(fit_points: Optional[Iterable[Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]]] = None, control_points: Optional[Iterable[Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3]]] = None, knot_values: Optional[Iterable[float]] = None, weights: Optional[Iterable[float]] = None, degree: int = 3, periodic: int = 0, start_tangent: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3, None] = None, end_tangent: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3, None] = None) → ezdxf.entities.boundary_paths.SplineEdge¶ Add a
SplineEdge
.Parameters:  fit_points – points through which the spline must go, at least 3 fit points are required. list of (x, y)tuples
 control_points – affects the shape of the spline, mandatory and AutoCAD crashes on invalid data. list of (x, y)tuples
 knot_values – (knot vector) mandatory and AutoCAD crashes on invalid
data. list of floats; ezdxf provides two tool functions to
calculate valid knot values:
ezdxf.math.uniform_knot_vector()
,ezdxf.math.open_uniform_knot_vector()
(default ifNone
)  weights – weight of control point, not mandatory, list of floats.
 degree – degree of spline (int)
 periodic – 1 for periodic spline, 0 for none periodic spline
 start_tangent – start_tangent as 2d vector, optional
 end_tangent – end_tangent as 2d vector, optional
Warning
Unlike for the spline entity AutoCAD does not calculate the necessary knot_values for the spline edge itself. On the contrary, if the knot_values in the spline edge are missing or invalid AutoCAD crashes.


class
ezdxf.entities.
LineEdge
¶ Straight boundary edge.

type
¶ Edge type as
EdgeType.LINE
enum

start
¶ Start point as (x, y)tuple. (read/write)

end
¶ End point as (x, y)tuple. (read/write)


class
ezdxf.entities.
ArcEdge
¶ Arc as boundary edge in counterclockwise orientation, see
EdgePath.add_arc()
.
type
¶ Edge type as
EdgeType.ARC
enum

center
¶ Center point of arc as (x, y)tuple. (read/write)

radius
¶ Arc radius as float. (read/write)

start_angle
¶ Arc start angle in counterclockwise orientation in degrees. (read/write)

end_angle
¶ Arc end angle in counterclockwise orientation in degrees. (read/write)

ccw
¶ True
for counter clockwise arc elseFalse
. (read/write)


class
ezdxf.entities.
EllipseEdge
¶ Elliptic arc as boundary edge in counterclockwise orientation, see
EdgePath.add_ellipse()
.
type
¶ Edge type as
EdgeType.ELLIPSE
enum

major_axis_vector
¶ Ellipse major axis vector as (x, y)tuple. (read/write)

minor_axis_length
¶ Ellipse minor axis length as float. (read/write)

radius
¶ Ellipse radius as float. (read/write)

start_angle
¶ Ellipse start angle in counterclockwise orientation in degrees. (read/write)

end_angle
¶ Ellipse end angle in counterclockwise orientation in degrees. (read/write)

ccw
¶ True
for counter clockwise ellipse elseFalse
. (read/write)


class
ezdxf.entities.
SplineEdge
¶ Spline as boundary edge.

type
¶ Edge type as
EdgeType.SPLINE
enum

degree
¶ Spline degree as int. (read/write)

rational
¶ 1 for rational spline else 0. (read/write)

periodic
¶ 1 for periodic spline else 0. (read/write)

knot_values
¶ List of knot values as floats. (read/write)

control_points
¶ List of control points as (x, y)tuples. (read/write)

fit_points
¶ List of fit points as (x, y)tuples. (read/write)

weights
¶ List of weights (of control points) as floats. (read/write)

start_tangent
¶ Spline start tangent (vector) as (x, y)tuple. (read/write)

end_tangent
¶ Spline end tangent (vector) as (x, y)tuple. (read/write)

Hatch Pattern Definition Classes¶

class
ezdxf.entities.
Pattern
¶ 
lines
¶ List of pattern definition lines (read/write). see
PatternLine

add_line
(angle: float = 0, base_point: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = (0, 0), offset: Union[Sequence[float], ezdxf.math._vector.Vec2, ezdxf.math._vector.Vec3] = (0, 0), dash_length_items: Optional[Iterable[float]] = None) → None¶ Create a new pattern definition line and add the line to the
Pattern.lines
attribute.

clear
() → None¶ Delete all pattern definition lines.

scale
(factor: float = 1, angle: float = 0) → None¶ Scale and rotate pattern.
Be careful, this changes the base pattern definition, maybe better use
Hatch.set_pattern_scale()
orHatch.set_pattern_angle()
.Parameters:  factor – scaling factor
 angle – rotation angle in degrees


class
ezdxf.entities.
PatternLine
¶ Represents a pattern definition line, use factory function
Pattern.add_line()
to create new pattern definition lines.
angle
¶ Line angle in degrees. (read/write)

base_point
¶ Base point as (x, y)tuple. (read/write)

offset
¶ Offset as (x, y)tuple. (read/write)

dash_length_items
¶ List of dash length items (item > 0 is line, < 0 is gap, 0.0 = dot). (read/write)

Hatch Gradient Fill Class¶

class
ezdxf.entities.
Gradient
¶ 
color1
¶ First rgb color as (r, g, b)tuple, rgb values in range 0 to 255. (read/write)

color2
¶ Second rgb color as (r, g, b)tuple, rgb values in range 0 to 255. (read/write)

one_color
¶ If
one_color
is 1  the hatch is filled with a smooth transition betweencolor1
and a specifiedtint
ofcolor1
. (read/write)

rotation
¶ Gradient rotation in degrees. (read/write)

centered
¶ Specifies a symmetrical gradient configuration. If this option is not selected, the gradient fill is shifted up and to the left, creating the illusion of a light source to the left of the object. (read/write)
