matplotlib.patheffects

Defines classes for path effects. The path effects are supported in Text, Line2D and Patch.

See also

Path effects guide

class matplotlib.patheffects.AbstractPathEffect(offset=(0.0, 0.0))

Bases: object

A base class for path effects.

Subclasses should override the draw_path method to add effect functionality.

Parameters:

offset(float, float), default: (0, 0)

The (x, y) offset to apply to the path, measured in points.

draw_path(renderer, gc, tpath, affine, rgbFace=None)

Derived should override this method. The arguments are the same as matplotlib.backend_bases.RendererBase.draw_path() except the first argument is a renderer.

class matplotlib.patheffects.Normal(offset=(0.0, 0.0))

Bases: AbstractPathEffect

The "identity" PathEffect.

The Normal PathEffect's sole purpose is to draw the original artist with no special path effect.

Parameters:

offset(float, float), default: (0, 0)

The (x, y) offset to apply to the path, measured in points.

class matplotlib.patheffects.PathEffectRenderer(path_effects, renderer)

Bases: RendererBase

Implements a Renderer which contains another renderer.

This proxy then intercepts draw calls, calling the appropriate AbstractPathEffect draw method.

Note

Not all methods have been overridden on this RendererBase subclass. It may be necessary to add further methods to extend the PathEffects capabilities further.

Parameters:

path_effectsiterable of AbstractPathEffect

The path effects which this renderer represents.

renderermatplotlib.backend_bases.RendererBase subclass

copy_with_path_effect(path_effects)

draw_markers(gc, marker_path, marker_trans, path, *args, **kwargs)

Draw a marker at each of path's vertices (excluding control points).

The base (fallback) implementation makes multiple calls to draw_path. Backends may want to override this method in order to draw the marker only once and reuse it multiple times.

Parameters:

gcGraphicsContextBase

The graphics context.

marker_transmatplotlib.transforms.Transform

An affine transform applied to the marker.

transmatplotlib.transforms.Transform

An affine transform applied to the path.

draw_path(gc, tpath, affine, rgbFace=None)

Draw a Path instance using the given affine transform.

draw_path_collection(gc, master_transform, paths, *args, **kwargs)

Draw a collection of paths.

Each path is first transformed by the corresponding entry in all_transforms (a list of (3, 3) matrices) and then by master_transform. They are then translated by the corresponding entry in offsets, which has been first transformed by offset_trans.

facecolors, edgecolors, linewidths, linestyles, and antialiased are lists that set the corresponding properties.

offset_position is unused now, but the argument is kept for backwards compatibility.

The base (fallback) implementation makes multiple calls to draw_path. Backends may want to override this in order to render each set of path data only once, and then reference that path multiple times with the different offsets, colors, styles etc. The generator methods _iter_collection_raw_paths and _iter_collection are provided to help with (and standardize) the implementation across backends. It is highly recommended to use those generators, so that changes to the behavior of draw_path_collection can be made globally.

class matplotlib.patheffects.PathPatchEffect(offset=(0, 0), **kwargs)

Bases: AbstractPathEffect

Draws a PathPatch instance whose Path comes from the original PathEffect artist.

Parameters:

offset(float, float), default: (0, 0)

The (x, y) offset to apply to the path, in points.

**kwargs

All keyword arguments are passed through to the PathPatch constructor. The properties which cannot be overridden are "path", "clip_box" "transform" and "clip_path".

draw_path(renderer, gc, tpath, affine, rgbFace)

Derived should override this method. The arguments are the same as matplotlib.backend_bases.RendererBase.draw_path() except the first argument is a renderer.

class matplotlib.patheffects.SimpleLineShadow(offset=(2, -2), shadow_color='k', alpha=0.3, rho=0.3, **kwargs)

Bases: AbstractPathEffect

A simple shadow via a line.

Parameters:

offset(float, float), default: (2, -2)

The (x, y) offset to apply to the path, in points.

shadow_colorcolor, default: 'black'

The shadow color. A value of None takes the original artist's color with a scale factor of rho.

alphafloat, default: 0.3

The alpha transparency of the created shadow patch.

rhofloat, default: 0.3

A scale factor to apply to the rgbFace color if shadow_color is None.

**kwargs

Extra keywords are stored and passed through to AbstractPathEffect._update_gc().

draw_path(renderer, gc, tpath, affine, rgbFace)

Overrides the standard draw_path to add the shadow offset and necessary color changes for the shadow.

class matplotlib.patheffects.SimplePatchShadow(offset=(2, -2), shadow_rgbFace=None, alpha=None, rho=0.3, **kwargs)

Bases: AbstractPathEffect

A simple shadow via a filled patch.

Parameters:

offset(float, float), default: (2, -2)

The (x, y) offset of the shadow in points.

shadow_rgbFacecolor

The shadow color.

alphafloat, default: 0.3

The alpha transparency of the created shadow patch.

rhofloat, default: 0.3

