User-defined utility applets — OVITO Python Reference 3.16.0 documentation

# User-defined utility applets

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

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

- Python extensions

- Code template for an OVITO utility extension (GitHub)