Add gallery examples

eric-wieser · eric-wieser · commit 18851b2ff710 · 2017-07-15T21:14:00.000+01:00
diff --git a/examples/mplot3d/voxels.py b/examples/mplot3d/voxels.py
@@ -0,0 +1,35 @@
+'''
+==========================
+3D voxel / volumetric plot
+==========================
+
+Demonstrates plotting 3D volumetric objects with ``ax.voxels``
+'''
+
+import matplotlib.pyplot as plt
+import numpy as np
+from mpl_toolkits.mplot3d import Axes3D
+
+# prepare some coordinates
+x, y, z = np.indices((8, 8, 8))
+
+# draw cuboids in the top left and bottom right corners, and a link between them
+cube1 = (x < 3) & (y < 3) & (z < 3)
+cube2 = (x >= 5) & (y >= 5) & (z >= 5)
+link = abs(x - y) + abs(y - z) + abs(z - x) <= 2
+
+# combine the objects into a single boolean array
+voxels = cube1 | cube2 | link
+
+# set the colors of each object
+colors = np.empty(voxels.shape, dtype=object)
+colors[link] = 'red'
+colors[cube1] = 'blue'
+colors[cube2] = 'green'
+
+# and plot everything
+fig = plt.figure()
+ax = fig.gca(projection='3d')
+ax.voxels(voxels, color=colors, edgecolor='k')
+
+plt.show()
diff --git a/examples/mplot3d/voxels_rgb.py b/examples/mplot3d/voxels_rgb.py
@@ -0,0 +1,33 @@
+'''
+==========================================
+3D voxel / volumetric plot with rgb colors
+==========================================
+
+Demonstrates using ``ax.voxels`` to visualize parts of a color space
+'''
+
+import matplotlib.pyplot as plt
+import numpy as np
+from mpl_toolkits.mplot3d import Axes3D
+
+# prepare some coordinates, and attach rgb values to each
+x, y, z = np.indices((16, 16, 16))
+r = (x + 0.5) / 16
+g = (y + 0.5) / 16
+b = (z + 0.5) / 16
+
+# define a sphere about [0.5, 0.5, 0.5]
+sphere = (r - 0.5)**2 + (g - 0.5)**2 + (b - 0.5)**2 < 0.5**2
+
+# combine the color components
+colors = np.zeros(sphere.shape + (3,))
+colors[..., 0] = r
+colors[..., 1] = g
+colors[..., 2] = b
+
+# and plot everything
+fig = plt.figure()
+ax = fig.gca(projection='3d')
+ax.voxels(sphere, color=colors, edgecolor='gray', linewidth=0.5)
+
+plt.show()
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -2785,6 +2785,12 @@ def voxels(self, filled, color=None, **kwargs):
             ``filled[i,j,k]``. If no faces were drawn for a given voxel, either
             because it was not asked to be drawn, or it is fully occluded, then
             ``(i,j,k) not in faces``.
+
+        Examples
+        --------
+
+        .. plot:: gallery/mplot3d/voxels.py
+        .. plot:: gallery/mplot3d/voxels_rgb.py
         """
         # check dimensions
         if filled.ndim != 3:
