View

Note

The view() function is available in AMS2026+

The view() function aims to simplify the process of visualizing molecular and periodic systems in PLAMS. It can generate images for displaying systems in a Jupyter notebook as well as saving images to files.

Movies

Note

The movie() and display_movie() functions are available in AMS2027+

The movie() function creates animations from existing image frames. Frames can be image file paths, a directory containing image files, PIL images, matplotlib figures or matplotlib axes. This makes it possible to combine movie() with view(), because view() returns a PIL image.

For example, you can make a GIF or animated WebP from a sequence of molecules:

from scm.plams import movie, view

frames = (view(mol) for mol in trajectory[::10])
movie(frames, "trajectory.webp", fps=12)

GIF and animated WebP movies are written directly with Pillow. Animated WebP is usually much smaller than GIF and is useful for web pages and notebooks. MP4 output is also supported, but requires an external ffmpeg executable:

movie("frames/", "trajectory.mp4", fps=24)

If ffmpeg cannot be found, movie() raises an error explaining how to provide it. PLAMS searches for an explicitly supplied ffmpeg path, SCM_FFMPEG, $AMSBIN/ffmpeg, and finally ffmpeg on PATH.

Use display_movie() to display a saved movie in a Jupyter notebook:

from scm.plams import display_movie

display_movie("trajectory.webp", width=600)

Image grids

The plot_image_grid() function displays a dictionary of images in a matplotlib grid. It is useful when you want to compare several images from view() in one figure:

from scm.plams import plot_image_grid, view

images = {
    "initial": view(initial_molecule),
    "final": view(final_molecule),
}
plot_image_grid(images, cols=2)

For a detailed worked example demonstrating the capabilities and uses of the view() function, see the Visualization example. Otherwise see below for the full API specification.

API

view(system, config=None, *, width=None, height=None, padding=None, direction=None, fixed_atom_size=None, show_atom_labels=None, atom_label_type=None, guess_bonds=None, show_regions=None, show_unit_cell_edges=None, show_lattice_vectors=None, picture_path=None, backend=None, open_window=None)[source]

View a chemical system or molecule in a Jupyter notebook by generating an image using AMSview/ASE. A completed AMSJob or rkf file can also be supplied, in which case the main molecule will be displayed from the results.

Parameters:

  • system (Molecule | ChemicalSystem | AMSJob | str | PathLike) – molecule or chemical system to visualize

  • config (ViewConfig | None) – configuration for view

  • width (int | None) – override for width of the image in pixels

  • height (int | None) – override for height of the image in pixels

  • padding (float | None) – override for padding around system in Angstrom

  • direction (Literal['along_x', 'along_y', 'along_z', 'along_a', 'along_b', 'along_c', 'along_pca1', 'along_pca2', 'along_pca3', 'tilt_x', 'tilt_y', 'tilt_z', 'tilt_a', 'tilt_b', 'tilt_c', 'tilt_pca1', 'tilt_pca2', 'tilt_pca3', 'small_tilt_x', 'small_tilt_y', 'small_tilt_z', 'small_tilt_a', 'small_tilt_b', 'small_tilt_c', 'small_tilt_pca1', 'small_tilt_pca2', 'small_tilt_pca3', 'large_tilt_x', 'large_tilt_y', 'large_tilt_z', 'large_tilt_a', 'large_tilt_b', 'large_tilt_c', 'large_tilt_pca1', 'large_tilt_pca2', 'large_tilt_pca3', 'corner_x', 'corner_y', 'corner_z', 'corner_a', 'corner_b', 'corner_c', 'corner_pca1', 'corner_pca2', 'corner_pca3'] | None) – override for direction to view system along

  • fixed_atom_size (bool | None) – override to use the same radius for all elements (except Hydrogen)

  • show_atom_labels (bool | None) – override to display text label on each atom

  • atom_label_type (Literal['Element', 'AtomType', 'Name'] | None) – override for property used for atom labels

  • guess_bonds (bool | None) – override for guessing bonds before viewing

  • show_regions (bool | None) – override to display translucent spheres on atoms according to their regions

  • show_unit_cell_edges (bool | None) – override to display unit cell for periodic systems using semi-transparent edges

  • show_lattice_vectors (bool | None) – override to display the lattice vectors for periodic systems

  • picture_path (str | PathLike | None) – override for path for the location to save the generated image file

  • backend (Literal['amsview', 'amsview_xvfb', 'ase_plot', 'auto'] | None) – override for program to use as a backend to generate images

  • open_window (bool | None) – override to open AMSview in a dedicated window

