add zoom_inset_rectangle

jklymak · jklymak · commit cebac4fb74c2 · 2018-04-16T14:16:03.000-07:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -405,7 +405,7 @@ def _remove_legend(self, legend):
 
     def inset_axes(self, rect, transform=None, **kwargs):
         """
-        Add a child axes to the existing axes.
+        Add a child inset axes to this existing axes.
 
         Parameters
         ----------
@@ -417,6 +417,10 @@ def inset_axes(self, rect, transform=None, **kwargs):
             Defaults to `ax.transAxes`, i.e. the units of *rect* are in
             axes-relative coordinates.
 
+        zorder : number
+            Defaults to 5 (same as `.Axes.legend`).  Adjust higher or lower
+            to change whether it is above or below data plotted on the axes.
+
         Other Parameters
         ----------------
 
@@ -447,64 +451,91 @@ def inset_axes(self, rect, transform=None, **kwargs):
         bb = _inset_locator(rect, transform, self)(None, None)
         # if not set, set to the same zorder as legend
         zorder = kwargs.pop('zorder', 5)
-        axins = Axes(self.figure, bb.bounds, zorder=zorder,
+        inset_ax = Axes(self.figure, bb.bounds, zorder=zorder,
                 label=label, **kwargs)
 
         # this locator lets the axes move if in data coordinates.
         # it gets called in `ax.apply_aspect() (of all places)
         axes_locator = _inset_locator(rect, transform, self)
-        axins.set_axes_locator(axes_locator)
+        inset_ax.set_axes_locator(axes_locator)
 
-        self.add_child_axes(axins)
+        self.add_child_axes(inset_ax)
 
-        return axins
+        return inset_ax
 
-    def inset_indicator(self, rect, axins=None, transform=None,
+    def inset_rectangle(self, rect, inset_ax=None, transform=None,
             facecolor='none', edgecolor='0.5', alpha=0.5,
             zorder=4.99, **kwargs):
         """
-        Add an inset indicator to the axes.  This is a box on the plot that
-        can optionally have lines joining it to an inset axes *axins*.
+        Add an inset indicator to the axes.  This is a rectangle on the plot
+        at the position indicated by *rect* that optionally has lines that
+        connect the rectangle to an inset axes (`.Axes.inset_axes`).
 
         Parameters
         ----------
 
         rect : [x0, y0, width, height]
-            Lower-left corner of area to be marked, and its width and height.
+            Lower-left corner of rectangle to be marked, and its width
+            and height.
 
-        axins : `Axes`
-            An optional axes to join this indicator to.  Two lines are drawn
-            connecting the indicator box to the inset axes on corners chosen
-            so as to not overlap with the indicator box.
+        inset_ax : `.Axes`
+            An optional inset axes to draw connecting lines to.  Two lines are
+            drawn connecting the indicator box to the inset axes on corners
+            chosen so as to not overlap with the indicator box.
 
         transform : `.Transform`
-            Defaults to `ax.transAxes`, i.e. the units of *rect* are in
-            axes-relative coordinates.
+            Transform for the rectangle co-ordinates. Defaults to
+            `ax.transAxes`, i.e. the units of *rect* are in axes-relative
+            coordinates.
+
+        facecolor : Matplotlib color
+            Facecolor of the rectangle (default 'none')
+
+        edgecolor : Matplotlib color
+            Color of the rectangle and color of the connecting lines.  Default
+            is '0.5'
+
+        alpha : number
+            Transparency of the rectangle and connector lines.  Default 0.5
+
+        zorder : number
+            drawing order of the rectangle and connector lines. Default 4.99
+            (just below the default level of inset axes)
 
         Other Parameters
         ----------------
 
-        kwargs are passed on to the `axes.Axes` child axes.
+        Other *kwargs* are passed on to the rectangle patch.
 
         Returns
         -------
 
