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.

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)

   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

      * **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, 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, backend='auto', timeout=None, open_window=False)

   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"

      * **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"

      * **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()

      Check if config values are valid for AMSview

      Raises:
         **ValueError** -- if any value in the config is invalid

      Return type:
         None
