Master Matplotlib From Scratch

Learn Matplotlib fundamentals, figure anatomy, basic plotting, chart customization, subplots, statistical visualizations, color mapping, annotations, 3D plotting, animations, and interactive visualizations through structured practical lessons.

COURSE SYLLABUS
1. Introduction & Environment Setup
What is Matplotlib? Installation Environment Setup Imports and Conventions
2. Core Figure Anatomy & Structures
Figure vs Axes Creating Canvas Dimensions and Resolution Saving Visuals
3. Basic Plotting
Line Plots Scatter Plots Bar Charts Histograms
4. Basic Visual Formatting & Labels
Titles and Labels Text Customization Legends Grid Lines
5. Advanced Plot Customization
Format Strings Line and Marker Styling Color Systems Transparency
6. Axis Control, Ticks & Limits
Axis Limits Custom Ticks Tick Labels Axis Scaling
7. Multi-Plot Layouts & Subplots
Basic Subplots Indexing Subplots Layout Tuning Advanced Grids
8. Advanced Statistical & Data-Specific Plots
Pie Charts Box and Whisker Plots Violin Plots Error Bars
9. Color Mapping & 2D Data Visualizations
Colormaps Heatmaps and Images Colorbars Contour Plots
10. Annotations & Shapes
Basic Text Smart Annotations Drawing Shapes Shading Areas
11. Customizing Styles & Themes
Built-in Styles Custom Style Sheets Global Configurations
12. Object-Oriented API vs Pyplot
Pyplot vs Object-Oriented API Transitioning Methods Dual Axis Plots
13. Deep Integration with Pandas & Seaborn
Pandas Plotting Backend Seaborn Overlays Passing Axes
14. 3D Plotting
3D Setup 3D Lines and Scatter Surface and Wireframes Camera View
15. Dynamic & Live Plots
Interactive Mode Animation Module Real-time Updates Exporting Animations
16. Performance Optimization & Interactive Backends
Plotting Speed Interactive Backends Event Handling

Drawing Shapes in Matplotlib

Learn how to draw rectangles, circles, ellipses, polygons, and arrows inside Matplotlib charts. Understand patches, coordinates, colours, borders, transparency, and shape positioning.

1. Learning Objectives

After completing this lesson, you will be able to:

  • Understand shapes and patches in Matplotlib.
  • Import shape classes from matplotlib.patches.
  • Draw rectangles using Rectangle.
  • Draw circles using Circle.
  • Create ellipses using Ellipse.
  • Draw custom polygons using Polygon.
  • Use FancyArrowPatch to draw arrows.
  • Customize shape colours, borders, and transparency.
  • Add shapes to axes using ax.add_patch().
  • Combine shapes with charts for practical visualisations.

2. Introduction to Drawing Shapes

Matplotlib is not only used to create line charts, bar charts, and statistical plots. It also allows us to draw different geometric shapes inside a figure.

These shapes are useful for highlighting chart regions, marking important areas, drawing boundaries, showing relationships, and creating simple diagrams.

Matplotlib provides a collection of shape objects called Patches. Most commonly used patch classes are available in matplotlib.patches.

Common shapes in Matplotlib

  • Rectangle - Draws rectangular shapes.
  • Circle - Draws circular shapes.
  • Ellipse - Draws oval or elliptical shapes.
  • Polygon - Draws custom closed polygons.
  • FancyArrowPatch - Draws customizable arrows.
Rectangle Circle Ellipse Polygon Arrow

Different geometric shapes supported by Matplotlib patches.

3. Understanding Patches

A patch is a 2D graphical object that represents a shape. Matplotlib uses patch objects to draw geometric shapes inside an Axes.

To draw a patch, we generally follow three steps:

  1. Import the required shape class.
  2. Create an object of that shape.
  3. Add the shape to an Axes using ax.add_patch().

Basic syntax

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle

fig, ax = plt.subplots()

shape = Rectangle(
    (1, 1),
    width=3,
    height=2
)

ax.add_patch(shape)

plt.show()

Output

A Matplotlib figure is displayed
with a rectangle added to the Axes.

