"""

axes3d.py, original mplot3d version by John Porter

Created: 23 Sep 2005

Parts fixed by Reinier Heeres <[email protected]>

Minor additions by Ben Axelrod <[email protected]>

Significant updates and revisions by Ben Root <[email protected]>

Module containing Axes3D, an object which can plot 3D objects on a

2D matplotlib figure.

Coordinate Systems

------------------

3D plotting involves several coordinate transformations:

1. **Data coordinates**: The user's raw x, y, z values.

2. **Transformed coordinates**: Data coordinates after applying axis scale

transforms (log, symlog, etc.). For linear scales, these equal data

coordinates. Zoom/pan operations work in this space to ensure uniform

behavior with non-linear scales.

3. **Normalized coordinates**: Transformed coordinates mapped to a [0, 1]

unit cube based on the current axis limits.

4. **Projected coordinates**: 2D coordinates after applying the 3D to 2D

projection matrix, ready for display.

Artists receive data in data coordinates, apply scale transforms internally

via ``do_3d_projection()``, then project to 2D for rendering.

"""

from collections import defaultdict

import itertools

import math

import textwrap

import warnings

import numpy as np

import matplotlib as mpl

from matplotlib import _api, cbook, _docstring, _preprocess_data

import matplotlib.artist as martist

import matplotlib.collections as mcoll

import matplotlib.colors as mcolors

import matplotlib.image as mimage

import matplotlib.lines as mlines

import matplotlib.patches as mpatches

import matplotlib.container as mcontainer

import matplotlib.transforms as mtransforms

from matplotlib.axes import Axes

from matplotlib.axes._base import _axis_method_wrapper, _process_plot_format

from matplotlib.transforms import Bbox

from matplotlib.tri._triangulation import Triangulation

from . import art3d

from . import proj3d

from . import axis3d

@_docstring.interpd

@_api.define_aliases({

"xlim": ["xlim3d"], "ylim": ["ylim3d"], "zlim": ["zlim3d"]})

class Axes3D(Axes):

"""

3D Axes object.

.. note::

As a user, you do not instantiate Axes directly, but use Axes creation

methods instead; e.g. from `.pyplot` or `.Figure`:

`~.pyplot.subplots`, `~.pyplot.subplot_mosaic` or `.Figure.add_axes`.

.. note::

Some of the inherited behavior of Axes is not applicable to 3d and will raise

an `.UnsupportedError`.

"""

name = '3d'

_axis_names = ("x", "y", "z")

Axes._shared_axes["z"] = cbook.Grouper()

Axes._shared_axes["view"] = cbook.Grouper()

def __init__(

self, fig, rect=None, *args,

elev=30, azim=-60, roll=0, shareview=None, sharez=None,

proj_type='persp', focal_length=None,

box_aspect=None,

computed_zorder=True,

**kwargs,

):

"""

Parameters

----------

fig : Figure

The parent figure.

rect : tuple (left, bottom, width, height), default: (0, 0, 1, 1)

The ``(left, bottom, width, height)`` Axes position.

elev : float, default: 30

The elevation angle in degrees rotates the camera above and below

the x-y plane, with a positive angle corresponding to a location

above the plane.

azim : float, default: -60

The azimuthal angle in degrees rotates the camera about the z axis,

with a positive angle corresponding to a right-handed rotation. In

other words, a positive azimuth rotates the camera about the origin

from its location along the +x axis towards the +y axis.

roll : float, default: 0

The roll angle in degrees rotates the camera about the viewing

axis. A positive angle spins the camera clockwise, causing the

scene to rotate counter-clockwise.

shareview : Axes3D, optional

Other Axes to share view angles with. Note that it is not possible

to unshare axes.

sharez : Axes3D, optional

Other Axes to share z-limits with. Note that it is not possible to

unshare axes.

proj_type : {'persp', 'ortho'}

The projection type, default 'persp'.

focal_length : float, default: None

For a projection type of 'persp', the focal length of the virtual

camera. Must be > 0. If None, defaults to 1.

For a projection type of 'ortho', must be set to either None

or infinity (numpy.inf). If None, defaults to infinity.

The focal length can be computed from a desired Field Of View via

the equation: focal_length = 1/tan(FOV/2)

box_aspect : 3-tuple of floats, default: None

Changes the physical dimensions of the Axes3D, such that the ratio

of the axis lengths in display units is x:y:z.

If None, defaults to 4:4:3

computed_zorder : bool, default: True

If True, the draw order is computed based on the average position

along the view direction for supported artist types (currently

Collections and Patches only).

Set to False if you want to manually control the order in which

Artists are drawn on top of each other using their *zorder*

attribute. This can be used for fine-tuning if the automatic order

does not produce the desired result. Note however, that a manual

order will only be correct for a limited view angle. If the figure

is rotated by the user, it will look wrong from certain angles.

**kwargs

Other optional keyword arguments:

%(Axes3D:kwdoc)s

"""

