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

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

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

dxf.elevation

Z value represents the elevation height of the OCS. (float)

paths

BoundaryPaths object.

pattern

Pattern object.

gradient

Gradient object.

seeds

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

property has_solid_fill: bool

True if entity has a solid fill. (read only)

property has_pattern_fill: bool

True if entity has a pattern fill. (read only)

property has_gradient_data: bool

True if entity has a gradient fill. A hatch with gradient fill has also a solid fill. (read only)

property bgcolor: RGB | None

Set pattern fill background color as (r, g, b)-tuple, rgb values in the range [0, 255] (read/write/del)

usage:

r, g, b = entity.bgcolor  # get pattern fill background color
entity.bgcolor = (10, 20, 30)  # set pattern fill background color
del entity.bgcolor  # delete pattern fill background color
set_pattern_definition(lines: Sequence, factor: float = 1, angle: float = 0) None

Setup pattern definition by a list of definition lines and the definition line is a 4-tuple (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

  • base-point: (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 attribute dxf.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 attribute dxf.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: RGB | None = None)

Set the solid fill mode and removes all gradient and pattern fill related data.

Parameters:
  • colorAutoCAD 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 = user-defined; 1 = predefined; 2 = custom)

  • definition – list of definition lines and a definition line is a 4-tuple [angle, base_point, offset, dash_length_items], see set_pattern_definition()

set_gradient(color1: RGB = RGB(0, 0, 0), color2: RGB = RGB(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 and EdgePath objects. (read/write)

external_paths() Iterable[AbstractBoundaryPath]

Iterable of external paths, could be empty.

outermost_paths() Iterable[AbstractBoundaryPath]

Iterable of outermost paths, could be empty.

default_paths() Iterable[AbstractBoundaryPath]

Iterable of default paths, could be empty.

rendering_paths(hatch_style: int = const.HATCH_STYLE_NESTED) Iterable[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) 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.BoundaryPathType
POLYLINE

polyline path type

EDGE

edge path type

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 it del hatch.dxf.pixel_size and maybe the problem is solved. Ezdxf does not use the Hatch.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 of SplineEdge. 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 and EllipseEdge are ALWAYS represented in counter-clockwise 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

see PolylinePath.path_type_flags

edges

List of boundary edges of type LineEdge, ArcEdge, EllipseEdge of SplineEdge

source_boundary_objects

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

clear() None

Delete all edges.

add_line(start: UVec, end: UVec) 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: UVec, 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 the ArcEdge objects are always represented in counter-clockwise orientation. To add a clockwise oriented ArcEdge you have to swap the start- and end angle and set the ccw flag to False, e.g. to add a clockwise oriented ArcEdge from 180 to 90 degree, add the ArcEdge in counter-clockwise 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)

  • ccwTrue for counter-clockwise False for clockwise orientation

add_ellipse(center: UVec, major_axis: UVec = (1.0, 0.0), ratio: float = 1.0, start_angle: float = 0.0, end_angle: float = 360.0, ccw: bool = True) EllipseEdge

Add an EllipseEdge.

Adding Clockwise Oriented Ellipses:

Clockwise oriented EllipseEdge objects are sometimes necessary to build closed loops, but the EllipseEdge objects are always represented in counter-clockwise orientation. To add a clockwise oriented EllipseEdge you have to swap the start- and end angle and set the ccw flag to False, e.g. to add a clockwise oriented EllipseEdge from 180 to 90 degree, add the EllipseEdge in counter-clockwise 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)

  • ccwTrue for counter-clockwise False for clockwise orientation

add_spline(fit_points: Iterable[UVec] | None = None, control_points: Iterable[UVec] | None = None, knot_values: Iterable[float] | None = None, weights: Iterable[float] | None = None, degree: int = 3, periodic: int = 0, start_tangent: UVec | None = None, end_tangent: UVec | None = None) 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 if None)

  • 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.EdgeType
LINE
ARC
ELLIPSE
SPLINE
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 counter-clockwise 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 counter-clockwise orientation in degrees. (read/write)

end_angle

Arc end angle in counter-clockwise orientation in degrees. (read/write)

ccw

True for counter clockwise arc else False. (read/write)

class ezdxf.entities.EllipseEdge

Elliptic arc as boundary edge in counter-clockwise 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 counter-clockwise orientation in degrees. (read/write)

end_angle

Ellipse end angle in counter-clockwise orientation in degrees. (read/write)

ccw

True for counter clockwise ellipse else False. (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: UVec = (0, 0), offset: UVec = (0, 0), dash_length_items: Iterable[float] | None = 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() or Hatch.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 between color1 and a specified tint of color1. (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)

tint

Specifies the tint (color1 mixed with white) of a color to be used for a gradient fill of one color. (read/write)