Skip to content

Commit bc25a66

Browse files
committed
DOC: add warnings about get_window_extent and BboxImage
Closes matplotlib#2831
1 parent 5c90c35 commit bc25a66

2 files changed

Lines changed: 74 additions & 17 deletions

File tree

‎lib/matplotlib/artist.py‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -329,19 +329,29 @@ def get_window_extent(self, renderer=None):
329329
"""
330330
Get the artist's bounding box in display space.
331331
332-
The bounding box' width and height are nonnegative.
332+
The bounding box's width and height are non-negative.
333333
334334
Subclasses should override for inclusion in the bounding box
335335
"tight" calculation. Default is to return an empty bounding
336336
box at 0, 0.
337337
338-
Be careful when using this function, the results will not update
339-
if the artist window extent of the artist changes. The extent
340-
can change due to any changes in the transform stack, such as
341-
changing the Axes limits, the figure size, or the canvas used
342-
(as is done when saving a figure). This can lead to unexpected
343-
behavior where interactive figures will look fine on the screen,
344-
but will save incorrectly.
338+
.. warning ::
339+
340+
Be careful when using this function, the results will not update if
341+
the artist window extent of the artist changes.
342+
343+
The extent can change due to any changes in the transform stack, such
344+
as changing the Axes limits, the figure size, the canvas used (as is
345+
done when saving a figure), or the DPI.
346+
347+
This can lead to unexpected behavior where interactive figures will
348+
look fine on the screen, but will save incorrectly.
349+
350+
To get accurate results you may need to manually call
351+
`matplotlib.figure.Figure.savefig` or
352+
`matplotlib.figure.Figure.draw_without_rendering` to have Matplotlib
353+
compute the rendered size.
354+
345355
"""
346356
return Bbox([[0, 0], [0, 0]])
347357

‎lib/matplotlib/image.py‎

Lines changed: 56 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1374,8 +1374,61 @@ def set_data(self, A):
13741374

13751375

13761376
class BboxImage(_ImageBase):
1377-
"""The Image class whose size is determined by the given bbox."""
1377+
"""
1378+
The Image class whose size is determined by the given bbox.
1379+
1380+
Parameters
1381+
----------
1382+
bbox : BboxBase or Callable[RendererBase, BboxBase]
1383+
The bbox or a function to generate the bbox
1384+
1385+
.. warning ::
1386+
1387+
If using `matplotlib.artist.Artist.get_window_extent` as the
1388+
callable ensure that the other artist is drawn first (lower zorder)
1389+
or you may need to renderer the figure twice to ensure that the
1390+
computed bbox is accurate.
1391+
1392+
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
1393+
The Colormap instance or registered colormap name used to map scalar
1394+
data to colors.
1395+
norm : str or `~matplotlib.colors.Normalize`
1396+
Maps luminance to 0-1.
1397+
interpolation : str, default: :rc:`image.interpolation`
1398+
Supported values are 'none', 'auto', 'nearest', 'bilinear',
1399+
'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite',
1400+
'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell',
1401+
'sinc', 'lanczos', 'blackman'.
1402+
interpolation_stage : {'data', 'rgba'}, default: 'data'
1403+
If 'data', interpolation
1404+
is carried out on the data provided by the user. If 'rgba', the
1405+
interpolation is carried out after the colormapping has been
1406+
applied (visual interpolation).
1407+
origin : {'upper', 'lower'}, default: :rc:`image.origin`
1408+
Place the [0, 0] index of the array in the upper left or lower left
1409+
corner of the Axes. The convention 'upper' is typically used for
1410+
matrices and images.
1411+
extent : tuple, optional
1412+
The data axes (left, right, bottom, top) for making image plots
1413+
registered with data plots. Default is to label the pixel
1414+
centers with the zero-based row and column indices.
1415+
filternorm : bool, default: True
1416+
A parameter for the antigrain image resize filter
1417+
(see the antigrain documentation).
1418+
If filternorm is set, the filter normalizes integer values and corrects
1419+
the rounding errors. It doesn't do anything with the source floating
1420+
point values, it corrects only integers according to the rule of 1.0
1421+
which means that any sum of pixel weights must be equal to 1.0. So,
1422+
the filter function must produce a graph of the proper shape.
1423+
filterrad : float > 0, default: 4
1424+
The filter radius for filters that have a radius parameter, i.e. when
1425+
interpolation is one of: 'sinc', 'lanczos' or 'blackman'.
1426+
resample : bool, default: False
1427+
When True, use a full resampling method. When False, only resample when
1428+
the output image is larger than the input image.
1429+
**kwargs : `~matplotlib.artist.Artist` properties
13781430
1431+
"""
13791432
def __init__(self, bbox,
13801433
*,
13811434
cmap=None,
@@ -1388,12 +1441,7 @@ def __init__(self, bbox,
13881441
resample=False,
13891442
**kwargs
13901443
):
1391-
"""
1392-
cmap is a colors.Colormap instance
1393-
norm is a colors.Normalize instance to map luminance to 0-1
13941444

1395-
kwargs are an optional list of Artist keyword args
1396-
"""
13971445
super().__init__(
13981446
None,
13991447
cmap=cmap,
@@ -1409,12 +1457,11 @@ def __init__(self, bbox,
14091457
self.bbox = bbox
14101458

14111459
def get_window_extent(self, renderer=None):
1412-
if renderer is None:
1413-
renderer = self.get_figure()._get_renderer()
1414-
14151460
if isinstance(self.bbox, BboxBase):
14161461
return self.bbox
14171462
elif callable(self.bbox):
1463+
if renderer is None:
1464+
renderer = self.get_figure()._get_renderer()
14181465
return self.bbox(renderer)
14191466
else:
14201467
raise ValueError("Unknown type of bbox")

0 commit comments

Comments
 (0)