Add InsetIndicator artist · matplotlib/matplotlib@143a228 · GitHub
Skip to content

Commit 143a228

Browse files
rcomerrcomer
committed
Add InsetIndicator artist
1 parent 86f04cb commit 143a228

13 files changed

Lines changed: 492 additions & 81 deletions

File tree

‎ci/mypy-stubtest-allowlist.txt‎

Lines changed: 3 additions & 0 deletions

‎doc/api/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ Alphabetical list of modules:
106106
gridspec_api.rst
107107
hatch_api.rst
108108
image_api.rst
109+
inset_api.rst
109110
layout_engine_api.rst
110111
legend_api.rst
111112
legend_handler_api.rst

‎doc/api/inset_api.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
********************
2+
``matplotlib.inset``
3+
********************
4+
5+
.. automodule:: matplotlib.inset
6+
:members:
7+
:undoc-members:
8+
:show-inheritance:

‎doc/api/next_api_changes/behavior/27996-REC.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
``InsetIndicator`` artist
2+
~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
`~.Axes.indicate_inset` and `~.Axes.indicate_inset_zoom` now return an instance
5+
of `~matplotlib.inset.InsetIndicator`. Use the
6+
`~matplotlib.inset.InsetIndicator.rectangle` and
7+
`~matplotlib.inset.InsetIndicator.connectors` properties of this artist to
8+
access the objects that were previously returned directly.

‎doc/users/next_whats_new/inset_indicator.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
``InsetIndicator`` artist
2+
~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
`~.Axes.indicate_inset` and `~.Axes.indicate_inset_zoom` now return an instance
5+
of `~matplotlib.inset.InsetIndicator` which contains the rectangle and
6+
connector patches. These patches now update automatically so that
7+
8+
.. code-block:: python
9+
10+
ax.indicate_inset_zoom(ax_inset)
11+
ax_inset.set_xlim(new_lim)
12+
13+
gives the same result as
14+
15+
.. code-block:: python
16+
17+
ax_inset.set_xlim(new_lim)
18+
ax.indicate_inset_zoom(ax_inset)

‎lib/matplotlib/axes/_axes.py‎

Lines changed: 40 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
import matplotlib.contour as mcontour
1717
import matplotlib.dates # noqa: F401, Register date unit converter as side effect.
1818
import matplotlib.image as mimage
19+
import matplotlib.inset as minset
1920
import matplotlib.legend as mlegend
2021
import matplotlib.lines as mlines
2122
import matplotlib.markers as mmarkers
@@ -418,9 +419,9 @@ def inset_axes(self, bounds, *, transform=None, zorder=5, **kwargs):
418419
return inset_ax
419420

420421
@_docstring.dedent_interpd
421-
def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
422+
def indicate_inset(self, bounds=None, inset_ax=None, *, transform=None,
422423
facecolor='none', edgecolor='0.5', alpha=0.5,
423-
zorder=4.99, **kwargs):
424+
zorder=None, **kwargs):
424425
"""
425426
Add an inset indicator to the Axes. This is a rectangle on the plot
426427
at the position indicated by *bounds* that optionally has lines that
@@ -432,18 +433,19 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
432433
433434
Parameters
434435
----------
435-
bounds : [x0, y0, width, height]
436+
bounds : [x0, y0, width, height], optional
436437
Lower-left corner of rectangle to be marked, and its width
437-
and height.
438+
and height. If not set, the bounds will be calculated from the
439+
data limits of *inset_ax*, which must be supplied.
438440
439-
inset_ax : `.Axes`
441+
inset_ax : `.Axes`, optional
440442
An optional inset Axes to draw connecting lines to. Two lines are
441443
drawn connecting the indicator box to the inset Axes on corners
442444
chosen so as to not overlap with the indicator box.
443445
444446
transform : `.Transform`
445447
Transform for the rectangle coordinates. Defaults to
446-
`ax.transAxes`, i.e. the units of *rect* are in Axes-relative
448+
``ax.transAxes``, i.e. the units of *rect* are in Axes-relative
447449
coordinates.
448450
449451
facecolor : :mpltype:`color`, default: 'none'
@@ -468,15 +470,20 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
468470
469471
Returns
470472
-------
471-
rectangle_patch : `.patches.Rectangle`
472-
The indicator frame.
473+
inset_indicator : `.inset.InsetIndicator`
474+
An artist which contains
473475
474-
connector_lines : 4-tuple of `.patches.ConnectionPatch`
475-
The four connector lines connecting to (lower_left, upper_left,
476-
lower_right upper_right) corners of *inset_ax*. Two lines are
477-
set with visibility to *False*, but the user can set the
478-
visibility to True if the automatic choice is not deemed correct.
476+
inset_indicator.rectangle : `.Rectangle`
477+
The indicator frame.
479478
479+
inset_indicator.connectors : 4-tuple of `.patches.ConnectionPatch`
480+
The four connector lines connecting to (lower_left, upper_left,
481+
lower_right upper_right) corners of *inset_ax*. Two lines are
482+
set with visibility to *False*, but the user can set the
483+
visibility to True if the automatic choice is not deemed correct.
484+
485+
.. versionchanged:: 3.10
486+
Previously the rectangle and connectors tuple were returned.
480487
"""
481488
# to make the Axes connectors work, we need to apply the aspect to
482489
# the parent Axes.
@@ -486,51 +493,13 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
486493
transform = self.transData
487494
kwargs.setdefault('label', '_indicate_inset')
488495

