The artist layer constitutes the bulk of what matplotlib actually does—the generation of the plots for the purpose of display, manipulation, and publication. Most work in the artist layer is performed by a number of classes, most of which are derived from the Artist base class.
The artist layer is concerned with things such as the lines, shapes, axes, text, and so on. These are the subclasses of the Artist class that define things such as the following:
- A canvas-artist coordinate transformation
- Visibility
- A clip box that defines the paintable area
- Labels
- A callback registry instance to handle user interaction events
The Artist subclasses can be classified into one of the following two groups:
- Primitives
- Containers
The following two sections provide more details about these groups.
The matplotlib artist primitives are classes of graphical objects that are supposed to be painted on a figure's canvas. These include, but are not limited to, the following:
Line2D- Shape (patch) classes such as
Rectangle,Polygon,Ellipse,Circle,ArcText,Annotation, andTextPath AxesImageandFigureImage
Each of these primitive classes is a subclass of Artist, and as such have at their core the same definition of purpose—something that renders into an implementation of FigureCanvasBase.
This is another set of classes that subclass from Artist and which have additional responsibilities. They offer a useful abstraction to gather primitives. Examples of the containers include the following:
FigureXAxisandYAxisAxes,PolarAxes,HammerAxes,MollweideAxes, andLambertAxesSubplot
Typically, a Figure would be instantiated and used to create one or more Axes or Subplot instances. The methods available for these objects would then be used to create the primitives as needed. Thus the user does not have to manually track the creation of the primitives and store them in the appropriate containers.
Of all the containers, the Axes class is one of the most important. It is the primary mover and shaker in the artist layer. The reason for this is simple—the Axes instances are where most of the matplotlib objects go (both primitives and other containers). In addition to the creation of primitives, the methods of this class can prepare the supplied data that is needed for the creation of primitives such as lines and shapes, add them to the appropriate containers, and draw them when called by some other objects.
Furthermore, the Axes objects set the coordinate system for the figure and track callbacks that can be connected to the xlim_changed and ylim_changed events. The callbacks will be called with the Axes instances as an argument.
Another component of the artist layer that we will touch on briefly is collections. These are the classes that provide for the efficient drawing of large numbers of similar objects. If you find yourself creating tens or hundreds of thousands of circles, polygons, lines, and so on, in most cases you will get much better performance from matplotlib if you put these in collections. The available classes include, but are not limited to PathCollection, CircleCollection, PolyCollection, EllipseCollection, LineCollection, and EventCollection.
We now have enough additional information to create a diagram of the artist layer:
You may notice that a base class may paradoxically contain a parent class. This is really just a reference to a parent class that is often created at the time of creating the base class. Keeping this in mind is helpful when investigating matplotlib internals.
Like the logical backend diagram, the matplotlib internals is not intended to be comprehensive. However, it was meant to provide a conceptual aid for the visually oriented when thinking about how the bits fit together.
With this, we are brought to the final layer of the matplotlib architecture.