# `ovito`

This module contains 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 including all pipelines to a `.ovito` session state file, which can be opened in the graphical OVITO application.

ovito.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

  A module-level attribute reporting the OVITO program version number (as a tuple of three `int`).

ovito.version_string

  Module-level attribute reporting the OVITO program version (as a 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)

    Loads the pipeline(s) stored in a .ovito session state file. This function works like the Load Session State function of the graphical OVITO application. It can load session state files that were produced with the interactive OVITO application or which have been written by the `Scene.save()` method.

    Parameters

      filename (str) – File path of the .ovito session file to load

    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 when it was saved. See also this section for more information.

  property pipelines

    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 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)

    Saves the scene to a `.ovito` session state file. The scene comprises, in particular, all data pipelines currently in the `Scene.pipelines` list, the modifiers and visual elements in these pipelines, and their parameters. This function works like the Save Session State As function of the graphical OVITO application.

    Note

    Only `Pipeline` objects for which you did call `add_to_scene()` will be included in the session state file. Pipelines that have not been added to the scene will not be saved.

    Parameters

      filename (str) – Output file path

    The saved session state may be restored again from disk at a later time by

    > - calling the `Scene.load()` method,

    > - using the -o command line option of the ovitos interpreter, or

    > - opening the state file with the graphical OVITO application.

    After loading the state file, the `Scene.pipelines` list will contain again all data pipelines that were part of the scene at the time it was saved. See also this section for more information.

  property selected_pipeline

    Returns the `Pipeline` that is currently selected in the graphical OVITO 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 scripts running in the context of the graphical OVITO application which want to perform some action on the currently selected pipeline, e.g. insert a new modifier.

ovito.enable_logging()

  Calling this function at the beginning of a Python script enables activity logging for OVITO’s internal operations. When performing long-running operations, OVITO will print messages to `stderr` indicating the current activity, e.g. file reading and writing, modifier execution, or rendering.