DOC: Clarify/simplify example of multiple images with one colorbar (matplotlib#28546)

Co-authored-by: hannah <[email protected]>

Author: timhoffm

galleries/examples/images_contours_and_fields/multi_image.py

@@ -1,9 +1,19 @@
 """
-===============
-Multiple images
-===============
+=================================
+Multiple images with one colorbar
+=================================
 
-Make a set of images with a single colormap, norm, and colorbar.
+Use a single colorbar for multiple images.
+
+Currently, a colorbar can only be connected to one image. The connection
+guarantees that the data coloring is consistent with the colormap scale
+(i.e. the color of value *x* in the colormap is used for coloring a data
+value *x* in the image).
+
+If we want one colorbar to be representative for multiple images, we have
+to explicitly ensure consistent data coloring by using the same data
+normalization for all the images. We ensure this by explicitly creating a
+``norm`` object that we pass to all the image plotting methods.
 """
 
 import matplotlib.pyplot as plt
@@ -12,47 +22,53 @@
 from matplotlib import colors
 
 np.random.seed(19680801)
-Nr = 3
-Nc = 2
 
-fig, axs = plt.subplots(Nr, Nc)
+datasets = [
+    (i+1)/10 * np.random.rand(10, 20)
+    for i in range(4)
+]
+
+fig, axs = plt.subplots(2, 2)
 fig.suptitle('Multiple images')
 
-images = []
-for i in range(Nr):
-    for j in range(Nc):
-        # Generate data with a range that varies from one plot to the next.
-        data = ((1 + i + j) / 10) * np.random.rand(10, 20)
-        images.append(axs[i, j].imshow(data))
-        axs[i, j].label_outer()
+# create a single norm to be shared across all images
+norm = colors.Normalize(vmin=np.min(datasets), vmax=np.max(datasets))
 
-# Find the min and max of all colors for use in setting the color scale.
-vmin = min(image.get_array().min() for image in images)
-vmax = max(image.get_array().max() for image in images)
-norm = colors.Normalize(vmin=vmin, vmax=vmax)
-for im in images:
-    im.set_norm(norm)
+images = []
+for ax, data in zip(axs.flat, datasets):
+    images.append(ax.imshow(data, norm=norm))
 
 fig.colorbar(images[0], ax=axs, orientation='horizontal', fraction=.1)
 
-
-# Make images respond to changes in the norm of other images (e.g. via the
-# "edit axis, curves and images parameters" GUI on Qt), but be careful not to
-# recurse infinitely!
-def update(changed_image):
-    for im in images:
-        if (changed_image.get_cmap() != im.get_cmap()
-                or changed_image.get_clim() != im.get_clim()):
-            im.set_cmap(changed_image.get_cmap())
-            im.set_clim(changed_image.get_clim())
-
-
-for im in images:
-    im.callbacks.connect('changed', update)
-
 plt.show()
 
 # %%
+# The colors are now kept consistent across all images when changing the
+# scaling, e.g. through zooming in the colorbar or via the "edit axis,
+# curves and images parameters" GUI of the Qt backend. This is sufficient
+# for most practical use cases.
+#
+# Advanced: Additionally sync the colormap
+# ----------------------------------------
+#
+# Sharing a common norm object guarantees synchronized scaling because scale
+# changes modify the norm object in-place and thus propagate to all images
+# that use this norm. This approach does not help with synchronizing colormaps
+# because changing the colormap of an image (e.g. through the "edit axis,
+# curves and images parameters" GUI of the Qt backend) results in the image
+# referencing the new colormap object. Thus, the other images are not updated.
+#
+# To update the other images, sync the
+# colormaps using the following code::
+#
+#     def sync_cmaps(changed_image):
+#         for im in images:
+#         if changed_image.get_cmap() != im.get_cmap():
+#             im.set_cmap(changed_image.get_cmap())
+#
+#     for im in images:
+#         im.callbacks.connect('changed', sync_cmaps)
+#
 #
 # .. admonition:: References
 #
@@ -63,6 +79,4 @@ def update(changed_image):
 #    - `matplotlib.figure.Figure.colorbar` / `matplotlib.pyplot.colorbar`
 #    - `matplotlib.colors.Normalize`
 #    - `matplotlib.cm.ScalarMappable.set_cmap`
-#    - `matplotlib.cm.ScalarMappable.set_norm`
-#    - `matplotlib.cm.ScalarMappable.set_clim`
 #    - `matplotlib.cbook.CallbackRegistry.connect`