Ipyvolume

IPyvolume is a Python library to visualize 3d volumes and glyphs (e.g. 3d scatter plots), in the Jupyter notebook, with minimal configuration and effort. It is currently pre-1.0, so use at own risk. IPyvolume’s volshow is to 3d arrays what matplotlib’s imshow is to 2d arrays.

Other (more mature but possibly more difficult to use) related packages are yt, VTK and/or Mayavi.

Feedback and contributions are welcome: Github, Email or Twitter.

Quick intro

Volume

For quick resuls, use ipyvolume.volume.quickvolshow. From a numpy array, we create two boxes, using slicing, and visualize it.

import numpy as np
import ipyvolume
V = np.zeros((128,128,128)) # our 3d array
# outer box
V[30:-30,30:-30,30:-30] = 0.75
V[35:-35,35:-35,35:-35] = 0.0
# inner box
V[50:-50,50:-50,50:-50] = 0.25
V[55:-55,55:-55,55:-55] = 0.0
ipyvolume.quickvolshow(V, level=[0.25, 0.75], opacity=0.03, level_width=0.1, data_min=0, data_max=1)

Scatter plot

Simple scatter plots are also supported.

import ipyvolume
import numpy as np
x, y, z = np.random.random((3, 10000))
ipyvolume.quickscatter(x, y, z, size=1, marker="sphere")

Quiver plot

Quiver plots are also supported, showing a vector at each point.

import ipyvolume
import numpy as np
x, y, z, u, v, w = np.random.random((6, 1000))*2-1
quiver = ipyvolume.quickquiver(x, y, z, u, v, w, size=5)

Built on Ipywidgets

For anything more sophisticed, use ipyvolume.pylab, ipyvolume’s copy of matplotlib’s 3d plotting (+ volume rendering).

Since ipyvolume is built on ipywidgets, we can link widget’s properties.

import ipyvolume.pylab as p3
import numpy as np
x, y, z, u, v, w = np.random.random((6, 1000))*2-1
selected = np.random.randint(0, 1000, 100)
p3.figure()
quiver = p3.quiver(x, y, z, u, v, w, size=5, size_selected=8, selected=selected)

from ipywidgets import FloatSlider, ColorPicker, VBox, jslink
size = FloatSlider(min=0, max=30, step=0.1)
size_selected = FloatSlider(min=0, max=30, step=0.1)
color = ColorPicker()
color_selected = ColorPicker()
jslink((quiver, 'size'), (size, 'value'))
jslink((quiver, 'size_selected'), (size_selected, 'value'))
jslink((quiver, 'color'), (color, 'value'))
jslink((quiver, 'color_selected'), (color_selected, 'value'))
VBox([p3.gcc(), size, size_selected, color, color_selected])

Try changing the slider to the change the size of the vectors, or the colors.

Quick installation

This will most likely work, otherwise read Installation

pip install ipyvolume
jupyter nbextension enable --py --sys-prefix ipyvolume
jupyter nbextension enable --py --sys-prefix widgetsnbextension

For conda/anaconda, use:

conda install -c conda-forge ipyvolume
pip install ipywidgets~=6.0.0b5 --user

About

Ipyvolume is an offspring project from vaex. Ipyvolume makes use of threejs, and excellent Javascript library for OpenGL/WebGL rendering.

Contents

Installation

Pip as root

pip install ipyvolume
jupyter nbextension enable --py --sys-prefix ipyvolume
jupyter nbextension enable --py --sys-prefix widgetsnbextension

Pip as user

pip install ipyvolume --user
jupyter nbextension enable --py --user ipyvolume
jupyter nbextension enable --py --user widgetsnbextension

Conda/Anaconda

conda install -c conda-forge ipyvolume

Examples

Mixing ipyvolume with Bokeh

This example shows how the selection from a ipyvolume quiver plot can be controlled with a bokeh scatter plot and it’s selection tools.

Ipyvolume quiver plot

The 3d quiver plot is done using ipyvolume

In [1]:
import ipyvolume
import ipyvolume.pylab as p3
import vaex

