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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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
andplot_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:
-
ipyvolume.pylab.
xyzlim
(vmin, vmax=None)[source]¶ Set limits or all axis the same, if vmax not given, use [-vmin, vmax]
-
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: Returns:
-
ipyvolume.pylab.
gcc
()[source]¶ Return the current container, that is the widget holding the figure and all the control widgets, buttons etc.
-
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: - object –
Scatter
orMesh
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
orplot_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
- object –
-
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
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.
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.
-
render_continuous
¶ A boolean (True, False) trait.
-
scatters
¶ An instance of a Python list.
-
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.
-