@@ -14,9 +14,10 @@ Creating, viewing, and saving Matplotlib Figures
1414When looking at Matplotlib visualization, you are almost always looking at
1515Artists placed on a `~.Figure `. In the example above, the figure is the
1616gray region and `~.Figure.add_subplot ` has added an `~.axes.Axes ` artist to the
17- `~.Figure ` (see:ref: `figure_parts `). A more complicated visualization can add multiple Axes to
18- the Figure, colorbars, legends, annotations, and the Axes theselves can have
19- multiple Artists added to them (e.g. ``ax.plot `` or ``ax.imshow ``).
17+ `~.Figure ` (see:ref: `figure_parts `). A more complicated visualization can add
18+ multiple Axes to the Figure, colorbars, legends, annotations, and the Axes
19+ themselves can have multiple Artists added to them
20+ (e.g. ``ax.plot `` or ``ax.imshow ``).
2021
2122.. _viewing_figures :
2223
@@ -70,8 +71,9 @@ By far the most common way to create a figure is using the
7071:ref: `api_interfaces `, the pyplot interface serves two purposes. One is to spin
7172up the Backend and keep track of GUI windows. The other is a global state for
7273Axes and Artists that allow a short-form API to plotting methods. In the
73- example above, we only use pyplot for the first purpose, to create the Figure
74- object, ``fig ``.
74+ example above, we use pyplot for the first purpose, and create the Figure object,
75+ ``fig ``. As a side effect ``fig `` is also added to pyplot's global state, and
76+ can be accessed via `~.pyplot.gcf `.
7577
7678In addition to `~.pyplot.figure `, there are convenience methods to create Axes
7779at the same time that the figure is created since these two actions are so commonly
@@ -144,6 +146,25 @@ rescale axes inside the Figure to prevent overlap of ticklabels, and try and ali
144146axes, and can save significant manual adjustment of artists on a Figure for many
145147common cases.
146148
149+ Adding Artists
150+ --------------
151+
152+ The `~.FigureBase ` class has a number of methods to add artists to a `~.Figure ` or
153+ a `~.SubFigure `. By far the most common are to add Axes of various configurations
154+ (`~.FigureBase.add_axes `, `~.FigureBase.add_subplot `, `~.FigureBase.subplots `,
155+ `~.FigureBase.subplot_mosaic `) and subfigures (`~.FigureBase.subfigures `). Colorbars
156+ are added to Axes or group of Axes at the Figure level (`~.FigureBase.colorbar `).
157+ It is also possible to have a Figure-level legend (`~.FigureBase.legend `).
158+ Other Artists include figure-wide labels (`~.suptitle `,
159+ `~.subxlabel `, `~.subpylabel `) and text (`~.FigureBase.text `). Finally, low-level
160+ Artists can be added directly using `~.FigureBase.add_artist ` usually with care being
161+ taken to use the appropriate transform. Usually these include ``Figure.transFigure ``
162+ which ranges from 0 to 1 in each direction, and represents the fraction of the current
163+ Figure size, or ``Figure.dpi_scale_trans `` which will be in physical units of inches
164+ from the bottom left corner of the Figure (see
165+ :doc: `/tutorials/advanced/transforms_tutorial ` for more details).
166+
167+
147168.. _saving_figures :
148169
149170Saving Figures