8000 API: change interpolation default to 'auto' · matplotlib/matplotlib@d0e3ce8 · GitHub
[go: up one dir, main page]
Skip to content

Commit d0e3ce8

Browse files
jklymakjklymak
committed
API: change interpolation default to 'auto'
1 parent e09535f commit d0e3ce8

File tree

11 files changed

+64
-54
lines changed

11 files changed

+64
-54
lines changed

‎doc/api/next_api_changes/behavior/28061-JMK.rst

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
imshow *interpolation_stage* default changed to 'antialiased'
2-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1+
imshow *interpolation_stage* default changed to 'auto'
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33

44
The *interpolation_stage* keyword argument `~.Axes.imshow` has a new default
5-
value 'antialiased'. For images that are up-sampled less than a factor of
6-
three or down-sampled , image interpolation will occur in 'rgba' space. For images
5+
value 'auto'. For images that are up-sampled less than a factor of
6+
three or down-sampled, image interpolation will occur in 'rgba' space. For images
77
that are up-sampled by more than a factor of 3, then image interpolation occurs
88
in 'data' space.
99

@@ -12,3 +12,11 @@ the new default. However, the new default also avoids floating point artifacts
1212
at sharp boundaries in a colormap when down-sampling.
1313

1414
The previous behavior can achieved by changing :rc:`image.interpolation_stage`.
15+
16+
imshow default *interpolation* changed to 'auto'
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
19+
The *interpolation* keyword argument `~.Axes.imshow` has a new default
20+
value 'auto', changed from 'antialiased', for consistency with *interpolation_stage*
21+
and because the interpolation is only anti-aliasing during down-sampling. The
22+
'antialiased' string still works, and behaves exactly the same as 'auto'.

‎galleries/examples/images_contours_and_fields/image_antialiasing.py

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -131,10 +131,10 @@
131131
# colormap, it is what we perceive when a blue and red stripe are close to each
132132
# other.
133133
#
134-
# The default for the *interpolation* keyword argument is 'antialiased' which
134+
# The default for the *interpolation* keyword argument is 'auto' which
135135
# will choose a Hanning filter if the image is being down-sampled or up-sampled
136136
# by less than a factor of three. The default *interpolation_stage* keyword
137-
# argument is also 'antialiased', and for images that are down-sampled or
137+
# argument is also 'auto', and for images that are down-sampled or
138138
# up-sampled by less than a factor of three it defaults to 'rgba'
139139
# interpolation.
140140
#
@@ -151,8 +151,8 @@
151151
# %%
152152
# Better anti-aliasing algorithms can reduce this effect:
153153
fig, ax = plt.subplots(figsize=(6.8, 6.8))
154-
ax.imshow(alarge, interpolation='antialiased', cmap='grey')
155-
ax.set_title("up-sampled by factor a 1.17, interpolation='antialiased'")
154+
ax.imshow(alarge, interpolation='auto', cmap='grey')
155+
ax.set_title("up-sampled by factor a 1.17, interpolation='auto'")
156156

157157
# %%
158158
# Apart from the default 'hanning' anti-aliasing, `~.Axes.imshow` supports a
@@ -174,8 +174,8 @@
174174
# you do not use an anti-aliasing filter (*interpolation* set set to
175175
# 'nearest'), however, that makes the part of the data susceptible to Moiré
176176
# patterns much worse (second panel). Therefore, we recommend the default
177-
# *interpolation* of 'hanning'/'antialiased', and *interpolation_stage* of
178-
# 'rgba'/'antialiased' for most down-sampling situations (last panel).
177+
# *interpolation* of 'hanning'/'auto', and *interpolation_stage* of
178+
# 'rgba'/'auto' for most down-sampling situations (last panel).
179179

180180
a = alarge + 1
181181
cmap = plt.get_cmap('RdBu_r')
@@ -206,7 +206,7 @@
206206

207207
fig, axs = plt.subplots(1, 2, figsize=(6.5, 4), layout='compressed')
208208
axs[0].imshow(asmall, cmap='viridis')
209-
axs[0].set_title("interpolation='antialiased'\nstage='antialiased'")
209+
axs[0].set_title("interpolation='auto'\nstage='auto'")
210210
axs[1].imshow(asmall, cmap='viridis', interpolation="nearest",
211211
interpolation_stage="data")
212212
axs[1].set_title("interpolation='nearest'\nstage='data'")
@@ -218,7 +218,7 @@
218218
# where the filters can cause colors that are not in the colormap to be the result of
219219
# the interpolation. In the following example, note that when the interpolation is
220220
# 'rgba' there are red colors as interpolation artifacts. Therefore, the default
221-
# 'antialiased' choice for *interpolation_stage* is set to be the same as 'data'
221+
# 'auto' choice for *interpolation_stage* is set to be the same as 'data'
222222
# when up-sampling is greater than a factor of three:
223223

224224
fig, axs = plt.subplots(1, 2, figsize=(6.5, 4), layout='compressed')

