Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 31, 2024
Merged

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76e6c58
DOC: Clarify/simplify example of multiple images with one colorbar
timhoffm Jul 12, 2024
b1ead92
Update galleries/examples/images_contours_and_fields/multi_image.py
timhoffm Jul 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 51 additions & 37 deletions galleries/examples/images_contours_and_fields/multi_image.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
Comment on lines +48 to +49
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# curves and images parameters" GUI of the Qt backend. This is sufficient
# for most practical use cases.
# curves and images parameters" GUI of the Qt backend.

Folks will tell us if it's sufficient?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this as guidance and affirmation that most users can stop here. They don't have to inverst the following extra effort for cmap handling.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, maybe "this is" is just ambiguous pronoun reference then.

#
# 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
#
Expand All @@ -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`