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

Commit 3f985bd

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

File tree

1 file changed

+92
-57
lines changed

1 file changed

+92
-57
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 92 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -5093,103 +5093,140 @@ 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.
5135+
5136+
Defaults to :rc:`image.aspect`.
51315137
5132-
interpolation : string, optional, default: None
5133-
Acceptable values are 'none', 'nearest', 'bilinear', 'bicubic',
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+
Note that the vertical axes points upward for 'lower'
5175+
but downward for 'upper'.
5176+
5177+
extent : scalars (left, right, bottom, top), optional
51665178
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.
5179+
upper-right corners.
5180+
5181+
By default, pixels have a size of (1, 1). They are centered on
5182+
integer coordinates and their center coordinates range from 0 to
5183+
columns-1 horizontally and from 0 to rows-1 vertically.
5184+
5185+
Note that the relation of *top* and *bottom* to data coordinates
5186+
depends on *origin* because *origin* changes the direction of the
5187+
vertical axis.
5188+
5189+
- If origin is set to "upper", the center of the lower left
5190+
pixel is at (0, rows) , this corresponds to an extent
5191+
of (-0.5, columns-0.5, rows-0.5, -0.5).
5192+
- If origin is set to "lower", the center of the lower left
5193+
pixel is at (0, 0). This is equivalent to an extent
5194+
of (-0.5, columns-0.5, -0.5, rows-0.5).
51695195
51705196
shape : scalars (columns, rows), optional, default: None
5171-
For raw buffer images
5197+
For raw buffer images.
5198+
5199+
filternorm : {0, 1}, optional, default: 1
5200+
Determines, whether the antigrain image resize filter will
5201+
normalize integer values.
51725202
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
5203+
From the antigrain documentation: if *filternorm* = 1, the filter
51765204
normalizes integer values and corrects the rounding errors. It
51775205
doesn't do anything with the source floating point values, it
51785206
corrects only integers according to the rule of 1.0 which means
51795207
that any sum of pixel weights must be equal to 1.0. So, the
51805208
filter function must produce a graph of the proper shape.
51815209
5182-
filterrad : scalar, optional, default: 4.0
5210+
filterrad : float > 0, optional, default: 4.0
51835211
The filter radius for filters that have a radius parameter, i.e.
5184-
when interpolation is one of: 'sinc', 'lanczos' or 'blackman'
5212+
when interpolation is one of: 'sinc', 'lanczos' or 'blackman'.
5213+
5214+
resample : bool, optional
5215+
When *True*, use a full resampling method. When *False*, only
5216+
resample when the output image is larger than the input image.
5217+
5218+
url : str, optional
5219+
Set the url of the created `.AxesImage`. See `.Artist.set_url`.
51855220
51865221
Returns
51875222
-------
51885223
image : `~matplotlib.image.AxesImage`
51895224
51905225
Other Parameters
51915226
----------------
5192-
**kwargs : `~matplotlib.artist.Artist` properties.
5227+
**kwargs : `~matplotlib.artist.Artist` properties
5228+
These parameters are passed on to the constructor of the
5229+
`.AxesImage` artist.
51935230
51945231
See also
51955232
--------
@@ -5201,7 +5238,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
52015238
coordinates. In other words: the origin will coincide with the center
52025239
of pixel (0, 0).
52035240
5204-
Two typical representations are used for RGB images with an alpha
5241+
There are two common representations for RGB images with an alpha
52055242
channel:
52065243
52075244
- Straight (unassociated) alpha: R, G, and B channels represent the
@@ -5227,8 +5264,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
52275264
if im.get_clip_path() is None:
52285265
# image does not already have clipping set, clip to axes patch
52295266
im.set_clip_path(self.patch)
5230-
#if norm is None and shape is None:
5231-
# im.set_clim(vmin, vmax)
52325267
if vmin is not None or vmax is not None:
52335268
im.set_clim(vmin, vmax)
52345269
else:

0 commit comments

Comments
 (0)
0