ovito

ovito.dataset

This module-level attribute holds the current DataSet, a global object representing the state of the program. It provides access to OVITO’s viewports, the objects in the scene, and the current animation and render settings.

ovito.version

This module-level attribute contains the OVITO program version number (as a 3-tuple).

ovito.version_string

This module-level attribute contains the OVITO program version (as a string).

class ovito.DataSet

A container object holding all data associated with an OVITO program session. It provides access to the scene data, the viewports, the current selection, and the animation settings. Basically everything that would get saved in an OVITO state file.

There exists only one global instance of this class, which can be accessed via the ovito.dataset module-level attribute.

anim

An AnimationSettings object, which manages various animation-related settings in OVITO such as the number of frames, the current frame, playback speed etc.

render_settings

The global RenderSettings object, which stores the current settings for rendering pictures and movies. These are the settings the user can edit in the graphical version of OVITO.

save(filename)

Saves the dataset including the viewports, all nodes in the scene, modification pipelines, and other settings to an OVITO file. This function works like the Save State As function in OVITO’s file menu.

Parameters:filename (str) – The path of the file to be written
scene_nodes

A list-like object containing the ObjectNode instances that are part of the three-dimensional scene. Only nodes which are in this list are visible in the viewports. You can add or remove nodes from this list either by calling ObjectNode.add_to_scene() and ObjectNode.remove_from_scene() or by using the standard Python append() and del statements.

selected_node

The ObjectNode that is currently selected in OVITO’s graphical user interface, or None if no node is selected.

viewports

A ViewportConfiguration object managing the viewports in OVITO’s main window.

class ovito.ObjectNode

This class encapsulates a data source, a modification pipeline, and the output of the pipeline.

An ObjectNode is typically created by calling import_file(). But you can also create an object node yourself, e.g., to build a particle system from scratch.

Each node has a data source associated with it, which generates or loads the input data of the modification pipeline. It is accessible through the node’s source attribute. For nodes creates by the import_file() function, the data source is an instance of the FileSource class, which is responsible for loading the input data from the external file. Note that FileSource is derived from the DataCollection base class. Thus, the FileSource also caches the data that it has loaded from the external file and allows you to access or even modify this data.

The node’s modification pipeline is accessible through the modifiers attribute. This list is initially empty and you can populate it with new modifier instances (see the ovito.modifiers module).

Once the modification pipeline is set up, you can request an evaluation of the pipeline, which means that the all modifiers in the pipeline are applied to the input data one after another. The output data of this computation is stored in the output cache of the ObjectNode, which is accessible through its output attribute. This DataCollection, which holds the output data, is also the one that is directly returned by the compute() method.

The following example creates a node by importing a simulation file and inserts a SliceModifier to cut away some of the particles. It then prints the total number of particle in the input and in the output.

from ovito.io import import_file
from ovito.modifiers import SliceModifier

# Import a simulation file.
node = import_file('simulation.dump')

# Print original number of particles.
input = node.source
print("Input particle count: %i" % input.number_of_particles)

# Set up modification pipeline.
node.modifiers.append(SliceModifier(normal = (0,0,1), distance = 0))

# Compute effect of slice modifier.
output = node.compute()
print("Output particle count: %i" % output.number_of_particles)

An ObjectNode can be part of the current scene, which means that it appears in the viewports and in rendered images. By default a node is not part of the scene, but you can insert it into the scene with the add_to_scene() method.

add_to_scene()

Inserts the node into the current scene by appending it to the ovito.DataSet.scene_nodes list. The visual representation of the node will appear in the viewports.

You can remove the node from the scene again by calling remove_from_scene().

compute(frame=None)

Computes and returns the results of the node’s modification pipeline.

This method requests an update of the node’s modification pipeline and waits until the effect of all modifiers in the node’s modification pipeline has been computed. If the modification pipeline is already up to date, i.e., results are already available in the node’s pipeline cache, the method returns immediately.

The optional frame parameter lets you control at which animation time the modification pipeline is evaluated. (Animation frames start at 0.) If it is omitted, the current animation position (AnimationSettings.current_frame) is used.

Even if you are not interested in the final output of the modification pipeline, you should still call this method in case you are going to directly access information reported by individual modifiers in the pipeline. This method will ensure that all modifiers have been computed and their output fields are up to date.

This function raises a RuntimeError when the modification pipeline could not be successfully evaluated for some reason. This may happen due to invalid modifier parameters for example.

Returns:A reference to the node’s internal DataCollection containing the output of the modification pipeline. It is also accessible via the output attribute after calling compute().
modifiers

The node’s modification pipeline.

This list contains the modifiers that are applied to the input data provided by the node’s source object. You can add and remove modifiers from this list as needed. The first modifier in the list is always evaluated first, and its output is passed on to the second modifier and so on. The results of the last modifier are displayed in the viewports and can be access through the output field.

Example:

node.modifiers.append(WrapPeriodicImagesModifier())
output

Provides access to the last results computed by the node’s data modification pipeline.

After calling the compute() method, this attribute holds a DataCollection with the output of the node’s modification pipeline.

remove_from_scene()

Removes the node from the scene by deleting it from the ovito.DataSet.scene_nodes list. The visual representation of the node will disappear from the viewports after calling this method.

source

The object that provides or generates the data that enters the node’s modification pipeline. This typically is a FileSource instance if the node was created by a call to import_file().