DOC: manually placing images example

jklymak · jklymak · commit 470fb6faaef2 · 2024-09-03T08:09:58.000-07:00
diff --git a/doc/api/next_api_changes/behavior/28375-MP.rst b/doc/api/next_api_changes/behavior/28375-MP.rst
@@ -0,0 +1,5 @@
+``transforms.AffineDeltaTransform`` updates correctly on axis limit changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before this change, transform sub-graphs with ``AffineDeltaTransform`` did not update correctly.
+This PR ensures that changes to the child transform are passed through correctly.
diff --git a/galleries/examples/images_contours_and_fields/image_exact_placement.py b/galleries/examples/images_contours_and_fields/image_exact_placement.py
@@ -0,0 +1,148 @@
+"""
+=========================================
+Placing images, preserving relative sizes
+=========================================
+
+By default Matplotlib resamples images created with `~.Axes.imshow` to
+fit inside the parent `~.axes.Axes`.  This can mean that images that have very
+different original sizes can end up appearing similar in size.
+
+Sometimes, however,  it is desirable to keep the images the same relative size, or
+even to make the images keep exactly the same pixels as the original data.
+Matplotlib does not automatically make either of these things happen,
+but it is possible with some manual manipulation.
+
+Preserving relative sizes
+=========================
+
+By default the two images are made a similar size, despite one being 1.5 times the width
+of the other:
+"""
+
+# sphinx_gallery_thumbnail_number = -1
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import matplotlib.patches as mpatches
+
+# make the data:
+N = 450
+x = np.arange(N) / N
+y = np.arange(N) / N
+
+X, Y = np.meshgrid(x, y)
+R = np.sqrt(X**2 + Y**2)
+f0 = 5
+k = 100
+a = np.sin(np.pi * 2 * (f0 * R + k * R**2 / 2))
+A = a[:100, :300]
+B = A[:40, :200]
+
+# plot with default axes handling:
+fig, axs = plt.subplots(1, 2, facecolor='aliceblue')
+
+axs[0].imshow(A, vmin=-1, vmax=1)
+axs[1].imshow(B, vmin=-1, vmax=1)
+
+
+def annotate_rect(ax):
+    # add a rectangle that is the size of the B matrix
+    rect = mpatches.Rectangle((0, 0), 200, 40, linewidth=1,
+                              edgecolor='r', facecolor='none')
+    ax.add_patch(rect)
+    return rect
+
+annotate_rect(axs[0])
+
+# %%
+# Note that both images are rendered at a 1:1 ratio, but are made to look almost the
+# same width, despite image B being smaller than image A.
+#
+# If the size of the images are amenable, we can preserve the relative sizes of two
+# images by using either the *width_ratio* or *height_ratio* of the subplots.  Which
+# one you use depends on the shape of the image and the size of the figure.
+# We can control the relative sizes using the *width_ratios* argument *if* the images
+# are wider than they are tall and shown side by side, as is the case here.
+
+fig, axs = plt.subplots(1, 2, width_ratios=[300/200, 1], facecolor='aliceblue')
+
+axs[0].imshow(A, vmin=-1, vmax=1)
+annotate_rect(axs[0])
+
+axs[1].imshow(B, vmin=-1, vmax=1)
+
+# %%
+# Given that the data subsample is in the upper left of the larger image,
+# it might make sense if the top of the smaller Axes aligned with the top of the larger.
+# This can be done manually by using `~.Axes.set_anchor`, and using "NW" (for
+# northwest).
+
+fig, axs = plt.subplots(1, 2, width_ratios=[300/200, 1], facecolor='aliceblue')
+
+axs[0].imshow(A, vmin=-1, vmax=1)
+annotate_rect(axs[0])
+
+axs[0].set_anchor('NW')
+axs[1].imshow(B, vmin=-1, vmax=1)
+axs[1].set_anchor('NW')
+
+# %%
+# Note that this procedure still leaves large white spaces (that can be trimmed
+# in a final product by ``bbox_inches="tight"`` in `~.Figure.savefig`), and is
+# not very general.  For instance, if the axes had been arranged vertically
+# instead of horizontally, setting the height aspect ratio would not have
+# helped because the axes are wider than they are tall. For more complicated
+# situations it is necessary to place the axes manually.
+#
+# Manual placement
+# ================
+#
+# We can manually place axes when they are created by passing a position to
+# `~.Figure.add_axes`.  This position takes the form ``[left bottom width height]`` and
+# is in units that are a fraction of the figure width and height. Here we decide how
+# large to make the axes based on the size of the images, and add a small buffer of
+# 0.35 inches.  We do all this at 100 dpi.
+
+dpi = 100  # 100 pixels is one inch
+
+# All variables from here are in pixels:
+buffer = 0.35 * dpi  # pixels
+
+# Get the position of A axes
+left = buffer
+bottom = buffer
+ny, nx = np.shape(A)
+posA = [left, bottom, nx, ny]
+# we know this is tallest, so we can already get the fig height (in pixels)
+fig_height = bottom + ny + buffer
+
+# place the B axes to the right of the A axes
+left = left + nx + buffer
+
+ny, nx = np.shape(B)
+# align the bottom so that the top lines up with the top of the A axes:
+bottom = fig_height - buffer - ny
+posB = [left, bottom, nx, ny]
+
+# now we can get the fig width (in pixels)
+fig_width = left + nx + buffer
+
+# figsize must be in inches:
+fig = plt.figure(figsize=(fig_width / dpi, fig_height / dpi), facecolor='aliceblue')
+
+# the position posA must be normalized by the figure width and height:
+ax = fig.add_axes([posA[0] / fig_width, posA[1] / fig_height,
+                   posA[2] / fig_width, posA[3] / fig_height])
+ax.imshow(A, vmin=-1, vmax=1)
+annotate_rect(ax)
+
+ax = fig.add_axes([posB[0] / fig_width, posB[1] / fig_height,
+                   posB[2] / fig_width, posB[3] / fig_height])
+ax.imshow(B, vmin=-1, vmax=1)
+
+# %%
+# Inspection of the image will show that it is exactly 3* 35 + 300 + 200 = 605
+# pixels wide, and 2 * 35 + 100 = 170 pixels high (or twice that if the 2x
+# version is used by the browser instead).  The images should be rendered with
+# exactly 1 pixel per data point (or four, if 2x).
diff --git a/lib/matplotlib/tests/test_transforms.py b/lib/matplotlib/tests/test_transforms.py
@@ -341,6 +341,31 @@ def test_deepcopy(self):
         assert_array_equal(s.get_matrix(), a.get_matrix())
 
 