if rect is None:

rect = [0.0, 0.0, 1.0, 1.0]

self.initial_azim = azim

self.initial_elev = elev

self.initial_roll = roll

self.set_proj_type(proj_type, focal_length)

self.computed_zorder = computed_zorder

self.xy_viewLim = Bbox.unit()

self.zz_viewLim = Bbox.unit()

xymargin = 0.05 * 10/11 # match mpl3.8 appearance

self.xy_dataLim = Bbox([[xymargin, xymargin],

[1 - xymargin, 1 - xymargin]])

# z-limits are encoded in the x-component of the Bbox, y is un-used

self.zz_dataLim = Bbox.unit()

# inhibit autoscale_view until the axes are defined

# they can't be defined until Axes.__init__ has been called

self.view_init(self.initial_elev, self.initial_azim, self.initial_roll)

self._sharez = sharez

if sharez is not None:

self._shared_axes["z"].join(self, sharez)

self._adjustable = 'datalim'

self._shareview = shareview

if shareview is not None:

self._shared_axes["view"].join(self, shareview)

if kwargs.pop('auto_add_to_figure', False):

raise AttributeError(

'auto_add_to_figure is no longer supported for Axes3D. '

'Use fig.add_axes(ax) instead.'

)

super().__init__(

fig, rect, frameon=True, box_aspect=box_aspect, *args, **kwargs

)

# Disable drawing of axes by base class

super().set_axis_off()

# Enable drawing of axes by Axes3D class

self.set_axis_on()

self.M = None

self.invM = None

self._view_margin = 1/48 # default value to match mpl3.8

self.autoscale_view()

# func used to format z -- fall back on major formatters

self.fmt_zdata = None

self.mouse_init()

fig = self.get_figure(root=True)

fig.canvas.callbacks._connect_picklable(

'motion_notify_event', self._on_move)

fig.canvas.callbacks._connect_picklable(

'button_press_event', self._button_press)

fig.canvas.callbacks._connect_picklable(

'button_release_event', self._button_release)

self.set_top_view()

self.patch.set_linewidth(0)

# Calculate the pseudo-data width and height

pseudo_bbox = self.transLimits.inverted().transform([(0, 0), (1, 1)])

self._pseudo_w, self._pseudo_h = pseudo_bbox[1] - pseudo_bbox[0]

# mplot3d currently manages its own spines and needs these turned off

# for bounding box calculations

self.spines[:].set_visible(False)

def set_axis_off(self):

self._axis3don = False

self.stale = True

def set_axis_on(self):

self._axis3don = True

self.stale = True

def convert_zunits(self, z):

"""

For artists in an Axes, if the zaxis has units support,

convert *z* using zaxis unit type

"""

return self.zaxis.convert_units(z)

def set_top_view(self):

# this happens to be the right view for the viewing coordinates

# moved up and to the left slightly to fit labels and axes

xdwl = 0.95 / self._dist

xdw = 0.9 / self._dist

ydwl = 0.95 / self._dist

ydw = 0.9 / self._dist

# Set the viewing pane.

self.viewLim.intervalx = (-xdwl, xdw)

self.viewLim.intervaly = (-ydwl, ydw)

