8000 Improve docstring of Axes.imshow · matplotlib/matplotlib@dbd28f6 · GitHub
[go: up one dir, main page]
Skip to content

Commit dbd28f6

Browse files
timhoffmtimhoffm
committed
Improve docstring of Axes.imshow
1 parent e2a0813 commit dbd28f6

File tree

1 file changed

+75
-56
lines changed

1 file changed

+75
-56
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 75 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -5093,86 +5093,99 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
50935093
origin=None, extent=None, shape=None, filternorm=1,
50945094
filterrad=4.0, imlim=None, resample=None, url=None, **kwargs):
50955095
"""
5096-
Display an image on the axes.
5096+
Display an image, i.e. data on a 2d regular raster.
50975097
50985098
Parameters
50995099
----------
5100-
X : array_like, shape (n, m) or (n, m, 3) or (n, m, 4)
5101-
Display the image in `X` to current axes. `X` may be an
5102-
array or a PIL image. If `X` is an array, it
5103-
can have the following shapes and types:
5100+
X : array-like or PIL image
5101+
The image data. Supported array shapes are:
51045102
5105-
- MxN -- values to be mapped (float or int)
5106-
- MxNx3 -- RGB (float or uint8)
5107-
- MxNx4 -- RGBA (float or uint8)
5103+
- (N, M): an image with scalar data. The data is visualized
5104+
using a colormap.
5105+
- (N, M, 3): an image with RGB values (float or uint8).
5106+
- (N, M, 4): an image with RGBA values (float or uint8), i.e.
5107+
including transparency.
51085108
5109-
MxN arrays are mapped to colors based on the `norm` (mapping
5110-
scalar to scalar) and the `cmap` (mapping the normed scalar to
5111-
a color).
5109+
The first two dimensions (N, M) define the rows and columns of
5110+
the image.
51125111
5113-
Elements of RGB and RGBA arrays represent pixels of an MxN image.
5114-
All values should be in the range [0 .. 1] for floats or
5112+
The RGB(A) values should be in the range [0 .. 1] for floats or
51155113
[0 .. 255] for integers. Out-of-range values will be clipped to
51165114
these bounds.
51175115
5118-
cmap : `~matplotlib.colors.Colormap`, optional, default: None
5119-
If None, default to rc `image.cmap` value. `cmap` is ignored
5120-
if `X` is 3-D, directly specifying RGB(A) values.
5116+
cmap : str or `~matplotlib.colors.Colormap`, optional
5117+
A Colormap instance or registered colormap name. The colormap
5118+
maps scalar data to colors. It is ignored for RGB(A) data.
5119+
Defaults to :rc:`image.cmap`.
51215120
5122-
aspect : ['auto' | 'equal' | scalar], optional, default: None
5123-
If 'auto', changes the image aspect ratio to match that of the
5124-
axes.
5121+
aspect : {'equal', 'auto'} or float, optional
5122+
Controls the aspect ratio of the axes. The aspect is of particular
5123+
relevance for images since it may distort the image, i.e. pixel
5124+
would not be square.
51255125
5126-
If 'equal', and `extent` is None, changes the axes aspect ratio to
5127-
match that of the image. If `extent` is not `None`, the axes
5128-
aspect ratio is changed to match that of the extent.
5126+
This parameter is just a shortcut for explicitly calling
5127+
`.Axes.set_aspect`. See there for further details.
51295128
5130-
If None, default to rc ``image.aspect`` value.
5129+
- 'equal': Ensures an aspect ratio of 1. Pixels will be square
5130+
(unless pixel sizes are explicitly made non-square in data
5131+
coordinates using *extent*).
5132+
- 'auto': The axes is kept fixed and the aspect is adjusted so
5133+
that the data fit in the axes. In general, this will result in
5134+
non-square pixels.
51315135
5132-
interpolation : string, optional, default: None
5133-
Acceptable values are 'none', 'nearest', 'bilinear', 'bicubic',
5136+
Defaults to :rc:`image.aspect`.
5137+
5138+
interpolation : str, optional
5139+
Supported values are 'none', 'nearest', 'bilinear', 'bicubic',
51345140
'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser',
51355141
'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc',
5136-
'lanczos'
5142+
'lanczos'.
5143+
5144+
Defaults to :rc:`image.interpolation`.
51375145
5138-
If `interpolation` is None, default to rc `image.interpolation`.
5139-
See also the `filternorm` and `filterrad` parameters.
5140-
If `interpolation` is 'none', then no interpolation is performed
5146+
See also the *filternorm* and *filterrad* parameters.
5147+
If *interpolation* is 'none', then no interpolation is performed
51415148
on the Agg, ps and pdf backends. Other backends will fall back to
51425149
'nearest'.
51435150
5144-
norm : `~matplotlib.colors.Normalize`, optional, default: None
5145-
A `~matplotlib.colors.Normalize` instance is used to scale
5146-
a 2-D float `X` input to the (0, 1) range for input to the
5147-
`cmap`. If `norm` is None, use the default func:`normalize`.
5148-
If `norm` is an instance of `~matplotlib.colors.NoNorm`,
5149-
`X` must be an array of integers that index directly into
5150-
the lookup table of the `cmap`.
5151+
norm : `~matplotlib.colors.Normalize`, optional
5152+
If scalar data is used, the Normalize instance scales the
5153+
data values to the canonical colormap range [0,1] for mapping
5154+
to colors. By default, the data range is mapped to the
5155+
colorbar range using linear scaling. This parameter is ignored for
5156+
RGB(A) data.
51515157
5152-
vmin, vmax : scalar, optional, default: None
5153-
`vmin` and `vmax` are used in conjunction with norm to normalize
5154-
luminance data. Note if you pass a `norm` instance, your
5155-
settings for `vmin` and `vmax` will be ignored.
5158+
vmin, vmax : scalar, optional
5159+
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5160+
define the data range that the colormap covers. By default,
5161+
the colormap covers the complete value range of the supplied
5162+
data. *vmin*, *vmax* are ignored if the *norm* parameter is used.
51565163
5157-
alpha : scalar, optional, default: None
5164+
alpha : scalar, optional
51585165
The alpha blending value, between 0 (transparent) and 1 (opaque).
5159-
The ``alpha`` argument is ignored for RGBA input data.
5166+
This parameter is ignored for RGBA input data.
51605167
5161-
origin : ['upper' | 'lower'], optional, default: None
5168+
origin : {'upper', 'lower'}, optional
51625169
Place the [0,0] index of the array in the upper left or lower left
5163-
corner of the axes. If None, default to rc `image.origin`.
5170+
corner of the axes. The convention 'upper' is typically used for
5171+
matrices and images.
5172+
Defaults to :rc:`image.origin`.
51645173
5165-
extent : scalars (left, right, bottom, top), optional, default: None
5174+
extent : scalars (left, right, bottom, top), optional
51665175
The location, in data-coordinates, of the lower-left and
5167-
upper-right corners. If `None`, the image is positioned such that
5168-
the pixel centers fall on zero-based (row, column) indices.
5176+
upper-right corners. By default, the center of the lower left
5177+
pixel is at (0, 0) and pixels have a size of (1, 1), i.e. *extent*
5178+
would be (-0.5, columns-0.5, -0.5, rows-0.5). Note that using
5179+
``origin='lower'`` will exchange the meaning of 'bottom' and 'top'.
51695180
51705181
shape : scalars (columns, rows), optional, default: None
5171-
For raw buffer images
5182+
For raw buffer images.
5183+
5184+
filternorm : {0, 1}, optional, default: 1
5185+
Determines, whether the antigrain image resize filter will
5186+
normalize integer values.
51725187
5173-
filternorm : scalar, optional, default: 1
5174-
A parameter for the antigrain image resize filter. From the
5175-
antigrain documentation, if `filternorm` = 1, the filter
5188+
From the antigrain documentation: if *filternorm* = 1, the filter
51765189
normalizes integer values and corrects the rounding errors. It
51775190
doesn't do anything with the source floating point values, it
51785191
corrects only integers according to the rule of 1.0 which means
@@ -5181,15 +5194,23 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
51815194
51825195
filterrad : scalar, optional, default: 4.0
51835196
The filter radius for filters that have a radius parameter, i.e.
5184-
when interpolation is one of: 'sinc', 'lanczos' or 'blackman'
5197+
when interpolation is one of: 'sinc', 'lanczos' or 'blackman'.
5198+
5199+
resample
5200+
Undocumented.
5201+
5202+
url : str, optional
5203+
Set the url of the created `.AxesImage`. See `.Artist.set_url`.
51855204
51865205
Returns
51875206
-------
51885207
image : `~matplotlib.image.AxesImage`
51895208
51905209
Other Parameters
51915210
----------------
5192-
**kwargs : `~matplotlib.artist.Artist` properties.
5211+
**kwargs : `~matplotlib.artist.Artist` properties
5212+
These parameters are passed on to the constructor of the
5213+
`.AxesImage` artist.
51935214
51945215
See also
51955216
--------
@@ -5201,7 +5222,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
52015222
coordinates. In other words: the origin will coincide with the center
52025223
of pixel (0, 0).
52035224
5204-
Two typical representations are used for RGB images with an alpha
5225+
There are two common representations for RGB images with an alpha
52055226
channel:
52065227
52075228
- Straight (unassociated) alpha: R, G, and B channels represent the
@@ -5227,8 +5248,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
52275248
if im.get_clip_path() is None:
52285249
# image does not already have clipping set, clip to axes patch
52295250
im.set_clip_path(self.patch)
5230-
#if norm is None and shape is None:
5231-
# im.set_clim(vmin, vmax)
52325251
if vmin is not None or vmax is not None:
52335252
im.set_clim(vmin, vmax)
52345253
else:

0 commit comments

Comments
 (0)
0