489-
x, y, width, height = bounds
490-
rectangle_patch = mpatches.Rectangle(
491-
(x, y), width, height,
496+
indicator_patch = minset.InsetIndicator(
497+
bounds, inset_ax=inset_ax,
492498
facecolor=facecolor, edgecolor=edgecolor, alpha=alpha,
493499
zorder=zorder, transform=transform, **kwargs)
494-
self.add_patch(rectangle_patch)
495-
496-
connects = []
497-
498-
if inset_ax is not None:
499-
# connect the inset_axes to the rectangle
500-
for xy_inset_ax in [(0, 0), (0, 1), (1, 0), (1, 1)]:
501-
# inset_ax positions are in axes coordinates
502-
# The 0, 1 values define the four edges if the inset_ax
503-
# lower_left, upper_left, lower_right upper_right.
504-
ex, ey = xy_inset_ax
505-
if self.xaxis.get_inverted():
506-
ex = 1 - ex
507-
if self.yaxis.get_inverted():
508-
ey = 1 - ey
509-
xy_data = x + ex * width, y + ey * height
510-
p = mpatches.ConnectionPatch(
511-
xyA=xy_inset_ax, coordsA=inset_ax.transAxes,
512-
xyB=xy_data, coordsB=self.transData,
513-
arrowstyle="-", zorder=zorder,
514-
edgecolor=edgecolor, alpha=alpha)
515-
connects.append(p)
516-
self.add_patch(p)
517-
518-
# decide which two of the lines to keep visible....
519-
pos = inset_ax.get_position()
520-
bboxins = pos.transformed(self.figure.transSubfigure)
521-
rectbbox = mtransforms.Bbox.from_bounds(
522-
*bounds
523-
).transformed(transform)
524-
x0 = rectbbox.x0 < bboxins.x0
525-
x1 = rectbbox.x1 < bboxins.x1
526-
y0 = rectbbox.y0 < bboxins.y0
527-
y1 = rectbbox.y1 < bboxins.y1
528-
connects[0].set_visible(x0 ^ y0)
529-
connects[1].set_visible(x0 == y1)
530-
connects[2].set_visible(x1 == y0)
531-
connects[3].set_visible(x1 ^ y1)
532-
533-
return rectangle_patch, tuple(connects) if connects else None
500+
self.add_artist(indicator_patch)
501+
502+
return indicator_patch
534503

535504
def indicate_inset_zoom(self, inset_ax, **kwargs):
536505
"""
@@ -554,22 +523,23 @@ def indicate_inset_zoom(self, inset_ax, **kwargs):
554523
555524
Returns
556525
-------
557-
rectangle_patch : `.patches.Rectangle`
558-
Rectangle artist.
559-
560-
connector_lines : 4-tuple of `.patches.ConnectionPatch`
561-
Each of four connector lines coming from the rectangle drawn on
562-
this axis, in the order lower left, upper left, lower right,
563-
upper right.
564-
Two are set with visibility to *False*, but the user can
565-
set the visibility to *True* if the automatic choice is not deemed
566-
correct.
526+
inset_indicator : `.inset.InsetIndicator`
527+
An artist which contains
528+
529+
inset_indicator.rectangle : `.Rectangle`
530+
The indicator frame.
531+
532+
inset_indicator.connectors : 4-tuple of `.patches.ConnectionPatch`
533+
The four connector lines connecting to (lower_left, upper_left,
534+
lower_right upper_right) corners of *inset_ax*. Two lines are
535+
set with visibility to *False*, but the user can set the
536+
visibility to True if the automatic choice is not deemed correct.
537+
538+
.. versionchanged:: 3.10
539+
Previously the rectangle and connectors tuple were returned.
567540
"""
568541

569-
xlim = inset_ax.get_xlim()
570-
ylim = inset_ax.get_ylim()
571-
rect = (xlim[0], ylim[0], xlim[1] - xlim[0], ylim[1] - ylim[0])
572-
return self.indicate_inset(rect, inset_ax, **kwargs)
542+
return self.indicate_inset(None, inset_ax, **kwargs)
573543

574544
@_docstring.dedent_interpd
575545
def secondary_xaxis(self, location, functions=None, *, transform=None, **kwargs):

‎lib/matplotlib/axes/_axes.pyi‎

Lines changed: 5 additions & 4 deletions

0 commit comments

Comments
 (0)