Skip to content

Implement head resizing (and reversal) for larrow/rarrow/darrow #29998

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 24 commits into
base: main
Choose a base branch
from
+353 −31
Open

Implement head resizing (and reversal) for larrow/rarrow/darrow #29998

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
2f366fa
Make arrow annotation arrowhead adjustable
Abitamim Dec 16, 2022
e8d7eb7
Add test - not sure if correct
Abitamim Dec 16, 2022
15bd7dc
Update tutorial
Abitamim Dec 16, 2022
4f57495
Fixed linting
Abitamim Dec 16, 2022
5c3fa60
Add reversed arrow-head support to larrow/rarrow
CharlieThornton33 Apr 17, 2025
8065549
Fix reversed arrow-head support for single arrows, handle edge cases
CharlieThornton33 Apr 20, 2025
0471e92
Add support for reversed arrow-heads and edge cases in DArrow, update…
CharlieThornton33 Apr 20, 2025
212cbc9
Update docstings, add what's new notes
CharlieThornton33 Apr 22, 2025
273a2fe
Fix typo in DArrow drawing code
CharlieThornton33 Apr 28, 2025
bf2d06b
Fixed padding inconsistency: reverted breaking API change
CharlieThornton33 Apr 28, 2025
0ea2f5a
Fix what's new example
CharlieThornton33 Apr 28, 2025
d7fd405
Create unit test for boxarrow head adjustment
CharlieThornton33 Apr 30, 2025
ff34b4b
Fixed linting
CharlieThornton33 Apr 30, 2025
d9b0b32
Update new test to use mpl20 figure style
CharlieThornton33 May 1, 2025
f3369c0
Changed padding for LArrow/RArrow to prevent text spilling out
CharlieThornton33 May 14, 2025
3913ef6
[skip ci] Fix spelling mistake in LArrow padding code
CharlieThornton33 May 14, 2025
63a4ba9
Remove 'poking-out' behaviour from reversed arrow-heads, add padding …
CharlieThornton33 Jun 19, 2025
7ed9fd1
Remove now-unneeded manual padding from What's New page
CharlieThornton33 Jun 19, 2025
d953aef
Remove test_boxarrow_adjustment
CharlieThornton33 Jun 19, 2025
d2105da
Prevent text overspill from DArrows using padding
CharlieThornton33 Jun 19, 2025
54147e6
Added test for arrow-head adjustments
CharlieThornton33 Jun 20, 2025
b5ba28e
Fix padding from straight-edges of reversed arrow heads, fix incorrec…
CharlieThornton33 Jul 5, 2025
976e54b
[skip ci] Fix indentation in galleries/users_explain/text/annotations.py
CharlieThornton33 Jul 9, 2025
a08c67b
[skip ci] Use python % operator rather than np.mod() to act on scalar…
CharlieThornton33 Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions doc/users/next_whats_new/box_arrow_size_controls.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
Arrow-style sub-classes of ``BoxStyle`` support arrow head resizing
-------------------------------------------------------------------

The new *head_width* and *head_angle* parameters to
`.BoxStyle.LArrow`, `.BoxStyle.RArrow` and `.BoxStyle.DArrow` allow for adjustment
of the size and aspect ratio of the arrow heads used.

By using negative angles (or corresponding reflex angles) for *head_angle*, arrows
with 'backwards' heads may be created.

.. plot::
:include-source: false
:alt: A plot containing two arrow-shaped text boxes. One arrow has a pentagonal 'road-sign' shape, and the other an inverted arrow head on each end.

import numpy as np
import matplotlib.pyplot as plt

# Data for plotting; here, an intensity distribution for Fraunhofer diffraction
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't really need data for this example.

# from 7 thin slits
x_data = np.linspace(-3 * np.pi, 3 * np.pi, num=1000)
I_data = (np.sin(x_data * 3.5) / np.sin(x_data / 2)) ** 2

# Generate plot

fig, ax = plt.subplots()
plt.plot(x_data, I_data)

plt.xlim(-3 * np.pi, 3 * np.pi)
plt.ylim(0, 50)

