Vispy Backend

The vispy backend uses vispy to render shapes interactively using openGL. It supports both desktop use with a variety of GUI backends and use inline in jupyter notebooks. While the GUI backends are essentially interchangeable, the notebook backend is more restrictive in its capabilities and some features are not currently available with it.

Select the vispy backend to use with the standard vispy mechanism before calling Scene.show():

import vispy, vispy.app
# use in ipython notebook
vispy.app.use_app('ipynb_webgl')
# use pyside2
vispy.app.use_app('pyside2')
scene = plato.draw.vispy.Scene(...)
scene.show()
vispy.app.run()

Mouse controls: Live vispy windows support rotating the scene in three dimensions by dragging the mouse. Dragging while holding the control or meta keys causes the mouse movement to rotate the scene about the z axis and zoom in or out. Holding the alt key while dragging the mouse cursor will translate the scene; for two-dimensional scenes, it may be preferable to enable the pan feature, which causes mouse motion to translate, rather than rotate, the scene by default.

Keyboard controls: Live vispy windows also support controlling the camera via the keyboard. Control or meta in conjunction with the arrow keys rotate the system in 15 degree increments. The same functionality is mapped to the I (up), J (left), K (down), and L (right) keys. X, Y, and Z directly snap the scene to look down the x, y, or z axes, respectively.

class plato.draw.vispy.Scene(*args, canvas_kwargs={}, **kwargs)[source]

A container to hold and display collections of primitives.

Scene keeps track of global information about a set of things to be rendered and handles configuration of optional (possibly backend-specific) rendering parameters.

Global information managed by a Scene includes the size of the viewing window, translation and rotation applied to the scene as a whole, and a zoom level.

Primitives can be added to a scene through the primitives argument of the constructor or the add_primitive method. Primitives can be retrieved by iterating over the scene:

for prim in scene:
    # (do something with prim)

Primitives can also be accessed in the order they were added to the scene using list-like syntax:

first_three_prims = scene[:3]
last_prim = scene[-1]

Optional rendering arguments are enabled as features, which are name-value pairs identifying a feature by name and any configuration of the feature in the value.

This Scene supports the following features:

  • pan: If enabled, mouse movement will translate the scene instead of rotating it.
  • directional_light: Add directional lights. The given value indicates the magnitude*direction normal vector.
  • ambient_light: Enable trivial ambient lighting. The given value indicates the magnitude of the light (in [0, 1]).
  • translucency: Enable order-independent transparency rendering.
  • fxaa: Enable fast approximate anti-aliasing.
  • ssao: Enable screen space ambient occlusion.
  • additive_rendering: Enable additive rendering. This mode is good for visualizing densities projected through the viewing direction. Takes an optional ‘invert’ argument to invert the additive rendering (i.e., black-on-white instead of white-on-black).
  • outlines: Enable cartoony outlines. The given value indicates the width of the outlines (start small, perhaps 1e-5 to 1e-3).
  • pick: Select a single particle with the mouse on the next mouse click. The given callback function receives the scene, primitive index within the scene, and shape index within the primitive that are selected. If no particle is selected, the callback is not run but pick mode remains enabled until a particle is selected; to disable this behavior, set the optional persist argument to False.
  • select_point: Perform a callback on the next mouse click. The callback receives the clicked position (in the coordinate system of the scene unless the ‘units’ parameter is set to another valid target for Scene.transform()) and any additional keyword arguments passed in the feature config.
  • select_rect: Perform a callback on the next mouse drag event. The callback receives the start and end point of the selected area (in the coordinate system of the scene unless the ‘units’ parameter is set to another valid target for Scene.transform()) and any additional keyword arguments passed in the feature config.
  • static: Enable static rendering. When possible (when vispy is using a non-notebook backend), display a statically-rendered image of a scene instead of the live webGL version when Scene.show() is called.
add_primitive(primitive)[source]

Adds a primitive to the scene.

disable(name, strict=True)[source]

Disable an optional rendering feature.

Parameters:
  • name – Name of the feature to disable
  • strict – if True, raise a KeyError if the feature was not enabled
enable(name, auto_value=None, **parameters)[source]

Enable an optional rendering feature.

Parameters:
  • name – Name of the feature to enable
  • auto_value – Shortcut for features with single-value configuration. If given as a positional argument, will be given the default configuration name ‘value’.
  • parameters – Keyword arguments specifying additional configuration options for the given feature
render()[source]

Have vispy redraw this Scene object.

save(filename)[source]

Render and save an image of this Scene.

Parameters:filename – target filename to save the image into
show()[source]

Display this Scene object.

size

Width and height, in scene units, of the viewport.

