matplotlib.patches.Patch#

class matplotlib.patches.Patch(*, edgecolor=None, facecolor=None, color=None, linewidth=None, linestyle=None, antialiased=None, hatch=None, fill=True, capstyle=None, joinstyle=None, hatchcolor=None, edgegapcolor=None, **kwargs)[source]#

Bases: Artist

A patch is a 2D artist with a face color and an edge color.

If any of edgecolor, facecolor, linewidth, or antialiased are None, they default to their rc params setting.

The following kwarg properties are supported

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	unknown
animated	bool
antialiased or aa	bool or None
blend_mode	blend mode
capstyle	CapStyle or {'butt', 'projecting', 'round'}
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
color	color
edgecolor or ec	color or None
edgegapcolor	color or None
facecolor or fc	color or None
figure	Figure or SubFigure
fill	bool
fill_rule	{'nonzero', 'evenodd'}
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	unknown
hatchcolor	color or 'edge' or None
in_layout	bool
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle or ls	linestyle
linewidth or lw	float or None
mouseover	bool
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

contains(mouseevent, radius=None)[source]#

Test whether the mouse event occurred in the patch.

Parameters:

mouseeventMouseEvent

Where the user clicked.

radiusfloat, optional

Additional margin on the patch in target coordinates of Patch.get_transform. See Path.contains_point for further details.

If None, the default value depends on the state of the object:

• If Artist.get_picker is a number, the default is that value. This is so that picking works as expected.

• Otherwise if the edge color has a non-zero alpha, the default is half of the linewidth. This is so that all the colored pixels are "in" the patch.

• Finally, if the edge has 0 alpha, the default is 0. This is so that patches without a stroked edge do not have points outside of the filled region report as "in" due to an invisible edge.

Returns:

(bool, empty dict)

contains_point(point, radius=None)[source]#

Return whether the given point is inside the patch.

Parameters:

point(float, float)

The point (x, y) to check, in target coordinates of .Patch.get_transform(). These are display coordinates for patches that are added to a figure or Axes.

radiusfloat, optional

Additional margin on the patch in target coordinates of Patch.get_transform. See Path.contains_point for further details.

If None, the default value depends on the state of the object:

• If Artist.get_picker is a number, the default is that value. This is so that picking works as expected.

• Otherwise if the edge color has a non-zero alpha, the default is half of the linewidth. This is so that all the colored pixels are "in" the patch.

• Finally, if the edge has 0 alpha, the default is 0. This is so that patches without a stroked edge do not have points outside of the filled region report as "in" due to an invisible edge.

Returns:

bool

Notes

The proper use of this method depends on the transform of the patch. Isolated patches do not have a transform. In this case, the patch creation coordinates and the point coordinates match. The following example checks that the center of a circle is within the circle

>>> center = 0, 0
>>> c = Circle(center, radius=1)
>>> c.contains_point(center)
True

The convention of checking against the transformed patch stems from the fact that this method is predominantly used to check if display coordinates (e.g. from mouse events) are within the patch. If you want to do the above check with data coordinates, you have to properly transform them first:

>>> center = 0, 0
>>> c = Circle(center, radius=3)
>>> plt.gca().add_patch(c)
>>> transformed_interior_point = c.get_data_transform().transform((0, 2))
>>> c.contains_point(transformed_interior_point)
True

contains_points(points, radius=None)[source]#

Return whether the given points are inside the patch.

Parameters:

points(N, 2) array

The points to check, in target coordinates of self.get_transform(). These are display coordinates for patches that are added to a figure or Axes. Columns contain x and y values.

radiusfloat, optional

Additional margin on the patch in target coordinates of Patch.get_transform. See Path.contains_point for further details.

If None, the default value depends on the state of the object:

• If Artist.get_picker is a number, the default is that value. This is so that picking works as expected.

• Otherwise if the edge color has a non-zero alpha, the default is half of the linewidth. This is so that all the colored pixels are "in" the patch.

