API docs

Note that ipyvolume.pylab and ipyvolume.widgets are imported in the ipyvolume namepsace, to you can access ipyvolume.scatter instead of ipyvolume.pylab.scatter.

ipyvolume.pylab

ipyvolume.pylab.plot(x, y, z, color='red', **kwargs)[source]

Plot a line in 3d

Parameters:
  • x – numpy array of shape (N,) or (S, N) with x positions (can be a sequence)
  • y – idem for y
  • z – idem for z
  • color – color for each point/vertex/symbol, can be string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (N, 3) or (S, N, 3)
  • kwargs – extra arguments passed to the Scatter constructor
Returns:

Scatter

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

Plots many markers/symbols in 3d

Parameters:
  • x – numpy array of shape (N,) or (S, N) with x positions (can be a sequence)
  • y – idem for y
  • z – idem for z
  • color – color for each point/vertex/symbol, can be string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (N, 3) or (S, 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 – numpy array of shape (N,) or (S, N) with indices of x,y,z arrays of the selected markers, which can have a different size and color
  • kwargs
Returns:

Scatter

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 – numpy array of shape (N,) or (S, N) with x positions (can be a sequence)
  • y – idem for y
  • z – idem for z
  • u – numpy array of shape (N,) or (S, N) indicating the x component of a vector (can be a sequence)
  • v – idem for y
  • w – idem for z
  • 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 – color for each point/vertex/symbol, can be string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (N, 3) or (S, N, 3)
  • color_selected – like color, but for selected glyphs
  • marker – (currently only ‘arrow’ would make sense)
  • kwargs – extra arguments passed on to the Scatter constructor
Returns:

Scatter

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 (bool) – use lighting or not, if set to false, lighting parameters will be overriden
  • data_min (float) – minimum value to consider for data, if None, computed using np.nanmin
  • data_max (float) – maximum value to consider for data, if None, computed using np.nanmax
  • tf – transfer function (or a default one)
  • stereo (bool) – 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 (float) – 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 (bool) – add controls for lighting and transfer function or not
  • max_opacity (float) – 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, defined by the 2d ordered arrays x,y,z

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

Mesh

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

The following example 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 – numpy array of shape (N,) or (S, N) with x positions (can be a sequence)
  • y – idem for y
  • z – idem for z
  • triangles – numpy array with indices referring to the vertices, defining the triangles, with shape (M, 3)
  • lines – numpy array with indices referring to the vertices, defining the lines, with shape (K, 2)
  • color – color for each point/vertex/symbol, can be string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (N, 3) or (S, N, 3)
  • u – numpy array of shape (N,) or (S, N) indicating the u (x) coordinate for the texture (can be a sequence)
  • v – numpy array of shape (N,) or (S, N) indicating the v (y) coordinate for the texture (can be a sequence)
  • texture – PIL.Image object or ipywebrtc.MediaStream (can be a seqence)
Returns:

Mesh

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

See also ipyvolume.pylab.plot_mesh

Parameters:
  • x – numpy array of shape (N,M) or (S, N, M) with x positions (can be a sequence)
  • y – idem for y
  • z – idem for z
  • color – color for each point/vertex string format, examples for red:’red’, ‘#f00’, ‘#ff0000’ or ‘rgb(1,0,0), or rgb array of shape (2, N, 3) or (S, 2, N, 3)
  • wrapx (bool) – when True, the x direction is assumed to wrap, and polygons are drawn between the begin and end points
  • wrapy (bool) – idem for y
Returns:

Mesh

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

Draws a 2d wireframe+surface in 3d: generalization of plot_wireframe and plot_surface

Parameters:
  • x – {x2d}
  • y – {y2d}
  • z – {z2d}
  • color – {color2d}
  • wireframe (bool) – draw lines between the vertices
  • surface (bool) – draw faces/triangles between the vertices
  • wrapx (bool) – when True, the x direction is assumed to wrap, and polygons are drawn between the begin and end points
  • wrapy (boool) – idem for y
  • u – {u}
  • v – {v}
  • texture – {texture}
Returns:

Mesh

ipyvolume.pylab.plot_isosurface(data, level=None, color='red', wireframe=True, surface=True, controls=True)[source]

Plot a surface at constant value (like a 2d contour)

Parameters:
  • level (float) – value where the surface should lie
  • color – color of the surface, although it can be an array, the length is difficult to predict beforehand, if per vertex color are needed, it is better to set them on the returned mesh afterwards.
  • wireframe (bool) – draw lines between the vertices
  • surface (bool) – draw faces/triangles between the vertices
  • controls (bool) – add controls to change the isosurface
Returns:

Mesh

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 (float) – rotation around the axis pointing up in degrees
  • elevation (float) – rotation where +90 means ‘up’, -90 means ‘down’, in degrees
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 (int) – pixel width of WebGL canvas
  • height (int) –
  • lighting (bool) – use lighting or not
  • controls (bool) – show controls or not
  • controls_vr (bool) – show controls for VR or not
  • debug (bool) – show debug buttons or not
Returns:

Figure

ipyvolume.pylab.gcf()[source]

Get current figure, or create a new one

Returns:Figure
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(filepath, makedirs=True, title=u'IPyVolume Widget', all_states=False, offline=False, scripts_path='js', drop_defaults=False, template_options=(('extra_script_head', ''), ('body_pre', ''), ('body_post', '')), devmode=False, offline_cors=False)[source]

Save the current container to a HTML file

By default the HTML file is not standalone and requires an internet connection to fetch a few javascript libraries. Use offline=True to download these and make the HTML file work without an internet connection.

Parameters:
  • filepath (str) – The file to write the HTML output to.
  • makedirs (bool) – whether to make directories in the filename path, if they do not already exist
  • title (str) – title for the html page
  • all_states (bool) – if True, the state of all widgets know to the widget manager is included, else only those in widgets
  • offline (bool) – if True, use local urls for required js/css packages and download all js/css required packages (if not already available), such that the html can be viewed with no internet connection
  • scripts_path (str) – the folder to save required js/css packages to (relative to the filepath)
  • drop_defaults (bool) – Whether to drop default values from the widget states
  • template_options – list or dict of additional template options
  • devmode (bool) – if True, attempt to get index.js from local js/dist folder
  • offline_cors (bool) – if True, sets crossorigin attribute of script tags to anonymous
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 (float) – 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
ipyvolume.pylab.screenshot(width=None, height=None, format='png', fig=None, timeout_seconds=10, output_widget=None)[source]

Save the figure to a PIL.Image object.

Parameters:
  • width (int) – the width of the image in pixels
  • height (int) – the height of the image in pixels
  • format – format of output data (png, jpeg or svg)
  • 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:

PIL.Image

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

If the filename ends in .gif, convert is used to convert all frames to an animated gif using the cmd_template_gif template. Otherwise ffmpeg is assumed to know the file format.

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)

Note that in the example above we use endpoint=False to avoid to first and last frame to be the same

Parameters:
  • f (str) – 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 (int) – total number of frames
  • endpoint (bool) – if fraction goes from [0, 1] (inclusive) or [0, 1) (endpoint=False is useful for loops/rotatations)
  • cmd_template_ffmpeg (str) – template command when running ffmpeg (non-gif ending filenames)
  • cmd_template_gif (str) – template command when running imagemagick’s convert (if filename ends in .gif)
  • gif_loop – None for no loop, otherwise the framenumber to go to after the last frame
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:
  • objectScatter or Mesh object (having an sequence_index property), or a list of these to control multiple.
  • 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. Should be equal to the S in the shape of the numpy arrays as for instance documented in scatter or plot_mesh.
  • add – if True, add the widgets to the container, else return a HBox with the slider and play button. Useful when you want to customise the layout of the widgets yourself.
  • interval – interval in msec between each frame
Returns:

If add is False, if returns the ipywidgets.HBox object containing the controls

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:

ipyvolume.widgets

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

class ipyvolume.widgets.Figure(**kwargs)[source]

Bases: ipywebrtc.webrtc.MediaStream

Widget class representing a volume (rendering) using three.js

ambient_coefficient

A float trait.

angle_order

A trait for unicode strings.

anglex

A float trait.

angley

A float trait.

anglez

A float trait.

animation

A float trait.

animation_exponent

A float trait.

camera_center

An instance of a Python list.

camera_control

A trait for unicode strings.

camera_fov

A casting version of the float trait.

data_max

A casting version of the float trait.

data_min

A casting version of the float trait.

diffuse_coefficient

A float trait.

downscale

A casting version of the int trait.

eye_separation

A casting version of the float trait.

height

A casting version of the int trait.

matrix_projection

An instance of a Python list.

matrix_world

An instance of a Python list.

meshes

An instance of a Python list.

on_lasso(callback, remove=False)[source]
on_screenshot(callback, remove=False)[source]
project(x, y, z)[source]
render_continuous

A boolean (True, False) trait.

scatters

An instance of a Python list.

screenshot(width=None, height=None, mime_type='image/png')[source]
show

A trait for unicode strings.

specular_coefficient

A float trait.

specular_exponent

A float trait.

stereo

A boolean (True, False) trait.

style

An instance of a Python dict.

tf

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

volume_data

A numpy array trait type.

width

A casting version of the int trait.

xlabel

A trait for unicode strings.

xlim

An instance of a Python list.

ylabel

A trait for unicode strings.

ylim

An instance of a Python list.

zlabel

A trait for unicode strings.

zlim

An instance of a Python list.

class ipyvolume.widgets.Scatter(**kwargs)[source]

Bases: ipywidgets.widgets.domwidget.DOMWidget

color

A numpy array trait type.

color_selected

A trait type representing a Union type.

connected

A casting version of the boolean trait.

geo

A trait for unicode strings.

selected

A numpy array trait type.

sequence_index

An integer trait.

Longs that are unnecessary (<= sys.maxint) are cast to ints.

size

A trait type representing a Union type.

size_selected

A trait type representing a Union type.

visible

A casting version of the boolean trait.

visible_lines

A casting version of the boolean trait.

visible_markers

A casting version of the boolean trait.

vx

A numpy array trait type.

vy

A numpy array trait type.

vz

A numpy array trait type.

x

A numpy array trait type.

y

A numpy array trait type.

z

A numpy array trait type.

class ipyvolume.widgets.Mesh(**kwargs)[source]

Bases: ipywidgets.widgets.domwidget.DOMWidget

color

A numpy array trait type.

lines

A numpy array trait type.

sequence_index

An integer trait.

Longs that are unnecessary (<= sys.maxint) are cast to ints.

texture

A trait type representing a Union type.

triangles

A numpy array trait type.

u

A numpy array trait type.

v

A numpy array trait type.

visible

A casting version of the boolean trait.

visible_faces

A casting version of the boolean trait.

visible_lines

A casting version of the boolean trait.

x

A numpy array trait type.

y

A numpy array trait type.

z

A numpy array trait type.

ipyvolume.headless