Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit f308ccc

Browse filesBrowse files
timhoffmtimhoffm
committed
Improve docstring of Axes.imshow
1 parent e22a16a commit f308ccc
Copy full SHA for f308ccc

File tree

Expand file treeCollapse file tree

1 file changed

+98
-56
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+98
-56
lines changed

‎lib/matplotlib/axes/_axes.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_axes.py
+98-56Lines changed: 98 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -4988,82 +4988,117 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
49884988
origin=None, extent=None, shape=None, filternorm=1,
49894989
filterrad=4.0, imlim=None, resample=None, url=None, **kwargs):
49904990
"""
4991-
Display an image on the axes.
4991+
Display an image, i.e. data on a 2D regular raster.
49924992
49934993
Parameters
49944994
----------
4995-
X : array_like, shape (n, m) or (n, m, 3) or (n, m, 4)
4996-
Display the image in `X` to current axes. `X` may be an
4997-
array or a PIL image. If `X` is an array, it
4998-
can have the following shapes and types:
4995+
X : array-like or PIL image
4996+
The image data. Supported array shapes are:
49994997
5000-
- MxN -- values to be mapped (float or int)
5001-
- MxNx3 -- RGB (float or uint8)
5002-
- MxNx4 -- RGBA (float or uint8)
4998+
- (M, N): an image with scalar data. The data is visualized
4999+
using a colormap.
5000+
- (M, N, 3): an image with RGB values (float or uint8).
5001+
- (M, N, 4): an image with RGBA values (float or uint8), i.e.
5002+
including transparency.
50035003
5004-
MxN arrays are mapped to colors based on the `norm` (mapping
5005-
scalar to scalar) and the `cmap` (mapping the normed scalar to
5006-
a color).
5004+
The first two dimensions (M, N) define the rows and columns of
5005+
the image.
50075006
5008-
Elements of RGB and RGBA arrays represent pixels of an MxN image.
5009-
All values should be in the range [0 .. 1] for floats or
5007+
The RGB(A) values should be in the range [0 .. 1] for floats or
50105008
[0 .. 255] for integers. Out-of-range values will be clipped to
50115009
these bounds.
50125010
5013-
cmap : `~matplotlib.colors.Colormap`, optional, default: None
5014-
If None, default to rc `image.cmap` value. `cmap` is ignored
5015-
if `X` is 3-D, directly specifying RGB(A) values.
5011+
cmap : str or `~matplotlib.colors.Colormap`, optional
5012+
A Colormap instance or registered colormap name. The colormap
5013+
maps scalar data to colors. It is ignored for RGB(A) data.
5014+
Defaults to :rc:`image.cmap`.
50165015
5017-
aspect : ['auto' | 'equal' | scalar], optional, default: None
5018-
If 'auto', changes the image aspect ratio to match that of the
5019-
axes.
5016+
aspect : {'equal', 'auto'} or float, optional
5017+
Controls the aspect ratio of the axes. The aspect is of particular
5018+
relevance for images since it may distort the image, i.e. pixel
5019+
will not be square.
50205020
5021-
If 'equal', and `extent` is None, changes the axes aspect ratio to
5022-
match that of the image. If `extent` is not `None`, the axes
5023-
aspect ratio is changed to match that of the extent.
5021+
This parameter is a shortcut for explicitly calling
5022+
`.Axes.set_aspect`. See there for further details.
50245023
5025-
If None, default to rc ``image.aspect`` value.
5024+
- 'equal': Ensures an aspect ratio of 1. Pixels will be square
5025+
(unless pixel sizes are explicitly made non-square in data
5026+
coordinates using *extent*).
5027+
- 'auto': The axes is kept fixed and the aspect is adjusted so
5028+
that the data fit in the axes. In general, this will result in
5029+
non-square pixels.
5030+
5031+
Defaults to :rc:`image.aspect`.
5032+
5033+
interpolation : str, optional
5034+
The interpolation method used. If *None*
5035+
:rc:`image.interpolation` is used, which defaults to 'nearest'.
50265036
5027-
interpolation : string, optional, default: None
5028-
Acceptable values are 'none', 'nearest', 'bilinear', 'bicubic',
5037+
Supported values are 'none', 'nearest', 'bilinear', 'bicubic',
50295038
'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser',
50305039
'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc',
5031-
'lanczos'
5040+
'lanczos'.
50325041
5033-
If `interpolation` is None, default to rc `image.interpolation`.
5034-
See also the `filternorm` and `filterrad` parameters.
5035-
If `interpolation` is 'none', then no interpolation is performed
5042+
If *interpolation* is 'none', then no interpolation is performed
50365043
on the Agg, ps and pdf backends. Other backends will fall back to
50375044
'nearest'.
50385045
5039-
norm : `~matplotlib.colors.Normalize`, optional, default: None
5040-
A `~matplotlib.colors.Normalize` instance is used to scale
5041-
a 2-D float `X` input to the (0, 1) range for input to the
5042-
`cmap`. If `norm` is None, use the default func:`normalize`.
5043-
If `norm` is an instance of `~matplotlib.colors.NoNorm`,
5044-
`X` must be an array of integers that index directly into
5045-
the lookup table of the `cmap`.
5046+
See
5047+
:doc:`/gallery/images_contours_and_fields/interpolation_methods`
5048+
for an overview of the supported interpolation methods.
50465049
5047-
vmin, vmax : scalar, optional, default: None
5048-
`vmin` and `vmax` are used in conjunction with norm to normalize
5049-
luminance data. Note if you pass a `norm` instance, your
5050-
settings for `vmin` and `vmax` will be ignored.
5050+
Some interpolation methods require an additional radius parameter,
5051+
which can be set by *filterrad*. Additionally, the antigrain image
5052+
resize filter is controlled by the parameter *filternorm*.
50515053
5052-
alpha : scalar, optional, default: None
5054+
norm : `~matplotlib.colors.Normalize`, optional
5055+
If scalar data are used, the Normalize instance scales the
5056+
data values to the canonical colormap range [0,1] for mapping
5057+
to colors. By default, the data range is mapped to the
5058+
colorbar range using linear scaling. This parameter is ignored for
5059+
RGB(A) data.
5060+
5061+
vmin, vmax : scalar, optional
5062+
When using scalar data and no explicit *norm*, *vmin* and *vmax*
5063+
define the data range that the colormap covers. By default,
5064+
the colormap covers the complete value range of the supplied
5065+
data. *vmin*, *vmax* are ignored if the *norm* parameter is used.
5066+
5067+
alpha : scalar, optional
50535068
The alpha blending value, between 0 (transparent) and 1 (opaque).
5054-
The ``alpha`` argument is ignored for RGBA input data.
5069+
This parameter is ignored for RGBA input data.
50555070
5056-
origin : ['upper' | 'lower'], optional, default: None
5071+
origin : {'upper', 'lower'}, optional
50575072
Place the [0,0] index of the array in the upper left or lower left
5058-
corner of the axes. If None, default to rc `image.origin`.
5073+
corner of the axes. The convention 'upper' is typically used for
5074+
matrices and images.
5075+
If not given, :rc:`image.origin` is used, defaulting to 'upper'.
5076+
5077+
Note that the vertical axes points upward for 'lower'
5078+
but downward for 'upper'.
5079+
5080+
extent : scalars (left, right, bottom, top), optional
5081+
The bounding box in data coordinates that the image will fill.
5082+
The image is stretched individually along x and y to fill the box.
50595083
5060-
extent : scalars (left, right, bottom, top), optional, default: None
5061-
The location, in data-coordinates, of the lower-left and
5062-
upper-right corners. If `None`, the image is positioned such that
5063-
the pixel centers fall on zero-based (row, column) indices.
5084+
The default extent is determined by the following conditions.
5085+
Pixels have unit size in data coordinates. Their centers are on
5086+
integer coordinates, and their center coordinates range from 0 to
5087+
columns-1 horizontally and from 0 to rows-1 vertically.
5088+
5089+
Note that the direction of the vertical axis and thus the default
5090+
values for top and bottom depend on *origin*:
5091+
5092+
- For ``origin == 'upper'`` the default is
5093+
``(-0.5, numcols-0.5, numrows-0.5, -0.5)``.
5094+
- For ``origin == 'lower'`` the default is
5095+
``(-0.5, numcols-0.5, -0.5, numrows-0.5)``.
5096+
5097+
See the example :doc:`/tutorials/intermediate/imshow_extent` for a
5098+
more detailed description.
50645099
50655100
shape : scalars (columns, rows), optional, default: None
5066-
For raw buffer images
5101+
For raw buffer images.
50675102
50685103
filternorm : bool, optional, default: True
50695104
A parameter for the antigrain image resize filter (see the
@@ -5074,17 +5109,26 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
50745109
that any sum of pixel weights must be equal to 1.0. So, the
50755110
filter function must produce a graph of the proper shape.
50765111
5077-
filterrad : scalar, optional, default: 4.0
5112+
filterrad : float > 0, optional, default: 4.0
50785113
The filter radius for filters that have a radius parameter, i.e.
5079-
when interpolation is one of: 'sinc', 'lanczos' or 'blackman'
5114+
when interpolation is one of: 'sinc', 'lanczos' or 'blackman'.
5115+
5116+
resample : bool, optional
5117+
When *True*, use a full resampling method. When *False*, only
5118+
resample when the output image is larger than the input image.
5119+
5120+
url : str, optional
5121+
Set the url of the created `.AxesImage`. See `.Artist.set_url`.
50805122
50815123
Returns
50825124
-------
50835125
image : `~matplotlib.image.AxesImage`
50845126
50855127
Other Parameters
50865128
----------------
5087-
**kwargs : `~matplotlib.artist.Artist` properties.
5129+
**kwargs : `~matplotlib.artist.Artist` properties
5130+
These parameters are passed on to the constructor of the
5131+
`.AxesImage` artist.
50885132
50895133
See also
50905134
--------
@@ -5096,7 +5140,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
50965140
coordinates. In other words: the origin will coincide with the center
50975141
of pixel (0, 0).
50985142
5099-
Two typical representations are used for RGB images with an alpha
5143+
There are two common representations for RGB images with an alpha
51005144
channel:
51015145
51025146
- Straight (unassociated) alpha: R, G, and B channels represent the
@@ -5122,8 +5166,6 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
51225166
if im.get_clip_path() is None:
51235167
# image does not already have clipping set, clip to axes patch
51245168
im.set_clip_path(self.patch)
5125-
#if norm is None and shape is None:
5126-
# im.set_clim(vmin, vmax)
51275169
if vmin is not None or vmax is not None:
51285170
im.set_clim(vmin, vmax)
51295171
else:
@@ -7273,7 +7315,7 @@ def matshow(self, Z, **kwargs):
72737315
72747316
Parameters
72757317
----------
7276-
Z : array-like(N, M)
7318+
Z : array-like(M, N)
72777319
The matrix to be displayed.
72787320
72797321
Returns

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.