• Finally, if the edge has 0 alpha, the default is 0. This is so that patches without a stroked edge do not have points outside of the filled region report as "in" due to an invisible edge.

Returns:

length-N bool array

Notes

The proper use of this method depends on the transform of the patch. See the notes on Patch.contains_point.

draw(renderer)[source]#

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:

rendererRendererBase subclass.

Notes

This method is overridden in the Artist subclasses.

property fill#

Return whether the patch is filled.

get_aa()[source]#

Alias for get_antialiased.

get_antialiased()[source]#

Return whether antialiasing is used for drawing.

get_capstyle()[source]#

Return the capstyle.

get_data_transform()[source]#

Return the Transform mapping data coordinates to physical coordinates.

get_ec()[source]#

Alias for get_edgecolor.

get_edgecolor()[source]#

Return the edge color.

get_edgegapcolor()[source]#

Return the edge gap color.

Added in version 3.11.

See also set_edgegapcolor.

get_extents()[source]#

Return the Patch's axis-aligned extents as a Bbox.

get_facecolor()[source]#

Return the face color.

get_fc()[source]#

Alias for get_facecolor.

get_fill()[source]#

Return whether the patch is filled.

get_fill_rule()[source]#

get_hatch()[source]#

Return the hatching pattern.

get_hatch_linewidth()[source]#

Return the hatch linewidth.

get_hatchcolor()[source]#

Return the hatch color.

get_joinstyle()[source]#

Return the joinstyle.

get_linestyle()[source]#

Return the linestyle.

get_linewidth()[source]#

Return the line width in points.

get_ls()[source]#

Alias for get_linestyle.

get_lw()[source]#

Alias for get_linewidth.

get_patch_transform()[source]#

Return the Transform instance mapping patch coordinates to data coordinates.

For example, one may define a patch of a circle which represents a radius of 5 by providing coordinates for a unit circle, and a transform which scales the coordinates (the patch coordinate) by 5.

get_path()[source]#

Return the path of this patch.

get_transform()[source]#

Return the Transform applied to the Patch.

get_verts()[source]#

Return a copy of the vertices used in this patch.

If the patch contains Bzier curves, the curves will be interpolated by line segments. To access the curves as curves, use get_path.

get_window_extent(renderer=None)[source]#

Get the artist's bounding box in display space, ignoring clipping.

The bounding box's width and height are non-negative.

Subclasses should override for inclusion in the bounding box "tight" calculation. Default is to return an empty bounding box at 0, 0.

Warning

The extent can change due to any changes in the transform stack, such as changing the Axes limits, the figure size, the canvas used (as is done when saving a figure), or the DPI.

Relying on a once-retrieved window extent can lead to unexpected behavior in various cases such as interactive figures being resized or moved to a screen with different dpi, or figures that look fine on screen render incorrectly when saved to file.

To get accurate results you may need to manually call savefig or draw_without_rendering to have Matplotlib compute the rendered size.

Parameters:

rendererRendererBase, optional

Renderer used to draw the figure (i.e. fig.canvas.get_renderer()).

See also

Artist.get_tightbbox

Get the artist bounding box, taking clipping into account.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, blend_mode=<UNSET>, capstyle=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, edgegapcolor=<UNSET>, facecolor=<UNSET>, fill=<UNSET>, fill_rule=<UNSET>, gid=<UNSET>, hatch=<UNSET>, hatch_linewidth=<UNSET>, hatchcolor=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	unknown
animated	bool
antialiased	bool or None
blend_mode	blend mode
capstyle	CapStyle or {'butt', 'projecting', 'round'}
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
color	color
edgecolor	color or None
edgegapcolor	color or None
facecolor	color or None
figure	Figure or SubFigure
fill	bool
fill_rule	{'nonzero', 'evenodd'}
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	unknown
hatchcolor	color or 'edge' or None
in_layout	bool
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle	linestyle
linewidth	float or None
mouseover	bool
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

