Packaging and installing extensions
OVITO Pro
To make a Python extension permanently available in OVITO Pro, you package it as a regular Python package and install it in OVITO Pro’s Python interpreter. OVITO Pro automatically discovers installed extensions at program startup and lists them alongside its built-in functions, e.g. in the list of available modifiers or file formats. Packaging also makes it easy to maintain the code of your extension in a Git repository and to share it with other users.
The discovery mechanism is based on Python’s standard entry point specification.
Tip
The OVITO developers provide GitHub repository templates for each type of extension, which contain the directory structure, a pyproject.toml file,
and step-by-step instructions:
Project layout
As an example, we’ll package a user-defined modifier class. The project has the following structure:
<root-dir>/
├── pyproject.toml
└── src/
└── MyModifier/
└── __init__.py
The file src/MyModifier/__init__.py contains the modifier class:
from ovito.data import DataCollection
from ovito.pipeline import ModifierInterface
class MyModifier(ModifierInterface):
def modify(self, data: DataCollection, frame: int, **kwargs):
...
A more complex extension can consist of several modules or subpackages.
The pyproject.toml file
The pyproject.toml file contains the package metadata, including dependencies on other Python packages such as SciPy, which pip installs
automatically:
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "MyModifier"
version = "1.0"
description = "A custom Python modifier for OVITO."
keywords = ["ovito", "python-modifier"]
authors = [{name = "Author Name", email = "author@organization.org"}]
license = "MIT"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
"ovito >= 3.12.0",
]
[project.urls]
repository = "https://github.com/author/MyModifier"
[project.entry-points.'OVITO.Modifier']
"My Modifier" = "MyModifier:MyModifier"
[tool.setuptools.packages.find]
where = ["src"]
The [project.entry-points.'OVITO.Modifier'] section registers the extension with OVITO. The entry’s key specifies the name under which the extension
appears in the user interface of OVITO Pro. The value specifies the module and the name of the class implementing the extension, separated by a colon.
Each type of extension has its own entry point group:
Extension base class |
Entry point group |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
A single package may register several extensions, even of different types.
Installing the package
To install the package in OVITO Pro’s Python interpreter, run pip via the ovitos interpreter from a terminal:
ovitos -m pip install --user --editable <root-dir>
where <root-dir> is the directory containing the pyproject.toml file. Thanks to the --editable option,
code changes take effect without reinstalling the package, which is convenient during development.
Restart OVITO Pro to let it discover the new extension.
Alternatively, use the package installer of OVITO Pro to install the package from within the application. If you work with the conda version of OVITO Pro, install the package with pip in the conda environment.
To use the extension in a Python script running in a different Python interpreter, install the package in that interpreter with pip and import it
like any other Python module, e.g. from MyModifier import MyModifier.