API docs

ipyvolume.volume

ipyvolume.widgets.quickvolshow(data, lighting=False, data_min=None, data_max=None, tf=None, stereo=False, width=400, height=500, ambient_coefficient=0.5, diffuse_coefficient=0.8, specular_coefficient=0.5, specular_exponent=5, downscale=1, level=[0.1, 0.5, 0.9], opacity=[0.01, 0.05, 0.1], level_width=0.1, **kwargs)[source]

Visualize a 3d array using volume rendering

Parameters:
  • data – 3d numpy array
  • lighting – boolean, to use lighting or not, if set to false, lighting parameters will be overriden
  • data_min – minimum value to consider for data, if None, computed using np.nanmin
  • data_max – maximum value to consider for data, if None, computed using np.nanmax
  • tf – transfer function (see ipyvolume.transfer_function, or use the argument below)
  • stereo – stereo view for virtual reality (cardboard and similar VR head mount)
  • width – width of rendering surface
  • height – height of rendering surface
  • ambient_coefficient – lighting parameter
  • diffuse_coefficient – lighting parameter
  • specular_coefficient – lighting parameter
  • specular_exponent – lighting parameter
  • downscale – downscale the rendering for better performance, for instance when set to 2, a 512x512 canvas will show a 256x256 rendering upscaled, but it will render twice as fast.
  • level – level(s) for the where the opacity in the volume peaks, maximum sequence of length 3
  • opacity – opacity(ies) for each level, scalar or sequence of max length 3
  • level_width – width of the (gaussian) bumps where the opacity peaks, scalar or sequence of max length 3
  • kwargs – extra argument passed to Volume and default transfer function
Returns:

ipyvolume.widgets.quickscatter(x, y, z, **kwargs)[source]
ipyvolume.widgets.quickquiver(x, y, z, u, v, w, **kwargs)[source]
ipyvolume.widgets.volshow(*args, **kwargs)[source]

Deprecated: please use ipyvolume.quickvolshow or use the ipyvolume.pylab interface

ipyvolume.pylab

ipyvolume.pylab.scatter(x, y, z, color='red', size=2, size_selected=2.6, color_selected='white', marker='diamond', selection=None, **kwargs)[source]

Create a scatter 3d plot with

Parameters:
  • x – 1d numpy array with x positions
  • y
  • z
  • color – string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (N, 3)
  • size – float representing the size of the glyph in percentage of the viewport, where 100 is the full size of the viewport
  • size_selected – like size, but for selected glyphs
  • color_selected – like color, but for selected glyphs
  • marker – name of the marker, options are: ‘arrow’, ‘box’, ‘diamond’, ‘sphere’
  • selection – array with indices of x,y,z arrays of the selected markers, which can have a different size and color
  • kwargs
Returns:

ipyvolume.pylab.quiver(x, y, z, u, v, w, size=20, size_selected=26.0, color='red', color_selected='white', marker='arrow', **kwargs)[source]

Create a quiver plot, which is like a scatter plot but with arrows pointing in the direction given by u, v and w

Parameters:
  • x – {x}
  • y
  • z
  • u – {u}
  • v
  • w
  • size – {size}
  • size_selected – like size, but for selected glyphs
  • color – {color}
  • color_selected – like color, but for selected glyphs
  • marker – (currently only ‘arrow’ would make sense)
  • kwargs
Returns:

ipyvolume.pylab.volshow(data, lighting=False, data_min=None, data_max=None, tf=None, stereo=False, ambient_coefficient=0.5, diffuse_coefficient=0.8, specular_coefficient=0.5, specular_exponent=5, downscale=1, level=[0.1, 0.5, 0.9], opacity=[0.01, 0.05, 0.1], level_width=0.1, controls=True, max_opacity=0.2)[source]

Visualize a 3d array using volume rendering.

Currently only 1 volume can be rendered.

