Introduction

The scripting interface of OVITO lets you

  • automate data visualization and analysis steps,

  • integrate OVITO’s data I/O, analysis, and rendering capabilities into custom workflows or Python programs,

  • extend OVITO capabilities by developing new modifiers or viewports layers that integrate into the graphical user interface.

The script programming interface described in this manual consists of a collection of Python functions and classes, which expose OVITO’s internal data model, data pipeline framework, and rendering capabilities.

Automation scripts

A common use case for OVITO’s programming interface is automating laborious tasks. Python scripts don’t require any user interaction and can (repeatedly) perform sequences of actions that you would otherwise have to carry out by hand in the graphical application. The following example script remove_hydrogens.py loads an atomic structure from a simulation file, selects all hydrogen atoms, deletes them, and writes the resulting dataset back to an output file:

from ovito.io import import_file, export_file
from ovito.modifiers import SelectTypeModifier, DeleteSelectedModifier

pipeline = import_file('input_file.xyz')
pipeline.modifiers.append(SelectTypeModifier(property='Particle Type', types={'H'}))
pipeline.modifiers.append(DeleteSelectedModifier())
export_file(pipeline, 'output_file.xyz', 'xyz', columns=['Particle Type', 'Position.X', 'Position.Y', 'Position.Z']])

Scripts like this example can be easily created with OVITO Pro’s built-in code generator in the graphical user interface. You can then execute the Python script from the system terminal using ovitos, the preconfigured Python interpreter shipping with the OVITO Pro desktop application:

ovitos remove_hydrogens.py

Alternatively, you can execute the script – like any other Python program – using your Python interpreter of choice:

python remove_hydrogens.py

For this to work, you first need to install the ovito module in your Python interpreter as will be explained later.

Running scripts within the desktop application

A Python script can also be executed right within the context of the running OVITO Pro desktop application. This option can be useful, especially during the development phase, because it allows you to directly observe what your script is doing and how the final outcome looks like.

Use the Run Script File function found in the File menu of OVITO Pro to execute an existing Python script file. Note that, in this case, all script actions will be executed within the context of the current program session – as if you would perform them by hand. Alternatively, you can use the --script command line option when invoking OVITO from the system terminal to execute a given Python script right after application startup.

User-defined modifiers and viewport overlays

OVITO’s scripting interface furthermore enables you to develop new types of modifiers that can manipulate or analyze data in ways not covered by any of the built-in modifiers of the program. So-called Python script modifiers (see User-defined modifiers section for more information) participate in the data pipeline system of OVITO and behave just like the built-in modifiers from a user’s perspective. Such a user-defined modifier essentially is a Python function written by you that gets executed automatically by OVITO whenever the data pipeline is evaluated.

Furthermore, you can write custom viewport layers. A script viewport layer is a user-defined Python function that gets called by OVITO every time a viewport image is being rendered. This allows you to enrich rendered images or movies with custom text and graphics and include additional information, such as data plots that are dynamically generated from the simulation data.