-        ??
+        rectangle_patch, connector_lines :
+            `.Patches.Rectagle`, (four-tupple `.Patches.ConnectionPatch`) one
+            for each of four connector lines.  Two are set with visibility to
+            *False*,  but the user can set the visibility to True if the
+            automatic choice is not deemed correct.
 
         """
+
+        # to make the axes connectors work, we need to apply the aspect to
+        # the parent axes.
+        self.apply_aspect()
+
         if transform is None:
             transform = self.transData
         label = kwargs.pop('label', 'inset_indicator')
+
         xy = (rect[0], rect[1])
         rectpatch = mpatches.Rectangle(xy, rect[2], rect[3],
                 facecolor=facecolor, edgecolor=edgecolor, alpha=alpha,
                 zorder=zorder,  label=label, transform=transform, **kwargs)
         self.add_patch(rectpatch)
 
-        if not axins is None:
+        if not inset_ax is None:
             # want to connect the indicator to the rect....
 
-            pos = axins.get_position() # this is in fig-fraction.
+            pos = inset_ax.get_position() # this is in fig-fraction.
             coordsA='axes fraction'
             connects = []
             xr = [rect[0], rect[0]+rect[2]]
@@ -515,11 +546,12 @@ def inset_indicator(self, rect, axins=None, transform=None,
                     xyB = (xr[xc], yr[yc])
                     connects += [mpatches.ConnectionPatch(xyA, xyB,
                             'axes fraction', 'data',
-                            axesA=axins, axesB=self, arrowstyle="-",
+                            axesA=inset_ax, axesB=self, arrowstyle="-",
                             zorder=zorder, edgecolor=edgecolor, alpha=alpha)]
                     self.add_patch(connects[-1])
             # decide which two of the lines to keep visible....
-            bboxins = axins.get_position().transformed(self.figure.transFigure)
+            pos = inset_ax.get_position()
+            bboxins = pos.transformed(self.figure.transFigure)
             rectbbox = mtransforms.Bbox.from_bounds(rect[0], rect[1],
                     rect[2], rect[3]).transformed(transform)
             if rectbbox.x0 < bboxins.x0:
@@ -533,10 +565,44 @@ def inset_indicator(self, rect, axins=None, transform=None,
                 connects[1].set_visible(False)
                 connects[2].set_visible(False)
 
-            return rectpatch, connects
+        return rectpatch, connects
+
+    def zoom_inset_rectangle(self, inset_ax, **kwargs):
+        """
+        Add an inset indicator rectangle to the axes based on the axis
+        limits for an *inset_ax* and draw connectors between *inset_ax*
+        and the rectangle.
+
+        Parameters
+        ----------
+
+        inset_ax : `.Axes`
+            Inset axes to draw connecting lines to.  Two lines are
+            drawn connecting the indicator box to the inset axes on corners
+            chosen so as to not overlap with the indicator box.
+
+        Other Parameters
+        ----------------
 
+        Other *kwargs* are passed on to `.Axes.inset_rectangle`
+
+        Returns
+        -------
+
+        rectangle_patch, connector_lines :
+            `.Patches.Rectagle`, (four-tupple `.Patches.ConnectionPatch`) one
+            for each of four connector lines.  Two are set with visibility to
+            *False*,  but the user can set the visibility to True if the
+            automatic choice is not deemed correct.
+
+        """
 
+        xlim = inset_ax.get_xlim()
+        ylim = inset_ax.get_ylim()
+        rect = [xlim[0], ylim[0], xlim[1] - xlim[0], ylim[1] - ylim[0]]
+        rectpatch, connects = self.inset_rectangle(rect, inset_ax, **kwargs)
 
+        return rectpatch, connects
 
     def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         """
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -4140,6 +4140,8 @@ def get_tightbbox(self, renderer, call_axes_locator=True):
                 bb.append(child.get_window_extent(renderer))
             elif isinstance(child, Legend) and child.get_visible():
                 bb.append(child._legend_box.get_window_extent(renderer))
+            elif isinstance(child, _AxesBase) and child.get_visible():
+                bb.append(child.get_tightbbox(renderer))
 
         _bbox = mtransforms.Bbox.union(
             [b for b in bb if b.width != 0 or b.height != 0])
