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)

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)

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)

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)

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)

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)

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)

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)

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.xlim(xmin, xmax)

Set limits of x axis

ipyvolume.pylab.ylim(ymin, ymax)

Set limits of y axis

ipyvolume.pylab.zlim(zmin, zmax)

Set limits of zaxis

ipyvolume.pylab.xyzlim(vmin, vmax=None)

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

ipyvolume.pylab.xlabel(label)

Set the labels for the x-axis

ipyvolume.pylab.ylabel(label)

Set the labels for the y-axis

ipyvolume.pylab.zlabel(label)

Set the labels for the z-axis

ipyvolume.pylab.xyzlabel(labelx, labely, labelz)

Set all labels at once

ipyvolume.pylab.view(azimuth, elevation)

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)

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()

Get current figure, or create a new one

Returns:Figure

ipyvolume.pylab.gcc()

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

ipyvolume.pylab.clear()

Remove current figure (and container)

ipyvolume.pylab.show(extra_widgets=[])

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)

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)

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)

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)

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)

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

Parameters:

• object – Scatter 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)

Create a transfer function, see volshow

class ipyvolume.pylab.style

‘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()

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)

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)

ipyvolume.widgets.quickquiver(x, y, z, u, v, w, **kwargs)

ipyvolume.widgets.volshow(*args, **kwargs)

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

class ipyvolume.widgets.Figure(**kwargs)

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)

on_screenshot(callback, remove=False)

project(x, y, z)

render_continuous

A boolean (True, False) trait.

scatters

An instance of a Python list.

screenshot(width=None, height=None, mime_type='image/png')

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)

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)

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.