We load some data from vaex, but only use the first 10 000 samples for performance reasons of Bokeh.

In [2]:
ds = vaex.example()
N = 10000

We make a quiver plot using ipyvolume’s matplotlib’s style api.

In [3]:
p3.figure()
quiver = p3.quiver(ds.data.x[:N], ds.data.y[:N], ds.data.z[:N],
              ds.data.vx[:N], ds.data.vy[:N], ds.data.vz[:N],
                  size=1, size_selected=5, color_selected="grey")
p3.xyzlim(-30, 30)
p3.show()
Bokeh scatter part

The 2d scatter plot is done using Bokeh.

In [4]:
from bokeh.io import output_notebook, show
from bokeh.plotting import figure
import ipyvolume.bokeh
output_notebook()
Loading BokehJS ...
In [5]:
tools = "wheel_zoom,box_zoom,box_select,lasso_select,help,reset,"
p = figure(title="E Lz space", tools=tools, webgl=True, width=500, height=500)
r = p.circle(ds.data.Lz[:N], ds.data.E[:N],color="navy", alpha=0.2)
# A 'trick' from ipyvolume to link the selection (one way traffic atm)
ipyvolume.bokeh.link_data_source_selection_to_widget(r.data_source, quiver, 'selected')
show(p)

Now try doing a selection and see how the above 3d quiver plot reflects this selection.

In [6]:
import ipywidgets
In [7]:
out = ipywidgets.Output()
with out:
    show(p)
In [8]:
ipywidgets.HBox([out, p3.gcc()])
Embedding in html

A bit of a hack, but it is possible to embed the widget and the bokeh part into a single html file (use at own risk).

In [9]:
from bokeh.resources import CDN
from bokeh.embed import components

script, div = components((p))
ipyvolume.embed.embed_html("bokeh.html",
       [p3.current.container, ipyvolume.bokeh.wmh], all=True,
       extra_script_head=script + CDN.render_js() + CDN.render_css(),
       body_pre="<h2>Do selections in 2d (bokeh)<h2>"+div+"<h2>And see the selection in ipyvolume<h2>")
In [ ]:

Mixing ipyvolume with bqplot

This example shows how the selection from a ipyvolume quiver plot can be controlled with a bqplot scatter plot and it’s selection tools. We first get a small dataset from vaex

In [1]:
import numpy as np
import vaex
In [2]:
ds = vaex.example()
N = 2000 # for performance reasons we only do a subset
x, y, z, vx, vy, vz, Lz, E = [ds.columns[k][:N] for k in "x y z vx vy vz Lz E".split()]
bqplot scatter plot

And create a scatter plot with bqplot

In [3]:
import bqplot.pyplot as plt
In [4]:
plt.figure(1, title="E Lz space")
scatter = plt.scatter(Lz, E,
                selected_style={'opacity': 0.2, 'size':1, 'stroke': 'red'},
                unselected_style={'opacity': 0.2, 'size':1, 'stroke': 'blue'},
                default_size=1,
               )
plt.brush_selector()
plt.show()
Ipyvolume quiver plot

And use ipyvolume to create a quiver plot

In [5]:
import ipyvolume.pylab as p3
In [6]:
p3.clear()
quiver = p3.quiver(x, y, z, vx, vy, vz, size=2, size_selected=5, color_selected="blue")
p3.show()
Linking ipyvolume and bqplot

Using jslink, we link the selected properties of both widgets, and we display them next to eachother using a VBox.

In [7]:
from ipywidgets import jslink, VBox
In [8]:
jslink((scatter, 'selected'), (quiver, 'selected'))
In [9]:
hbox = VBox([p3.current.container, plt.figure(1)])
hbox
Embedding

We embed the two widgets in an html file, creating a standlone plot.

In [10]:
import ipyvolume.embed
# if we don't do this, the bqplot will be really tiny in the standalone html
bqplot_layout = hbox.children[1].layout
bqplot_layout.min_width = "400px"
In [11]:
ipyvolume.embed.embed_html("bqplot.html", hbox)
In [ ]: