ovito.gui — OVITO Python Reference 3.16.0 documentation

# `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 a `WidgetViewportWindow` that displays the contents of a virtual `Viewport`

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

> - `MainWindow` - An OVITO application window with the full graphical user interface

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.

  static get_current() → MainWindow | None

    Returns the currently active main window, or `None` if no main windows are open. The active window is the one displaying the same `Scene` as the calling context. If no window matches, but exactly one main window is open, that window is returned.

  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.

  grab_image() → PySide6.QtGui.QImage

    Captures the current on-screen appearance of this viewport window and returns it as a Qt QImage. The image has the same resolution, in physical device pixels, as the window’s drawing surface – see `size`.

    The captured image reproduces what the user sees, including the viewport caption, the orientation indicator, and any interactive gizmos. This makes it different from `Viewport.render_image()`, which performs a full offscreen rendering of the scene at an arbitrary resolution and without any interactive decorations. Grabbing is cheap in comparison, because it reuses the frame that has already been computed for the on-screen display.

  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