DOC: Clarify/simplify example of multiple images with one colorbar

timhoffm · timhoffm · commit f199fd4d1a1a · 2024-07-29T12:13:18.000+02:00
diff --git a/galleries/examples/images_contours_and_fields/multi_image.py b/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. The most important aspect
+is the data normalization. By explicitly creating a norm and using that
+for all images, we ensure that all images are scaled consistently.
 """
 
 import matplotlib.pyplot as plt
@@ -12,47 +22,56 @@
 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
+# ----------------------------------------
+#
+# While the norm is shared in the above example, the colormaps are not:
+# Each image holds an independent reference to the colormap it wants to
+# use. We implicitly rely on all images using the same colormap. This is
+# often ok because colormaps are usually not changed dynamically. However,
+# a user could change the colormap of an individual image through the
+# "edit axis, curves and images parameters" GUI of the Qt backend.
+# Unlike with a norm, it does not help to share colormaps between images.
+# Changes to the norm limits modify the norm object in place and thus
+# propagate to all images. But changing a colormap sets a new colormap
+# object to the images and thus does not propagate to the other images.
+# To make all other images follow, you could additionally 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 +82,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`