self.stale = True

def _init_axis(self):

"""Init 3D Axes; overrides creation of regular X/Y Axes."""

self.xaxis = axis3d.XAxis(self)

self.yaxis = axis3d.YAxis(self)

self.zaxis = axis3d.ZAxis(self)

def get_zaxis(self):

"""Return the ``ZAxis`` (`~.axis3d.Axis`) instance."""

return self.zaxis

get_zgridlines = _axis_method_wrapper("zaxis", "get_gridlines")

get_zticklines = _axis_method_wrapper("zaxis", "get_ticklines")

def _transformed_cube(self, vals):

"""Return cube with limits from *vals* transformed by self.M.

The vals are in data space and are first transformed through the

axis scale transforms before being projected.

"""

minx, maxx, miny, maxy, minz, maxz = vals

# Transform from data space to transformed coordinates

minx, maxx = self.xaxis.get_transform().transform([minx, maxx])

miny, maxy = self.yaxis.get_transform().transform([miny, maxy])

minz, maxz = self.zaxis.get_transform().transform([minz, maxz])

xyzs = [(minx, miny, minz),

(maxx, miny, minz),

(maxx, maxy, minz),

(minx, maxy, minz),

(minx, miny, maxz),

(maxx, miny, maxz),

(maxx, maxy, maxz),

(minx, maxy, maxz)]

return np.column_stack(proj3d._proj_trans_points(xyzs, self.M))

def _update_transScale(self):

"""

Override transScale to always use identity transforms.

In 2D axes, transScale applies scale transforms (log, symlog, etc.) to

convert data coordinates to display coordinates. In 3D axes, scale

transforms are applied to data coordinates before 3D projection via

each axis's transform. The projected 2D coordinates are already in

display space, so transScale must be identity to avoid double-scaling.

"""

self.transScale.set(

mtransforms.blended_transform_factory(

mtransforms.IdentityTransform(),

mtransforms.IdentityTransform()))

@_api.delete_parameter("3.11", "share")

@_api.delete_parameter("3.11", "anchor")

def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):

"""

Set the aspect ratios.

Parameters

----------

aspect : {'auto', 'equal', 'equalxy', 'equalxz', 'equalyz'}

Possible values:

========= ==================================================

value description

========= ==================================================

'auto' automatic; fill the position rectangle with data.

'equal' adapt all the axes to have equal aspect ratios.

'equalxy' adapt the x and y axes to have equal aspect ratios.

'equalxz' adapt the x and z axes to have equal aspect ratios.

'equalyz' adapt the y and z axes to have equal aspect ratios.

========= ==================================================

adjustable : {'box', 'datalim'}, default: 'box'

Defines which parameter to adjust to meet the aspect ratio.

- 'box': Change the physical dimensions of the axes bounding box.

- 'datalim': Change the x, y, or z data limits.

anchor : None or str or 2-tuple of float, optional

.. deprecated:: 3.11

This parameter has no effect.

share : bool, default: False

.. deprecated:: 3.11

This parameter has no effect.

See Also

--------

mpl_toolkits.mplot3d.axes3d.Axes3D.set_box_aspect

"""

if adjustable is None:

adjustable = 'box'

_api.check_in_list(['box', 'datalim'], adjustable=adjustable)

_api.check_in_list(('auto', 'equal', 'equalxy', 'equalyz', 'equalxz'),

aspect=aspect)

self.set_adjustable(adjustable)

self._aspect = aspect

if aspect in ('equal', 'equalxy', 'equalxz', 'equalyz'):

ax_indices = self._equal_aspect_axis_indices(aspect)

view_intervals = np.array([self.xaxis.get_view_interval(),

self.yaxis.get_view_interval(),

self.zaxis.get_view_interval()])

ptp = np.ptp(view_intervals, axis=1)

if self._adjustable == 'datalim':

mean = np.mean(view_intervals, axis=1)

scale = max(ptp[ax_indices] / self._box_aspect[ax_indices])

deltas = scale * self._box_aspect