set_aa(aa)[source]#

Alias for set_antialiased.

set_alpha(alpha)[source]#

Set the alpha value used for blending - not supported on all backends.

Parameters:

alphafloat or None

alpha must be within the 0-1 range, inclusive.

set_antialiased(aa)[source]#

Set whether to use antialiased rendering.

Parameters:

aabool or None

set_capstyle(s)[source]#

Set the CapStyle.

The default capstyle is 'round' for FancyArrowPatch and 'butt' for all other patches.

Parameters:

sCapStyle or {'butt', 'projecting', 'round'}

set_color(c)[source]#

Set both the edgecolor and the facecolor.

Parameters:

ccolor

See also

Patch.set_facecolor, Patch.set_edgecolor

For setting the edge or face color individually.

set_ec(color)[source]#

Alias for set_edgecolor.

set_edgecolor(color)[source]#

Set the patch edge color.

Parameters:

colorcolor or None

set_edgegapcolor(edgegapcolor)[source]#

Set a color to fill the gaps in the dashed edge style.

Added in version 3.11.

Note

Striped edges are created by drawing two interleaved dashed lines. There can be overlaps between those two, which may result in artifacts when using transparency.

This functionality is experimental and may change.

Parameters:

edgegapcolorcolor or None

The color with which to fill the gaps. If None, the gaps are unfilled.

set_facecolor(color)[source]#

Set the patch face color.

Parameters:

colorcolor or None

set_fc(color)[source]#

Alias for set_facecolor.

set_fill(b)[source]#

Set whether to fill the patch.

Parameters:

bbool

set_fill_rule(fill_rule)[source]#

Set the rule for filling a shape.

See Fill rule demo.

Parameters:

fill_rule{'nonzero', 'evenodd'}

'nonzero' for the non-zero winding rule (the default), or 'evenodd' for the even-odd rule

References

• Wikipedia: Non-zero winding rule

• Wikipedia: Even-odd rule

set_hatch(hatch)[source]#

Set the hatching pattern.

hatch can be one of:

/   - diagonal hatching
\   - back diagonal
|   - vertical
-   - horizontal
+   - crossed
x   - crossed diagonal
o   - small circle
O   - large circle
.   - dots
*   - stars

Letters can be combined, in which case all the specified hatchings are done. If same letter repeats, it increases the density of hatching of that pattern.

In regular (non-raw) Python strings, backslashes must be doubled: '\\\\' and r'\\' are both a double back-diagonal hatch.

Parameters:

hatch{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}

set_hatch_linewidth(lw)[source]#

Set the hatch linewidth.

set_hatchcolor(color)[source]#

Set the patch hatch color.

Parameters:

colorcolor or 'edge' or None

set_joinstyle(s)[source]#

Set the JoinStyle.

The default joinstyle is 'round' for FancyArrowPatch and 'miter' for all other patches.

Parameters:

sJoinStyle or {'miter', 'round', 'bevel'}

set_linestyle(ls)[source]#

Set the patch linestyle.

Parameters:

lslinestyle

A named line style (e.g. "dashed", or short "--") or a dash tuple (offset, (on_off_seq)).

For a full reference see Linestyles.

set_linewidth(w)[source]#

Set the patch linewidth in points.

Parameters:

wfloat or None

set_ls(ls)[source]#

Alias for set_linestyle.

set_lw(w)[source]#

Alias for set_linewidth.

update_from(other)[source]#

Copy properties from other to self.

zorder = 1#

Examples using matplotlib.patches.Patch#

[]

Stairs Demo

Stairs Demo

[]

Many ways to plot images

Many ways to plot images

[]

Clipping images with patches

Clipping images with patches

[]

Placing images, preserving relative sizes

Placing images, preserving relative sizes

[]

Create boxes from error bars using PatchCollection

Create boxes from error bars using PatchCollection

[]

Plot a confidence ellipse of a two-dimensional dataset

Plot a confidence ellipse of a two-dimensional dataset

[]

Curve with error band

Curve with error band

[]

Boxplots

Boxplots

[]

Bar of pie

Bar of pie

[]

Controlling view limits using margins and sticky_edges

Controlling view limits using margins and sticky_edges

[]

Axes box aspect

Axes box aspect

[]

Axes zoom effect

Axes zoom effect

[]

Text alignment

Text alignment

[]

Text rotation mode

Text rotation mode

[]

Using a text as a Path

Using a text as a Path

[]

Annotate plots

Annotate plots

[]

Angle annotations on bracket arrows

Angle annotations on bracket arrows

[]

Placing text boxes

Placing text boxes

[]

Artists as annotations

Artists as annotations

[]

Scale invariant angle label

Scale invariant angle label

[]

Compose custom legends

Compose custom legends

[]

Arrow guide

Arrow guide

[]

Reference for Matplotlib artists

Reference for Matplotlib artists

[]

Compound path

Compound path

[]

Dolphins

Dolphins

[]

Mmh Donuts!!!

Mmh Donuts!!!

[]

Ellipse with orientation arrow demo

Ellipse with orientation arrow demo

[]

Ellipse Demo

Ellipse Demo

[]

Drawing fancy boxes

Drawing fancy boxes

[]

Fill rule demo

Fill rule demo

[]

Hatch demo

Hatch demo

[]

Hatch style reference

Hatch style reference

[]

Hatchcolor Demo

Hatchcolor Demo

[]

Circles, Wedges and Polygons

Circles, Wedges and Polygons

[]

PathPatch object

PathPatch object

[]

Bezier curve

Bezier curve

[]

List of named colors

List of named colors

[]

ggplot style sheet

ggplot style sheet

[]

Grayscale style sheet

Grayscale style sheet

[]

Petroff style sheets

Petroff style sheets

[]

Style sheets reference

Style sheets reference

[]

Draw flat objects in 3D plot

Draw flat objects in 3D plot

[]

Inset locator demo

Inset locator demo

[]

Multiple Axes animation

Multiple Axes animation

[]

Menu

Menu

[]

Looking glass

Looking glass

[]

Path editor

Path editor

[]

Pick event demo

Pick event demo

[]

Polygon editor

Polygon editor

[]

Trifinder Event Demo

Trifinder Event Demo

[]

Viewlims

Viewlims

[]

Artist tests

Artist tests

[]

Ellipse with units

Ellipse with units

[]

Anchored Artists

Anchored Artists

[]

Identify whether artists intersect

Identify whether artists intersect

[]

Custom projection

Custom projection

[]

Building histograms using Rectangles and PolyCollections

Building histograms using Rectangles and PolyCollections

[]

Matplotlib logo

Matplotlib logo

[]

Packed-bubble chart

Packed-bubble chart

[]

SVG filter pie

SVG filter pie

[]

TickedStroke patheffect

TickedStroke patheffect

[]

Anatomy of a figure

Anatomy of a figure

[]

Firefox

Firefox

[]

Integral as the area under a curve

Integral as the area under a curve

[]

Hinton diagrams

Hinton diagrams

[]

Ishikawa Diagram

Ishikawa Diagram

[]

Radar chart (aka spider or star chart)

Radar chart (aka spider or star chart)

[]

SkewT-logP diagram: using transforms and custom projections

SkewT-logP diagram: using transforms and custom projections

[]

Path Tutorial

Path Tutorial

[]

Transformations Tutorial

Transformations Tutorial

[]

Legend guide

Legend guide

[]

Specifying colors

Specifying colors

[]

Blending and compositing artists

Blending and compositing artists

[]

Blending and compositing groups of artists

Blending and compositing groups of artists

[]

Annotations

Annotations

[]

Text properties and layout

Text properties and layout