Rectangle starting point: (1, 1)
Width: 3
Height: 2
Tip: The ax.add_patch() method adds a patch object to a specific Axes. It is commonly used when drawing shapes with the object-oriented Matplotlib interface.

4. Drawing Rectangles

A rectangle is a four-sided shape with opposite sides equal. Matplotlib provides the Rectangle class to draw rectangular shapes.

Import it using:

from matplotlib.patches import Rectangle

Rectangle syntax

Rectangle(
    xy,
    width,
    height,
    angle=0,
    **kwargs
)

Important arguments:

  • xy: Bottom-left starting position of the rectangle.
  • width: Width of the rectangle.
  • height: Height of the rectangle.
  • angle: Rotation angle in degrees.
  • facecolor: Interior fill colour.
  • edgecolor: Border colour.
  • linewidth: Border thickness.

Example: Creating a rectangle

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle

fig, ax = plt.subplots()

rectangle = Rectangle(
    (2, 2),
    width=4,
    height=3,
    facecolor="skyblue",
    edgecolor="blue",
    linewidth=2
)

ax.add_patch(rectangle)

ax.set_xlim(0, 10)
ax.set_ylim(0, 8)

ax.set_title("Rectangle Example")
ax.set_xlabel("X Axis")
ax.set_ylabel("Y Axis")

plt.show()

Output

A blue-bordered rectangle is displayed.

Starting position: (2, 2)
Width: 4
Height: 3
Fill colour: Sky blue
Border colour: Blue

The rectangle occupies the region
from X = 2 to X = 6
and Y = 2 to Y = 5.
Bottom-left Width Height X Coordinate

Rectangle position, width, and height determine its dimensions.

Example: Rotated rectangle

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle

fig, ax = plt.subplots()

rectangle = Rectangle(
    (3, 2),
    width=4,
    height=2,
    angle=30,
    facecolor="lightgreen",
    edgecolor="green",
    linewidth=2
)

ax.add_patch(rectangle)

ax.set_xlim(0, 10)
ax.set_ylim(0, 8)

ax.set_title("Rotated Rectangle")
plt.show()

Output

A rotated light-green rectangle is displayed
with a green border.

Rotation angle: 30 degrees
Starting position: (3, 2)
Width: 4
Height: 2
Practical Use: Rectangles are useful for highlighting a particular area of a chart, showing ranges, and marking selected regions in a visualisation.

5. Drawing Circles

A circle is a round shape where every point on its boundary is at the same distance from its centre.

Matplotlib provides the Circle class to create circular shapes.

from matplotlib.patches import Circle

Circle syntax

Circle(
    xy,
    radius,
    **kwargs
)

Important arguments:

  • xy: Centre coordinates of the circle.
  • radius: Radius of the circle.
  • facecolor: Interior colour.
  • edgecolor: Border colour.
  • linewidth: Border thickness.
  • alpha: Transparency level.

Example: Creating a circle

import matplotlib.pyplot as plt
from matplotlib.patches import Circle

fig, ax = plt.subplots()

circle = Circle(
    (5, 5),
    radius=2,
    facecolor="lightcoral",
    edgecolor="red",
    linewidth=2
)

ax.add_patch(circle)

ax.set_xlim(0, 10)
ax.set_ylim(0, 10)

ax.set_aspect("equal")
ax.set_title("Circle Example")

plt.show()

Output

A light-coral circle is displayed
with a red border.

Centre: (5, 5)
Radius: 2
Diameter: 4

The X and Y axes use equal scaling
to maintain the circular shape.
Radius Diameter Centre

A circle is defined by its centre coordinates and radius.

6. Drawing Ellipses

An ellipse is an oval-shaped figure. It has a horizontal radius and a vertical radius, which may have different lengths.

Matplotlib provides the Ellipse class for drawing elliptical shapes.

from matplotlib.patches import Ellipse

Ellipse syntax

Ellipse(
    xy,
    width,
    height,
    angle=0,
    **kwargs
)

Important arguments:

  • xy: Centre coordinates of the ellipse.
  • width: Total width of the ellipse.
  • height: Total height of the ellipse.
  • angle: Rotation angle in degrees.
  • facecolor: Fill colour.
  • edgecolor: Border colour.

