Visualization

automol.geom.view builds on py3Dmol for interactive 3D viewing (e.g. in a Jupyter notebook) and on xyzrender for static image and animation output.

Interactive viewing

automol.View is a py3Dmol.view subclass with convenience methods for adding Geometry objects and annotations:

from automol import Geometry, View

water = Geometry(
    symbols=["O", "H", "H"],
    coordinates=[[0.0, 0.0, 0.0], [0.0, 0.0, 0.96], [0.93, 0.0, -0.24]],
    charge=0,
    spin=0,
)

v = View()
v.add_geometry(water, label=True)  # label=True adds atom-index labels
v.show()

In a notebook, the view renders inline; v.show() (inherited from py3Dmol.view) is only needed outside of that auto-display context.

For a one-off view without constructing a View yourself:

from automol import view

v = view.view(water, label=True)

Annotating with vectors

add_xyz_axes draws the standard x/y/z axes (useful for checking orientation after a rotation), and add_vector/add_vectors draw arbitrary arrows — for example, an inertial axis or a bond dipole:

v.add_xyz_axes(scale=2.0)
v.add_vector([1.0, 0.0, 0.0], start_coord=[0.0, 0.0, 0.0], color="purple")
v.add_vectors(
    [[1, 0, 0], [0, 1, 0]],
    colors=["red", "green"],
)

direction=True treats the vector as an offset from start_coord rather than an absolute endpoint.

Rendering to files

render_svg and render_gif produce a static or rotating image without needing a browser or notebook — useful for scripts, reports, or CI artifacts:

from automol import view

view.render_svg(water, out="water.svg")
view.render_gif(water, out="water.gif", rotation_axis="y")

Both accept config (an xyzrender RenderConfig, or "default") and include_h to control whether hydrogens are drawn. out is optional — omit it to get the rendered result back without writing a file; the result also displays inline automatically in a notebook.