From 12aaf517909970769987627984d97c38a50e2ac9 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 26 Apr 2019 16:24:55 +0200
Subject: [PATCH] Improve fill() example

---
 .flake8                                 |  1 +
 examples/lines_bars_and_markers/fill.py | 98 +++++++++++++++++++------
 2 files changed, 75 insertions(+), 24 deletions(-)

diff --git a/.flake8 b/.flake8
index aa7c8e5dd2ed..f2fa5cccf8d6 100644
--- a/.flake8
+++ b/.flake8
@@ -137,6 +137,7 @@ per-file-ignores =
     examples/images_contours_and_fields/triplot_demo.py: E201, E402
     examples/images_contours_and_fields/watermark_image.py: E402
     examples/lines_bars_and_markers/errorbar_limits_simple.py: E402
+    examples/lines_bars_and_markers/fill.py: E402
     examples/lines_bars_and_markers/fill_between_demo.py: E402
     examples/lines_bars_and_markers/filled_step.py: E402
     examples/lines_bars_and_markers/joinstyle.py: E402
diff --git a/examples/lines_bars_and_markers/fill.py b/examples/lines_bars_and_markers/fill.py
index 21f92d87c2ca..f254949cd212 100644
--- a/examples/lines_bars_and_markers/fill.py
+++ b/examples/lines_bars_and_markers/fill.py
@@ -1,43 +1,93 @@
 """
 ==============
-Fill plot demo
+Filled polygon
 ==============
 
-Demo fill plot.
+`~.Axes.fill()` draws a filled polygon based based on lists of point
+coordinates *x*, *y*.
+
+This example uses the `Koch snowflake`_ as an example polygon.
+
+.. _Koch snowflake: https://en.wikipedia.org/wiki/Koch_snowflake
+
 """
 
-###############################################################################
-# First, the most basic fill plot a user can make with matplotlib:
 import numpy as np
 import matplotlib.pyplot as plt
 
-x = [0, 1, 2, 1]
-y = [1, 2, 1, 0]
 
-fig, ax = plt.subplots()
-ax.fill(x, y)
-plt.show()
+def koch_snowflake(order, scale=10):
+    """
+    Return two lists x, y of point coordinates of the Koch snowflake.
+
+    Arguments
+    ---------
+    order : int
+        The recursion depth.
+    scale : float
+        The extent of the snowflake (edge length of the base triangle).
+    """
+    def _koch_snowflake_complex(order):
+        if order == 0:
+            # initial triangle
+            angles = np.array([0, 120, 240]) + 90
+            return scale / np.sqrt(3) * np.exp(np.deg2rad(angles) * 1j)
+        else:
+            ZR = 0.5 - 0.5j * np.sqrt(3) / 3
+
+            p1 = _koch_snowflake_complex(order - 1)  # start points
+            p2 = np.roll(p1, shift=-1)  # end points
+            dp = p2 - p1  # connection vectors
+
+            new_points = np.empty(len(p1) * 4, dtype=np.complex128)
+            new_points[::4] = p1
+            new_points[1::4] = p1 + dp / 3
+            new_points[2::4] = p1 + dp * ZR
+            new_points[3::4] = p1 + dp / 3 * 2
+            return new_points
+
+    points = _koch_snowflake_complex(order)
+    x, y = points.real, points.imag
+    return x, y
+
 
 ###############################################################################
-# Next, a few more optional features:
-#
-# * Multiple curves with a single command.
-# * Setting the fill color.
-# * Setting the opacity (alpha value).
+# Basic usage:
 
+x, y = koch_snowflake(order=5)
 
-x = np.linspace(0, 1.5 * np.pi, 500)
-y1 = np.sin(x)
-y2 = np.sin(3 * x)
+plt.figure(figsize=(8, 8))
+plt.axis('equal')
+plt.fill(x, y)
+plt.show()
 
-fig, ax = plt.subplots()
+###############################################################################
+# Use keyword arguments *facecolor* and *edgecolor* to modify the the colors
+# of the polygon. Since the *linewidth* of the edge is 0 in the default
+# Matplotlib style, we have to set it as well for the edge to become visible.
 
-ax.fill(x, y1, 'b', x, y2, 'r', alpha=0.3)
+x, y = koch_snowflake(order=2)
 
-# Outline of the region we've filled in
-ax.plot(x, y1, c='b', alpha=0.8)
-ax.plot(x, y2, c='r', alpha=0.8)
-ax.plot([x[0], x[-1]], [y1[0], y1[-1]], c='b', alpha=0.8)
-ax.plot([x[0], x[-1]], [y2[0], y2[-1]], c='r', alpha=0.8)
+fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize=(9, 3),
+                                    subplot_kw={'aspect': 'equal'})
+ax1.fill(x, y)
+ax2.fill(x, y, facecolor='lightsalmon', edgecolor='orangered', linewidth=3)
+ax3.fill(x, y, facecolor='none', edgecolor='purple', linewidth=3)
 
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods, classes and modules is shown
+# in this example:
+
+import matplotlib
+matplotlib.axes.Axes.fill
+matplotlib.pyplot.fill
+matplotlib.axes.Axes.axis
+matplotlib.pyplot.axis