ovito

This module defines the Scene class, which serves as a “universe” or context for all actions performed by a script. The global scene object is accessible as module-level variable ovito.scene. The scene manages a list of Pipeline objects, which will be visible in images and videos when rendering the scene through a Viewport. Furthermore, you can save the entire scene definition including all pipelines to a .ovito session state file, which can be opened in the graphical OVITO application.

ovito.scene: Scene

This module-level variable points to the global Scene object, which serves as context for all operations performed by the script. The Scene object represents the program state and provides access to the contents of the visualization scene:

import ovito

# Retrieve the output data of the pipeline that is currently selected in OVITO:
data = ovito.scene.selected_pipeline.compute()
ovito.version: tuple[int, int, int]

A module-level attribute reporting the current OVITO software version (as three numeric components).

ovito.version_string: str

Module-level attribute reporting the current OVITO software version (as a human-readable string).

class ovito.Scene

This class encompasses all data of an OVITO program session (basically everything that gets saved in a .ovito state file). It manages the list of objects (i.e. Pipeline instances) that are part of the three-dimensional scene and which will show up in rendered images.

From a script’s point of view, there exists exactly one universal instance of this class at any time, which is accessible through the ovito.scene module-level variable. A script cannot create another Scene instance by itself.

load(filename: str | PathLike)

Loads all pipelines stored in a .ovito session state file. This function works like the ‘Load Session State’ function of the desktop application. It can load session state files that were produced with the OVITO Pro desktop application or which have been written by the Scene.save() method. It cannot load session state files created with the OVITO Basic desktop application.

After the state file has been loaded, the pipelines list will be populated with exact copies of the data pipelines that were part of the scene at the time it was saved. See also this section for more information.

property pipelines: MutableSequence[Pipeline]

The list of Pipeline objects that are currently part of the three-dimensional scene. Only pipelines in this list will display their output data in the interactive viewports and in rendered images. You can add or remove a pipeline either by calling its add_to_scene() or remove_from_scene() methods or by directly manipulating this list using the standard Python append() and del statements:

from ovito import scene
from ovito.io import import_file

pipeline = import_file('input/simulation.dump')

# Insert the pipeline into the visualization scene.
pipeline.add_to_scene()
# It's now part of the 'scene.pipelines' list.
assert pipeline in scene.pipelines
# If needed, we can take it out again.
pipeline.remove_from_scene()
save(filename: str | PathLike)

Saves the current scene to a .ovito session state file on disk. The scene comprises all pipelines in the Scene.pipelines list. This function works like the ‘Save Session State As’ function of the OVITO desktop application.

Note

Only Pipeline objects for which add_to_scene() has been called will be included in the session state file. Independent pipelines in Python variables that have not been added to the scene’s pipelines list will be left out.

The saved scene may be restored again from disk by

When the state file is loaded back from disk, the global Scene.pipelines list will contain again all pipelines that were part of the scene at the time it was saved, including all modifiers and their settings. See also the section Session state files.

property selected_pipeline: Pipeline | None

The Pipeline currently selected in the OVITO desktop application, or None if no pipeline is selected. Typically, this is the last pipeline that was added to the scene using Pipeline.add_to_scene().

This field can be useful for macro scripts running in the context of an interactive OVITO session, which want to perform some operation on the currently selected pipeline, e.g. inserting a new modifier.

ovito.enable_logging()

You can call this function at the beginning of your Python script to enable logging of otherwise invisible operations performed by OVITO. Whenever OVITO performs long-running work or computations, it will print informational messages to stderr to indicate the current activity, e.g. file I/O, modifier execution, and image rendering.

ovito.set_pipeline_caching_policy(policy: Literal['full', 'minimal'])

Controls how much intermediate data OVITO’s pipeline system keeps in memory. The setting applies to all pipelines.

Parameters:

policy – Either 'full' (the default) or 'minimal'.

Under the default 'full' policy, every stage of a Pipeline, i.e., the data source and each modifier, keeps its most recent output in memory. This speeds up subsequent calls to Pipeline.compute() after you have changed the parameters of a modifier, because only the modifiers following it in the pipeline need to be recomputed. Note that the pipeline stages share all data a modifier leaves unchanged with each other; only the properties and objects a modifier creates or modifies occupy additional memory.

Under the 'minimal' policy, only the output of the pipeline’s data source and the final output of the pipeline are kept in memory. Intermediate results produced by the individual modifiers are discarded as soon as they have been passed on to the next pipeline stage. This can substantially reduce the memory footprint of pipelines processing very large datasets, in particular if they contain several modifiers. The downside is that changing a modifier’s parameters requires recomputing the entire pipeline, starting at the data source. The results computed by the pipeline are the same under both policies.

Animation frames that a modifier explicitly requests from the upstream pipeline, e.g. the reference configuration of the CalculateDisplacementsModifier, remain cached under both policies.

Tip

The caching policy can also be preset by setting the environment variable OVITO_PIPELINE_CACHING to full or minimal. In the OVITO desktop application, the 'minimal' policy is available as memory saver mode in the application settings dialog.

Added in version 3.17.0.