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) → 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]

  • 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

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.

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

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

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)