ovito.gui

Added in version 3.12.0.

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

The ViewportWindow and WidgetViewportWindow classes represent the physical, on-screen windows that give a non-visual Viewport a pixel size and turn it into something the user can actually see and interact with.

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.MainWindow(contents: Pipeline | Viewport | None = None)

Added in version 3.16.0.

Represents a top-level main window in the OVITO Pro desktop application, including all GUI elements such as 3D viewports and the interactive pipeline editor.

Important

This class is only available in OVITO Pro and the OVITO Pro Jupyter kernel. It is not available in the PyPI ovito package, because this distribution lacks support for a full graphical user interface.

This class is meant to be used in Jupyter notebooks to launch an OVITO Pro session with a full graphical user interface. Changes you make to the scene, pipeline(s), or viewport(s) are synchronized between the Jupyter notebook and the GUI in both directions.

Parameters:

contents – The Pipeline or Viewport to be displayed in the OVITO main window. If none is provided, the current ovito.scene, including all added pipelines, will be displayed.

Use the all_windows() class method to obtain a list of all already open main windows.

static all_windows() → list[MainWindow]

Returns the list of all currently open main windows.

get_actions() → dict[str, PySide6.QtGui.QAction]

Returns a dictionary of all QAction objects registered with this main window. This gives an AI agent programmatic access to the same commands, tools and toggles that a human user has access to in the graphical user interface.

Each action is uniquely identified by its objectName(), which is used as the key in the returned dictionary. The action’s text() provides a human-readable title (as shown in menus and toolbars, possibly containing a & character marking a keyboard accelerator), and its statusTip() gives a short description of what the action does. An action can be activated programmatically by calling its trigger() method; check the action’s isEnabled() property first, since a disabled action represents a command that is currently unavailable, e.g. because no applicable object is selected.

Example: List the ID, title and description of every action currently available in a main window:

for action_id, action in window.get_actions().items():
    print(f"{action_id}: {action.text()} - {action.statusTip()}")

Trigger a specific action programmatically, e.g. to save the current scene file:

window.get_actions()["FileSave"].trigger()
get_viewport_windows() → list[WidgetViewportWindow]

Returns the list of all WidgetViewportWindow instances currently associated with this main window, one for each of its on-screen viewport panes. Use viewport on an individual window to find out which Viewport it is displaying.

property scene: Scene

The Scene object that is currently displayed in this main window.

take_screenshot() → list[tuple[PySide6.QtGui.QPixmap, str]]

Captures a screenshot of this main window in its current on-screen appearance. If any other top-level windows belonging to this main window are currently visible, e.g. modal or non-modal dialogs the user has opened, a screenshot of each of them is captured as well.

Returns:

A list of (image, title) tuples, one for the main window followed by one for each additional visible window, where image is a QPixmap holding the captured screenshot and title is the window’s title text.

property widget: PySide6.QtWidgets.QWidget

Returns the actual window, which is a top-level QWidget from the PySide6 Qt library. This property may be None if the main window has already been closed and is no longer available.

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.

class ovito.gui.ViewportWindow

Added in version 3.16.0.

A viewport window gives a non-visual Viewport a physical, on-screen presence: it provides the window, with a size in device pixels, that the viewport’s contents are rendered into, and it translates mouse and keyboard input from the user back into camera movements and other viewport interactions. A single Viewport may be associated with zero, one, or several windows at the same time; call get_windows() to obtain the list of windows currently showing a given viewport. Conversely, MainWindow.get_viewport_windows() returns all WidgetViewportWindow instances belonging to a given main window.

WidgetViewportWindow is the concrete kind of viewport window that embeds a viewport in a Qt widget; it is the type of object returned by create_qwidget(), and it also underlies the interactive viewports of a MainWindow.

property auto_update_enabled: bool

Controls whether the window automatically refreshes its displayed contents whenever the viewport’s camera or the scene shown in it change. Temporarily disable this to avoid redundant re-rendering while making several changes to the scene or camera in a row.

Default:

True

property device_pixel_ratio: float

The ratio between physical device pixels and device-independent pixels of the window’s drawing surface, e.g. 2.0 on a high-DPI (“Retina”) display.

property rendered_frames_counter: int

Counts how often this window has rendered and displayed a frame since the current program session started. Mainly useful for benchmarking and debugging purposes.

property show_orientation_indicator: bool

Controls whether the coordinate axis tripod, indicating the orientation of the viewport’s camera, is displayed in the window’s lower-left corner.

Default:

True

property show_title: bool

Controls whether the viewport’s title caption is displayed in the window’s upper-left corner.

Default:

True

property size: tuple[int, int]

The current size, in physical device pixels, of the window’s drawing surface, as a (width, height) tuple.

property viewport: Viewport | None

The Viewport currently displayed by this window. Assign a different Viewport to this property to make the window switch to displaying that viewport instead.

property visible: bool

Indicates whether this window is currently shown on screen.

class ovito.gui.WidgetViewportWindow

Added in version 3.16.0.

Base: ViewportWindow

A ViewportWindow that displays its Viewport inside a Qt QWidget, accessible through the widget property. This is the type of window created by create_qwidget(), and it is also the base class of the viewport windows underlying the interactive viewports of a MainWindow – see MainWindow.get_viewport_windows() to retrieve them.

property widget: PySide6.QtWidgets.QWidget

The Qt widget that renders and displays this viewport window’s contents on screen, which you can embed into your own PySide6-based user interface. This is the widget underlying the WidgetViewportWindow object returned by create_qwidget().

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, 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_ipywidget(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 WidgetViewportWindow that displays the three-dimensional scene as seen through a virtual Viewport. The window accepts mouse input 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:

WidgetViewportWindow

Changed in version 3.16.0: This method used to return the PySide6.QtWidgets.QWidget directly. It now returns the encompassing WidgetViewportWindow object instead, whose widget property gives access to the underlying QWidget.

The returned WidgetViewportWindow object manages the interactive viewport window; use its widget property to get the actual PySide6.QtWidgets.QWidget that you can embed into your own Qt user interface.

The window 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 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())

See also

Example B4: Standalone trajectory viewer