WIP

Author: melissawm

doc/users/explain/architecture.rst

@@ -6,3 +6,83 @@ Matplotlib architecture
 
 .. _article: https://www.aosabook.org/en/matplotlib.html
 .. _blog: https://medium.datadriveninvestor.com/data-visualization-with-python-matplotlib-architecture-6b05af533569
+.. _she06: Maxim Shemanarev. Anti-Grain Geometry: A high quality rendering engine for C++, 2002-2006.
+
+Overview of matplotlib Architecture
+-----------------------------------
+
+The top-level matplotlib object that contains and manages all of the elements in
+a given graphic is called the Figure. 
+
+From :ref:`figure_parts`:
+
+    * :class:`~matplotlib.figure.Figure`
+      The **whole** figure.  The Figure keeps track of all the child
+      :class:`~matplotlib.axes.Axes`, a group of 'special' Artists (titles, figure
+      legends, colorbars, etc), and even nested subfigures.
+
+One of the core architectural tasks matplotlib must solve is implementing a
+framework for representing and manipulating the ``Figure`` that is segregated
+from the act of rendering the ``Figure`` to a user interface window or hardcopy.
+This enables us to build increasingly sophisticated features and logic into the
+``Figures``, while keeping the "backends", or output devices, relatively simple.
+matplotlib encapsulates not just the drawing interfaces to allow rendering to
+multiple devices, but also the basic event handling and windowing of most
+popular user interface toolkits. Because of this, users can create fairly rich
+interactive graphics and toolkits incorporating mouse and keyboard input that
+can be plugged without modification into the six user interface toolkits we
+support. [1]
+
+The architecture to accomplish this is logically separated into three layers,
+which can be viewed as a stack. Each layer that sits above another layer knows
+how to talk to the layer below it, but the lower layer is not aware of the
+layers above it. The three layers from bottom to top are: *backend*, *artist*,
+and *scripting*. [1]
+
+Backend Layer
+~~~~~~~~~~~~~
+
+At the bottom of the stack is the backend layer, which provides concrete
+implementations of the abstract interface classes:
+
+* ``FigureCanvas`` encapsulates the concept of a surface to draw onto (e.g. "the
+  paper").
+* ``Renderer`` does the drawing (e.g. "the paintbrush").
+* ``Event`` handles user inputs such as keyboard and mouse events.
+
+The abstract base class ``FigureCanvas`` has concrete implementations for all
+user interface toolkits, such as Qt and GTK. The abstract base classes reside in
+`matplotlib.backend_bases` and all of the derived classes live in dedicated
+modules like `matplotlib.backends.backend_qt4agg`.
+
+The job of the ``Renderer`` is to provide a low-level drawing interface for
+putting ink onto the canvas. One of the design decisions that has worked quite
+well for matplotlib is support for a core pixel-based renderer using the C++
+template library *Anti-Grain Geometry* or "agg" [She06]. This is a
+high-performance library for rendering anti-aliased 2D graphics that produces
+attractive images. matplotlib provides support for inserting pixel buffers
+rendered by the agg backend into each user interface toolkit we support, so one
+can get pixel-exact graphics across UIs and operating systems. Because the PNG
+output matplotlib produces also uses the agg renderer, the hardcopy is identical
+to the screen display, so what you see is what you get across UIs, operating
+systems and PNG output.
+
+The matplotlib ``Event`` framework maps underlying UI events like
+``key-press-event`` or ``mouse-motion-event`` to the matplotlib classes
+``KeyEvent`` or ``MouseEvent``. Users can connect to these events to callback
+functions and interact with their figure and data; for example, to pick a data
+point or group of points, or manipulate some aspect of the figure or its
+constituents.
+
+Artist layer
+~~~~~~~~~~~~
+
+The ``Artist`` is the object that knows how to take the ``Renderer`` (the
+paintbrush) and put ink on the canvas. Everything you see in a matplotlib
+``Figure`` is an ``Artist`` instance; the title, the lines, the tick labels, the
+images, and so on all correspond to individual ``Artist`` instances. The base
+class is ``matplotlib.artist.Artist``, which contains attributes that every
+``Artist`` shares.
+
+There is a hierarchy between artists in the same ``Figure``.
+