Interactive viewer widgets

Python scripts

Besides rendering static images, OVITO can display the three-dimensional scene in an interactive viewer, which you can rotate and zoom with the mouse. The ovito.gui module provides such viewers for Jupyter notebooks and for graphical applications built with the Qt framework.

Jupyter notebooks

The create_ipywidget() function creates a Jupyter widget that shows the scene in a notebook. It requires the ipywidgets package to be installed in your Jupyter environment:

from ovito.io import import_file
from ovito.vis import Viewport
from ovito.gui import create_ipywidget

pipeline = import_file("input/simulation.dump")
pipeline.add_to_scene()

viewport = Viewport(type=Viewport.Type.Perspective, camera_dir=(0.5, 1.0, -0.4))
viewport.zoom_all()

widget = create_ipywidget(viewport, layout=ipywidgets.Layout(width="600px", height="400px"))
widget     # In a notebook cell, this displays the interactive widget.

The widget is rendered by the web browser using WebGL. It is linked to the Viewport object you pass to the function: camera changes you make in the notebook through the Viewport object are reflected by the widget, and vice versa, mouse interactions with the widget update the Viewport object:

viewport.camera_dir = (1, 0, -0.5)   # The widget follows changes made to the Viewport object.
viewport.zoom_all()

If you pass a Pipeline instead of a Viewport, the widget shows just that pipeline’s output. Without an argument, it shows all pipelines in the current scene.

Note

The notebook widget is still under development. It doesn’t support viewport layers yet and may render semi-transparent objects incorrectly. To produce high-quality pictures in a notebook, render an image and display it using IPython’s display functions.

The OVITO Pro Jupyter kernel OVITO Pro

If you have an OVITO Pro license, you can run your notebook with the OVITO Pro Jupyter kernel. It lets you open the full graphical user interface of OVITO Pro from a notebook by creating a MainWindow:

from ovito.gui import MainWindow

window = MainWindow(pipeline)

The main window shows the pipeline in the interactive viewports and the pipeline editor. Changes you make in the user interface, e.g. to modifier parameters, are immediately visible to the Python code in your notebook, and vice versa.

Qt applications

The create_qwidget() function creates an interactive viewport widget, which you can embed in a graphical application built with Qt for Python (PySide6). OVITO itself uses the Qt framework, and PySide6 gets installed along with the ovito Python module:

from ovito.io import import_file
from ovito.vis import Viewport
from ovito.gui import create_qwidget
from PySide6.QtWidgets import QApplication
import sys

# Import a particle model and add it to the global visualization scene.
pipeline = import_file('input/simulation.dump')
pipeline.add_to_scene()

# Create a virtual viewport.
vp = Viewport(type=Viewport.Type.Perspective, camera_dir=(2, 1, -1))

# Create a WidgetViewportWindow associated with the viewport, and get its physical Qt widget.
vpwin = create_qwidget(vp)
widget = vpwin.widget
widget.resize(500, 400)
widget.setWindowTitle('OVITO Viewport Demo')
widget.show()
widget.raise_()
vp.zoom_all((widget.width(), widget.height()))

# Start the Qt event loop by invoking the QApplication.exec() method.
sys.exit(QApplication.instance().exec())

The function returns a WidgetViewportWindow, whose widget attribute is the Qt widget you insert into your application’s user interface. Like the Jupyter widget, it is linked to the Viewport object.

The trajectory viewer example shows how to build a small application that combines the viewport widget with a slider for stepping through the frames of a trajectory.