Example: Creating an ellipse

import matplotlib.pyplot as plt
from matplotlib.patches import Ellipse

fig, ax = plt.subplots()

ellipse = Ellipse(
    (5, 5),
    width=6,
    height=3,
    angle=0,
    facecolor="lightyellow",
    edgecolor="orange",
    linewidth=2
)

ax.add_patch(ellipse)

ax.set_xlim(0, 10)
ax.set_ylim(0, 10)

ax.set_aspect("equal")
ax.set_title("Ellipse Example")

plt.show()

Output

A horizontal oval-shaped ellipse is displayed.

Centre: (5, 5)
Width: 6
Height: 3
Rotation: 0 degrees

Fill colour: Light yellow
Border colour: Orange

Example: Rotated ellipse

import matplotlib.pyplot as plt
from matplotlib.patches import Ellipse

fig, ax = plt.subplots()

ellipse = Ellipse(
    (5, 5),
    width=6,
    height=3,
    angle=45,
    facecolor="lightblue",
    edgecolor="blue",
    linewidth=2
)

ax.add_patch(ellipse)

ax.set_xlim(0, 10)
ax.set_ylim(0, 10)

ax.set_aspect("equal")
ax.set_title("Rotated Ellipse")

plt.show()

Output

A light-blue ellipse is displayed
with a blue border.

Centre: (5, 5)
Width: 6
Height: 3
Rotation: 45 degrees
Remember: The width and height of an ellipse represent its full dimensions, not its radii.

7. Drawing Polygons

A polygon is a closed shape made using multiple connected straight lines. It can have three or more sides.

Matplotlib provides the Polygon class to draw custom shapes using a collection of vertices.

from matplotlib.patches import Polygon

Polygon syntax

Polygon(
    xy,
    closed=True,
    **kwargs
)

Important arguments:

  • xy: List of vertex coordinates.
  • closed: Determines whether the polygon is closed.
  • facecolor: Interior fill colour.
  • edgecolor: Border colour.
  • linewidth: Border thickness.

Example: Creating a triangle

import matplotlib.pyplot as plt
from matplotlib.patches import Polygon

fig, ax = plt.subplots()

points = [
    (2, 2),
    (5, 7),
    (8, 2)
]

triangle = Polygon(
    points,
    closed=True,
    facecolor="lightgreen",
    edgecolor="green",
    linewidth=2
)

ax.add_patch(triangle)

ax.set_xlim(0, 10)
ax.set_ylim(0, 10)

ax.set_aspect("equal")
ax.set_title("Triangle Polygon")

plt.show()

Output

A green triangle is displayed.

Vertex 1: (2, 2)
Vertex 2: (5, 7)
Vertex 3: (8, 2)

The polygon is closed and filled
with light green colour.

Example: Creating a custom polygon

import matplotlib.pyplot as plt
from matplotlib.patches import Polygon

fig, ax = plt.subplots()

points = [
    (2, 2),
    (3, 6),
    (5, 8),
    (8, 6),
    (9, 2)
]

polygon = Polygon(
    points,
    closed=True,
    facecolor="plum",
    edgecolor="purple",
    linewidth=2
)

ax.add_patch(polygon)

ax.set_xlim(0, 11)
ax.set_ylim(0, 10)

ax.set_aspect("equal")
ax.set_title("Custom Polygon")

plt.show()

Output

A custom five-vertex polygon is displayed.

The shape is created using five coordinates.
The polygon is closed and filled with plum colour.
Its border is purple.
Practical Use: Polygons are useful for drawing custom regions, map boundaries, triangular markers, and other geometric diagrams.

8. Drawing Arrows Using FancyArrowPatch

Matplotlib provides FancyArrowPatch to draw customizable arrows between two points.

It is useful when you want to show direction, movement, relationships, or connections between different parts of a chart.

from matplotlib.patches import FancyArrowPatch

Basic syntax

FancyArrowPatch(
    posA,
    posB,
    arrowstyle="->",
    **kwargs
)

