Matplotlib Backend

The matplotlib backend uses matplotlib to render shapes. Different matplotlib backends can be configured for interactivity, but plato does not currently otherwise support interactive manipulation of shapes using this backend.

Matplotlib has extensive support for a wide range of graphical formats, so it is ideal for saving vector versions of figures.

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

This Scene supports the following features:

  • antialiasing: Enable antialiasing. Primitives that support antialiasing will fudge some distances (typically for drawing outlines) to reduce visual artifacts.
render(figure=None, axes=None)[source]

Render all the shapes in this Scene.

Parameters:
  • figure – Figure object to render within (created using pyplot if not given)
  • axes – Axes object to render within (created from the figure if not given)
save(filename, figure=None, axes=None)[source]

Render and save an image of this Scene.

Parameters:filename – target filename to save the image into
show(figure=None, axes=None)[source]

Render and show the shapes in this Scene.

Parameters:
  • figure – Figure object to render within (created using pyplot if not given)
  • axes – Axes object to render within (created from the figure if not given)

2D Graphics Primitives

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

3D Graphics Primitives

class plato.draw.matplotlib.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.matplotlib.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
class plato.draw.matplotlib.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
class plato.draw.matplotlib.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
class plato.draw.matplotlib.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
  • light_levels: Number of quantized light levels to use
colors

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

light_levels

Number of quantized light levels to use

positions

Position of each particle

radii

Radius of each particle