2D Graphics Primitives

class plato.draw.vispy.Arrows2D(*args, **kwargs)[source]

A collection of 2D arrows.

Each arrow has an independent position, orientation, color, and magnitude. The shape of arrows can be configured by changing its vertices attribute. The default orientation and scale of the vertices is an arrow centered at (0, 0), pointing in the (1, 0) direction, with length 1.

The origin of the arrows can be shifted to have the base lie on the given position by modifying vertices:

arrows.vertices = arrows.vertices + (0.5, 0)
This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • vertices: Vertices in local coordinates for the shape, to be replicated for each particle (CCW order)
  • outline: Outline width for all particles
This primitive has the following opengl-specific attributes:
  • outline: Outline width for shapes
camera

Internal: 4x4 Camera matrix for world projection

outline

Outline width for shapes

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

class plato.draw.vispy.DiskUnions(*args, **kwargs)[source]

A collection of identical disk-union bodies in 2D.

A DiskUnions object consists of one or more disks, each with its own radius and color. Each object has its own position and orientation that affect the final position of the constituent disks.

This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each disk in the union
  • points: Positions in local coordinates for the disks in the union, to be replicated for each particle
  • radii: Radius of each disk in the union
  • outline: Outline width for all particles
This primitive has the following opengl-specific attributes:
  • outline: Outline width for shapes
camera

Internal: 4x4 Camera matrix for world projection

outline

Outline width for shapes

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

class plato.draw.vispy.Disks(*args, **kwargs)[source]

A collection of disks in 2D.

Each disk can have a different color and diameter.

This primitive has the following attributes:
  • positions: Position of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • radii: Radius of each particle
  • outline: Outline width for all particles
This primitive has the following opengl-specific attributes:
  • outline: Outline for all particles
camera

Internal: 4x4 Camera matrix for world projection

outline

Outline for all particles

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

class plato.draw.vispy.Polygons(*args, **kwargs)[source]

A collection of polygons.

A Polygons object has a common shape for the whole collection. Each shape can have a different orientation and color. Vertices should be specified in counterclockwise order.

This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • vertices: Vertices in local coordinates for the shape, to be replicated for each particle (CCW order)
  • outline: Outline width for all particles
This primitive has the following opengl-specific attributes:
  • outline: Outline width for shapes
camera

Internal: 4x4 Camera matrix for world projection

outline

Outline width for shapes

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

class plato.draw.vispy.Spheropolygons(*args, **kwargs)[source]

A collection of rounded polygons.

A Spheropolygons object has a common shape and rounding radius for the whole collection. Each shape can have a different orientation and color. Vertices should be specified in counterclockwise order.

This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • vertices: Vertices in local coordinates for the interior (non-rounded) shape, to be replicated for each particle (CCW order)
  • outline: Outline width for all particles
  • radius: Rounding radius for all particles
This primitive has the following opengl-specific attributes:
  • outline: Outline width for shapes
  • radius: Rounding radius for shapes
camera

Internal: 4x4 Camera matrix for world projection

outline

Outline width for shapes

radius

Rounding radius for shapes

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

class plato.draw.vispy.Voronoi(*args, **kwargs)[source]

A Voronoi diagram of a set of 2D points.

The region of space nearest to each given point will be colored by the color associated with that point.

This primitive has the following attributes:
  • positions: Position of each point
  • colors: Color, RGBA, [0, 1] for each point
This primitive has the following opengl-specific attributes:
  • radius: Maximum distance between displayed points
  • clip_extent: Matrix specifying areas to not display when dot(clip_extent, position) is outside [-1, 1]
camera

Internal: 4x4 Camera matrix for world projection

clip_extent

Matrix specifying areas to not display when dot(clip_extent, position) is outside [-1, 1]

radius

Maximum distance between displayed points

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

3D Graphics Primitives

class plato.draw.vispy.Box(*args, **kwargs)[source]

A triclinic box frame.

This primitive draws a triclinic box centered at the origin. It is specified in terms of three lattice vector lengths Lx, Ly, Lz and tilt factors, defined using the hoomd-blue schema.

Rather than directly initializing via attributes, Box objects can also be automatically created from box-type objects using the from_box() method.

Examples:

Lx = Ly = Lz = 10
xy = xz = yz = 0
box_primitive = draw.Box(Lx=Lx, Ly=Ly, Lz=Lz, width=width, color=color)
box_tuple = (Lx, Ly, Lz, xy, xz, yz)
box_primitive = draw.Box.from_box(box_tuple)
This primitive has the following attributes:
  • start_points: Beginning coordinate for each line segment
  • end_points: Ending coordinate for each line segment
  • widths: Width of each line segment
  • colors: Color, RGBA, [0, 1] for each line segment
  • Lx: Length of first box vector
  • Ly: Length of second box vector
  • Lz: Length of third box vector
  • xy: Tilt factor between the first and second box vectors
  • xz: Tilt factor between the first and third box vectors
  • yz: Tilt factor between the second and third box vectors
  • width: Width of box line segments
  • color: Color, RGBA, [0, 1] for the box line segments