Important arguments:

  • posA: Starting point of the arrow.
  • posB: Ending point of the arrow.
  • arrowstyle: Defines the arrow style.
  • color: Arrow colour.
  • linewidth: Arrow line thickness.
  • mutation_scale: Controls arrowhead size.
  • connectionstyle: Controls the connection path.

Example: Creating an arrow

import matplotlib.pyplot as plt
from matplotlib.patches import FancyArrowPatch

fig, ax = plt.subplots()

arrow = FancyArrowPatch(
    (2, 3),
    (8, 7),
    arrowstyle="->",
    color="red",
    linewidth=2,
    mutation_scale=20
)

ax.add_patch(arrow)

ax.set_xlim(0, 10)
ax.set_ylim(0, 10)

ax.set_title("Fancy Arrow Example")

plt.show()

Output

A red arrow is displayed.

Starting point: (2, 3)
Ending point: (8, 7)
Arrow style: ->
Line width: 2
Arrowhead scale: 20

Example: Double-headed arrow

import matplotlib.pyplot as plt
from matplotlib.patches import FancyArrowPatch

fig, ax = plt.subplots()

arrow = FancyArrowPatch(
    (2, 5),
    (8, 5),
    arrowstyle="<->",
    color="blue",
    linewidth=2,
    mutation_scale=20
)

ax.add_patch(arrow)

ax.set_xlim(0, 10)
ax.set_ylim(0, 10)

ax.set_title("Double-Headed Arrow")

plt.show()

Output

A blue horizontal arrow is displayed
with arrowheads at both ends.

Starting point: (2, 5)
Ending point: (8, 5)
Arrow style: <->
Tip: Use FancyArrowPatch when you need more control over an arrow's appearance than a simple line with an arrowhead.

9. Customizing Shape Appearance

Matplotlib patch objects support several properties that allow us to customize the appearance of shapes.

Property Purpose Example
facecolor Sets the inside fill colour. facecolor="skyblue"
edgecolor Sets the border colour. edgecolor="blue"
linewidth Controls border thickness. linewidth=2
alpha Controls transparency. alpha=0.5
linestyle Changes border line style. linestyle="dashed"
zorder Controls drawing order. zorder=3

Example: Styling a rectangle

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle

fig, ax = plt.subplots()

rectangle = Rectangle(
    (2, 2),
    width=5,
    height=3,
    facecolor="orange",
    edgecolor="red",
    linewidth=3,
    linestyle="dashed",
    alpha=0.6
)

ax.add_patch(rectangle)

ax.set_xlim(0, 10)
ax.set_ylim(0, 8)

ax.set_title("Styled Rectangle")

plt.show()

Output

An orange rectangle is displayed.

Fill colour: Orange
Border colour: Red
Border style: Dashed
Border width: 3
Transparency: 0.6

Understanding transparency

The alpha parameter controls how transparent a shape is. Its value generally ranges from 0 to 1.

  • alpha=0 means fully transparent.
  • alpha=0.5 means partially transparent.
  • alpha=1 means fully opaque.

10. Drawing Multiple Shapes in One Figure

We can add multiple patch objects to the same Axes. This allows us to create diagrams containing different shapes.

Example: Rectangle, Circle, and Ellipse

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle, Circle, Ellipse

fig, ax = plt.subplots(figsize=(9, 5))

rectangle = Rectangle(
    (1, 2),
    2,
    3,
    facecolor="skyblue",
    edgecolor="blue"
)

circle = Circle(
    (5, 3.5),
    1,
    facecolor="lightgreen",
    edgecolor="green"
)

ellipse = Ellipse(
    (8, 3.5),
    2,
    1,
    facecolor="lightcoral",
    edgecolor="red"
)

ax.add_patch(rectangle)
ax.add_patch(circle)
ax.add_patch(ellipse)

ax.set_xlim(0, 10)
ax.set_ylim(0, 7)

ax.set_aspect("equal")
ax.set_title("Multiple Shapes")

plt.show()

Output

One Matplotlib figure displays three shapes:

1. Blue rectangle
2. Green circle
3. Red ellipse

All three shapes are added to the same Axes.
Rectangle Circle Ellipse