#
# Annotate with boxed text in arrows
#

# head_width=1 gives 'road-sign' shape
t1 = ax.text(-1, 35, "Primary maximum",
ha="right", va="center", rotation=30, size=10,
bbox=dict(boxstyle="rarrow,pad=0.3,head_width=1,head_angle=60",
fc="lightblue", ec="steelblue", lw=2))

# Negative head_angle gives reversed arrow heads
t2 = ax.text(np.pi, 30, "Lower intensity",
ha="center", va="center", rotation=0, size=10,
bbox=dict(boxstyle="darrow,pad=0.3,head_width=2,head_angle=-80",
fc="lightblue", ec="steelblue", lw=2))


plt.show()
10 changes: 5 additions & 5 deletions galleries/users_explain/text/annotations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,10 +234,10 @@
# Class Name Attrs
# ========== ============== ==========================
# Circle ``circle`` pad=0.3
# DArrow ``darrow`` pad=0.3
# DArrow ``darrow`` pad=0.3,head_width=1.5,head_angle=90
# Ellipse ``ellipse`` pad=0.3
# LArrow ``larrow`` pad=0.3
# RArrow ``rarrow`` pad=0.3
# LArrow ``larrow`` pad=0.3,head_width=1.5,head_angle=90
# RArrow ``rarrow`` pad=0.3,head_width=1.5,head_angle=90
# Round ``round`` pad=0.3,rounding_size=None
# Round4 ``round4`` pad=0.3,rounding_size=None
# Roundtooth ``roundtooth`` pad=0.3,tooth_size=None
Expand Down Expand Up @@ -303,8 +303,8 @@ def custom_box_style(x0, y0, width, height, mutation_size):
x0, y0 = x0 - pad, y0 - pad
x1, y1 = x0 + width, y0 + height
# return the new path
return Path([(x0, y0), (x1, y0), (x1, y1), (x0, y1),
(x0-pad, (y0+y1)/2), (x0, y0), (x0, y0)],
return Path([(x0, y0), (x1, y0), (x1, y1), (x0, y1), (x0, y1-pad),
(x0-pad, (y0+y1)/2), (x0, y0+pad), (x0, y0), (x0, y0)],
closed=True)

fig, ax = plt.subplots(figsize=(3, 3))
Expand Down
273 changes: 249 additions & 24 deletions lib/matplotlib/patches.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2508,33 +2508,142 @@ def __call__(self, x0, y0, width, height, mutation_size):
class LArrow:
"""A box in the shape of a left-pointing arrow."""

def __init__(self, pad=0.3):
def __init__(self, pad=0.3, head_width=1.5, head_angle=90.0):
"""
Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
head_width : float, default: 1.5
The width of the arrow head, relative to that of the arrow body.
Only positive values are accepted.
head_angle : float, default: 90.0
The angle subtended by the tip of the arrow head, in degrees.
Only nonzero angles are accepted.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't appear to be checked?

"""
self.pad = pad

if head_width < 0:
raise ValueError("The relative head width must be a positive number.")
else:
self.head_width = head_width

# Set arrow-head angle to within [0, 360 deg)
self.head_angle = head_angle % 360.

def __call__(self, x0, y0, width, height, mutation_size):
# padding
# scaled padding
pad = mutation_size * self.pad
# width and height with padding added.
# add padding to width and height
width, height = width + 2 * pad, height + 2 * pad
# boundary of the padded box
# boundary points of the padded box (arrow tail/body)
x0, y0 = x0 - pad, y0 - pad,
x1, y1 = x0 + width, y0 + height

# half-width and quarter-width of arrow tail
dx = (y1 - y0) / 2
dxx = dx / 2

x0 = x0 + pad / 1.4 # adjust by ~sqrt(2)

return Path._create_closed(
[(x0 + dxx, y0), (x1, y0), (x1, y1), (x0 + dxx, y1),
(x0 + dxx, y1 + dxx), (x0 - dx, y0 + dx),
(x0 + dxx, y0 - dxx), # arrow
(x0 + dxx, y0)])
# The width adjustment is the distance that must be subtracted from
# y0 and added to y1 to reach the non-tip vertices of the head.
# The body width is 2dx.
# Subtracting 1 from the head width gives, in units of the body width,
# the total 'width' of arrow-head not within the body.
width_adjustment = (self.head_width - 1) * dx

if self.head_angle == 0:
# This would cause a division by zero ('infinitely long' arrow head)
raise ValueError("Head angle of zero is not valid.")
elif self.head_angle <= 180:
# Non-reversed arrow head (<---)

# tan(1/2 * angle subtended by arrow tip)
tan_half_angle = np.tan(self.head_angle * (math.pi / 360))

# The angle adjustment is the tip-to-body length of the arrow head.
# Each half of the arrow head is a right-angled triangle. Therefore,
# each half of the arrow head has, by trigonometry, tan(head_angle/2)=
# (dx+width_adjustment)/(dxx+angle_adjustment).
angle_adjustment = ((dx + width_adjustment) / tan_half_angle) - dxx

# Check padding; the left end of the text should have a minimum
# clearance of pad from the head
if -width_adjustment < pad:
# Only do this if the text fits into the head
text_clearance = (width_adjustment / tan_half_angle) + \
pad * ((1 / tan_half_angle) - 1)

if text_clearance < pad:
# Lengthen arrow body to accommodate text
x0 = x0 + text_clearance - pad
else:
# Pad away from head straight-edge
x0 = x0 - pad
Comment on lines +2570 to +2582
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Check padding; the left end of the text should have a minimum
# clearance of pad from the head
if -width_adjustment < pad:
# Only do this if the text fits into the head
text_clearance = (width_adjustment / tan_half_angle) + \
pad * ((1 / tan_half_angle) - 1)
if text_clearance < pad:
# Lengthen arrow body to accommodate text
x0 = x0 + text_clearance - pad
else:
# Pad away from head straight-edge
x0 = x0 - pad
# Check padding; the left end of the text should have a minimum
# clearance of pad from the head
if -width_adjustment < pad:
# Only do this if the text fits into the head
text_clearance = (width_adjustment / tan_half_angle) + \
pad * ((1 / tan_half_angle) - 1)
# Lengthen arrow body to accommodate text
pad = max(pad - text_clearance, 0)
x0 -= pad

but note that coverage says some of this is uncovered.


return Path._create_closed(
[(x0 + dxx, y0), (x1, y0), (x1, y1), (x0 + dxx, y1),
(x0 + dxx, y1 + width_adjustment), (x0 - angle_adjustment, y0
+ dx), (x0 + dxx, y0 - width_adjustment), # arrow
Comment on lines +2586 to +2587
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would not break in the middle of the tuple, and what does the arrow comment mean?

(x0 + dxx, y0)])
else:
# Reversed arrow head (>---)

# Distance to pad x0 by, in order to ensure consistent spacing
a, b = 1.214, 0.250 # Empirical factors
Copy link
Member

@QuLogic QuLogic Jul 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have you checked these empirical factors for different font sizes?

padding_offset = (a * pad) + (b * mutation_size)

# No arrow head available for enclosed text to spill over into; add
# padding to left of text
x0 = x0 - padding_offset
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
x0 = x0 - padding_offset
x0 -= padding_offset


# tan(1/2 * angle subtended by arrow tip)
tan_half_angle = -np.tan(self.head_angle * (math.pi / 360))

if self.head_width <= 1:
# Rectangle; head entirely enclosed by body (don't count head
# 'poking' out of back of body)

return Path._create_closed([
(x0 + dxx, y0),
(x1, y0),
(x1, y1),
(x0 + dxx, y1),
(x0 + dxx, y0)
])


# Distance from end of arrow to points where slanted parts of head
# intercept arrow body
intercept_adjustment = width_adjustment / tan_half_angle

if intercept_adjustment < width:
# Some of arrow body is outside of head

return Path._create_closed([
(x0 + dxx, y0 - width_adjustment),
(x0 + dxx + intercept_adjustment, y0),
(x1, y0),
(x1, y1),
(x0 + dxx + intercept_adjustment, y1),
(x0 + dxx, y1 + width_adjustment),
(x0 + dxx, y0 - width_adjustment)
])
else:
# Trapezium-shaped reversed arrow (reversed triangle 'cut off' by
# end of body

# Vertical distance between top of text at end furthest from arrow
# head and corner of trapezium
vertical_offset = width_adjustment + ((x0 - x1) * tan_half_angle)

return Path._create_closed([
(x0 + dxx, y0 - width_adjustment),
(x1, y0 - vertical_offset),
(x1, y1 + vertical_offset),
(x0 + dxx, y1 + width_adjustment),
(x0 + dxx, y0 - width_adjustment)
])

@_register_style(_style_list)
class RArrow(LArrow):
Expand All @@ -2551,37 +2660,153 @@ class DArrow:
"""A box in the shape of a two-way arrow."""
# Modified from LArrow to add a right arrow to the bbox.

def __init__(self, pad=0.3):
def __init__(self, pad=0.3, head_width=1.5, head_angle=90.0):
"""
Parameters
----------
pad : float, default: 0.3
The amount of padding around the original box.
head_width : float, default: 1.5
The width of each arrow head, relative to that of the arrow body.
Only positive values are accepted.
head_angle : float, default: 90.0
The angle subtended by the tip of each arrow head, in degrees.
Only nonzero angles are accepted.
"""
self.pad = pad

if head_width < 0:
raise ValueError("The relative head width must be a positive number.")
else:
self.head_width = head_width

# Set arrow-head angle to within [0, 360 deg)
self.head_angle = head_angle % 360.

def __call__(self, x0, y0, width, height, mutation_size):
# padding
# scaled padding
pad = mutation_size * self.pad
# width and height with padding added.
# The width is padded by the arrows, so we don't need to pad it.
# add padding to height
height = height + 2 * pad
# boundary of the padded box
# boundary points of the padded box (arrow tail/body)
x0, y0 = x0 - pad, y0 - pad
x1, y1 = x0 + width, y0 + height

# half-width and quarter-width of arrow tail
dx = (y1 - y0) / 2
dxx = dx / 2

x0 = x0 + pad / 1.4 # adjust by ~sqrt(2)

return Path._create_closed([
(x0 + dxx, y0), (x1, y0), # bot-segment
(x1, y0 - dxx), (x1 + dx + dxx, y0 + dx),
(x1, y1 + dxx), # right-arrow
(x1, y1), (x0 + dxx, y1), # top-segment
(x0 + dxx, y1 + dxx), (x0 - dx, y0 + dx),
(x0 + dxx, y0 - dxx), # left-arrow
(x0 + dxx, y0)])
# The width adjustment is the distance that must be subtracted from
# y0 and added to y1 to reach the non-tip vertices of the head.
# The body width is 2dx.
# Subtracting 1 from the head width gives, in units of the body width,
# the total 'width' of arrow-head not within the body.
width_adjustment = (self.head_width - 1) * dx

if self.head_angle == 0:
# This would cause a division by zero ('infinitely long' arrow head)
raise ValueError("Head angle of zero is not valid.")
elif self.head_angle <= 180:
# Non-reversed arrow heads (<--->)

# tan(1/2 * angle subtended by arrow tip)
tan_half_angle = np.tan(self.head_angle * (math.pi / 360))

# The angle adjustment is the tip-to-body length of the arrow head.
# Each half of the arrow head is a right-angled triangle. Therefore,
# each half of the arrow head has, by trigonometry, tan(head_angle/2)=
# (dx+width_adjustment)/(dxx+angle_adjustment).
angle_adjustment = ((dx + width_adjustment) / tan_half_angle) - dxx

# Check padding; the ends of the text should have a minimum
# clearance of pad from the heads
if -width_adjustment < pad:
# Only do this if the text fits into the head
text_clearance = (width_adjustment / tan_half_angle) + \
pad * ((1 / tan_half_angle) - 1)

if text_clearance < pad:
# Lengthen arrow body to accommodate text
x0 = x0 + text_clearance - pad
x1 = x1 + pad - text_clearance
else:
# Pad away from head straight-edges
x0 = x0 - pad
x1 = x1 + pad
Comment on lines +2722 to +2736
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Check padding; the ends of the text should have a minimum
# clearance of pad from the heads
if -width_adjustment < pad:
# Only do this if the text fits into the head
text_clearance = (width_adjustment / tan_half_angle) + \
pad * ((1 / tan_half_angle) - 1)
if text_clearance < pad:
# Lengthen arrow body to accommodate text
x0 = x0 + text_clearance - pad
x1 = x1 + pad - text_clearance
else:
# Pad away from head straight-edges
x0 = x0 - pad
x1 = x1 + pad
# Check padding; the ends of the text should have a minimum
# clearance of pad from the heads
if -width_adjustment < pad:
# Only do this if the text fits into the head
text_clearance = (width_adjustment / tan_half_angle) + \
pad * ((1 / tan_half_angle) - 1)
# Lengthen arrow body to accommodate text
pad = max(pad - text_clearance, 0)
# Pad away from head straight-edges
x0 -= pad
x1 += pad

but note that coverage says some of these lines aren't covered, so this suggestion may not be correct in all cases until tested.


return Path._create_closed([
(x0 + dxx, y0),
(x1, y0),
(x1, y0 - width_adjustment),
(x1 + dxx + angle_adjustment, y0 + dx),
(x1, y1 + width_adjustment),
(x1, y1),
(x0 + dxx, y1),
(x0 + dxx, y1 + width_adjustment),
(x0 - angle_adjustment, y0 + dx),
(x0 + dxx, y0 - width_adjustment),
(x0 + dxx, y0)
])
else:
# Reversed arrow heads (>---<)

# Distance to pad x0 and x1 by, in order to ensure consistent spacing
a, b = 1.214, 0.250 # Empirical factors
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same question about font sizes.

padding_offset = (a * pad) + (b * mutation_size)

# No arrow head available for enclosed text to spill over into; add
# padding to both sides of text
x0 = x0 - padding_offset
x1 = x1 + padding_offset
Comment on lines +2760 to +2761
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
x0 = x0 - padding_offset
x1 = x1 + padding_offset
x0 -= padding_offset
x1 += padding_offset


# tan(1/2 * angle subtended by arrow tip)
tan_half_angle = -np.tan(self.head_angle * (math.pi / 360))

if self.head_width <= 1:
# Rectangle; heads entirely enclosed by body

return Path._create_closed([
(x0 + dxx, y0),
(x1, y0),
(x1, y1),
(x0 + dxx, y1),
(x0 + dxx, y0)
])

# Distance from end of arrow to points where slanted parts of head
# intercept arrow body
intercept_adjustment = width_adjustment / tan_half_angle

if (2 * intercept_adjustment) < width:
# Some of arrow body is outside of heads

return Path._create_closed([
(x0 + dxx, y0 - width_adjustment),
(x0 + dxx + intercept_adjustment, y0),
(x1 - intercept_adjustment, y0),
(x1, y0 - width_adjustment),
(x1, y1 + width_adjustment),
(x1 - intercept_adjustment, y1),
(x0 + dxx + intercept_adjustment, y1),
(x0 + dxx, y1 + width_adjustment),
(x0 + dxx, y0 - width_adjustment)
])
else:
# Draw overlapping arrow heads

# y-offset inwards of central points
centre_offset = (width * tan_half_angle) / 2

return Path._create_closed([
(x0 + dxx, y0 - width_adjustment),
((x0 + x1 + dxx) / 2, y0 - width_adjustment + centre_offset),
(x1, y0 - width_adjustment),
(x1, y1 + width_adjustment),
((x0 + x1 + dxx) / 2, y1 + width_adjustment - centre_offset),
(x0 + dxx, y1 + width_adjustment),
(x0 + dxx, y0 - width_adjustment)
])

@_register_style(_style_list)
class Round:
Expand Down
Loading