Skip to content

plot_surface docstring + edge case fix #9277

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
Oct 5, 2017
Merged

plot_surface docstring + edge case fix #9277

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
171 changes: 91 additions & 80 deletions lib/mpl_toolkits/mplot3d/axes3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1560,49 +1560,60 @@ def plot(self, xs, ys, *args, **kwargs):
plot3D = plot

def plot_surface(self, X, Y, Z, *args, **kwargs):
'''
"""
Create a surface plot.

By default it will be colored in shades of a solid color,
but it also supports color mapping by supplying the *cmap*
argument.

The `rstride` and `cstride` kwargs set the stride used to
sample the input data to generate the graph. If 1k by 1k
arrays are passed in, the default values for the strides will
result in a 100x100 grid being plotted. Defaults to 10.
Raises a ValueError if both stride and count kwargs
Copy link
Member

Choose a reason for hiding this comment

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

You are also lost the information that the stride and count kwargs can't be used together, and will raise a ValueError.

(see next section) are provided.

The `rcount` and `ccount` kwargs supersedes `rstride` and
`cstride` for default sampling method for surface plotting.
These arguments will determine at most how many evenly spaced
samples will be taken from the input data to generate the graph.
This is the default sampling method unless using the 'classic'
style. Will raise ValueError if both stride and count are
specified.
Added in v2.0.0.
Copy link
Member

Choose a reason for hiding this comment

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

The fact that this kwarg was added in v2.0.0 is important. I can't tell you the number of times I run into situations where I tried using a feature in an older codebase only to discover that the feature isn't available in the older version of the package because it wasn't documented as such on the website.

By default it will be colored in shades of a solid color, but it also
supports color mapping by supplying the *cmap* argument.

============= ================================================
Argument Description
============= ================================================
*X*, *Y*, *Z* Data values as 2D arrays
*rstride* Array row stride (step size)
*cstride* Array column stride (step size)
*rcount* Use at most this many rows, defaults to 50
*ccount* Use at most this many columns, defaults to 50
*color* Color of the surface patches
*cmap* A colormap for the surface patches.
*facecolors* Face colors for the individual patches
*norm* An instance of Normalize to map values to colors
*vmin* Minimum value to map
*vmax* Maximum value to map
*shade* Whether to shade the facecolors
============= ================================================
.. note::

Other arguments are passed on to
:class:`~mpl_toolkits.mplot3d.art3d.Poly3DCollection`
'''
The *rcount* and *ccount* kwargs, which both default to 50,
determine the maximum number of samples used in each direction. If
the input data is larger, it will be downsampled (by slicing) to
these numbers of points.

Parameters
----------
X, Y, Z : 2d arrays
Data values.

rcount, ccount : int
Maximum number of samples used in each direction. If the input
data is larger, it will be downsampled (by slicing) to these
numbers of points. Defaults to 50.

.. versionadded:: 2.0

rstride, cstride : int
Downsampling stride in each direction. These arguments are
mutually exclusive with *rcount* and *ccount*. If only one of
*rstride* or *cstride* is set, the other defaults to 10.

'classic' mode uses a default of ``rstride = cstride = 10`` instead
of the new default of ``rcount = ccount = 50``.

color : color-like
Color of the surface patches.

cmap : Colormap
Colormap of the surface patches.

facecolors : array-like of colors.
Colors of each individual patch.

norm : Normalize
Normalization for the colormap.

vmin, vmax : float
Bounds for the normalization.

shade : bool
Whether to shade the face colors.

**kwargs :
Other arguments are forwarded to `~.Poly3DCollection`.
"""

had_data = self.has_data()

Expand All @@ -1628,14 +1639,14 @@ def plot_surface(self, X, Y, Z, *args, **kwargs):
# So, only compute strides from counts
# if counts were explicitly given
if has_count:
rstride = int(np.ceil(rows / rcount))
cstride = int(np.ceil(cols / ccount))
rstride = int(max(np.ceil(rows / rcount), 1))
cstride = int(max(np.ceil(cols / ccount), 1))
else:
# If the strides are provided then it has priority.
# Otherwise, compute the strides from the counts.
if not has_stride:
rstride = int(np.ceil(rows / rcount))
cstride = int(np.ceil(cols / ccount))
rstride = int(max(np.ceil(rows / rcount), 1))
cstride = int(max(np.ceil(cols / ccount), 1))

if 'facecolors' in kwargs:
fcolors = kwargs.pop('facecolors')
Expand Down Expand Up @@ -1779,44 +1790,44 @@ def _shade_colors_lightsource(self, data, cmap, lightsource):
return lightsource.shade(data, cmap)

def plot_wireframe(self, X, Y, Z, *args, **kwargs):
'''
"""
Plot a 3D wireframe.