Multiple patch objects can be displayed inside a single Axes.

11. Combining Shapes with Charts

Shapes can also be added to normal charts. For example, we can highlight a specific range in a line chart using a rectangle or mark a particular point using a circle.

Example: Highlighting a chart region

import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle

months = [1, 2, 3, 4, 5, 6]
sales = [10, 15, 12, 25, 30, 28]

fig, ax = plt.subplots()

ax.plot(
    months,
    sales,
    marker="o",
    color="blue"
)

highlight = Rectangle(
    (3.5, 0),
    width=2,
    height=35,
    facecolor="yellow",
    edgecolor="orange",
    alpha=0.25
)

ax.add_patch(highlight)

ax.set_xlim(0, 7)
ax.set_ylim(0, 35)

ax.set_title("Sales Chart with Highlighted Region")
ax.set_xlabel("Month")
ax.set_ylabel("Sales")

plt.show()

Output

A line chart displays monthly sales.

A transparent yellow rectangle
highlights the region between
X = 3.5 and X = 5.5.

The sales line remains visible
through the transparent rectangle.

Example: Highlighting a specific data point

import matplotlib.pyplot as plt
from matplotlib.patches import Circle

fig, ax = plt.subplots()

x = [1, 2, 3, 4, 5]
y = [10, 20, 15, 35, 50]

ax.plot(x, y, marker="o")

highlight = Circle(
    (5, 50),
    radius=0.4,
    facecolor="none",
    edgecolor="red",
    linewidth=2
)

ax.add_patch(highlight)

ax.set_xlim(0, 6)
ax.set_ylim(0, 60)

ax.set_title("Highlighted Data Point")

plt.show()

Output

A line chart is displayed.

The data point (5, 50) is surrounded
by a red circular outline.

The other data points remain unchanged.
Practical Use: Use shapes to highlight selected regions, important values, threshold areas, and specific events in business and scientific charts.

12. Comparison of Shape Classes

Shape Class Purpose Main Arguments
Rectangle Draws rectangular shapes. xy, width, height
Circle Draws circular shapes. xy, radius
Ellipse Draws oval shapes. xy, width, height
Polygon Draws custom closed shapes. xy, closed
FancyArrowPatch Draws customizable arrows. posA, posB, arrowstyle
Important: For most shapes, set suitable axis limits using ax.set_xlim() and ax.set_ylim(). Otherwise, a shape may appear outside the visible plotting region.

13. Practical Activity

Activity: Create a Simple Business Diagram

Create a figure containing different shapes to represent a simple business process.

Your tasks:

  1. Create a rectangle to represent the Start section.
  2. Create a circle to represent a decision point.
  3. Create an ellipse to represent a process.
  4. Use a polygon to represent a custom step.
  5. Connect the shapes using arrows.
  6. Use different colours for every shape.
  7. Add text labels to explain each shape.
  8. Set suitable X-axis and Y-axis limits.

14. Practice Questions

  1. What are patches in Matplotlib?
  2. Which module provides common Matplotlib shape classes?
  3. How do you draw a rectangle?
  4. What is the difference between Circle and Ellipse?
  5. Which argument defines the centre of a circle?
  6. How can you create a custom polygon?
  7. What is the purpose of ax.add_patch()?
  8. How do you change the fill and border colours of a shape?
  9. What is the purpose of the alpha parameter?
  10. How can you draw a double-headed arrow?
  11. How can shapes highlight a particular chart region?
  12. Why are axis limits important when drawing shapes?

Summary

In this lesson, we learned how to draw geometric shapes in Matplotlib using patch classes from matplotlib.patches. We understood how patch objects are created and added to an Axes using ax.add_patch().

We explored the Rectangle class for rectangular shapes, Circle for circular shapes, and Ellipse for oval shapes. We also learned how to create custom polygons using Polygon.

We used FancyArrowPatch to create arrows and learned how to customize shape properties such as fill colour, border colour, line width, line style, transparency, and drawing order.

Finally, we combined shapes with charts to highlight important regions and data points. In the next lesson, we will learn how to shade areas between curves and highlight selected regions using Matplotlib shading functions.