matplotlib.path¶

A module for dealing with the polylines used throughout matplotlib.

The primary class for polyline handling in matplotlib isPath.Almost all vector drawing makes use of Paths somewhere in the drawingpipeline.

Whilst aPath instance itself cannot be drawn, there existsArtist subclasses which can be used forconvenient Path visualisation - the two most frequently used of these arePathPatch andPathCollection.

classmatplotlib.path.Path(vertices,codes=None,_interpolation_steps=1,closed=False,readonly=False)¶

Bases:object

Path represents a series of possibly disconnected,possibly closed, line and curve segments.

The underlying storage is made up of two parallel numpy arrays:

• vertices: an Nx2 float array of vertices
• codes: an N-length uint8 array of vertex types

These two arrays always have the same length in the firstdimension. For example, to represent a cubic curve, you mustprovide three vertices as well as three codesCURVE3.

The code types are:

• STOP:1 vertex (ignored)

  A marker for the end of the entire path (currently notrequired and ignored)

• MOVETO:1 vertex

  Pick up the pen and move to the given vertex.

• LINETO:1 vertex

  Draw a line from the current position to the given vertex.

• CURVE3:1 control point, 1 endpoint

  Draw a quadratic Bezier curve from the current position,with the given control point, to the given end point.

• CURVE4:2 control points, 1 endpoint

  Draw a cubic Bezier curve from the current position, withthe given control points, to the given end point.

• CLOSEPOLY:1 vertex (ignored)

  Draw a line segment to the start point of the currentpolyline.

Users of Path objects should not access the vertices and codesarrays directly. Instead, they should useiter_segments()orcleaned() to get the vertex/code pairs. This is important,since manyPath objects, as an optimization, do not store acodes at all, but have a default one provided for them byiter_segments().

Note

The vertices and codes arrays should be treated asimmutable – there are a number of optimizations and assumptionsmade up front in the constructor that will not change when thedata changes.

Create a new path with the given vertices and codes.

Parameters:

vertices : array_like The(n,2) float array, masked array or sequence of pairsrepresenting the vertices of the path. Ifvertices contains masked values, they will be convertedto NaNs which are then handled correctly by the AggPathIterator and other consumers of path data, such asiter_segments(). codes : {None, array_like}, optional n-length array integers representing the codes of the path.If not None, codes must be the same length as vertices.If None,vertices will be treated as a series of line segments. _interpolation_steps : int, optional Used as a hint to certain projections, such as Polar, that thispath should be linearly interpolated immediately before drawing.This attribute is primarily an implementation detail and is notintended for public use. closed : bool, optional Ifcodes is None and closed is True, vertices will be treated asline segments of a closed polygon. readonly : bool, optional Makes the path behave in an immutable way and sets the verticesand codes as read-only arrays.

CLOSEPOLY = 79¶

CURVE3 = 3¶

CURVE4 = 4¶

LINETO = 2¶

MOVETO = 1¶

NUM_VERTICES_FOR_CODE = {0: 1, 1: 1, 2: 1, 3: 2, 4: 3, 79: 1}¶

A dictionary mapping Path codes to the number of vertices that thecode expects.

STOP = 0¶

classmethodarc(theta1,theta2,n=None,is_wedge=False)¶

Return an arc on the unit circle from angletheta1 to angletheta2 (in degrees).

Ifn is provided, it is the number of spline segments to make.Ifn is not provided, the number of spline segments isdetermined based on the delta betweentheta1 andtheta2.

Masionobe, L. 2003.Drawing an elliptical arc usingpolylines, quadratic or cubic Bezier curves.

classmethodcircle(center=(0.0,0.0),radius=1.0,readonly=False)¶

Return a Path representing a circle of a given radius and center.

Parameters:	center : pair of floats The center of the circle. Default(0,0). radius : float The radius of the circle. Default is 1. readonly : bool Whether the created path should have the “readonly” argumentset when creating the Path instance.

Notes

The circle is approximated using cubic Bezier curves. Thisuses 8 splines around the circle using the approach presentedhere:

Lancaster, Don.Approximating a Circle or an Ellipse Using FourBezier Cubic Splines.

cleaned(transform=None,remove_nans=False,clip=None,quantize=False,simplify=False,curves=False,stroke_width=1.0,snap=False,sketch=None)¶

Cleans up the path according to the parameters returning a newPath instance.

See also

Seeiter_segments() for details of the keyword arguments.

Returns:	Path instance with cleaned up vertices and codes.

clip_to_bbox(bbox,inside=True)¶

Clip the path to the given bounding box.

The path must be made up of one or more closed polygons. Thisalgorithm will not behave correctly for unclosed paths.

Ifinside isTrue, clip to the inside of the box, otherwiseto the outside of the box.

code_type¶

alias ofuint8

codes¶

The list of codes in thePath as a 1-D numpy array. Eachcode is one ofSTOP,MOVETO,LINETO,CURVE3,CURVE4orCLOSEPOLY. For codes that correspond to more than onevertex (CURVE3 andCURVE4), that code will be repeated sothat the length ofself.vertices andself.codes is alwaysthe same.

contains_path(path,transform=None)¶

ReturnsTrue if this path completely contains the given path.

Iftransform is notNone, the path will be transformedbefore performing the test.

contains_point(point,transform=None,radius=0.0)¶

ReturnsTrue if the path contains the given point.

Iftransform is notNone, the path will be transformedbefore performing the test.

radius allows the path to be made slightly larger orsmaller.

contains_points(points,transform=None,radius=0.0)¶

Returns a bool array which isTrue if the path contains thecorresponding point.

Iftransform is notNone, the path will be transformedbefore performing the test.

radius allows the path to be made slightly larger orsmaller.

copy()¶

Returns a shallow copy of thePath, which will share thevertices and codes with the sourcePath.

deepcopy(memo=None)¶

Returns a deepcopy of thePath. ThePath will not bereadonly, even if the sourcePath is.

get_extents(transform=None)¶

Returns the extents (xmin,ymin,xmax,ymax) of thepath.

Unlike computing the extents on thevertices alone, thisalgorithm will take into account the curves and deal withcontrol points appropriately.

has_nonfinite¶

True if the vertices array has nonfinite values.

classmethodhatch(hatchpattern,density=6)¶

Given a hatch specifier,hatchpattern, generates a Path thatcan be used in a repeated hatching pattern.density is thenumber of lines per unit square.

interpolated(steps)¶

Returns a new path resampled to length N x steps. Does notcurrently handle interpolating curves.

intersects_bbox(bbox,filled=True)¶

ReturnsTrue if this path intersects a givenBbox.

filled, when True, treats the path as if it was filled.That is, if one path completely encloses the other,intersects_path() will return True.

intersects_path(other,filled=True)¶

ReturnsTrue if this path intersects another given path.

filled, when True, treats the paths as if they were filled.That is, if one path completely encloses the other,intersects_path() will return True.

iter_segments(transform=None,remove_nans=True,clip=None,snap=False,stroke_width=1.0,simplify=None,curves=True,sketch=None)¶

Iterates over all of the curve segments in the path. Eachiteration returns a 2-tuple (vertices,code), wherevertices is a sequence of 1 - 3 coordinate pairs, andcode isone of thePath codes.

Additionally, this method can provide a number of standardcleanups and conversions to the path.

Parameters:

transform : None orTransform instance If not None, the given affine transformation willbe applied to the path. remove_nans : {False, True}, optional If True, will remove all NaNs from the path andinsert MOVETO commands to skip over them. clip : None or sequence, optional If not None, must be a four-tuple (x1, y1, x2, y2)defining a rectangle in which to clip the path. snap : None or bool, optional If None, auto-snap to pixels, to reducefuzziness of rectilinear lines. If True, force snapping, andif False, don’t snap. stroke_width : float, optional The width of the stroke being drawn. Needed as a hint for the snapping algorithm. simplify : None or bool, optional If True, perform simplification, to remove vertices that do not affect the appearance of the path. IfFalse, perform no simplification. If None, use theshould_simplify member variable. curves : {True, False}, optional If True, curve segments will be returned as curvesegments. If False, all curves will be converted to linesegments. sketch : None or sequence, optional If not None, must be a 3-tuple of the form(scale, length, randomness), representing the sketchparameters.

classmethodmake_compound_path(*args)¶

Make a compound path from a list of Path objects.

classmethodmake_compound_path_from_polys(XY)¶

Make a compound path object to draw a numberof polygons with equal numbers of sides XY is a (numpolys xnumsides x 2) numpy array of vertices. Return object is aPath

(Source code,png,pdf)

readonly¶

True if thePath is read-only.

should_simplify¶

True if the vertices array should be simplified.

simplify_threshold¶

The fraction of a pixel difference below which vertices willbe simplified out.

to_polygons(transform=None,width=0,height=0,closed_only=True)¶

Convert this path to a list of polygons or polylines. Eachpolygon/polyline is an Nx2 array of vertices. In other words,each polygon has noMOVETO instructions or curves. Thisis useful for displaying in backends that do not supportcompound paths or Bezier curves, such as GDK.

Ifwidth andheight are both non-zero then the lines willbe simplified so that vertices outside of (0, 0), (width,height) will be clipped.

Ifclosed_only isTrue (default), only closed polygons,with the last point being the same as the first point, will bereturned. Any unclosed polylines in the path will beexplicitly closed. Ifclosed_only isFalse, any unclosedpolygons in the path will be returned as unclosed polygons,and the closed polygons will be returned explicitly closed bysetting the last point to the same as the first point.

transformed(transform)¶

Return a transformed copy of the path.

See also

matplotlib.transforms.TransformedPath

A specialized path class that will cache thetransformed result and automatically update when thetransform changes.

classmethodunit_circle()¶

Return the readonlyPath of the unit circle.

For most cases,Path.circle() will be what you want.

classmethodunit_circle_righthalf()¶

Return aPath of the right halfof a unit circle. The circle is approximated using cubic Beziercurves. This uses 4 splines around the circle using the approachpresented here:

Lancaster, Don.Approximating a Circle or an Ellipse Using FourBezier Cubic Splines.

classmethodunit_rectangle()¶

Return aPath instance of the unit rectanglefrom (0, 0) to (1, 1).

classmethodunit_regular_asterisk(numVertices)¶

Return aPath for a unit regularasterisk with the given numVertices and radius of 1.0,centered at (0, 0).

classmethodunit_regular_polygon(numVertices)¶

Return aPath instance for a unit regularpolygon with the givennumVertices and radius of 1.0,centered at (0, 0).

classmethodunit_regular_star(numVertices,innerCircle=0.5)¶

Return aPath for a unit regular starwith the given numVertices and radius of 1.0, centered at (0,0).

vertices¶

The list of vertices in thePath as an Nx2 numpy array.

classmethodwedge(theta1,theta2,n=None)¶

Return a wedge of the unit circle from angletheta1 to angletheta2 (in degrees).

Ifn is provided, it is the number of spline segments to make.Ifn is not provided, the number of spline segments isdetermined based on the delta betweentheta1 andtheta2.

matplotlib.path.get_path_collection_extents(master_transform,paths,transforms,offsets,offset_transform)¶

Given a sequence ofPath objects,Transform objects and offsets, asfound in aPathCollection,returns the bounding box that encapsulates all of them.

master_transform is a global transformation to apply to all paths

paths is a sequence ofPath instances.

transforms is a sequence ofAffine2D instances.

offsets is a sequence of (x, y) offsets (or an Nx2 array)

offset_transform is aAffine2Dto apply to the offsets before applying the offset to the path.

The way thatpaths,transforms andoffsets are combinedfollows the same method as for collections. Each is iterated overindependently, so if you have 3 paths, 2 transforms and 1 offset,their combinations are as follows:

(A, A, A), (B, B, A), (C, A, A)

matplotlib.path.get_paths_extents(paths,transforms=[])¶

Given a sequence ofPath objects and optionalTransform objects, returns thebounding box that encapsulates all of them.

paths is a sequence ofPath instances.

transforms is an optional sequence ofAffine2D instances to apply toeach path.