From be5aadb532273ea1c8ebb9784ed3ed3231a2a155 Mon Sep 17 00:00:00 2001
From: jacoverster <versterrie@gmail.com>
Date: Wed, 26 Oct 2022 11:24:24 +0200
Subject: [PATCH] Backport PR #24145: Updated Angles on Bracket arrow styles
 example to make angles clear #23176

---
 .../angles_on_bracket_arrows.py               | 64 +++++++++++++++++++
 lib/matplotlib/patches.py                     |  8 +++
 2 files changed, 72 insertions(+)
 create mode 100644 examples/text_labels_and_annotations/angles_on_bracket_arrows.py

diff --git a/examples/text_labels_and_annotations/angles_on_bracket_arrows.py b/examples/text_labels_and_annotations/angles_on_bracket_arrows.py
new file mode 100644
index 000000000000..35a6cad22130
--- /dev/null
+++ b/examples/text_labels_and_annotations/angles_on_bracket_arrows.py
@@ -0,0 +1,64 @@
+"""
+===================================
+Angle annotations on bracket arrows
+===================================
+
+This example shows how to add angle annotations to bracket arrow styles
+created using `.FancyArrowPatch`. *angleA* and *angleB* are measured from a
+vertical line as positive (to the left) or negative (to the right). Blue
+`.FancyArrowPatch` arrows indicate the directions of *angleA* and *angleB*
+from the vertical and axes text annotate the angle sizes.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.patches import FancyArrowPatch
+
+
+def get_point_of_rotated_vertical(origin, line_length, degrees):
+    """Return xy coordinates of the vertical line end rotated by degrees."""
+    rad = np.deg2rad(-degrees)
+    return [origin[0] + line_length * np.sin(rad),
+            origin[1] + line_length * np.cos(rad)]
+
+
+fig, ax = plt.subplots(figsize=(8, 7))
+ax.set(xlim=(0, 6), ylim=(-1, 4))
+ax.set_title("Orientation of the bracket arrows relative to angleA and angleB")
+
+for i, style in enumerate(["]-[", "|-|"]):
+    for j, angle in enumerate([-40, 60]):
+        y = 2*i + j
+        arrow_centers = ((1, y), (5, y))
+        vlines = ((1, y + 0.5), (5, y + 0.5))
+        anglesAB = (angle, -angle)
+        bracketstyle = f"{style}, angleA={anglesAB[0]}, angleB={anglesAB[1]}"
+        bracket = FancyArrowPatch(*arrow_centers, arrowstyle=bracketstyle,
+                                  mutation_scale=42)
+        ax.add_patch(bracket)
+        ax.text(3, y + 0.05, bracketstyle, ha="center", va="bottom")
+        ax.vlines([i[0] for i in vlines], [y, y], [i[1] for i in vlines],
+                  linestyles="--", color="C0")
+        # Get the top coordinates for the drawn patches at A and B
+        patch_tops = [get_point_of_rotated_vertical(center, 0.5, angle)
+                      for center, angle in zip(arrow_centers, anglesAB)]
+        # Define the connection directions for the annotation arrows
+        connection_dirs = (1, -1) if angle > 0 else (-1, 1)
+        # Add arrows and annotation text
+        arrowstyle = "Simple, tail_width=0.5, head_width=4, head_length=8"
+        for vline, dir, patch_top, angle in zip(vlines, connection_dirs,
+                                                patch_tops, anglesAB):
+            kw = dict(connectionstyle=f"arc3,rad={dir * 0.5}",
+                      arrowstyle=arrowstyle, color="C0")
+            ax.add_patch(FancyArrowPatch(vline, patch_top, **kw))
+            ax.text(vline[0] - dir * 0.15, y + 0.3, f'{angle}°', ha="center",
+                    va="center")
+
+#############################################################################
+#
+# .. admonition:: References
+#
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
+#
+#    - `matplotlib.patches.ArrowStyle`
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
index 76e65859ac73..f61524f65597 100644
--- a/lib/matplotlib/patches.py
+++ b/lib/matplotlib/patches.py
@@ -3119,6 +3119,14 @@ class ArrowStyle(_Style):
     stroked. This is meant to be used to correct the location of the
     head so that it does not overshoot the destination point, but not all
     classes support it.
+
+    Notes
+    -----
+    *angleA* and *angleB* specify the orientation of the bracket, as either a
+    clockwise or counterclockwise angle depending on the arrow type. 0 degrees
+    means perpendicular to the line connecting the arrow's head and tail.
+
+    .. plot:: gallery/text_labels_and_annotations/angles_on_bracket_arrows.py
     """
 
     _style_list = {}