Parameters:
  • data – 3d numpy array
  • lighting – boolean, to use lighting or not, if set to false, lighting parameters will be overriden
  • data_min – minimum value to consider for data, if None, computed using np.nanmin
  • data_max – maximum value to consider for data, if None, computed using np.nanmax
  • tf – transfer function (or a default one)
  • stereo – stereo view for virtual reality (cardboard and similar VR head mount)
  • ambient_coefficient – lighting parameter
  • diffuse_coefficient – lighting parameter
  • specular_coefficient – lighting parameter
  • specular_exponent – lighting parameter
  • downscale – downscale the rendering for better performance, for instance when set to 2, a 512x512 canvas will show a 256x256 rendering upscaled, but it will render twice as fast.
  • level – level(s) for the where the opacity in the volume peaks, maximum sequence of length 3
  • opacity – opacity(ies) for each level, scalar or sequence of max length 3
  • level_width – width of the (gaussian) bumps where the opacity peaks, scalar or sequence of max length 3
  • controls – add controls for lighting and transfer function or not
  • max_opacity – maximum opacity for transfer function controls
Returns:

ipyvolume.pylab.plot_surface(x, y, z, color='red', wrapx=False, wrapy=False)[source]

Draws a 2d surface in 3d, defines by the 2d ordered arrays x,y,z

Parameters:
  • x – 2d numpy array with x positions
  • y
  • z
  • color – string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (2, N, 3)
  • wrapx – when True, the x direction is assumed to wrap, and polygons are drawn between the end end begin points
  • wrapy – simular for the y coordinate
Returns:

ipyvolume.pylab.plot_trisurf(x, y, z, triangles=None, lines=None, color='red', u=None, v=None, texture=None)[source]

Draws a polygon/triangle mesh defined by a coordinate and triangle indices

Example:

The following plots a rectangle in the z==2 plane, consisting of 2 triangles

>>> plot_trisurf([0, 0, 3., 3.], [0, 4., 0, 4.], 2, triangles=[[0, 2, 3], [0, 3, 1]])

Note that the z value is constant, and thus not a list/array. For guidance, the triangles refer to the vertices in this manner:

^ ydir | 2 3 0 1 —> x dir

Note that if you want per face/triangle colors, you need to duplicate each vertex.

Parameters:
  • x – 1d numpy array with x positions
  • y
  • z
  • triangles – ndarray with indices referring to the vertices, defining the triangles, with shape (M, 3)
  • lines – ndarray with indices referring to the vertices, defining the lines, with shape (K, 2)
  • color – string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (N, 3)
Returns:

ipyvolume.pylab.plot_wireframe(x, y, z, color='red', wrapx=False, wrapy=False)[source]

Draws a 2d wireframe in 3d, defines by the 2d ordered arrays x,y,z

Parameters:
  • x – 2d numpy array with x positions
  • y
  • z
  • color – string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (2, N, 3)
  • wrapx – when True, the x direction is assumed to wrap, and polygons are drawn between the end end begin points
  • wrapy – simular for the y coordinate
Returns:

ipyvolume.pylab.plot_mesh(x, y, z, color='red', wireframe=True, surface=True, wrapx=False, wrapy=False, u=None, v=None, texture=None)[source]
ipyvolume.pylab.xlim(xmin, xmax)[source]

Set limits of x axis

ipyvolume.pylab.ylim(ymin, ymax)[source]

Set limits of y axis

ipyvolume.pylab.zlim(zmin, zmax)[source]

Set limits of zaxis

ipyvolume.pylab.xyzlim(vmin, vmax=None)[source]

Set limits or all axis the same, if vmax not given, use [-vmin, vmax]

ipyvolume.pylab.xlabel(label)[source]

Set the labels for the x-axis

ipyvolume.pylab.ylabel(label)[source]

Set the labels for the y-axis

ipyvolume.pylab.zlabel(label)[source]

Set the labels for the z-axis

ipyvolume.pylab.xyzlabel(labelx, labely, labelz)[source]

Set all labels at once

ipyvolume.pylab.view(azimuth, elevation)[source]

Sets camera angles

Parameters:
  • azimuth – rotation around the axis pointing up in degrees
  • elevation – rotation where +90 means ‘up’, -90 means ‘down’, in degrees
Returns:

ipyvolume.pylab.figure(key=None, width=400, height=500, lighting=True, controls=True, controls_vr=False, debug=False, **kwargs)[source]

Create a new figure (if no key is given) or return the figure associated with key

