Hatch

The HATCH entity (DXF Reference) fills an enclosed area defined by one or more boundary paths with a hatch pattern, solid fill, or gradient fill.

All points in OCS as (x, y) tuples (Hatch.dxf.elevation is the z-axis value).

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 helper classes

Path manager: BoundaryPaths

Pattern and gradient helper classes

class ezdxf.entities.Hatch
dxf.pattern_name

Pattern name as string

dxf.solid_fill

1

solid fill, better use: Hatch.set_solid_fill()

0

pattern fill, better use: Hatch.set_pattern_fill()

dxf.associative

1

associative hatch

0

not associative hatch

Associations not handled by ezdxf, you have to set the handles to the associated DXF entities by yourself.

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

Pattern angle in degrees. (float)

dxf.pattern_scale

Pattern scaling factor. (float)

dxf.pattern_double

1 = double pattern size else 0. (int)

dxf.n_seed_points

Count of seed points (better user: 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

List of (x, y) tuples.

has_solid_fill

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

has_pattern_fill

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

has_gradient_data

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

bgcolor

Property background color as (r, g, b) tuple, rgb values in range 0..255 (read/write/del)

usage:

color = hatch.bgcolor  # get background color as (r, g, b) tuple
hatch.bgcolor = (10, 20, 30)  # set background color
del hatch.bgcolor  # delete background color
edit_boundary() → BoundaryPaths

Context manager to edit hatch boundary data, yields a BoundaryPaths object.

edit_pattern() → Pattern

Context manager to edit hatch pattern data, yields a PatternData object.

set_pattern_definition(lines: Sequence, factor: float = 1) → None

Setup hatch patten definition by a list of definition lines and a definition line is a 4-tuple [angle, base_point, offset, dash_length_items], the pattern definition should be designed for scaling factor 1.

  • angle: line angle in degrees

  • base-point: 2-tuple (x, y)

  • offset: 2-tuple (dx, dy)

  • 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 scaling factor

set_solid_fill(color: int = 7, style: int = 1, rgb: RGB = None)

Set Hatch to 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

Set Hatch to pattern fill mode. Removes all gradient related data. The pattern definition should be designed for scaling factor 1.

Parameters
  • name – pattern name as string

  • color – pattern color as AutoCAD Color Index (ACI)

  • angle – angle of pattern fill in degrees

  • scale – pattern scaling as float

  • 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 = (0, 0, 0), color2: RGB = (255, 255, 255), rotation: float = 0.0, centered: float = 0.0, one_color: int = 0, tint: float = 0.0, name: str = 'LINEAR') → None

Set Hatch to gradient fill mode and removes all pattern fill related data. Gradient support requires DXF DXF R2004. 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 range 0..255

  • color2(r, g, b) tuple for second color, rgb values as int in range 0..255

  • rotation – rotation in degrees

  • centered – determines whether the gradient is centered or not

  • one_color1 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'

get_gradient()

Returns gradient data as GradientData object.

edit_gradient() → ezdxf.entities.hatch.Gradient

Context manager to edit hatch gradient data, yields a GradientData object.

get_seed_points() → List

Returns seed points as list of (x, y) points, I don’t know why there can be more than one seed point. All points in OCS (Hatch.dxf.elevation is the Z value).

set_seed_points(points: Sequence[Tuple[float, float]]) → None

Set seed points, points is a list 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_to_wcs(ucs: UCS) → Hatch

Transform HATCH entity from local UCS coordinates to WCS coordinates.

New in version 0.11.

associate(path: Union[PolylinePath, EdgePath], 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!

New in version 0.11.

Hatch Boundary Helper 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)

add_polyline_path(path_vertices, is_closed=1, flags=1) → PolylinePath

Create and add a new PolylinePath object.

Parameters
  • path_vertices – list of polyline vertices as (x, y) or (x, y, bulge) tuples.

  • is_closed1 for a closed polyline else 0

  • flags – external(1) or outermost(16) or default (0)

add_edge_path(flags=1) → EdgePath

Create and add a new EdgePath object.

Parameters

flags – external(1) or outermost(16) or default (0)

clear() → None

Remove all boundary paths.

class ezdxf.entities.PolylinePath

A polyline as hatch boundary path.

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: Sequence[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. AutoCAD in this regard is very picky. ezdxf performs no checks on gaps between the edges.

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, end) → 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, radius=1., start_angle=0., end_angle=360., is_counter_clockwise=0) → ArcEdge

Add an ArcEdge.

Parameters
  • center (tuple) –

  • radius (float) – radius of circle

  • start_angle (float) – start angle of arc in degrees

  • end_angle (float) – end angle of arc in degrees

  • is_counter_clockwise (int) – 1 for yes 0 for no

  • center – center point of arc, (x, y) tuple

  • radius – radius of circle

  • start_angle – start angle of arc in degrees

  • end_angle – end angle of arc in degrees

  • is_counter_clockwise1 for counter clockwise 0 for clockwise orientation

add_ellipse(center, major_axis_vector=(1., 0.), minor_axis_length=1., start_angle=0., end_angle=360., is_counter_clockwise=0) → EllipsePath

Add an EllipseEdge.

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 arc in degrees

  • end_angle – end angle of arc in degrees

  • is_counter_clockwise1 for counter clockwise 0 for clockwise orientation

add_spline(fit_points=None, control_points=None, knot_values=None, weights=None, degree=3, rational=0, periodic=0) → SplinePath

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 amd 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.bspline.knot_values() and ezdxf.math.bspline.knot_values_uniform()

  • weights – weight of control point, not mandatory, list of floats.

  • degree – degree of spline (int)

  • rational1 for rational spline, 0 for none rational spline

  • periodic1 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.

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.

center

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

radius

Arc radius as float. (read/write)

start_angle

Arc start angle in degrees. (read/write)

end_angle

Arc end angle in degrees. (read/write)

is_counter_clockwise

1 for counter clockwise arc else 0. (read/write)

class ezdxf.entities.EllipseEdge

Elliptic arc as boundary edge.

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 degrees. (read/write)

end_angle

Ellipse end angle in degrees. (read/write)

is_counter_clockwise

1 for counter clockwise ellipse else 0. (read/write)

class ezdxf.entities.SplineEdge

Spline as boundary edge.

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 Helper Classes

class ezdxf.entities.Pattern
lines

List of pattern definition lines (read/write). see PatternLine

add_line(angle: float = 0.0, base_point: Tuple[float, float] = (0.0, 0.0), offset: Tuple[float, float] = (0.0, 0.0), dash_length_items: List[float] = None) → None

Create a new pattern definition line and add the line to the Pattern.lines attribute.

static new_line(angle: float = 0.0, base_point: Tuple[float, float] = (0.0, 0.0), offset: Tuple[float, float] = (0.0, 0.0), dash_length_items: List[float] = None) → ezdxf.entities.hatch.PatternLine

Create a new pattern definition line, but does not add the line to the Pattern.lines attribute.

clear() → None

Delete all pattern definition lines.

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 Helper Classes

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)