Imperative API

The imp module defines an imperative API for convenient, immediate visualization of results without directly creating separate primitive and scene objects. The set of available primitives and attributes are the same as in plato.draw, but the functions in this module are named as lowercase_with_underscores rather than CamelCase class names. Final scenes can be shown either directly, allowing for more careful selection of backends and passing arguments to the underlying scene by using show() or automatically by using the plato.imp IPython extension.

Examples:

import plato.imp as imp
imp.spheres(positions=[1, 0, 0])
imp.lines(start_points=(0, 1, 0), end_points=(1, 0, 0))
imp.show(backend='zdog', zoom=10)

# the line below causes cell contents to automatically be shown in jupyter notebooks
%load_ext plato.imp
imp.polygons(outline=.1)
imp.arrows_2D(positions=(-1, 0))
plato.imp.clear()[source]

Clears the imperative state.

plato.imp.get(backend=None, **kwargs)[source]

Returns the last-shown imperative scene, or creates a new one.

This method returns the most recent scene, either that has been shown via a call to show() or defined by calling primitive-creating functions. If a new scene is created, the user is responsible for calling Scene.show() as appropriate.

plato.imp.show(backend=None, **kwargs)[source]

Immediately show all pending primitives that have been created.

A backend name can optionally be specified, but all other keyword arguments are passed to the plato.draw.Scene constructor. If no backend is specified, a backend that can be imported and supports all the pending primitives will be selected.

plato.imp.arrows2D(*args, **kwargs)

Generates and immediately displays the object described below.

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
plato.imp.box(*args, **kwargs)

Generates and immediately displays the object described below.

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
plato.imp.convex_polyhedra(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.convex_spheropolyhedra(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.disks(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.disk_unions(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.ellipsoids(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.lines(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.mesh(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.polygons(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.sphere_points(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.spheres(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.sphere_unions(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.spheropolygons(**kwargs)

Generates and immediately displays the object described below.

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
plato.imp.voronoi(**kwargs)

Generates and immediately displays the object described below.

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