User-defined utility applets

../_images/user_defined_utility_applet.jpg

OVITO allows you to create custom utility applets that display a panel in the GUI, specifically on the Utilities tab of the command panel. These applets can include various GUI elements such as push buttons, which trigger specific actions when clicked.

To create a utility applet, you need to define a class that inherits from ovito.gui.UtilityInterface. You can then add a Button trait to your class and link it to an action handler method using the action_handler() decorator. Here is a basic example:

from ovito.gui import UtilityInterface
from ovito.traits import action_handler
from traits.api import Button

class MyUtilityApplet(UtilityInterface):
    hello_btn = Button(ovito_label="Click me")

    @action_handler("hello_btn")
    def say_hello(self):
        print("Hello world!")

In this example, clicking the “Click me” button will trigger the say_hello() method, which prints “Hello world!” to the log window of the utility applet. When implementing your own action handler, you can perform any custom operation you like, such as importing a new data file or accessing and modifying the existing data pipelines and viewports of the current ovito.scene.

For long-running operations, which can potentially block GUI event handling for an extended period of time, you should implement the action handler as a generator function using yield statements to report progress and status messages to the GUI:

@action_handler("process_btn")
def process_trajectory(self):
    num_frames = 1000
    yield f"Processing trajectory of {num_frames} frames..."
    for frame in range(num_frames):
        yield frame / num_frames # Report progress as a fraction
        do_some_work(frame)

Parameter traits

../_images/user_defined_utility_applet_parameters.jpg

User-defined applets can also expose other parameter traits, allowing users to enter input values before triggering an action. This makes it possible to create interactive and user-friendly utility applets tailored to specific tasks within OVITO Pro. See User parameters for more information.

from ovito.gui import UtilityInterface
from ovito.traits import action_handler
from traits.api import Button, Range
from ovito.traits import Vector3

class UtilityAppletWithParameters(UtilityInterface):

    frac = Range(low=0.0, high=1.0, value=0.3, label="Fract", ovito_group="Calculation")
    quality = Range(low=0.0, high=1.0, value=0.5, label="Quality", ovito_unit="percent", ovito_group="Calculation")
    radius = Range(low=0.0, value=0.0, label="Radius", ovito_placeholder="‹default›", ovito_group="Calculation")

    vec = Vector3((1.0, 0.5, 0.0), label="Direction", ovito_group="Displacement")

    run_button = Button(ovito_label="Run", ovito_group="Operation")

    @action_handler("run_button")
    def perform_operation(self):
        print(f"frac: {self.frac}")
        print(f"quality: {self.quality}")
        print(f"radius: {self.radius}")
        print(f"vec: {self.vec}")

Integration with OVITO Pro

By following the steps described in Packaging and installation of user extensions for OVITO, you can develop utility applets that integrate seamlessly into OVITO Pro’s GUI, allowing you to extend the functionality of the software to suit your needs.

See also