for i, set_lim in enumerate((self.set_xlim3d,

self.set_ylim3d,

self.set_zlim3d)):

if i in ax_indices:

set_lim(mean[i] - deltas[i]/2., mean[i] + deltas[i]/2.,

auto=True, view_margin=None)

else: # 'box'

# Change the box aspect such that the ratio of the length of

# the unmodified axis to the length of the diagonal

# perpendicular to it remains unchanged.

box_aspect = np.array(self._box_aspect)

box_aspect[ax_indices] = ptp[ax_indices]

remaining_ax_indices = {0, 1, 2}.difference(ax_indices)

if remaining_ax_indices:

remaining = remaining_ax_indices.pop()

old_diag = np.linalg.norm(self._box_aspect[ax_indices])

new_diag = np.linalg.norm(box_aspect[ax_indices])

box_aspect[remaining] *= new_diag / old_diag

self.set_box_aspect(box_aspect)

def _equal_aspect_axis_indices(self, aspect):

"""

Get the indices for which of the x, y, z axes are constrained to have

equal aspect ratios.

Parameters

----------

aspect : {'auto', 'equal', 'equalxy', 'equalxz', 'equalyz'}

See descriptions in docstring for `.set_aspect()`.

"""

ax_indices = [] # aspect == 'auto'

if aspect == 'equal':

ax_indices = [0, 1, 2]

elif aspect == 'equalxy':

ax_indices = [0, 1]

elif aspect == 'equalxz':

ax_indices = [0, 2]

elif aspect == 'equalyz':

ax_indices = [1, 2]

return ax_indices

def set_box_aspect(self, aspect, *, zoom=1):

"""

Set the Axes box aspect.

The box aspect is the ratio of height to width in display

units for each face of the box when viewed perpendicular to

that face. This is not to be confused with the data aspect (see

`~.Axes3D.set_aspect`). The default ratios are 4:4:3 (x:y:z).

To simulate having equal aspect in data space, set the box

aspect to match your data range in each dimension.

*zoom* controls the overall size of the Axes3D in the figure.

Parameters

----------

aspect : 3-tuple of floats or None

Changes the physical dimensions of the Axes3D, such that the ratio

of the axis lengths in display units is x:y:z.

If None, defaults to (4, 4, 3).

zoom : float, default: 1

Control overall size of the Axes3D in the figure. Must be > 0.

"""

if zoom <= 0:

raise ValueError(f'Argument zoom = {zoom} must be > 0')

if aspect is None:

aspect = np.asarray((4, 4, 3), dtype=float)

else:

aspect = np.asarray(aspect, dtype=float)

_api.check_shape((3,), aspect=aspect)

# The scale 1.8294640721620434 is tuned to match the mpl3.2 appearance.

# The 25/24 factor is to compensate for the change in automargin

# behavior in mpl3.9. This comes from the padding of 1/48 on both sides

# of the axes in mpl3.8.

aspect *= 1.8294640721620434 * 25/24 * zoom / np.linalg.norm(aspect)

self._box_aspect = self._roll_to_vertical(aspect, reverse=True)

self.stale = True

def apply_aspect(self, position=None):

if position is None:

position = self.get_position(original=True)

# in the superclass, we would go through and actually deal with axis

# scales and box/datalim. Those are all irrelevant - all we need to do

# is make sure our coordinate system is square.

trans = self.get_figure().transSubfigure

bb = mtransforms.Bbox.unit().transformed(trans)

# this is the physical aspect of the panel (or figure):

fig_aspect = bb.height / bb.width

box_aspect = 1

pb = position.frozen()

pb1 = pb.shrunk_to_aspect(box_aspect, pb, fig_aspect)

self._set_position(pb1.anchored(self.get_anchor(), pb), 'active')

@martist.allow_rasterization

def draw(self, renderer):

if not self.get_visible():

return

self._unstale_viewLim()

# draw the background patch

self.patch.draw(renderer)

self._frameon = False

# first, set the aspect

# this is duplicated from `axes._base._AxesBase.draw`

# but must be called before any of the artist are drawn as

# it adjusts the view limits and the size of the bounding box

# of the Axes

locator = self.get_axes_locator()

self.apply_aspect(locator(self, renderer) if locator else None)

# add the projection matrix to the renderer

self.M = self.get_proj()

self.invM = np.linalg.inv(self.M)

collections_and_patches = (

artist for artist in self._children

if isinstance(artist, (mcoll.Collection, mpatches.Patch))

and artist.get_visible())

if self.computed_zorder:

# Calculate projection of collections and patches and zorder

# them. Make sure they are drawn above the grids.

zorder_offset = max(axis.get_zorder()

for axis in self._axis_map.values()) + 1

collection_zorder = patch_zorder = zorder_offset

for artist in sorted(collections_and_patches,

key=lambda artist: artist.do_3d_projection(),

reverse=True):

if isinstance(artist, mcoll.Collection):

artist.zorder = collection_zorder

collection_zorder += 1

elif isinstance(artist, mpatches.Patch):

artist.zorder = patch_zorder

patch_zorder += 1

else:

for artist in collections_and_patches:

artist.do_3d_projection()

if self._axis3don:

# Draw panes first

for axis in self._axis_map.values():

axis.draw_pane(renderer)

# Then gridlines

for axis in self._axis_map.values():

axis.draw_grid(renderer)

# Then axes, labels, text, and ticks

for axis in self._axis_map.values():

axis.draw(renderer)

# Then rest

super().draw(renderer)

def get_axis_position(self):

tc = self._transformed_cube(self.get_w_lims())

xhigh = tc[1][2] > tc[2][2]

yhigh = tc[3][2] > tc[2][2]

zhigh = tc[0][2] > tc[2][2]

return xhigh, yhigh, zhigh

def update_datalim(self, xys, **kwargs):

"""

Not implemented in `~mpl_toolkits.mplot3d.axes3d.Axes3D`.

"""

pass

get_autoscalez_on = _axis_method_wrapper("zaxis", "_get_autoscale_on")

set_autoscalez_on = _axis_method_wrapper("zaxis", "_set_autoscale_on")

def get_zmargin(self):

"""

Retrieve autoscaling margin of the z-axis.

.. versionadded:: 3.9

Returns

-------

zmargin : float

See Also

--------

mpl_toolkits.mplot3d.axes3d.Axes3D.set_zmargin

"""

return self._zmargin

def set_zmargin(self, m):

"""

Set padding of Z data limits prior to autoscaling.

*m* times the data interval will be added to each end of that interval

before it is used in autoscaling. If *m* is negative, this will clip

the data range instead of expanding it.

For example, if your data is in the range [0, 2], a margin of 0.1 will

result in a range [-0.2, 2.2]; a margin of -0.1 will result in a range

of [0.2, 1.8].

Parameters

----------

m : float greater than -0.5

"""

if m <= -0.5:

raise ValueError("margin must be greater than -0.5")

self._zmargin = m

self._request_autoscale_view("z")

self.stale = True

def margins(self, *margins, x=None, y=None, z=None, tight=True):

"""

Set or retrieve autoscaling margins.

See `.Axes.margins` for full documentation. Because this function

applies to 3D Axes, it also takes a *z* argument, and returns

``(xmargin, ymargin, zmargin)``.

"""

if margins and (x is not None or y is not None or z is not None):

raise TypeError('Cannot pass both positional and keyword '

'arguments for x, y, and/or z.')

elif len(margins) == 1:

x = y = z = margins[0]

elif len(margins) == 3:

x, y, z = margins

elif margins:

raise TypeError('Must pass a single positional argument for all '

'margins, or one for each margin (x, y, z).')

if x is None and y is None and z is None:

if tight is not True:

_api.warn_external(f'ignoring tight={tight!r} in get mode')

return self._xmargin, self._ymargin, self._zmargin

if x is not None:

self.set_xmargin(x)

if y is not None:

self.set_ymargin(y)

if z is not None:

self.set_zmargin(z)

self.autoscale_view(

tight=tight, scalex=(x is not None), scaley=(y is not None),

scalez=(z is not None)

)

def autoscale(self, enable=True, axis='both', tight=None):

"""

Convenience method for simple axis view autoscaling.

See `.Axes.autoscale` for full documentation. Because this function

applies to 3D Axes, *axis* can also be set to 'z', and setting *axis*

to 'both' autoscales all three axes.

"""

if enable is None:

scalex = True

scaley = True

scalez = True

else:

if axis in ['x', 'both']:

self.set_autoscalex_on(enable)

scalex = self.get_autoscalex_on()

else:

scalex = False

if axis in ['y', 'both']:

self.set_autoscaley_on(enable)

scaley = self.get_autoscaley_on()

else:

scaley = False

if axis in ['z', 'both']:

self.set_autoscalez_on(enable)

scalez = self.get_autoscalez_on()

else:

scalez = False

if scalex:

self._request_autoscale_view("x", tight=tight)

if scaley:

self._request_autoscale_view("y", tight=tight)

if scalez:

self._request_autoscale_view("z", tight=tight)

def auto_scale_xyz(self, X, Y, Z=None, had_data=None):

# This updates the bounding boxes as to keep a record as to what the

# minimum sized rectangular volume holds the data.

if np.shape(X) == np.shape(Y):

self.xy_dataLim.update_from_data_xy(

np.column_stack([np.ravel(X), np.ravel(Y)]), not had_data)

else:

self.xy_dataLim.update_from_data_x(X, not had_data)

self.xy_dataLim.update_from_data_y(Y, not had_data)

if Z is not None:

self.zz_dataLim.update_from_data_x(Z, not had_data)

# Let autoscale_view figure out how to use this data.

self.autoscale_view()

def _autoscale_axis(self, axis, v0, v1, minpos, margin, set_bound, _tight):

"""

Autoscale a single axis.

Parameters

----------

axis : Axis

The axis to autoscale.

v0, v1 : float

Data interval limits.

minpos : float

Minimum positive value for log-scale handling.

margin : float

Margin to apply (e.g., self._xmargin).

set_bound : callable

Function to set the axis bound (e.g., self.set_xbound).

_tight : bool

Whether to use tight bounds.

"""

locator = axis.get_major_locator()

v0, v1 = locator.nonsingular(v0, v1)

# Validate limits for the scale (e.g., positive for log scale)

v0, v1 = axis._scale.limit_range_for_scale(v0, v1, minpos)

if margin > 0:

# Apply margin in transformed space to handle non-linear scales

transform = axis.get_transform()

inverse_trans = transform.inverted()

v0t, v1t = transform.transform([v0, v1])

delta = (v1t - v0t) * margin

if not np.isfinite(delta):

delta = 0

v0, v1 = inverse_trans.transform([v0t - delta, v1t + delta])

if not _tight:

v0, v1 = locator.view_limits(v0, v1)

set_bound(v0, v1, self._view_margin)

def autoscale_view(self, tight=None,

scalex=True, scaley=True, scalez=True):

"""

Autoscale the view limits using the data limits.

See `.Axes.autoscale_view` for full documentation. Because this

function applies to 3D Axes, it also takes a *scalez* argument.

"""

# This method looks at the rectangular volume (see above)

# of data and decides how to scale the view portal to fit it.

if tight is None:

_tight = self._tight

if not _tight:

# if image data only just use the datalim

for artist in self._children:

if isinstance(artist, mimage.AxesImage):

_tight = True

elif isinstance(artist, (mlines.Line2D, mpatches.Patch)):

_tight = False

break

else:

_tight = self._tight = bool(tight)

if scalex and self.get_autoscalex_on():

self._autoscale_axis(

self.xaxis, *self.xy_dataLim.intervalx,

self.xy_dataLim.minposx, self._xmargin,

self.set_xbound, _tight)

if scaley and self.get_autoscaley_on():

self._autoscale_axis(

self.yaxis, *self.xy_dataLim.intervaly,

self.xy_dataLim.minposy, self._ymargin,

self.set_ybound, _tight)

if scalez and self.get_autoscalez_on():

self._autoscale_axis(

self.zaxis, *self.zz_dataLim.intervalx,

self.zz_dataLim.minposx, self._zmargin,

self.set_zbound, _tight)

def get_w_lims(self):

"""Get 3D world limits."""

minx, maxx = self.get_xlim3d()

miny, maxy = self.get_ylim3d()

minz, maxz = self.get_zlim3d()

return minx, maxx, miny, maxy, minz, maxz

def _set_bound3d(self, get_bound, set_lim, axis_inverted,

lower=None, upper=None, view_margin=None):

"""

Set 3D axis bounds.

"""

if upper is None and np.iterable(lower):

lower, upper = lower

old_lower, old_upper = get_bound()

if lower is None:

lower = old_lower

if upper is None:

upper = old_upper

set_lim(sorted((lower, upper), reverse=bool(axis_inverted())),

auto=None, view_margin=view_margin)

def set_xbound(self, lower=None, upper=None, view_margin=None):

"""

Set the lower and upper numerical bounds of the x-axis.

This method will honor axis inversion regardless of parameter order.

It will not change the autoscaling setting (`.get_autoscalex_on()`).

Parameters

----------

lower, upper : float or None

The lower and upper bounds. If *None*, the respective axis bound

is not modified.

view_margin : float or None

The margin to apply to the bounds. If *None*, the margin is handled

by `.set_xlim`.

See Also

--------

get_xbound

get_xlim, set_xlim

invert_xaxis, xaxis_inverted

"""

self._set_bound3d(self.get_xbound, self.set_xlim, self.xaxis_inverted,

lower, upper, view_margin)

def set_ybound(self, lower=None, upper=None, view_margin=None):

"""

Set the lower and upper numerical bounds of the y-axis.

This method will honor axis inversion regardless of parameter order.

It will not change the autoscaling setting (`.get_autoscaley_on()`).

Parameters

----------

lower, upper : float or None

The lower and upper bounds. If *None*, the respective axis bound

is not modified.

view_margin : float or None

The margin to apply to the bounds. If *None*, the margin is handled

by `.set_ylim`.

See Also

--------

get_ybound

get_ylim, set_ylim

invert_yaxis, yaxis_inverted

"""

self._set_bound3d(self.get_ybound, self.set_ylim, self.yaxis_inverted,

lower, upper, view_margin)

def set_zbound(self, lower=None, upper=None, view_margin=None):

"""

Set the lower and upper numerical bounds of the z-axis.

This method will honor axis inversion regardless of parameter order.

It will not change the autoscaling setting (`.get_autoscaley_on()`).

Parameters

----------

lower, upper : float or None

The lower and upper bounds. If *None*, the respective axis bound

is not modified.

view_margin : float or None

The margin to apply to the bounds. If *None*, the margin is handled

by `.set_zlim`.

See Also

--------

get_zbound

get_zlim, set_zlim

invert_zaxis, zaxis_inverted

"""

self._set_bound3d(self.get_zbound, self.set_zlim, self.zaxis_inverted,

lower, upper, view_margin)

def _set_lim3d(self, axis, lower=None, upper=None, *, emit=True,

auto=False, view_margin=None, axmin=None, axmax=None,

minpos=np.inf):

"""

Set 3D axis limits.

"""

if upper is None:

if np.iterable(lower):

lower, upper = lower

elif axmax is None:

upper = axis.get_view_interval()[1]

if lower is None and axmin is None:

lower = axis.get_view_interval()[0]

if axmin is not None:

if lower is not None:

raise TypeError("Cannot pass both 'lower' and 'min'")

lower = axmin

if axmax is not None:

if upper is not None:

raise TypeError("Cannot pass both 'upper' and 'max'")

upper = axmax

if np.isinf(lower) or np.isinf(upper):

raise ValueError(f"Axis limits {lower}, {upper} cannot be infinite")

if view_margin is None:

if mpl.rcParams['axes3d.automargin']:

view_margin = self._view_margin

else:

view_margin = 0

# Apply margin in transformed space to handle non-linear scales properly

if view_margin > 0 and hasattr(axis, '_scale') and axis._scale is not None:

transform = axis.get_transform()

inverse_trans = transform.inverted()

lower, upper = axis._scale.limit_range_for_scale(lower, upper, minpos)

lower_t, upper_t = transform.transform([lower, upper])

delta = (upper_t - lower_t) * view_margin

if np.isfinite(delta):

new_range = [lower_t - delta, upper_t + delta]

lower, upper = inverse_trans.transform(new_range)

else:

delta = (upper - lower) * view_margin

lower -= delta

upper += delta

return axis._set_lim(lower, upper, emit=emit, auto=auto)

def set_xlim(self, left=None, right=None, *, emit=True, auto=False,

view_margin=None, xmin=None, xmax=None):

"""

Set the 3D x-axis view limits.

Parameters

----------

left : float, optional

The left xlim in data coordinates. Passing *None* leaves the

limit unchanged.

The left and right xlims may also be passed as the tuple

(*left*, *right*) as the first positional argument (or as

the *left* keyword argument).

.. ACCEPTS: (left: float, right: float)

right : float, optional

The right xlim in data coordinates. Passing *None* leaves the

limit unchanged.

emit : bool, default: True

Whether to notify observers of limit change.

auto : bool or None, default: False

Whether to turn on autoscaling of the x-axis. *True* turns on,

*False* turns off, *None* leaves unchanged.

view_margin : float, optional

The additional margin to apply to the limits.

xmin, xmax : float, optional

They are equivalent to left and right respectively, and it is an

error to pass both *xmin* and *left* or *xmax* and *right*.

Returns

-------

left, right : (float, float)

The new x-axis limits in data coordinates.

See Also

--------

get_xlim

set_xbound, get_xbound

invert_xaxis, xaxis_inverted

Notes

-----

The *left* value may be greater than the *right* value, in which

case the x-axis values will decrease from *left* to *right*.

Examples

--------

>>> set_xlim(left, right)

>>> set_xlim((left, right))

>>> left, right = set_xlim(left, right)

One limit may be left unchanged.

>>> set_xlim(right=right_lim)

Limits may be passed in reverse order to flip the direction of

the x-axis. For example, suppose ``x`` represents depth of the

ocean in m. The x-axis limits might be set like the following

so 5000 m depth is at the left of the plot and the surface,

0 m, is at the right.

>>> set_xlim(5000, 0)

"""

return self._set_lim3d(self.xaxis, left, right, emit=emit, auto=auto,

view_margin=view_margin, axmin=xmin, axmax=xmax,

minpos=self.xy_dataLim.minposx)

def set_ylim(self, bottom=None, top=None, *, emit=True, auto=False,

view_margin=None, ymin=None, ymax=None):

"""

Set the 3D y-axis view limits.

Parameters

----------

bottom : float, optional

The bottom ylim in data coordinates. Passing *None* leaves the

limit unchanged.

The bottom and top ylims may also be passed as the tuple

(*bottom*, *top*) as the first positional argument (or as

the *bottom* keyword argument).

.. ACCEPTS: (bottom: float, top: float)

top : float, optional

The top ylim in data coordinates. Passing *None* leaves the

limit unchanged.

emit : bool, default: True

Whether to notify observers of limit change.

auto : bool or None, default: False

Whether to turn on autoscaling of the y-axis. *True* turns on,

*False* turns off, *None* leaves unchanged.

view_margin : float, optional

The additional margin to apply to the limits.

ymin, ymax : float, optional

They are equivalent to bottom and top respectively, and it is an

error to pass both *ymin* and *bottom* or *ymax* and *top*.

Returns

-------

bottom, top : (float, float)

The new y-axis limits in data coordinates.

See Also

--------

get_ylim

set_ybound, get_ybound

invert_yaxis, yaxis_inverted

Notes

-----

The *bottom* value may be greater than the *top* value, in which

case the y-axis values will decrease from *bottom* to *top*.

Examples

--------

>>> set_ylim(bottom, top)

>>> set_ylim((bottom, top))