The `rstride` and `cstride` kwargs set the stride used to
sample the input data to generate the graph. If either is 0
the input data in not sampled along this direction producing a
3D line plot rather than a wireframe plot. The stride arguments
are only used by default if in the 'classic' mode. They are
now superseded by `rcount` and `ccount`. Will raise ValueError
if both stride and count are used.

` The `rcount` and `ccount` kwargs supersedes `rstride` and
`cstride` for default sampling method for wireframe plotting.
These arguments will determine at most how many evenly spaced
samples will be taken from the input data to generate the graph.
This is the default sampling method unless using the 'classic'
style. Will raise ValueError if both stride and count are
specified. If either is zero, then the input data is not sampled
along this direction, producing a 3D line plot rather than a
wireframe plot.
Added in v2.0.0.
.. note::

========== ================================================
Argument Description
========== ================================================
*X*, *Y*, Data values as 2D arrays
*Z*
*rstride* Array row stride (step size), defaults to 1
*cstride* Array column stride (step size), defaults to 1
*rcount* Use at most this many rows, defaults to 50
*ccount* Use at most this many columns, defaults to 50
========== ================================================
The *rcount* and *ccount* kwargs, which both default to 50,
determine the maximum number of samples used in each direction. If
the input data is larger, it will be downsampled (by slicing) to
these numbers of points.

Keyword arguments are passed on to
:class:`~matplotlib.collections.LineCollection`.
Parameters
----------
X, Y, Z : 2d arrays
Data values.

Returns a :class:`~mpl_toolkits.mplot3d.art3d.Line3DCollection`
'''
rcount, ccount : int
Maximum number of samples used in each direction. If the input
data is larger, it will be downsampled (by slicing) to these
numbers of points. Setting a count to zero causes the data to be
not sampled in the corresponding direction, producing a 3D line
plot rather than a wireframe plot. Defaults to 50.

.. versionadded:: 2.0

rstride, cstride : int
Downsampling stride in each direction. These arguments are
mutually exclusive with *rcount* and *ccount*. If only one of
*rstride* or *cstride* is set, the other defaults to 1. Setting a
stride to zero causes the data to be not sampled in the
corresponding direction, producing a 3D line plot rather than a
wireframe plot.

'classic' mode uses a default of ``rstride = cstride = 1`` instead
of the new default of ``rcount = ccount = 50``.

**kwargs :
Other arguments are forwarded to `~.Line3DCollection`.
"""

had_data = self.has_data()
if Z.ndim != 2:
Expand All @@ -1841,14 +1852,14 @@ def plot_wireframe(self, X, Y, Z, *args, **kwargs):
# So, only compute strides from counts
# if counts were explicitly given
if has_count:
rstride = int(np.ceil(rows / rcount)) if rcount else 0
cstride = int(np.ceil(cols / ccount)) if ccount else 0
rstride = int(max(np.ceil(rows / rcount), 1)) if rcount else 0
cstride = int(max(np.ceil(cols / ccount), 1)) if ccount else 0
else:
# If the strides are provided then it has priority.
# Otherwise, compute the strides from the counts.
if not has_stride:
rstride = int(np.ceil(rows / rcount)) if rcount else 0
cstride = int(np.ceil(cols / ccount)) if ccount else 0
rstride = int(max(np.ceil(rows / rcount), 1)) if rcount else 0
cstride = int(max(np.ceil(cols / ccount), 1)) if ccount else 0

# We want two sets of lines, one running along the "rows" of
# Z and another set of lines running along the "columns" of Z.
Expand Down