A scale factor to apply to the rgbFace color if shadow_rgbFace is not specified.

**kwargs

Extra keywords are stored and passed through to AbstractPathEffect._update_gc().

draw_path(renderer, gc, tpath, affine, rgbFace)

Overrides the standard draw_path to add the shadow offset and necessary color changes for the shadow.

class matplotlib.patheffects.Stroke(offset=(0, 0), **kwargs)

Bases: AbstractPathEffect

A line based PathEffect which re-draws a stroke.

The path will be stroked with its gc updated with the given keyword arguments, i.e., the keyword arguments should be valid gc parameter values.

draw_path(renderer, gc, tpath, affine, rgbFace)

Draw the path with updated gc.

class matplotlib.patheffects.TickedStroke(offset=(0, 0), spacing=10.0, angle=45.0, length=1.4142135623730951, **kwargs)

Bases: AbstractPathEffect

A line-based PathEffect which draws a path with a ticked style.

This line style is frequently used to represent constraints in optimization. The ticks may be used to indicate that one side of the line is invalid or to represent a closed boundary of a domain (i.e. a wall or the edge of a pipe).

The spacing, length, and angle of ticks can be controlled.

This line style is sometimes referred to as a hatched line.

See also the contour demo example.

See also the contours in optimization example.

Parameters:

offset(float, float), default: (0, 0)

The (x, y) offset to apply to the path, in points.

spacingfloat, default: 10.0

The spacing between ticks in points.

anglefloat, default: 45.0

The angle between the path and the tick in degrees. The angle is measured as if you were an ant walking along the curve, with zero degrees pointing directly ahead, 90 to your left, -90 to your right, and 180 behind you.

lengthfloat, default: 1.414

The length of the tick relative to spacing. Recommended length = 1.414 (sqrt(2)) when angle=45, length=1.0 when angle=90 and length=2.0 when angle=60.

**kwargs

Extra keywords are stored and passed through to AbstractPathEffect._update_gc().

Examples

See TickedStroke patheffect.

draw_path(renderer, gc, tpath, affine, rgbFace)

Draw the path with updated gc.

class matplotlib.patheffects.withSimplePatchShadow(offset=(2, -2), shadow_rgbFace=None, alpha=None, rho=0.3, **kwargs)

Bases: SimplePatchShadow

A shortcut PathEffect for applying SimplePatchShadow and then drawing the original Artist.

With this class you can use

artist.set_path_effects([path_effects.withSimplePatchShadow()])

as a shortcut for

artist.set_path_effects([path_effects.SimplePatchShadow(),
                         path_effects.Normal()])

Parameters:

offset(float, float), default: (2, -2)

The (x, y) offset of the shadow in points.

shadow_rgbFacecolor

The shadow color.

alphafloat, default: 0.3

The alpha transparency of the created shadow patch.

rhofloat, default: 0.3

A scale factor to apply to the rgbFace color if shadow_rgbFace is not specified.

**kwargs

Extra keywords are stored and passed through to AbstractPathEffect._update_gc().

draw_path(renderer, gc, tpath, affine, rgbFace)

Overrides the standard draw_path to add the shadow offset and necessary color changes for the shadow.

class matplotlib.patheffects.withStroke(offset=(0, 0), **kwargs)

Bases: Stroke

A shortcut PathEffect for applying Stroke and then drawing the original Artist.

With this class you can use

artist.set_path_effects([path_effects.withStroke()])

as a shortcut for

artist.set_path_effects([path_effects.Stroke(),
                         path_effects.Normal()])

The path will be stroked with its gc updated with the given keyword arguments, i.e., the keyword arguments should be valid gc parameter values.

draw_path(renderer, gc, tpath, affine, rgbFace)

Draw the path with updated gc.

class matplotlib.patheffects.withTickedStroke(offset=(0, 0), spacing=10.0, angle=45.0, length=1.4142135623730951, **kwargs)

Bases: TickedStroke

A shortcut PathEffect for applying TickedStroke and then drawing the original Artist.

With this class you can use

artist.set_path_effects([path_effects.withTickedStroke()])

as a shortcut for

artist.set_path_effects([path_effects.TickedStroke(),
                         path_effects.Normal()])

Parameters:

offset(float, float), default: (0, 0)

The (x, y) offset to apply to the path, in points.

spacingfloat, default: 10.0

The spacing between ticks in points.

anglefloat, default: 45.0

The angle between the path and the tick in degrees. The angle is measured as if you were an ant walking along the curve, with zero degrees pointing directly ahead, 90 to your left, -90 to your right, and 180 behind you.

lengthfloat, default: 1.414

The length of the tick relative to spacing. Recommended length = 1.414 (sqrt(2)) when angle=45, length=1.0 when angle=90 and length=2.0 when angle=60.

**kwargs

Extra keywords are stored and passed through to AbstractPathEffect._update_gc().

Examples

See TickedStroke patheffect.

draw_path(renderer, gc, tpath, affine, rgbFace)

Draw the path with updated gc.