Skip to content

Cleanup image docs #16245

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 1 commit into from
Jan 18, 2020
Merged

Cleanup image docs #16245

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
89 changes: 50 additions & 39 deletions lib/matplotlib/image.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ def composite_images(images, renderer, magnification=1.0):

renderer : `.RendererBase`

magnification : float
magnification : float, default: 1
The additional magnification to apply for the renderer in use.

Returns
Expand Down Expand Up @@ -303,8 +303,7 @@ def _get_scalar_alpha(self):

def changed(self):
"""
Call this whenever the mappable is changed so observers can
update state
Call this whenever the mappable is changed so observers can update.
"""
self._imcache = None
self._rgbacache = None
Expand Down Expand Up @@ -627,9 +626,7 @@ def draw(self, renderer, *args, **kwargs):
self.stale = False

def contains(self, mouseevent):
"""
Test whether the mouse event occurred within the image.
"""
"""Test whether the mouse event occurred within the image."""
inside, info = self._default_contains(mouseevent)
if inside is not None:
return inside, info
Expand Down Expand Up @@ -659,7 +656,7 @@ def contains(self, mouseevent):
return inside, {}

def write_png(self, fname):
"""Write the image to png file with fname"""
"""Write the image to png file *fname*."""
im = self.to_rgba(self._A[::-1] if self.origin == 'lower' else self._A,
bytes=True, norm=True)
PIL.Image.fromarray(im).save(fname, format="png")
Expand Down Expand Up @@ -733,15 +730,14 @@ def get_interpolation(self):
'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric',
'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos',
or 'none'.

"""
return self._interpolation

def set_interpolation(self, s):
"""
Set the interpolation method the image uses when resizing.

if None, use a value from rc setting. If 'none', the image is
If None, use :rc:`image.interpolation`. If 'none', the image is
shown as is without interpolating. 'none' is only supported in
agg, ps and pdf backends and will fall back to 'nearest' mode
for other backends.
Expand All @@ -750,8 +746,7 @@ def set_interpolation(self, s):
----------
s : {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16',
'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', \
'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'}

'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
"""
if s is None:
s = rcParams['image.interpolation']
Expand All @@ -775,7 +770,7 @@ def set_resample(self, v):
Parameters
----------
v : bool or None
If None, use :rc:`image.resample` = True.
If None, use :rc:`image.resample`.
"""
if v is None:
v = rcParams['image.resample']
Expand Down Expand Up @@ -862,7 +857,6 @@ class AxesImage(_ImageBase):
When True, use a full resampling method. When False, only resample when
the output image is larger than the input image.
**kwargs : `.Artist` properties

"""
def __str__(self):
return "AxesImage(%g,%g;%gx%g)" % tuple(self.axes.bbox.bounds)
Expand Down Expand Up @@ -911,9 +905,7 @@ def make_image(self, renderer, magnification=1.0, unsampled=False):
magnification, unsampled=unsampled)

def _check_unsampled_image(self, renderer):
"""
Return whether the image would be better drawn unsampled.
"""
"""Return whether the image would be better drawn unsampled."""
return (self.get_interpolation() == "none"
and renderer.option_scale_image())

Expand Down Expand Up @@ -999,7 +991,7 @@ def __init__(self, ax, *, interpolation='nearest', **kwargs):
"""
Parameters
----------
interpolation : {'nearest', 'bilinear'}
interpolation : {'nearest', 'bilinear'}, default: 'nearest'

