`ovito.gui`

Added in version 3.12.0.

This module defines functions for real-time interactive rendering using a graphical user interface (GUI):

create_qwidget() - Create an Qt widget that displays the contents of a virtual Viewport

create_ipywidget() - Create an interactive viewport widget for embedding in Jupyter notebooks

create_window() - Create an OVITO Pro window with the full graphical user interface

Furthermore, the module defines the UtilityInterface abstract base class, which lets you implement custom utility applets for the command panel of OVITO Pro.

class ovito.gui.UtilityInterface

Base: traits.has_traits.HasTraits

Base class for utility applets running in the command panel of OVITO Pro. See User-defined utility applets.

ovito.gui.create_ipywidget(contents: Pipeline | Viewport | None = None, *, antialiasing: bool = True, picking: bool = False, vr_scale: float = 0.0, layout: ipywidgets.Layout = ipywidgets.Layout(width='400px', height='200px')) → ipywidgets.DOMWidget

Creates an interactive widget for embedding in a Jupyter notebook, which displays the 3d scene as seen through a virtual Viewport. The method returns an interactive notebook element, which accepts mouse inputs similar to the viewport windows of the OVITO desktop application. It may be necessary to call display in order to show the widget:

vp = Viewport(type=Viewport.Type.Perspective, camera_dir=(0.5, 1.0, -0.4))
vp.zoom_all()
widget = ovito.gui.create_ipywidget(vp)
display(widget)

The Jupyter widget returned by this method is permanently linked to the Viewport instance. Any changes you subsequently make to the non-visual Viewport, for example, setting its camera_pos or camera_dir, will be reflected by the visual viewport widget. Vice versa do all user interactions with the viewport widget update the corresponding fields of the Viewport object.

Important

This method requires the ipywidgets Python package. Please install this package in your Jupyter environment.

Parameters:

contents (Pipeline | Viewport | None) – The Pipeline or Viewport object to be displayed by the widget.
antialiasing (bool) – Enables anti-aliasing to reduce jagged edges, which appear during WebGL rasterization.
picking (bool) – Enables object picking. When hovering the mouse cursor over an object, the widget will display the object’s properties as text.
vr_scale (float) – Enables VR support (WebXR browser interface) if set to a positive value. The parameter value specifies the ratio of 1 length unit of the simulation model and 1 meter in VR space. It thus controls the apparent size (scaling) of the model in virtual reality mode. For example, if object dimensions are specified in terms of nanometers in the simulation model, then a vr_scale value of 0.2 would let a 1 nanometer sphere appear 20 centimeters large in virtual reality space.
layout – The layout attribute for the new Jupyter widget.

Returns:

ipywidgets.DOMWidget

If you provide a Pipeline object as the contents argument, the method will create an ad-hoc viewport showing the output of just that pipeline. If you provide no contents argument at all, an ad-hoc viewport is created showing the contents of the global ovito.scene, including all pipelines that have been added.

The layout attribute lets you control the size of the widget, e.g.:

from ipywidgets import Layout
widget = create_jupyter_widget(vp, layout=Layout(width='100%', height='400px'))

Caution

This method is still under active development and not fully functional yet. Expect these (known) limitations:

Semi-transparent objects will likely be rendered incorrectly.

Viewport layers are not supported yet.

Please support the development of this new feature and report any issues you may encounter in our issue tracker or in the OVITO support forum.

ovito.gui.create_qwidget(contents=None, parent=None, *, show_orientation_indicator=True, show_title=False)

Creates an interactive visual widget that displays the three-dimensional scene as seen through a virtual Viewport. The method creates an interactive window accepting mouse inputs from the user similar to the viewport windows of the OVITO desktop application. You can use this method to develop custom user interfaces based on the Qt cross-platform framework that integrate OVITO’s functionality and display the output of a data pipeline.

Parameters:

contents (Union[Pipeline, Viewport, None]) – The Pipeline or Viewport object to be displayed by the widget.
parent (PySide6.QtWidgets.QWidget | None) – An optional Qt widget to be set as parent for the new viewport widget.
show_orientation_indicator (bool) – Controls the visibility of the coordinate axes in the lower left corner of the viewport widget.
show_title (bool) – Controls the visibility of viewport title in the upper left corner of the viewport widget.

Returns:

PySide6.QtWidgets.QWidget

The Qt widget returned by this method is linked to the Viewport instance if provided. Any changes your Python script subsequently makes to the non-visual Viewport object, for example setting its camera_pos or camera_dir, will automatically be reflected by the visual widget. Vice versa will user interactions with the viewport widget automatically lead to changes of the associated Viewport object.

If you provide a Pipeline object as the contents argument, the method will create an ad-hoc viewport showing the output of just the given pipeline. If you provide no contents argument, the method will create an ad-hoc viewport showing the contents of the global ovito.scene, including all pipelines that have been added.

OVITO automatically creates a global QApplication object if necessary, which can be accessed via the QApplication.instance() static method.

The following code example demonstrates the use of the create_qwidget() function in a standalone Python program. Please see the Qt for Python documentation for more information on how to create graphical user interfaces using the Qt framework.

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

# 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 GUI widget associated with the viewport.
widget = create_qwidget(vp)
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())

ovito.gui

`ovito.gui`