matplotlib · dstansby · Oct 5, 2021 · Jul 23, 2021 · Aug 26, 2021 · Sep 5, 2021
diff --git a/doc/users/next_whats_new/extending_MarkerStyle.rst b/doc/users/next_whats_new/extending_MarkerStyle.rst
@@ -0,0 +1,19 @@
+New customization of MarkerStyle
+--------------------------------
+
+New MarkerStyle parameters allow control of join style and cap style, and for
+the user to supply a transformation to be applied to the marker (e.g. a rotation).
+
+.. plot::
+    :include-source: true
+
+    import matplotlib.pyplot as plt
+    from matplotlib.markers import MarkerStyle
+    from matplotlib.transforms import Affine2D
+    fig, ax = plt.subplots(figsize=(6, 1))
+    fig.suptitle('New markers', fontsize=14)
+    for col, (size, rot) in enumerate(zip([2, 5, 10], [0, 45, 90])):
+        t = Affine2D().rotate_deg(rot).scale(size)
+        ax.plot(col, 0, marker=MarkerStyle("*", transform=t))
+    ax.axis("off")
+    ax.set_xlim(-0.1, 2.4)
diff --git a/examples/lines_bars_and_markers/marker_reference.py b/examples/lines_bars_and_markers/marker_reference.py
@@ -19,8 +19,10 @@
 .. redirect-from:: /gallery/shapes_and_collections/marker_path
 """
 
+from matplotlib.markers import MarkerStyle
 import matplotlib.pyplot as plt
 from matplotlib.lines import Line2D
+from matplotlib.transforms import Affine2D
 
 
 text_style = dict(horizontalalignment='right', verticalalignment='center',
@@ -159,3 +161,96 @@ def split_list(a_list):
 format_axes(ax)
 
 plt.show()
+
+###############################################################################
+# Advanced marker modifications with transform
+# ============================================
+#
+# Markers can be modified by passing a transform to the MarkerStyle
+# constructor. Following example shows how a supplied rotation is applied to
+# several marker shapes.
+
+common_style = {k: v for k, v in filled_marker_style.items() if k != 'marker'}
+angles = [0, 10, 20, 30, 45, 60, 90]
+
+fig, ax = plt.subplots()
+fig.suptitle('Rotated markers', fontsize=14)
+
+ax.text(-0.5, 0, 'Filled marker', **text_style)
+for x, theta in enumerate(angles):
+    t = Affine2D().rotate_deg(theta)
+    ax.plot(x, 0, marker=MarkerStyle('o', 'left', t), **common_style)
+
+ax.text(-0.5, 1, 'Un-filled marker', **text_style)
+for x, theta in enumerate(angles):
+    t = Affine2D().rotate_deg(theta)
+    ax.plot(x, 1, marker=MarkerStyle('1', 'left', t), **common_style)
+
+ax.text(-0.5, 2, 'Equation marker', **text_style)
+for x, theta in enumerate(angles):
+    t = Affine2D().rotate_deg(theta)
+    eq = r'$\frac{1}{x}$'
+    ax.plot(x, 2, marker=MarkerStyle(eq, 'left', t), **common_style)
+
+for x, theta in enumerate(angles):
+    ax.text(x, 2.5, f"{theta}°", horizontalalignment="center")
+format_axes(ax)
+
+fig.tight_layout()
+plt.show()
+
+###############################################################################
+# Setting marker cap style and join style
+# =======================================
+#
+# Markers have default cap and join styles, but these can be
+# customized when creating a MarkerStyle.
+
+from matplotlib.markers import JoinStyle, CapStyle
+
+marker_inner = dict(markersize=35,
+                    markerfacecolor='tab:blue',
+                    markerfacecoloralt='lightsteelblue',
+                    markeredgecolor='brown',
+                    markeredgewidth=8,
+                    )
+
+marker_outer = dict(markersize=35,
+                    markerfacecolor='tab:blue',
+                    markerfacecoloralt='lightsteelblue',
+                    markeredgecolor='white',
+                    markeredgewidth=1,
+                    )
+
+fig, ax = plt.subplots()
+fig.suptitle('Marker CapStyle', fontsize=14)
+fig.subplots_adjust(left=0.1)
+
+for y, cap_style in enumerate(CapStyle):
+    ax.text(-0.5, y, cap_style.name, **text_style)
+    for x, theta in enumerate(angles):
+        t = Affine2D().rotate_deg(theta)
+        m = MarkerStyle('1', transform=t, capstyle=cap_style)
+        ax.plot(x, y, marker=m, **marker_inner)
+        ax.plot(x, y, marker=m, **marker_outer)
+        ax.text(x, len(CapStyle) - .5, f'{theta}°', ha='center')
+format_axes(ax)
+plt.show()
+
+###############################################################################
+# Modifying the join style:
+
+fig, ax = plt.subplots()
+fig.suptitle('Marker JoinStyle', fontsize=14)
+fig.subplots_adjust(left=0.05)
+
+for y, join_style in enumerate(JoinStyle):
+    ax.text(-0.5, y, join_style.name, **text_style)
+    for x, theta in enumerate(angles):
+        t = Affine2D().rotate_deg(theta)
+        m = MarkerStyle('*', transform=t, joinstyle=join_style)
+        ax.plot(x, y, marker=m, **marker_inner)
+        ax.text(x, len(JoinStyle) - .5, f'{theta}°', ha='center')
+format_axes(ax)
+
+plt.show()
diff --git a/examples/lines_bars_and_markers/multivariate_marker_plot.py b/examples/lines_bars_and_markers/multivariate_marker_plot.py
@@ -0,0 +1,46 @@
+"""
+==============================================
+Mapping marker properties to multivariate data
+==============================================
+
+This example shows how to use different properties of markers to plot
+multivariate datasets. Here we represent a successful baseball throw as a
+smiley face with marker size mapped to the skill of thrower, marker rotation to
+the take-off angle, and thrust to the marker color.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.markers import MarkerStyle
+from matplotlib.transforms import Affine2D
+from matplotlib.textpath import TextPath
+from matplotlib.colors import Normalize
+
+SUCCESS_SYMBOLS = [
+    TextPath((0, 0), "☹"),
+    TextPath((0, 0), "😒"),
+    TextPath((0, 0), "☺"),
+]
+
+N = 25
+np.random.seed(42)
+skills = np.random.uniform(5, 80, size=N) * 0.1 + 5
+takeoff_angles = np.random.normal(0, 90, N)
+thrusts = np.random.uniform(size=N)
+successfull = np.random.randint(0, 3, size=N)
+positions = np.random.normal(size=(N, 2)) * 5
+data = zip(skills, takeoff_angles, thrusts, successfull, positions)
+
+cmap = plt.cm.get_cmap("plasma")
+fig, ax = plt.subplots()
+fig.suptitle("Throwing success", size=14)
+for skill, takeoff, thrust, mood, pos in data:
+    t = Affine2D().scale(skill).rotate_deg(takeoff)
+    m = MarkerStyle(SUCCESS_SYMBOLS[mood], transform=t)
+    ax.plot(pos[0], pos[1], marker=m, color=cmap(thrust))
+fig.colorbar(plt.cm.ScalarMappable(norm=Normalize(0, 1), cmap=cmap),
+             ax=ax, label="Normalized Thrust [a.u.]")
+ax.set_xlabel("X position [m]")
+ax.set_ylabel("Y position [m]")
+
+plt.show()
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -370,7 +370,10 @@ def __init__(self, xdata, ydata,
         self.set_color(color)
         if marker is None:
             marker = 'none'  # Default.
-        self._marker = MarkerStyle(marker, fillstyle)
+        if not isinstance(marker, MarkerStyle):
+            self._marker = MarkerStyle(marker, fillstyle)
+        else:
+            self._marker = marker
 
         self._markevery = None
         self._markersize = None