Returns:

image of the molecule generated using AMSView

Return type:

PilImage.Image

class ViewConfig(width=800, height=400, padding=0.0, direction='along_z', normal=None, normal_basis='xyz', dpi=300, picture_path=None, fixed_atom_size=True, show_atom_labels=False, atom_label_type='Element', atom_label_color='#000000', atom_label_size=1.0, atomic_property=None, atomic_property_type='color', show_colorbar=False, colorbar_range=None, guess_bonds=False, show_regions=False, show_unit_cell_edges=True, unit_cell_edge_thickness=0.05, show_unit_cell_faces=False, show_lattice_vectors=False, orbital=None, render_type='iso', iso_value=0.03, opacity=40, grid='medium', backend='auto', timeout=None, open_window=False)[source]

Configuration for view settings

Parameters:

  • width (int) – width of the image in pixels, defaults to 800

  • height (int) – height of the image in pixels, defaults to 400

  • padding (float) – padding around system in Angstrom, defaults to 0.0 (can be negative)

  • direction (Literal['along_x', 'along_y', 'along_z', 'along_a', 'along_b', 'along_c', 'along_pca1', 'along_pca2', 'along_pca3', 'tilt_x', 'tilt_y', 'tilt_z', 'tilt_a', 'tilt_b', 'tilt_c', 'tilt_pca1', 'tilt_pca2', 'tilt_pca3', 'small_tilt_x', 'small_tilt_y', 'small_tilt_z', 'small_tilt_a', 'small_tilt_b', 'small_tilt_c', 'small_tilt_pca1', 'small_tilt_pca2', 'small_tilt_pca3', 'large_tilt_x', 'large_tilt_y', 'large_tilt_z', 'large_tilt_a', 'large_tilt_b', 'large_tilt_c', 'large_tilt_pca1', 'large_tilt_pca2', 'large_tilt_pca3', 'corner_x', 'corner_y', 'corner_z', 'corner_a', 'corner_b', 'corner_c', 'corner_pca1', 'corner_pca2', 'corner_pca3'] | None) – direction to view system along, selected from a series of preset values, defaults to along_z

  • normal (Tuple[float, float, float] | None) – orientation of the normal to the view plane, takes precedence over direction when specified, defaults to None

  • normal_basis (Literal['xyz', 'abc', 'pca']) – whether to use cartesian axes, xyz, lattice vectors (where applicable), abc, or principal component analysis vectors pca, as the basis for the normal to the view plane, defaults to xyz

  • dpi (int) – resolution of any saved image in dots per inch, defaults to 300

  • picture_path (str | PathLike | None) – optional path for the location to save the generated image file, defaults to None

  • fixed_atom_size (bool) – use the same radius for all elements (except Hydrogen), defaults to True

  • show_atom_labels (bool) – display text label on each atom, defaults to False

  • atom_label_type (Literal['Element', 'AtomType', 'Name']) – property used for atom labels, defaults to Element

  • atom_label_color (str) – hexadecimal color code for atom labels, defaults to #000000 i.e. black

  • atom_label_size (float) – scale atom labels by the given factor, to make them larger or smaller, defaults to 1.0

  • show_colorbar (bool) – display a color legend for atom coloring, defaults to False

  • colorbar_range (Tuple[float, float] | None) – optional numeric range for atom coloring, defaults to None

  • guess_bonds (bool) – guess bonds before viewing, defaults to False

  • show_regions (bool) – display translucent spheres on atoms according to their regions, defaults to False

  • show_unit_cell_edges (bool) – display unit cell for periodic systems using semi-transparent edges, defaults to True

  • unit_cell_edge_thickness (float) – specify thickness of the displayed unit cell boundary, defaults to 0.05

  • show_unit_cell_faces (bool) – display unit cell for periodic systems using semi-transparent faces, defaults to False

  • show_lattice_vectors (bool) – display the lattice vectors for periodic systems, defaults to False

  • render_type (Literal['iso', 'iso_wireframe', 'volume']) – use isosurface, isosurface (wireframe) or volume rendering, defaults to iso

  • iso_value (float) – value to use for isosurface, defaults to 0.03

  • opacity (float) – opacity for volume rendering, defaults to 40

  • grid (Literal['fine', 'medium', 'coarse']) – fineness of grid used for rendering, defaults to medium

  • backend (Literal[typing.Literal['amsview', 'amsview_xvfb', 'ase_plot', 'auto']]) – program to use as a backend to generate images, defaults to auto i.e. any available program

  • timeout (int | None) – kill visualization process after given time in seconds, defaults to 10 if window is not opened, otherwise no limit

  • open_window (bool) – open AMSview in a dedicated window if True, otherwise render image offscreen, defaults to False

  • atomic_property (str | None) –

  • atomic_property_type (Literal['color', 'radius']) –

  • orbital (Tuple[Literal['homo', 'lumo'], int] | None) –

