DOC: Improve fancybox demo

- Create subsections
- The plot for the different boxstyle attributes
  had mixed mutation_scale with Axes aspect. This makes
  it more difficult to understand. Therefore, we now
  show the effect of mutation_scale in isoliation.
- The aspect-correction topic is separated into an
  additional plot.

galleries/examples/shapes_and_collections/fancybox_demo.py

@@ -3,7 +3,8 @@
 Drawing fancy boxes
 ===================
 
-The following examples show how to plot boxes with different visual properties.
+The following examples show how to plot boxes (`.FancyBboxPatch`) with different
+visual properties.
 """
 
 import inspect
@@ -15,7 +16,12 @@
 import matplotlib.transforms as mtransforms
 
 # %%
-# First we'll show some sample boxes with fancybox.
+# Box styles
+# ----------
+# `.FancyBboxPatch` supports different `.BoxStyle`\s. Note that `~.Axes.text`
+# allows to draw a box around the text by adding the ``bbox`` parameter. Therefore,
+# you don't see explicit `.FancyBboxPatch` and `.BoxStyle` calls in the following
+# example.
 
 styles = mpatch.BoxStyle.get_styles()
 ncol = 2
@@ -41,13 +47,21 @@
 
 
 # %%
-# Next we'll show off multiple fancy boxes at once.
-
+# Parameters for modifying the box
+# --------------------------------
+# `.BoxStyle`\s have additional parameters to configure their appearance.
+# For example, "round" boxes can have ``pad`` and ``rounding``.
+#
+# Additionally, the `.FancyBboxPatch` parameters ``mutation_scale`` and
+# ``mutation_aspect`` scale the box appearance.
 
 def add_fancy_patch_around(ax, bb, **kwargs):
-    fancy = FancyBboxPatch(bb.p0, bb.width, bb.height,
-                           fc=(1, 0.8, 1, 0.5), ec=(1, 0.5, 1, 0.5),
-                           **kwargs)
+    kwargs = {
+        'facecolor': (1, 0.8, 1, 0.5),
+        'edgecolor': (1, 0.5, 1, 0.5),
+        **kwargs
+    }
+    fancy = FancyBboxPatch(bb.p0, bb.width, bb.height, **kwargs)
     ax.add_patch(fancy)
     return fancy
 
@@ -65,7 +79,7 @@ def draw_control_points_for_patches(ax):
 
 ax = axs[0, 0]
 # a fancy box with round corners. pad=0.1
-fancy = add_fancy_patch_around(ax, bb, boxstyle="round,pad=0.1")
+add_fancy_patch_around(ax, bb, boxstyle="round,pad=0.1")
 ax.set(xlim=(0, 1), ylim=(0, 1), aspect=1,
        title='boxstyle="round,pad=0.1"')
 
@@ -84,33 +98,61 @@ def draw_control_points_for_patches(ax):
 ax = axs[1, 0]
 # mutation_scale determines the overall scale of the mutation, i.e. both pad
 # and rounding_size is scaled according to this value.
-fancy = add_fancy_patch_around(
-    ax, bb, boxstyle="round,pad=0.1", mutation_scale=2)
+add_fancy_patch_around(ax, bb, boxstyle="round,pad=0.1", mutation_scale=2)
 ax.set(xlim=(0, 1), ylim=(0, 1), aspect=1,
        title='boxstyle="round,pad=0.1"\n mutation_scale=2')
 
 ax = axs[1, 1]
-# When the aspect ratio of the Axes is not 1, the fancy box may not be what you
-# expected (green).
-fancy = add_fancy_patch_around(ax, bb, boxstyle="round,pad=0.2")
-fancy.set(facecolor="none", edgecolor="green")
-# You can compensate this by setting the mutation_aspect (pink).
-fancy = add_fancy_patch_around(
-    ax, bb, boxstyle="round,pad=0.3", mutation_aspect=0.5)
-ax.set(xlim=(-.5, 1.5), ylim=(0, 1), aspect=2,
-       title='boxstyle="round,pad=0.3"\nmutation_aspect=.5')
+# mutation_aspect scales the vertical influence of the parameters (technically,
+# it scales the height of the box down by mutation_aspect, applies the box parameters
+# and scales the result back up). In effect, the vertical pad is scaled to
+# pad * mutation_aspect, e.g. mutation_aspect=0.5 halves the vertical pad.
+add_fancy_patch_around(ax, bb, boxstyle="round,pad=0.1", mutation_aspect=0.5)
+ax.set(xlim=(0, 1), ylim=(0, 1),
+       title='boxstyle="round,pad=0.1"\nmutation_aspect=0.5')
 
 for ax in axs.flat:
     draw_control_points_for_patches(ax)
     # Draw the original bbox (using boxstyle=square with pad=0).
-    fancy = add_fancy_patch_around(ax, bb, boxstyle="square,pad=0")
-    fancy.set(edgecolor="black", facecolor="none", zorder=10)
+    add_fancy_patch_around(ax, bb, boxstyle="square,pad=0",
+                           edgecolor="black", facecolor="none", zorder=10)
 
 fig.tight_layout()
 
 
 plt.show()
 
+# %%
+# Creating visually constant padding on non-equal aspect Axes
+# -----------------------------------------------------------
+# Since padding is in box coordinates, i.e. usually data coordinates,
+# a given padding is rendered to different visual sizes if the
+# Axes aspect is not 1.
+# To get visually equal vertical and horizontal padding, set the
+# mutation_aspect to the inverse of the Axes aspect. This scales
+# the vertical padding appropriately.
+
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6.5, 5))
+
+# original boxes
+bb = mtransforms.Bbox([[-0.5, -0.5], [0.5, 0.5]])
+add_fancy_patch_around(ax1, bb, boxstyle="square,pad=0",
+                       edgecolor="black", facecolor="none", zorder=10)
+add_fancy_patch_around(ax2, bb, boxstyle="square,pad=0",
+                       edgecolor="black", facecolor="none", zorder=10)
+ax1.set(xlim=(-1.5, 1.5), ylim=(-1.5, 1.5), aspect=2)
+ax2.set(xlim=(-1.5, 1.5), ylim=(-1.5, 1.5), aspect=2)
+
+
+fancy = add_fancy_patch_around(
+    ax1, bb, boxstyle="round,pad=0.5")
+ax1.set_title("aspect=2\nmutation_aspect=1")
+
+fancy = add_fancy_patch_around(
+    ax2, bb, boxstyle="round,pad=0.5", mutation_aspect=0.5)
+ax2.set_title("aspect=2\nmutation_aspect=0.5")
+
+
 # %%
 #
 # .. admonition:: References