ovito.gui — OVITO Python Reference 3.15.3-dev-HEAD-b1e9512d 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 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, 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 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 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 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())

  See also

  Example B4: Standalone trajectory viewer

ovito.gui.create_window(contents=None)

  Opens a new OVITO main window, including all GUI elements such as the interactive pipeline editor.

  This function is meant to be used in Jupyter notebooks to launch an OVITO 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 (Pipeline | Viewport | None) – 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.

  Returns:

    PySide6.QtWidgets.QWidget

  Important

  This function is only available in the OVITO Pro Jupyter kernel and the Python interpreter embedded in OVITO Pro. It is not available in the standalone OVITO Python package from PyPI, because this version lacks support for a full graphical user interface. Calling this function in such an environment will raise a `RuntimeError`.