OVITO’s Python interface

OVITO’s scripting interface enables you to:

  • automate visualization and data analysis tasks,

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

  • extend OVITO by developing custom modifiers or viewports overlay.

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

Automation scripts

A typical application for OVITO’s programming interface is to automate tasks and let a script, which runs without user interaction, perform steps that you would otherwise 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 results 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')

We can execute the script from the system terminal using ovitos, the preconfigured Python interpreter shipping with OVITO:

ovitos remove_hydrogens.py

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

python3 remove_hydrogens.py

For this to work, you first need to install the ovito Python module from the PyPI repository in your interpreter as explained below.

Running scripts in the graphical application

Instead of running a script from the terminal you can also execute it right within the graphical OVITO application. This can be useful during script development, because it allows you to directly observe what your script is doing and how the final result, for example a modifier pipeline created by the script, looks like.

Use the Run Script File menu function of OVITO to execute a Python script file. Note that all script commands will be executed in the context of the current program session. Alternatively, you can use the --script command line parameter when invoking OVITO from the terminal to execute a 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 overlays. A Python script viewport overlay is a user-defined function that gets called by OVITO every time a viewport image is being rendered. This allows you to enrich images or movies with custom text and graphics, and include additional information such as data plots that are dynamically generated from the simulation data.

Installing the ovito module in your Python interpreter

To make OVITO’s scripting capabilities available to scripts running in your system’s Python interpreter, you first need to install the ovito module. It may be downloaded from the PyPI repository and installed using the pip install ovito command. For further instruction please refer to

OVITO’s Python interpreter

OVITO comes with a preconfigured Python interpreter named ovitos that can execute scripts written in the Python 3.x language. ovitos already has the ovito module and all other dependencies preinstalled that are required to run OVITO scripts. You typically execute a batch Python script from the terminal of your operating system using the ovitos command, which gets installed alongside with OVITO:

ovitos [-o file] [-g] [script.py] [args...]

ovitos is located in the bin/ subdirectory of OVITO for Linux, in the Ovito.app/Contents/MacOS/ directory of OVITO for macOS, and in the main application directory on Windows systems (look for ovitos.exe). It should not be confused with ovito, which is the graphical desktop application.

Let’s use a text editor to write a simple Python script file named hello.py:

import ovito
print("Hello, this is OVITO %i.%i.%i" % ovito.version)

We can execute the script file from a Linux terminal as follows:

me@linux:~/ovito-3.0.0-x86_64/bin$ ./ovitos hello.py
Hello, this is OVITO 3.0.0

The ovitos script interpreter is a console program without a graphical user interface. This enables you to run scripts on remote machines or computing clusters that don’t possess a graphical display. ovitos behaves like a regular Python interpreter. Any command line arguments following the script name are passed to the script via the sys.argv variable. Furthermore, it is possible to start an interactive interpreter session by invoking ovitos without any arguments.

Preloading program state

The -o command line option tells ovitos to load an .ovito state file before executing the script. This allows you to preload an existing data pipeline or visualization setup that you have previously prepared using the graphical version of OVITO. All script actions will subsequently be performed in the context of this preloaded program state. This can save you programming work, because things like modifiers and the camera setup already get loaded from the state file and you don’t need to set everything up programmatically in the script anymore.

Graphical mode

The -g command line option of ovitos starts a graphical program session and the script will be run in the context of OVITO’s main window. This allows you to follow your script’s actions as they are being executed. This is useful for debugging purposes if you want to visually check the outcome of your script’s action during the development phase. Keep in mind that the viewports will only show pipelines that have been inserted into the current scene. Thus, it is necessary to explicitly call Pipeline.add_to_scene() to make your imported data visible in this mode.

Number of CPU cores

OVITO uses all available processor cores by default to perform some computations. To explicitly restrict the program to a certain maximum number of parallel threads, use the --nthreads command line parameter, e.g. ovitos --nthreads 1 myscript.py.

Installing third-party Python modules in ovitos

OVITO’s embedded interpreter is a preconfigured version of the standard CPython interpreter with the ovito Python package built in. This makes it possible to run scripts both within the graphical program OVITO as well as through the ovitos command line interpreter. However, OVITO’s Python interpreter only ships with the NumPy and matplotlib preinstalled packages.

If you need to call other third-party Python packages from your OVITO scripts, it may be possible to install them in the ovitos interpreter using the normal pip or setuptools mechanisms (e.g., run ovitos -m pip install <package> to install a module from PyPI).

Installing Python extensions that include native code may fail, however, because such extensions may not be compatible with the build-time configuration of the embedded CPython interpreter. In this case, it is recommend that you instead install the ovito module in your system’s Python interpreter. Further instructions can be found here.

© 2019, Alexander Stukowski.
Close Menu