8000 Update to docs with regards to colorbar and colorizer · matplotlib/matplotlib@4af03f4 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4af03f4

Browse files
trygvradtrygvrad
committed
Update to docs with regards to colorbar and colorizer
1 parent 2fa96ed commit 4af03f4

File tree

4 files changed

+51
-53
lines changed

4 files changed

+51
-53
lines changed

‎galleries/examples/images_contours_and_fields/multi_image.py

Lines changed: 14 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,16 @@
1111
value *x* in the image).
1212
1313
If we want one colorbar to be representative for multiple images, we have
14-
to explicitly ensure consistent data coloring by using the same data
15-
normalization for all the images. We ensure this by explicitly creating a
16-
``norm`` object that we pass to all the image plotting methods.
14+
to explicitly ensure consistent data coloring by using the same
15+
data-to-color pipeline for all the images. We ensure this by explicitly
16+
creating a `matplotlib.colorizer.Colorizer` object that we pass to all
17+
the image plotting methods.
1718
"""
1819

1920
import matplotlib.pyplot as plt
2021
import numpy as np
2122

22-
from matplotlib import colors
23+
import matplotlib as mpl
2324

2425
np.random.seed(19680801)
2526

@@ -31,12 +32,13 @@
3132
fig, axs = plt.subplots(2, 2)
3233
fig.suptitle('Multiple images')
3334

34-
# create a single norm to be shared across all images
35-
norm = colors.Normalize(vmin=np.min(datasets), vmax=np.max(datasets))
35+
# create a single norm and colorizer to be shared across all images
36+
norm = mpl.colors.Normalize(vmin=np.min(datasets), vmax=np.max(datasets))
37+
colorizer = mpl.colorizer.Colorizer(norm=norm)
3638

3739
images = []
3840
for ax, data in zip(axs.flat, datasets):
39-
images.append(ax.imshow(data, norm=norm))
41+
images.append(ax.imshow(data, colorizer=colorizer))
4042

4143
fig.colorbar(images[0], ax=axs, orientation='horizontal', fraction=.1)
4244

@@ -45,30 +47,10 @@
4547
# %%
4648
# The colors are now kept consistent across all images when changing the
4749
# scaling, e.g. through zooming in the colorbar or via the "edit axis,
48-
# curves and images parameters" GUI of the Qt backend. This is sufficient
49-
# for most practical use cases.
50-
#
51-
# Advanced: Additionally sync the colormap
52-
# ----------------------------------------
53-
#
54-
# Sharing a common norm object guarantees synchronized scaling because scale
55-
# changes modify the norm object in-place and thus propagate to all images
56-
# that use this norm. This approach does not help with synchronizing colormaps
57-
# because changing the colormap of an image (e.g. through the "edit axis,
58-
# curves and images parameters" GUI of the Qt backend) results in the image
59-
# referencing the new colormap object. Thus, the other images are not updated.
60-
#
61-
# To update the other images, sync the
62-
# colormaps using the following code::
63-
#
64-
# def sync_cmaps(changed_image):
65-
# for im in images:
66-
# if changed_image.get_cmap() != im.get_cmap():
67-
# im.set_cmap(changed_image.get_cmap())
68-
#
69-
# for im in images:
70-
# im.callbacks.connect('changed', sync_cmaps)
71-
#
50+
# curves and images parameters" GUI of the Qt backend. Additionally,
51+
# if the colormap of the colorizer is changed, (e.g. through the "edit
52+
# axis, curves and images parameters" GUI of the Qt backend) this change
53+
# propagates to the other plots and the colorbar.
7254
#
7355
# .. admonition:: References
7456
#
@@ -77,6 +59,6 @@
7759
#
7860
# - `matplotlib.axes.Axes.imshow` / `matplotlib.pyplot.imshow`
7961
# - `matplotlib.figure.Figure.colorbar` / `matplotlib.pyplot.colorbar`
62+
# - `matplotlib.colorizer.Colorizer`
8063
# - `matplotlib.colors.Normalize`
81-
# - `matplotlib.cm.ScalarMappable.set_cmap`
8264
# - `matplotlib.cbook.CallbackRegistry.connect`

‎galleries/users_explain/colors/colorbar_only.py

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,11 @@
88
This tutorial shows how to build and customize standalone colorbars, i.e.
99
without an attached plot.
1010
11-
A `~.Figure.colorbar` needs a "mappable" (`matplotlib.cm.ScalarMappable`)
12-
object (typically, an image) which indicates the colormap and the norm to be
13-
used. In order to create a colorbar without an attached image, one can instead
14-
use a `.ScalarMappable` with no associated data.
11+
A `~.Figure.colorbar` needs a "mappable" (`matplotlib.colorizer.ColorizingArtist`)
12+
object (typically, an image) which contains a colorizer
13+
(`matplotlib.colorizer.Colorizer`) that holds the data-to-color pipeline (norm and
14+
colormap). In order to create a colorbar without an attached image, one can instead
15+
use a `.ColorizingArtist` with no associated data.
1516
"""
1617

1718
import matplotlib.pyplot as plt
@@ -23,17 +24,21 @@
2324
# -------------------------
2425
# Here, we create a basic continuous colorbar with ticks and labels.
2526
#
26-
# The arguments to the `~.Figure.colorbar` call are the `.ScalarMappable`
27-
# (constructed using the *norm* and *cmap* arguments), the axes where the
28-
# colorbar should be drawn, and the colorbar's orientation.
27+
# The arguments to the `~.Figure.colorbar` call are a `.ColorizingArtist`,
28+
# the axes where the colorbar should be drawn, and the colorbar's orientation.
29+
# To crate a `.ColorizingArtist` one must first make `.Colorizer` that holds the
30+
# desired *norm* and *cmap*.
31+
#
2932
#
3033
# For more information see the `~matplotlib.colorbar` API.
3134

3235
fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')
3336

3437
norm = mpl.colors.Normalize(vmin=5, vmax=10)
3538

36-
fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap="cool"),
39+
colorizer = mpl.colorizer.Colorizer(norm=norm, cmap="cool")
40+
41+
fig.colorbar(mpl.colorizer.ColorizingArtist(colorizer),
3742
cax=ax, orientation='horizontal', label='Some Units')
3843

3944
# %%
@@ -47,7 +52,9 @@
4752

4853
fig, ax = plt.subplots(layout='constrained')
4954

50-
fig.colorbar(mpl.cm.ScalarMappable(norm=mpl.colors.Normalize(0, 1), cmap='magma'),
55+
colorizer = mpl.colorizer.Colorizer(norm=mpl.colors.Normalize(0, 1), cmap='magma')
56+
57+
fig.colorbar(mpl.colorizer.ColorizingArtist(colorizer),
5158
ax=ax, orientation='vertical', label='a colorbar label')
5259

5360
# %%
@@ -65,7 +72,9 @@
6572
bounds = [-1, 2, 5, 7, 12, 15]
6673
norm = mpl.colors.BoundaryNorm(bounds, cmap.N, extend='both')
6774

68-
fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap="viridis"),
75+
colorizer = mpl.colorizer.Colorizer(norm=norm, cmap='viridis')
76+
77+
fig.colorbar(mpl.colorizer.ColorizingArtist(colorizer),
6978
cax=ax, orientation='horizontal',
7079
label="Discrete intervals with extend='both' keyword")
7180

@@ -94,8 +103,10 @@
94103
bounds = [1, 2, 4, 7, 8]
95104
norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
96105

106+
colorizer = mpl.colorizer.Colorizer(norm=norm, cmap=cmap)
107+
97108
fig.colorbar(
98-
mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
109+
mpl.colorizer.ColorizingArtist(colorizer),
99110
cax=ax, orientation='horizontal',
100111
extend='both',
101112
spacing='proportional',
@@ -116,8 +127,10 @@
116127
bounds = [-1.0, -0.5, 0.0, 0.5, 1.0]
117128
norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
118129

130+
colorizer = mpl.colorizer.Colorizer(norm=norm, cmap=cmap)
131+
119132
fig.colorbar(
120-
mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
133+
mpl.colorizer.ColorizingArtist(colorizer),
121134
cax=ax, orientation='horizontal',
122135
extend='both', extendfrac='auto',
123136
spacing='uniform',

‎lib/matplotlib/colorbar.py

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,9 @@
1616
import numpy as np
1717

1818
import matplotlib as mpl
19-
from matplotlib import _api, cbook, collections, cm, colors, contour, ticker
19+
from matplotlib import _api, cbook, collections, colors, contour, ticker
2020
import matplotlib.artist as martist
21+
import matplotlib.colorizer as mcolorizer
2122
import matplotlib.patches as mpatches
2223
import matplotlib.path as mpath
2324
import matplotlib.spines as mspines
@@ -199,12 +200,12 @@ class Colorbar:
199200
Draw a colorbar in an existing Axes.
200201
201202
Typically, colorbars are created using `.Figure.colorbar` or
202-
`.pyplot.colorbar` and associated with `.ScalarMappable`\s (such as an
203+
`.pyplot.colorbar` and associated with `.ColorizingArtist`\s (such as an
203204
`.AxesImage` generated via `~.axes.Axes.imshow`).
204205
205206
In order to draw a colorbar not associated with other elements in the
206207
figure, e.g. when showing a colormap by itself, one can create an empty
207-
`.ScalarMappable`, or directly pass *cmap* and *norm* instead of *mappable*
208+
`.ColorizingArtist`, or directly pass *cmap* and *norm* instead of *mappable*
208209
to `Colorbar`.
209210
210211
Useful public methods are :meth:`set_label` and :meth:`add_lines`.
@@ -244,7 +245,7 @@ def __init__(
244245
ax : `~matplotlib.axes.Axes`
245246
The `~.axes.Axes` instance in which the colorbar is drawn.
246247
247-
mappable : `.ScalarMappable`
248+
mappable : `.ColorizingArtist`
248249
The mappable whose colormap and norm will be used.
249250
250251
To show the colors versus index instead of on a 0-1 scale, set the
@@ -288,7 +289,8 @@ def __init__(
288289
colorbar and at the right for a vertical.
289290
"""
290291
if mappable is None:
291-
mappable = cm.ScalarMappable(norm=norm, cmap=cmap)
292+
colorizer = mcolorizer.Colorizer(norm=norm, cmap=cmap)
293+
mappable = mcolorizer.ColorizingArtist(colorizer)
292294

293295
self.mappable = mappable
294296
cmap = mappable.cmap

‎lib/matplotlib/figure.py

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1200,17 +1200,18 @@ def colorbar(
12001200
Parameters
12011201
----------
12021202
mappable
1203-
The `matplotlib.cm.ScalarMappable` (i.e., `.AxesImage`,
1203+
The `matplotlib.colorizer.ColorizingArtist` (i.e., `.AxesImage`,
12041204
`.ContourSet`, etc.) described by this colorbar. This argument is
12051205
mandatory for the `.Figure.colorbar` method but optional for the
12061206
`.pyplot.colorbar` function, which sets the default to the current
12071207
image.
12081208
1209-
Note that one can create a `.ScalarMappable` "on-the-fly" to
1210-
generate colorbars not attached to a previously drawn artist, e.g.
1209+
Note that one can create a `.colorizer.ColorizingArtist` "on-the-fly"
1210+
to generate colorbars not attached to a previously drawn artist, e.g.
12111211
::
12121212
1213-
fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax)
1213+
cr = colorizer.Colorizer(norm=norm, cmap=cmap)
1214+
fig.colorbar(colorizer.ColorizingArtist(cr), ax=ax)
12141215
12151216
cax : `~matplotlib.axes.Axes`, optional
12161217
Axes into which the colorbar will be drawn. If `None`, then a new

0 commit comments

Comments
 (0)
0