+class TestAffineDeltaTransform:
+    def test_invalidate(self):
+        before = np.array([[1.0, 4.0, 0.0],
+                           [5.0, 1.0, 0.0],
+                           [0.0, 0.0, 1.0]])
+        after = np.array([[1.0, 3.0, 0.0],
+                          [5.0, 1.0, 0.0],
+                          [0.0, 0.0, 1.0]])
+
+        # Translation and skew present
+        base = mtransforms.Affine2D.from_values(1, 5, 4, 1, 2, 3)
+        t = mtransforms.AffineDeltaTransform(base)
+        assert_array_equal(t.get_matrix(), before)
+
+        # Mess with the internal structure of `base` without invalidating
+        # This should not affect this transform because it's a passthrough:
+        # it's always invalid
+        base.get_matrix()[0, 1:] = 3
+        assert_array_equal(t.get_matrix(), after)
+
+        # Invalidate the base
+        base.invalidate()
+        assert_array_equal(t.get_matrix(), after)
+
+
 def test_non_affine_caching():
     class AssertingNonAffineTransform(mtransforms.Transform):
         """
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -2721,9 +2721,12 @@ class AffineDeltaTransform(Affine2DBase):
     This class is experimental as of 3.3, and the API may change.
     """
 
+    pass_through = True
+
     def __init__(self, transform, **kwargs):
         super().__init__(**kwargs)
         self._base_transform = transform
+        self.set_children(transform)
 
     __str__ = _make_str_method("_base_transform")
 
