Pythreejs Backend

The pythreejs backend renders scenes using three.js and is ideal for viewing scenes within Jupyter notebooks.

Note

To enable translucency in the pythreejs backend, a primitive must have the same value of alpha (less than 1) for all colors.

class plato.draw.pythreejs.Scene(*args, **kwargs)

add_primitive(prim)

Adds a primitive to the scene.

disable(name, strict=True)

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)

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

remove_primitive(primitive, strict=True)

Removes a primitive from the scene.

Parameters:

• primitive – primitive to (attempt to) remove
• strict – If True, raise an IndexError if the primitive was not in the scene

rotation

(r, x, y, z) rotation quaternion to be applied to the scene as a whole.

size

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

translation

(x, y, z) translation to be applied to the scene as a whole after rotating.

x is to the right, y is up, and z comes toward you out of the screen.

3D Graphics Primitives

class plato.draw.pythreejs.Box(*args, **kwargs)

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.pythreejs.ConvexPolyhedra(**kwargs)

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

class plato.draw.pythreejs.ConvexSpheropolyhedra(**kwargs)

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

class plato.draw.pythreejs.Ellipsoids(**kwargs)

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
• vertex_count: Number of vertices used to render ellipsoid

a

Radius in the x-direction

b

Radius in the y-direction

c

Radius in the z-direction

colors

Color, RGBA, [0, 1] for each particle

orientations

Orientation quaternion of each particle

positions

Position of each particle

vertex_count

Number of vertices used to render ellipsoid

class plato.draw.pythreejs.Lines(**kwargs)

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

class plato.draw.pythreejs.Mesh(**kwargs)

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

class plato.draw.pythreejs.Spheres(**kwargs)

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
• vertex_count: Number of vertices used to render sphere

colors

Color, RGBA, [0, 1] for each particle

positions

Position of each particle

radii

Radius of each particle

vertex_count

Number of vertices used to render sphere