Plato Primitives

Plato’s graphics primitives all follow a fairly standard form. Depending on the shapes to be rendered, different properties may be per-particle (such as positions, orientations, and colors) or global (the ConvexPolyhedra primitive is restricted to drawing any number of identically-shaped convex polyhedra; in other words, the vertices given are for all particles rendered).

Primitives’ data can be set and retrieved through properties, which are exposed as numpy arrays whenever possible. For example, to scale the diameter of each disk in a Disks primitive by 2:

disks = plato.draw.Disks(...)
disks.diameters *= 2

Primitives can be grouped together by placing them in the same plato.draw.Scene.

The classes inside plato.draw are simple containers and are not useful for visualization. Instead, a particular backend should be used, for example:

import plato.draw.matplotlib as draw
disks = draw.Disks(...)
scene = draw.Scene(disks, ...)
scene.show()

Note

For quick and simple visualizations, the imperative plato.imp module may be easier.

Base Drawing Module

class plato.draw.Scene(primitives=[], features={}, size=(40, 30), translation=(0, 0, -50), rotation=(1, 0, 0, 0), zoom=1, pixel_scale=20, **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.

add_primitive(primitive)[source]

Adds a primitive to the scene.

convert(backend, compatibility='warn', **kwargs)[source]

Convert this scene and all of its primitives to another backend.

Parameters:
  • backend – Backend plato.draw.* module to use in the new scene
  • compatibility – Behavior when unsupported primitives are encountered: ‘warn’, ‘ignore’, or ‘error’
  • kwargs – Additional keyword arguments to be passed into the backend Scene constructor
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
get_feature_config(name)[source]

Return the configuration dictionary for a given feature.

If the feature has not been enabled, return None.

remove_primitive(primitive, strict=True)[source]

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.

size_pixels

Width and height, in pixels, of the viewport.

transform(coords, source, dest='scene')[source]

Transform one or more points between two coordinate systems.

Parameters:
  • coords – Nx2 array-like of coordinates to transform
  • source – Coordinate system of coords: one of ‘pixels_gui’ (display pixel units, top left is (0, 0)), ‘pixels’ (display pixel units, bottom left is (0, 0)), ‘ndc’ ((-1, -1) to (1, 1) at the two corners), or ‘scene’ (working scene world coordinates)
  • source – Coordinate system of returned values: one of ‘pixels_gui’ (display pixel units, top left is (0, 0)), ‘pixels’ (display pixel units, bottom left is (0, 0)), ‘ndc’ ((-1, -1) to (1, 1) at the two corners), or ‘scene’ (working scene world coordinates)
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.

2D Graphics Primitives

class plato.draw.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
colors

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

magnitudes

Magnitude (size scale) of each particle

orientations

Orientation quaternion of each particle

outline

Outline width for all particles

positions

Position of each particle

vertices

Vertices in local coordinates for the shape, to be replicated for each particle (CCW order)

class plato.draw.DiskUnions(**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
angles

Orientation of each union, in radians

colors

Color, RGBA, [0, 1] for each disk in the union

diameters

Diameter of each disk in the union.

orientations

Orientation quaternion of each particle

outline

Outline width for all particles

points

Positions in local coordinates for the disks in the union, to be replicated for each particle

positions

Position of each particle

radii

Radius of each disk in the union

class plato.draw.Disks(**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
colors

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

diameters

Diameter of each particle.

outline

Outline width for all particles

positions

Position of each particle

radii

Radius of each particle

class plato.draw.Polygons(**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
angles

Orientation of each particle, in radians

colors

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

orientations

Orientation quaternion of each particle

outline

Outline width for all particles

positions

Position of each particle

vertices

Vertices in local coordinates for the shape, to be replicated for each particle (CCW order)

class plato.draw.Spheropolygons(**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
angles

Orientation of each particle, in radians

colors

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

orientations

Orientation quaternion of each particle

outline

Outline width for all particles

positions

Position of each particle

radius

Rounding radius for all particles

vertices

Vertices in local coordinates for the interior (non-rounded) shape, to be replicated for each particle (CCW order)

class plato.draw.Voronoi(**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
colors

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

positions

Position of each point

3D Graphics Primitives

class plato.draw.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
Lx

Length of first box vector

Ly

Length of second box vector

Lz

Length of third box vector

color

Color, RGBA, [0, 1] for the box line segments

colors

Color, RGBA, [0, 1] for each line segment

end_points

Ending coordinate for each line segment

classmethod from_box(box, width=0.01, color=(0, 0, 0, 1))[source]

Duck type the box from a valid input.

Boxes can be a list, dictionary, or object with attributes.

start_points

Beginning coordinate for each line segment

width

Width of box line segments

widths

Width of each line segment

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

class plato.draw.ConvexPolyhedra(**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
colors

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

orientations

Orientation quaternion of each particle

outline

Outline width for all shapes

positions

Position of each particle

vertices

Vertices in local coordinates for the shape, to be replicated for each particle

class plato.draw.ConvexSpheropolyhedra(**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
colors

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

orientations

Orientation quaternion of each particle

positions

Position of each particle

radius

Rounding radius to be applied to all shapes

vertices

Vertices in local coordinates for the interior (non-rounded) shape, to be replicated for each particle

class plato.draw.Ellipsoids(**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
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

class plato.draw.Lines(**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
colors

Color, RGBA, [0, 1] for each line segment

end_points

Ending coordinate for each line segment

start_points

Beginning coordinate for each line segment

widths

Width of each line segment

class plato.draw.Mesh(**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
colors

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

classmethod double_sided(vertices, indices, colors, thickness=0.001, **kwargs)[source]

Create a double-sided Mesh object.

Typically the “inside” of a Mesh (as determined by the order of triangle indices) is unlit. This method replicates the vertices, one for each side, after computing the appropriate normals.

indices

Indices of the vertex array specifying individual triangles (Nx3)

orientations

Orientations for each mesh to be replicated

positions

Central positions for each mesh to be replicated

shape_color_fraction

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

shape_colors

Color, RGBA, [0, 1] for each replica (shape) of the mesh

vertices

Vertex array specifying coordinates of the mesh nodes

class plato.draw.SpherePoints(**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
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

points

Points to be rendered

class plato.draw.SphereUnions(**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
colors

Color, RGBA, [0, 1] for each sphere in the union

diameters

Diameter of each particle.

orientations

Orientation quaternion of each particle

points

Positions in local coordinates for the spheres in the union, to be replicated for each particle

positions

Position of each particle

radii

Radius of each sphere in the union

class plato.draw.Spheres(**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
colors

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

diameters

Diameter of each particle.

positions

Position of each particle

radii

Radius of each particle