‎galleries/examples/images_contours_and_fields/interpolation_methods.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88
99
If *interpolation* is None, it defaults to the :rc:`image.interpolation`.
1010
If the interpolation is ``'none'``, then no interpolation is performed for the
11-
Agg, ps and pdf backends. Other backends will default to ``'antialiased'``.
11+
Agg, ps and pdf backends. Other backends will default to ``'auto'``.
1212
1313
For the Agg, ps and pdf backends, ``interpolation='none'`` works well when a
1414
big image is scaled down, while ``interpolation='nearest'`` works well when
1515
a small image is scaled up.
1616
1717
See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for a
18-
discussion on the default ``interpolation='antialiased'`` option.
18+
discussion on the default ``interpolation='auto'`` option.
1919
"""
2020

2121
import matplotlib.pyplot as plt

‎lib/matplotlib/axes/_axes.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5799,7 +5799,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
57995799
interpolation : str, default: :rc:`image.interpolation`
58005800
The interpolation method used.
58015801
5802-
Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
5802+
Supported values are 'none', 'auto', 'nearest', 'bilinear',
58035803
'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite',
58045804
'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell',
58055805
'sinc', 'lanczos', 'blackman'.
@@ -5814,7 +5814,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
58145814
pdf, and svg viewers may display these raw pixels differently. On
58155815
other backends, 'none' is the same as 'nearest'.
58165816
5817-
If *interpolation* is the default 'antialiased', then 'nearest'
5817+
If *interpolation* is the default 'auto', then 'nearest'
58185818
interpolation is used if the image is upsampled by more than a
58195819
factor of three (i.e. the number of display pixels is at least
58205820
three times the size of the data array). If the upsampling rate is
@@ -5832,12 +5832,12 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
58325832
which can be set by *filterrad*. Additionally, the antigrain image
58335833
resize filter is controlled by the parameter *filternorm*.
58345834
5835-
interpolation_stage : {'antialiased', 'data', 'rgba'}, default: 'antialiased'
5835+
interpolation_stage : {'auto', 'data', 'rgba'}, default: 'auto'
58365836
If 'data', interpolation is carried out on the data provided by the user,
58375837
useful if interpolating between pixels during upsampling.
58385838
If 'rgba', the interpolation is carried out in RGBA-space after the
58395839
color-mapping has been applied, useful if downsampling and combining
5840-
pixels visually. The default 'antialiased' is appropriate for most
5840+
pixels visually. The default 'auto' is appropriate for most
58415841
applications where 'rgba' is used when downsampling, or upsampling at a
58425842
rate less than 3, and 'data' is used when upsampling at a higher rate.
58435843
See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for

‎lib/matplotlib/axes/_axes.pyi

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -492,7 +492,7 @@ class Axes(_AxesBase):
492492
vmax: float | None = ...,
493493
origin: Literal["upper", "lower"] | None = ...,
494494
extent: tuple[float, float, float, float] | None = ...,
495-
interpolation_stage: Literal["data", "rgba"] | None = ...,
495+
interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
496496
filternorm: bool = ...,
497497
filterrad: float = ...,
498498
resample: bool | None = ...,

‎lib/matplotlib/image.py

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131

3232
# map interpolation strings to module constants
3333
_interpd_ = {
34-
'antialiased': _image.NEAREST, # this will use nearest or Hanning...
34+
'auto': _image.NEAREST, # this will use nearest or Hanning...
3535
'none': _image.NEAREST, # fall back to nearest when not supported
3636
'nearest': _image.NEAREST,
3737
'bilinear': _image.BILINEAR,
@@ -50,6 +50,7 @@
5050
'sinc': _image.SINC,
5151
'lanczos': _image.LANCZOS,
5252
'blackman': _image.BLACKMAN,
53+
'antialiased': _image.NEAREST, # this will use nearest or Hanning...
5354
}
5455

5556
interpolations_names = set(_interpd_)
@@ -186,7 +187,7 @@ def _resample(
186187
# compare the number of displayed pixels to the number of
187188
# the data pixels.
188189
interpolation = image_obj.get_interpolation()
189-
if interpolation == 'antialiased':
190+
if interpolation in ['antialiased', 'auto']:
190191
# don't antialias if upsampling by an integer number or
191192
# if zooming in more than a factor of 3
192193
pos = np.array([[0, 0], [data.shape[1], data.shape[0]]])
@@ -425,7 +426,7 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
425426
# if antialiased, this needs to change as window sizes
426427
# change:
427428
interpolation_stage = self._interpolation_stage
428-
if interpolation_stage == 'antialiased':
429+
if interpolation_stage in ['antialiased', 'auto']:
429430
pos = np.array([[0, 0], [A.shape[1], A.shape[0]]])
430431
disp = t.transform(pos)
431432
dispx = np.abs(np.diff(disp[:, 0])) / A.shape[1]
@@ -758,9 +759,9 @@ def get_interpolation(self):
758759
"""
759760
Return the interpolation method the image uses when resizing.
760761
761-
One of 'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16',
762-
'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric',
763-
'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos',
762+
One of 'auto', 'antialiased', 'nearest', 'bilinear', 'bicubic',
763+
'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser',
764+
'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos',
764765
or 'none'.
765766
"""
766767
return self._interpolation
@@ -776,7 +777,7 @@ def set_interpolation(self, s):
776777
777778
Parameters
778779
----------
779-
s : {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', \
780+
s : {'auto', 'nearest', 'bilinear', 'bicubic', 'spline16', \
780781
'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', \
781782
'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
782783
"""
@@ -799,14 +800,14 @@ def set_interpolation_stage(self, s):
799800
800801
Parameters
801802
----------
802-
s : {'data', 'rgba', 'antialiased'} or None
803+
s : {'data', 'rgba', 'auto'} or None
803804
Whether to apply up/downsampling interpolation in data or RGBA
804805
space. If None, use :rc:`image.interpolation_stage`.
805-
If 'antialiased' we will check upsampling rate and if less
806+
If 'auto' we will check upsampling rate and if less
806807
than 3 then use 'rgba', otherwise use 'data'.
807808
"""
808809
s = mpl._val_or_rc(s, 'image.interpolation_stage')
809-
_api.check_in_list(['data', 'rgba', 'antialiased'], s=s)
810+
_api.check_in_list(['data', 'rgba', 'auto'], s=s)
810811
self._interpolation_stage = s
811812
self.stale = True
812813

@@ -886,7 +887,7 @@ class AxesImage(_ImageBase):
886887
norm : str or `~matplotlib.colors.Normalize`
887888
Maps luminance to 0-1.
888889
interpolation : str, default: :rc:`image.interpolation`
889-
Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
890+
Supported values are 'none', 'auto', 'nearest', 'bilinear',
890891
'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite',
891892
'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell',
892893
'sinc', 'lanczos', 'blackman'.

‎lib/matplotlib/image.pyi

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ class _ImageBase(martist.Artist, cm.ScalarMappable):
7373
filterrad: float = ...,
7474
resample: bool | None = ...,
7575
*,
76-
interpolation_stage: Literal["data", "rgba"] | None = ...,
76+
interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
7777
**kwargs
7878
) -> None: ...
7979
def get_size(self) -> tuple[int, int]: ...
@@ -89,8 +89,8 @@ class _ImageBase(martist.Artist, cm.ScalarMappable):
8989
def get_shape(self) -> tuple[int, int, int]: ...
9090
def get_interpolation(self) -> str: ...
9191
def set_interpolation(self, s: str | None) -> None: ...
92-
def get_interpolation_stage(self) -> Literal["data", "rgba"]: ...
93-
def set_interpolation_stage(self, s: Literal["data", "rgba"]) -> None: ...
92+
def get_interpolation_stage(self) -> Literal["data", "rgba", "auto"]: ...
93+
def set_interpolation_stage(self, s: Literal["data", "rgba", "auto"]) -> None: ...
9494
def can_composite(self) -> bool: ...
9595
def set_resample(self, v: bool | None) -> None: ...
9696
def get_resample(self) -> bool: ...
@@ -112,7 +112,7 @@ class AxesImage(_ImageBase):
112112
filternorm: bool = ...,
113113
filterrad: float = ...,
114114
resample: bool = ...,
115-
interpolation_stage: Literal["data", "rgba"] | None = ...,
115+
interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
116116
**kwargs
117117
) -> None: ...
118118
def get_window_extent(self, renderer: RendererBase | None = ...) -> Bbox: ...

‎lib/matplotlib/mpl-data/matplotlibrc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -602,8 +602,8 @@
602602
## * IMAGES *
603603
## ***************************************************************************
604604
#image.aspect: equal # {equal, auto} or a number
605-
#image.interpolation: antialiased # see help(imshow) for options
606-
#image.interpolation_stage: antialiased # see help(imshow) for options
605+
#image.interpolation: auto # see help(imshow) for options
606+
#image.interpolation_stage: auto # see help(imshow) for options
607607
#image.cmap: viridis # A colormap name (plasma, magma, etc.)
608608
#image.lut: 256 # the size of the colormap lookup table
609609
#image.origin: upper # {lower, upper}

‎lib/matplotlib/pyplot.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3565,7 +3565,7 @@ def imshow(
35653565
vmax: float | None = None,
35663566
origin: Literal["upper", "lower"] | None = None,
35673567
extent: tuple[float, float, float, float] | None = None,
3568-
interpolation_stage: Literal["data", "rgba"] | None = None,
3568+
interpolation_stage: Literal["data", "rgba", "auto"] | None = None,
35693569
filternorm: bool = True,
35703570
filterrad: float = 4.0,
35713571
resample: bool | None = None,

‎lib/matplotlib/rcsetup.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1053,7 +1053,7 @@ def _convert_validator_spec(key, conv):
10531053

10541054
"image.aspect": validate_aspect, # equal, auto, a number
10551055
"image.interpolation": validate_string,
1056-
"image.interpolation_stage": ["antialiased", "data", "rgba"],
1056+
"image.interpolation_stage": ["auto", "data", "rgba"],
10571057
"image.cmap": _validate_cmap, # gray, jet, etc.
10581058
"image.lut": validate_int, # lookup table
10591059
"image.origin": ["upper", "lower"],

0 commit comments

Comments
 (0)
0