View¶

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, 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

Parameters:

• system (Molecule | ChemicalSystem) – 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

• 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, show_regions=False, show_unit_cell_edges=True, unit_cell_edge_thickness=0.05, show_unit_cell_faces=False, show_lattice_vectors=False, 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_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

• 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

validate()[source]¶

Check if config values are valid for AMSview

Raises:

ValueError – if any value in the config is invalid

Return type:

None