class plato.draw.vispy.ConvexPolyhedra(*args, **kwargs)[source]

A collection of identically-shaped convex polyhedra.

Each shape can have its own position, orientation, and color.

This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • vertices: Vertices in local coordinates for the shape, to be replicated for each particle
  • outline: Outline width for all shapes
This primitive has the following opengl-specific attributes:
  • outline: Outline width for shapes
  • light_levels: Number of light levels to quantize to (0: disable)
ambientLight

Internal: Ambient (minimum) light level for all surfaces

camera

Internal: 4x4 Camera matrix for world projection

diffuseLight

Internal: Diffuse light direction*magnitude

light_levels

Number of light levels to quantize to (0: disable)

outline

Outline width for shapes

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

transparency_mode

Internal: Transparency stage (<0: opaque, 0: all, 1: translucency stage 1, 2: translucency stage 2)

class plato.draw.vispy.ConvexSpheropolyhedra(*args, **kwargs)[source]

A collection of identically-shaped convex spheropolyhedra.

Each shape can have its own position, orientation, and color. The rounding radius is shared over all shapes.

This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • vertices: Vertices in local coordinates for the interior (non-rounded) shape, to be replicated for each particle
  • radius: Rounding radius to be applied to all shapes
This primitive has the following opengl-specific attributes:
  • radius: Rounding radius to be applied to all shapes
  • light_levels: Number of light levels to quantize to (0: disable)
ambientLight

Internal: Ambient (minimum) light level for all surfaces

camera

Internal: 4x4 Camera matrix for world projection

diffuseLight

Internal: Diffuse light direction*magnitude

light_levels

Number of light levels to quantize to (0: disable)

radius

Rounding radius to be applied to all shapes

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

transparency_mode

Internal: Transparency stage (<0: opaque, 0: all, 1: translucency stage 1, 2: translucency stage 2)

class plato.draw.vispy.Ellipsoids(*args, **kwargs)[source]

A collection of ellipsoids with identical dimensions.

Each ellipsoid can have its own position, orientation, and color. All shapes drawn by this primitive share common principal axis lengths.

This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • a: Radius in the x-direction
  • b: Radius in the y-direction
  • c: Radius in the z-direction
This primitive has the following opengl-specific attributes:
  • a: Radius in the x-direction
  • b: Radius in the y-direction
  • c: Radius in the z-direction
  • light_levels: Number of light levels to quantize to (0: disable)
  • outline: Outline for all particles
a

Radius in the x-direction

ambientLight

Internal: Ambient (minimum) light level for all surfaces

b

Radius in the y-direction

c

Radius in the z-direction

camera

Internal: 4x4 Camera matrix for world projection

diffuseLight

Internal: Diffuse light direction*magnitude

light_levels

Number of light levels to quantize to (0: disable)

outline

Outline for all particles

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

transparency_mode

Internal: Transparency stage (<0: opaque, 0: all, 1: translucency stage 1, 2: translucency stage 2)

class plato.draw.vispy.Lines(*args, **kwargs)[source]

A collection of line segments.

Each segment can have a different color and width. Lines can be used in both 2D and 3D scenes, but they are currently not shaded and may look out of place in 3D.

This primitive has the following attributes:
  • start_points: Beginning coordinate for each line segment
  • end_points: Ending coordinate for each line segment
  • widths: Width of each line segment
  • colors: Color, RGBA, [0, 1] for each line segment
This primitive has the following opengl-specific attributes:
  • cap_mode: Cap mode for lines (0: default, 1: round)
ambientLight

Internal: Ambient (minimum) light level for all surfaces

camera

Internal: 4x4 Camera matrix for world projection

cap_mode

Cap mode for lines (0: default, 1: round)

diffuseLight

Internal: Diffuse light direction*magnitude

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

transparency_mode

Internal: Transparency stage (<0: opaque, 0: all, 1: translucency stage 1, 2: translucency stage 2)

class plato.draw.vispy.Mesh(*args, **kwargs)[source]

A 3D triangle mesh.

Meshes are specified by an array of vertices and indices identifying triangles within that vertex array. Colors are assigned per-vertex and interpolated between vertices.