**kwargs
All other keyword arguments are identical to those of `.AxesImage`.
Expand Down Expand Up @@ -1091,8 +1083,8 @@ def set_interpolation(self, s):
"""
Parameters
----------
s : str, None
Either 'nearest', 'bilinear', or ``None``.
s : {'nearest', 'bilinear'} or None
If None, use :rc:`image.interpolation`.
"""
if s is not None and s not in ('nearest', 'bilinear'):
raise NotImplementedError('Only nearest neighbor and '
Expand Down Expand Up @@ -1137,12 +1129,28 @@ def __init__(self, ax,
**kwargs
):
"""
cmap defaults to its rc setting

cmap is a colors.Colormap instance
norm is a colors.Normalize instance to map luminance to 0-1

Additional kwargs are matplotlib.artist properties
Parameters
----------
ax : `~.axes.Axes`
The axes the image will belong to.
x, y : 1D array-like, optional
Monotonic arrays of length N+1 and M+1, respectively, specifying
rectangle boundaries. If not given, will default to
``range(N + 1)`` and ``range(M + 1)``, respectively.
A : array-like
The data to be color-coded. The interpretation depends on the
shape:

- (M, N) ndarray or masked array: values to be colormapped
- (M, N, 3): RGB array
- (M, N, 4): RGBA array

cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
The Colormap instance or registered colormap name used to map
scalar data to colors.
norm : `~matplotlib.colors.Normalize`
Maps luminance to 0-1.
**kwargs : `.Artist` properties
"""
super().__init__(ax, norm=norm, cmap=cmap)
self.update(kwargs)
Expand Down Expand Up @@ -1192,13 +1200,17 @@ def set_data(self, x, y, A):

Parameters
----------
x, y : 1D array-likes or None
Monotonic arrays of shapes (N + 1,) and (M + 1,), respectively,
specifying rectangle boundaries. If None, will default to
x, y : 1D array-like, optional
Monotonic arrays of length N+1 and M+1, respectively, specifying
Copy link
Member

Choose a reason for hiding this comment

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

Stupid question: what happens in the arrays are not monotonic?

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 didn't check, but probably the drawing is messed up. I'd assume that the edges define poligons that are just rendered and will overlap if the edges are not monotonic.

rectangle boundaries. If not given, will default to
``range(N + 1)`` and ``range(M + 1)``, respectively.
A : array-like
(M, N) ndarray or masked array of values to be colormapped, or
(M, N, 3) RGB array, or (M, N, 4) RGBA array.
The data to be color-coded. The interpretation depends on the
shape:

- (M, N) ndarray or masked array: values to be colormapped
- (M, N, 3): RGB array
- (M, N, 4): RGBA array
"""
A = cbook.safe_masked_invalid(A, copy=True)
if x is None:
Expand Down Expand Up @@ -1473,17 +1485,15 @@ def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None,
values that map to the colormap color limits. If either *vmin*
or *vmax* is None, that limit is determined from the *arr*
min/max value.
cmap : str or `~matplotlib.colors.Colormap`, optional
cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
A Colormap instance or registered colormap name. The colormap
maps scalar data to colors. It is ignored for RGB(A) data.
Defaults to :rc:`image.cmap` ('viridis').
format : str, optional
The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when this
is unset is documented under *fname*.
origin : {'upper', 'lower'}, optional
origin : {'upper', 'lower'}, default: :rc:`image.origin`
Indicates whether the ``(0, 0)`` index of the array is in the upper
left or lower left corner of the axes. Defaults to :rc:`image.origin`
('upper').
left or lower left corner of the axes.
dpi : int
The DPI to store in the metadata of the file. This does not affect the
resolution of the output image.
Expand Down Expand Up @@ -1547,7 +1557,8 @@ def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None,


def pil_to_array(pilImage):
"""Load a `PIL image`_ and return it as a numpy int array.
"""
Load a `PIL image`_ and return it as a numpy int array.

.. _PIL image: https://pillow.readthedocs.io/en/latest/reference/Image.html

Expand Down Expand Up @@ -1629,14 +1640,14 @@ def thumbnail(infile, thumbfile, scale=0.1, interpolation='bilinear',
thumbfile : str or file-like
The thumbnail filename.

scale : float, optional
scale : float, default: 0.1
The scale factor for the thumbnail.

interpolation : str, optional
interpolation : str, default: 'bilinear'
The interpolation scheme used in the resampling. See the
*interpolation* parameter of `~.Axes.imshow` for possible values.

preview : bool, optional
preview : bool, default: False
If True, the default backend (presumably a user interface
backend) will be used which will cause a figure to be raised if
`~matplotlib.pyplot.show` is called. If it is False, the figure is
Expand Down