Parameters:
  • key – Python object that identifies this figure
  • width – pixel width of WebGL canvas
  • height
  • lighting – use lighting or not
  • controls – show controls or not
  • controls_vr – show controls for VR or not
  • debug – show debug buttons or not
Returns:

ipyvolume.pylab.gcf()[source]

Get current figure, or create a new one

ipyvolume.pylab.gcc()[source]

Return the current container, that is the widget holding the figure and all the control widgets, buttons etc.

ipyvolume.pylab.clear()[source]

Remove current figure (and container)

ipyvolume.pylab.show(extra_widgets=[])[source]

Display (like in IPython.display.dispay(...) the current figure

ipyvolume.pylab.save(filename, copy_js=True, makedirs=True, **kwargs)[source]

Save the figure/visualization as html file, and optionally copy the .js file to the same directory

ipyvolume.pylab.savefig(filename, width=None, height=None, fig=None, timeout_seconds=10, output_widget=None)[source]

Save the figure to an image file

Parameters:
  • filename (str) – must have extension .png, .jpeg or .svg
  • width (int) – the width of the image in pixels
  • height (int) – the height of the image in pixels
  • fig (ipyvolume.widgets.Figure or None) – if None use the current figure
  • timeout_seconds (int) – maximum time to wait for image data to return
  • output_widget (ipywidgets.Output) – a widget to use as a context manager for capturing the data
Returns:

ipyvolume.pylab.movie(f='movie.mp4', function=<function _change_y_angle>, fps=30, frames=30, endpoint=False, cmd_template_ffmpeg='ffmpeg -y -r {fps} -i {tempdir}/frame-%5d.png -vcodec h264 -pix_fmt yuv420p {filename}', cmd_template_gif='convert -delay {delay} {loop} {tempdir}/frame-*.png {filename}', gif_loop=0)[source]

Create a movie (mp4/gif) out of many frames

Example: def set_angles(fig, i, fraction):

fig.angley = fraction*np.pi*2

# 4 second movie, that rotates around the y axis p3.movie(‘test2.gif’, set_angles, fps=20, frames=20*4, endpoint=False)

Parameters:
  • f – filename out output movie (e.g. ‘movie.mp4’ or ‘movie.gif’)
  • function – function called before each frame with arguments (figure, framenr, fraction)
  • fps – frames per seconds
  • frames – total number of frames
  • endpoint – if fraction goes from [0, 1] (inclusive) or [0, 1) (endpoint=False is useful for loops/rotatations)
  • cmd_template_ffmpeg – template command when running ffmpeg (non-gif ending filenames)
  • cmd_template_gif – template command when running imagemagick’s convert (if filename ends in .gif)
  • gif_loop – None for no loop, otherwise the framenumber to go after the end
Returns:

the temp dir where the frames are stored

ipyvolume.pylab.animation_control(object, sequence_length=None, add=True, interval=200)[source]

Animate scatter, quiver or mesh by adding a slider and play button.

Parameters:
  • object – scatter, quiver, or mesh object (having an sequence_index property), or a list of objects
  • sequence_length – If sequence_length is None we try try our best to figure out, in case we do it badly, you can tell us what it should be
  • add – if True, add the widgets to the container, else return a HBox with the slider and play button
  • interval – interval in msec between each frame
Returns:

ipyvolume.pylab.transfer_function(level=[0.1, 0.5, 0.9], opacity=[0.01, 0.05, 0.1], level_width=0.1, controls=True, max_opacity=0.2)[source]

Create a transfer function, see volshow

class ipyvolume.pylab.style[source]

‘Static class that mimics a matplotlib module.

Example: >>> import ipyvolume.pylab as p3 >>> p3.style.use(‘light’]) >>> p3.style.use(‘seaborn-darkgrid’]) >>> p3.style.use([‘seaborn-darkgrid’, {‘axes.x.color’:’orange’}])

Possible style values:
  • figure.facecolor: background color
  • axes.color: color of the box around the volume/viewport
  • xaxis.color: color of xaxis
  • yaxis.color: color of xaxis
  • zaxis.color: color of xaxis
static use(style)[source]

Set the style of the current figure/visualization

Parameters:style – matplotlib style name, or dict with values, or a sequence of these, where the last value overrides previous
Returns: