<divid="unreleased-message"> You are reading an old version of the documentation (v1.5.3). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<spanid="id1"></span><h1>Path Tutorial<aclass="headerlink" href="#path-tutorial" title="Permalink to this headline">¶</a></h1>
<p>The object underlying all of the <codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib.patch</span></code> objects is
the <aclass="reference internal" href="../api/path_api.html#matplotlib.path.Path" title="matplotlib.path.Path"><codeclass="xref py py-class docutils literal"><spanclass="pre">Path</span></code></a>, which supports the standard set of
moveto, lineto, curveto commands to draw simple and compound outlines
consisting of line segments and splines. The <codeclass="docutils literal"><spanclass="pre">Path</span></code> is instantiated
with a (N,2) array of (x,y) vertices, and a N-length array of path
codes. For example to draw the unit rectangle from (0,0) to (1,1), we
<h2>Compound paths<aclass="headerlink" href="#compound-paths" title="Permalink to this headline">¶</a></h2>
<p>All of the simple patch primitives in matplotlib, Rectangle, Circle,
Polygon, etc, are implemented with simple path. Plotting functions
like <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.hist" title="matplotlib.axes.Axes.hist"><codeclass="xref py py-meth docutils literal"><spanclass="pre">hist()</span></code></a> and
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.bar" title="matplotlib.axes.Axes.bar"><codeclass="xref py py-meth docutils literal"><spanclass="pre">bar()</span></code></a>, which create a number of
primitives, e.g., a bunch of Rectangles, can usually be implemented more
efficiently using a compound path. The reason <codeclass="docutils literal"><spanclass="pre">bar</span></code> creates a list
of rectangles and not a compound path is largely historical: the
<aclass="reference internal" href="../api/path_api.html#matplotlib.path.Path" title="matplotlib.path.Path"><codeclass="xref py py-class docutils literal"><spanclass="pre">Path</span></code></a> code is comparatively new and <codeclass="docutils literal"><spanclass="pre">bar</span></code>
predates it. While we could change it now, it would break old code,
so here we will cover how to create compound paths, replacing the
functionality in bar, in case you need to do so in your own code for
efficiency reasons, e.g., you are creating an animated bar plot.</p>
<p>We will make the histogram chart by creating a series of rectangles
for each histogram bar: the rectangle width is the bin width and the
rectangle height is the number of datapoints in that bin. First we’ll
create some random normally distributed data and compute the
histogram. Because numpy returns the bin edges and not centers, the
length of <codeclass="docutils literal"><spanclass="pre">bins</span></code> is 1 greater than the length of <codeclass="docutils literal"><spanclass="pre">n</span></code> in the
example below:</p>
<divclass="highlight-default"><divclass="highlight"><pre><span></span><spanclass="c1"># histogram our data with numpy</span>
<p>We’ll now extract the corners of the rectangles. Each of the
<codeclass="docutils literal"><spanclass="pre">left</span></code>, <codeclass="docutils literal"><spanclass="pre">bottom</span></code>, etc, arrays below is <codeclass="docutils literal"><spanclass="pre">len(n)</span></code>, where <codeclass="docutils literal"><spanclass="pre">n</span></code> is
the array of counts for each histogram bar:</p>
<divclass="highlight-default"><divclass="highlight"><pre><span></span><spanclass="c1"># get the corners of the rectangles for the histogram</span>
<p>Now we have to construct our compound path, which will consist of a
series of <codeclass="docutils literal"><spanclass="pre">MOVETO</span></code>, <codeclass="docutils literal"><spanclass="pre">LINETO</span></code> and <codeclass="docutils literal"><spanclass="pre">CLOSEPOLY</span></code> for each rectangle.
For each rectangle, we need 5 vertices: 1 for the <codeclass="docutils literal"><spanclass="pre">MOVETO</span></code>, 3 for
the <codeclass="docutils literal"><spanclass="pre">LINETO</span></code>, and 1 for the <codeclass="docutils literal"><spanclass="pre">CLOSEPOLY</span></code>. As indicated in the
table above, the vertex for the closepoly is ignored but we still need
it to keep the codes aligned with the vertices:</p>