validate()[source]

Check if config values are valid for AMSview

Raises:

ValueError – if any value in the config is invalid

Return type:

None

movie(frames, output, *, fps=10, loop=0, sort=True, ffmpeg=None, keep_frames=False, matplotlib_dpi=150)[source]

Write image frames to a GIF, animated WebP, or MP4 movie.

frames can be a directory of images, an image file path, a sequence or generator of image file paths, PIL images, matplotlib figures, or matplotlib axes.

Parameters:

  • frames (str | PathLike | Iterable[object]) – input frames

  • output (str | PathLike) – output movie path, ending in .gif, .webp, or .mp4

  • fps (float) – frames per second

  • loop (int) – GIF loop count, where 0 means loop forever

  • sort (bool) – sort directory frames lexically

  • ffmpeg (str | PathLike | None) – optional path to the ffmpeg executable for MP4 output

  • keep_frames (bool) – keep PNG frames written next to the output movie

  • matplotlib_dpi (int) – DPI used when rendering matplotlib objects

Returns:

path to the written movie

Return type:

Path

display_movie(path, *, embed=True, width=None, height=None)[source]

Display a GIF, animated WebP, or MP4 movie in a Jupyter notebook.

Parameters:

  • path (str | PathLike) – path to a GIF, WebP, or MP4 movie

  • embed (bool) – embed MP4 video data in the notebook, defaults to True

  • width (int | None) – optional display width in pixels

  • height (int | None) – optional display height in pixels

Return type:

None

plot_image_grid(images, rows=None, cols=None, figsize=None, show_labels=True, save_path=None)[source]

Plot a dictionary of images in a matplotlib grid.

Parameters:

  • images (Dict[str, PilImage.Image]) – dictionary with labels as keys and images as values; iteration order determines image order in the grid

  • rows (int | None) – number of rows in the grid; if None, infer from cols and number of images

  • cols (int | None) – number of columns in the grid; if None, infer from rows and number of images

  • figsize (Tuple[float, float] | None) – matplotlib figure size; if None, uses a grid-proportional default

  • show_labels (bool) – whether to show labels above images; labels are taken from dictionary keys

  • save_path (str | PathLike | None) – optional path to save the plotted grid image using matplotlib savefig

Returns:

2D numpy array of matplotlib axes with shape (rows, cols)

Return type:

np.ndarray