Merge pull request matplotlib#6404 from eric-wieser/patch-1

ENH: Add a ax.voxels(bool3d) function

Author: tacaswell

doc/users/whats_new/axes3d_voxels.rst

@@ -0,0 +1,5 @@
+``voxels`` function for mplot3d
+-------------------------------
+:class:`~mpl_toolkits.mplot3d.axes3d.Axes3D` now has a ``voxels`` method, for
+visualizing boolean 3d data. Uses could include plotting a sparse 3D heat map,
+or visualizing a volumetric model.

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, facecolors=colors, edgecolor='k')
+
+plt.show()

examples/mplot3d/voxels_numpy_logo.py

@@ -0,0 +1,47 @@
+'''
+===============================
+3D voxel plot of the numpy logo
+===============================
+
+Demonstrates using ``ax.voxels`` with uneven coordinates
+'''
+import matplotlib.pyplot as plt
+import numpy as np
+from mpl_toolkits.mplot3d import Axes3D
+
+
+def explode(data):
+    size = np.array(data.shape)*2
+    data_e = np.zeros(size - 1, dtype=data.dtype)
+    data_e[::2, ::2, ::2] = data
+    return data_e
+
+# build up the numpy logo
+n_voxels = np.zeros((4, 3, 4), dtype=bool)
+n_voxels[0, 0, :] = True
+n_voxels[-1, 0, :] = True
+n_voxels[1, 0, 2] = True
+n_voxels[2, 0, 1] = True
+facecolors = np.where(n_voxels, '#FFD65DC0', '#7A88CCC0')
+edgecolors = np.where(n_voxels, '#BFAB6E', '#7D84A6')
+filled = np.ones(n_voxels.shape)
+
+# upscale the above voxel image, leaving gaps
+filled_2 = explode(filled)
+fcolors_2 = explode(facecolors)
+ecolors_2 = explode(edgecolors)
+
+# Shrink the gaps
+x, y, z = np.indices(np.array(filled_2.shape) + 1).astype(float) // 2
+x[0::2, :, :] += 0.05
+y[:, 0::2, :] += 0.05
+z[:, :, 0::2] += 0.05
+x[1::2, :, :] += 0.95
+y[:, 1::2, :] += 0.95
+z[:, :, 1::2] += 0.95
+
+fig = plt.figure()
+ax = fig.gca(projection='3d')
+ax.voxels(x, y, z, filled_2, facecolors=fcolors_2, edgecolors=ecolors_2)
+
+plt.show()

examples/mplot3d/voxels_rgb.py

@@ -0,0 +1,45 @@
+'''
+==========================================
+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
+
+
+def midpoints(x):
+    sl = ()
+    for i in range(x.ndim):
+        x = (x[sl + np.index_exp[:-1]] + x[sl + np.index_exp[1:]]) / 2.0
+        sl += np.index_exp[:]
+    return x
+
+# prepare some coordinates, and attach rgb values to each
+r, g, b = np.indices((17, 17, 17)) / 16.0
+rc = midpoints(r)
+gc = midpoints(g)
+bc = midpoints(b)
+
+# define a sphere about [0.5, 0.5, 0.5]
+sphere = (rc - 0.5)**2 + (gc - 0.5)**2 + (bc - 0.5)**2 < 0.5**2
+
+# combine the color components
+colors = np.zeros(sphere.shape + (3,))
+colors[..., 0] = rc
+colors[..., 1] = gc
+colors[..., 2] = bc
+
+# and plot everything
+fig = plt.figure()
+ax = fig.gca(projection='3d')
+ax.voxels(r, g, b, sphere,
+          facecolors=colors,
+          edgecolors=np.clip(2*colors - 0.5, 0, 1),  # brighter
+          linewidth=0.5)
+ax.set(xlabel='r', ylabel='g', zlabel='b')
+
+plt.show()

examples/mplot3d/voxels_torus.py

@@ -0,0 +1,47 @@
+'''
+=======================================================
+3D voxel / volumetric plot with cylindrical coordinates
+=======================================================
+
+Demonstrates using the ``x, y, z`` arguments of ``ax.voxels``.
+'''
+
+import matplotlib.pyplot as plt
+import matplotlib.colors
+import numpy as np
+from mpl_toolkits.mplot3d import Axes3D
+
+
+def midpoints(x):
+    sl = ()
+    for i in range(x.ndim):
+        x = (x[sl + np.index_exp[:-1]] + x[sl + np.index_exp[1:]]) / 2.0
+        sl += np.index_exp[:]
+    return x
+
+# prepare some coordinates, and attach rgb values to each
+r, theta, z = np.mgrid[0:1:11j, 0:np.pi*2:25j, -0.5:0.5:11j]
+x = r*np.cos(theta)
+y = r*np.sin(theta)
+
+rc, thetac, zc = midpoints(r), midpoints(theta), midpoints(z)
+
+# define a wobbly torus about [0.7, *, 0]
+sphere = (rc - 0.7)**2 + (zc + 0.2*np.cos(thetac*2))**2 < 0.2**2
+
+# combine the color components
+hsv = np.zeros(sphere.shape + (3,))
+hsv[..., 0] = thetac / (np.pi*2)
+hsv[..., 1] = rc
+hsv[..., 2] = zc + 0.5
+colors = matplotlib.colors.hsv_to_rgb(hsv)
+
+# and plot everything
+fig = plt.figure()
+ax = fig.gca(projection='3d')
+ax.voxels(x, y, z, sphere,
+          facecolors=colors,
+          edgecolors=np.clip(2*colors - 0.5, 0, 1),  # brighter
+          linewidth=0.5)
+
+plt.show()