Meshes with a common set of vertices and face indices can be replicated multiple times using a set of positions and orientations. In order to set the color of individual replicas of the Mesh object, use the shape_colors and shape_color_fraction attributes.

This primitive has the following attributes:
  • vertices: Vertex array specifying coordinates of the mesh nodes
  • indices: Indices of the vertex array specifying individual triangles (Nx3)
  • colors: Color, RGBA, [0, 1] for each vertex
  • positions: Central positions for each mesh to be replicated
  • orientations: Orientations for each mesh to be replicated
  • shape_colors: Color, RGBA, [0, 1] for each replica (shape) of the mesh
  • shape_color_fraction: Fraction of a vertex’s color that should be assigned based on shape_colors
This primitive has the following opengl-specific attributes:
  • light_levels: Number of light levels to quantize to (0: disable)
  • shape_color_fraction: Fraction of a vertex’s color that should be assigned based on shape_colors
ambientLight

Internal: Ambient (minimum) light level for all surfaces

camera

Internal: 4x4 Camera matrix for world projection

diffuseLight

Internal: Diffuse light direction*magnitude

light_levels

Number of light levels to quantize to (0: disable)

rotation

Internal: Rotation to be applied to each scene as a quaternion

shape_color_fraction

Fraction of a vertex’s color that should be assigned based on shape_colors

translation

Internal: Translation to be applied to the scene

transparency_mode

Internal: Transparency stage (<0: opaque, 0: all, 1: translucency stage 1, 2: translucency stage 2)

class plato.draw.vispy.SpherePoints(*args, **kwargs)[source]

A collection of points, useful for illustrating 3D density maps.

This primitive has the following attributes:
  • points: Points to be rendered
  • blur: Blurring factor dictating the size of each point
  • intensity: Scaling factor dictating the magnitude of the color value of each point
  • on_surface: True if the points should always be projected onto the surface of a sphere
This primitive has the following opengl-specific attributes:
  • blur: Blurring factor dictating the size of each point
  • intensity: Scaling factor dictating the magnitude of the color value of each point
  • on_surface: True if the points should always be projected onto the surface of a sphere
  • radius: Radius of the sphere to normalize to
  • draw_front: If True, draw only the points facing the viewer
blur

Blurring factor dictating the size of each point

camera

Internal: 4x4 Camera matrix for world projection

draw_front

If True, draw only the points facing the viewer

intensity

Scaling factor dictating the magnitude of the color value of each point

inverse_size

Internal: inverse size of the given points array

on_surface

True if the points should always be projected onto the surface of a sphere

points

Points to be rendered

radius

Radius of the sphere to normalize to

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

class plato.draw.vispy.Spheres(*args, **kwargs)[source]

A collection of spheres in 3D.

Each sphere can have a different color and diameter.

This primitive has the following attributes:
  • positions: Position of each particle
  • colors: Color, RGBA, [0, 1] for each particle
  • radii: Radius of each particle
This primitive has the following opengl-specific attributes:
  • light_levels: Number of light levels to quantize to (0: disable)
  • outline: Outline for all particles
ambientLight

Internal: Ambient (minimum) light level for all surfaces

camera

Internal: 4x4 Camera matrix for world projection

diffuseLight

Internal: Diffuse light direction*magnitude

light_levels

Number of light levels to quantize to (0: disable)

outline

Outline for all particles

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

transparency_mode

Internal: Transparency stage (<0: opaque, 0: all, 1: translucency stage 1, 2: translucency stage 2)

class plato.draw.vispy.SphereUnions(*args, **kwargs)[source]

A collection of identical sphere-union bodies in 3D.

A SphereUnions object is a union of spheres, each of which has its own color, radius, and local position. The SphereUnions object can be rigidly rotated and translated via its position and orientation attributes.

This primitive has the following attributes:
  • positions: Position of each particle
  • orientations: Orientation quaternion of each particle
  • colors: Color, RGBA, [0, 1] for each sphere in the union
  • points: Positions in local coordinates for the spheres in the union, to be replicated for each particle
  • radii: Radius of each sphere in the union
This primitive has the following opengl-specific attributes:
  • light_levels: Number of light levels to quantize to (0: disable)
  • outline: Outline for all particles
ambientLight

Internal: Ambient (minimum) light level for all surfaces

camera

Internal: 4x4 Camera matrix for world projection

diffuseLight

Internal: Diffuse light direction*magnitude

light_levels

Number of light levels to quantize to (0: disable)

outline

Outline for all particles

rotation

Internal: Rotation to be applied to each scene as a quaternion

translation

Internal: Translation to be applied to the scene

transparency_mode

Internal: Transparency stage (<0: opaque, 0: all, 1: translucency stage 1, 2: translucency stage 2)