Add gallery example and whats new for 3d scales

scottshambaugh · scottshambaugh · commit 24ab58b7a76a · 2026-03-04T16:04:01.000-07:00
diff --git a/doc/release/next_whats_new/3d_scales.rst b/doc/release/next_whats_new/3d_scales.rst
@@ -0,0 +1,35 @@
+Non-linear scales on 3D axes
+----------------------------
+
+Resolving a long-standing issue, 3D axes now support non-linear axis scales
+such as 'log', 'symlog', 'logit', 'asinh', and custom 'function' scales, just
+like 2D axes. Use `~.Axes3D.set_xscale`, `~.Axes3D.set_yscale`, and
+`~.Axes3D.set_zscale` to set the scale for each axis independently.
+
+.. plot::
+    :include-source: true
+    :alt: A 3D plot with a linear x-axis, logarithmic y-axis, and symlog z-axis.
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    # A sine chirp with increasing frequency and amplitude
+    x = np.linspace(0, 1, 400)  # time
+    y = 10 ** (2 * x)  # frequency, growing exponentially from 1 to 100 Hz
+    phase = 2 * np.pi * (10 ** (2 * x) - 1) / (2 * np.log(10))
+    z = np.sin(phase) * x ** 2 * 10  # amplitude, growing quadratically
+
+    fig = plt.figure()
+    ax = fig.add_subplot(projection='3d')
+    ax.plot(x, y, z)
+
+    ax.set_xlabel('Time (linear)')
+    ax.set_ylabel('Frequency, Hz (log)')
+    ax.set_zlabel('Amplitude (symlog)')
+
+    ax.set_yscale('log')
+    ax.set_zscale('symlog')
+
+    plt.show()
+
+See `matplotlib.scale` for details on all available scales and their parameters.
diff --git a/galleries/examples/mplot3d/scales3d.py b/galleries/examples/mplot3d/scales3d.py
@@ -0,0 +1,52 @@
+"""
+================================
+Scales on 3D (Log, Symlog, etc.)
+================================
+
+Demonstrate how to use non-linear scales such as logarithmic scales on 3D axes.
+
+3D axes support the same axis scales as 2D plots: 'linear', 'log', 'symlog',
+'logit', 'asinh', and custom 'function' scales. This example shows a mix of
+scales: linear on X, log on Y, and symlog on Z.
+
+For a complete list of built-in scales, see `matplotlib.scale`. For an overview
+of scale transformations, see :doc:`/gallery/scales/scales`.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+# A sine chirp with increasing frequency and amplitude
+x = np.linspace(0, 1, 400)  # time
+y = 10 ** (2 * x)  # frequency, growing exponentially from 1 to 100 Hz
+phase = 2 * np.pi * (10 ** (2 * x) - 1) / (2 * np.log(10))
+z = np.sin(phase) * x **2 * 10  # amplitude, growing quadratically
+
+fig = plt.figure()
+ax = fig.add_subplot(projection='3d')
+ax.plot(x, y, z)
+
+ax.set_xlabel('Time (linear)')
+ax.set_ylabel('Frequency, Hz (log)')
+ax.set_zlabel('Amplitude (symlog)')
+
+ax.set_yscale('log')
+ax.set_zscale('symlog')
+
+plt.show()
+
+# %%
+#
+# .. admonition:: References
+#
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
+#
+#    - `mpl_toolkits.mplot3d.axes3d.Axes3D.set_xscale`
+#    - `mpl_toolkits.mplot3d.axes3d.Axes3D.set_yscale`
+#    - `mpl_toolkits.mplot3d.axes3d.Axes3D.set_zscale`
+#    - `matplotlib.scale`
+#
+# .. tags::
+#    plot-type: 3D,
+#    level: beginner
diff --git a/galleries/examples/scales/scales.py b/galleries/examples/scales/scales.py
@@ -5,8 +5,9 @@
 
 Illustrate the scale transformations applied to axes, e.g. log, symlog, logit.
 
-See `matplotlib.scale` for a full list of built-in scales, and
-:doc:`/gallery/scales/custom_scale` for how to create your own scale.
+See `matplotlib.scale` for a full list of built-in scales,
+:doc:`/gallery/scales/custom_scale` for how to create your own scale, and
+:doc:`/gallery/mplot3d/scales3d` for using scales on 3D axes.
 """
 
 import matplotlib.pyplot as plt
