`ovito.vis`

This module contains classes related to data visualization and rendering.

Rendering:

Viewport

Rendering engines:

OpenGLRenderer

TachyonRenderer

OSPRayRenderer

Data visualization elements:

DataVis (base class for all visual elements)

BondsVis

DislocationVis

ParticlesVis

SimulationCellVis

SurfaceMeshVis

TrajectoryVis

TriangleMeshVis

VectorVis

VoxelGridVis

Viewport overlays:

ViewportOverlay (base class for all overlay types)

ColorLegendOverlay

CoordinateTripodOverlay

PythonViewportOverlay

TextLabelOverlay

class ovito.vis.BondsVis

Base: ovito.vis.DataVis

A visualization element that renders cylindrical bonds between particles. An instance of this class is attached to every Bonds data object and controls the visual appearance of the bonds in rendered images.

See also the corresponding user manual page for this visual element. If you import a simulation file containing bonds, you can subsequently access the BondsVis element through the vis field of the bonds data object, which is part in the data collection managed by the pipeline’s source object:

pipeline = import_file('input/bonds.data.gz', atom_style='bond')
pipeline.add_to_scene()
bonds_vis = pipeline.source.data.particles.bonds.vis
bonds_vis.width = 0.4

In cases where the Bonds data is dynamically generated by a modifier, e.g. the CreateBondsModifier, the BondsVis element is managed by the modifier:

modifier = CreateBondsModifier(cutoff = 2.8)
modifier.vis.flat_shading = True
pipeline.modifiers.append(modifier)

property color

The uniform color of bonds. This parameter is only used if coloring_mode is set to Uniform and if the bonds do not possess a bond property named Color, i.e., explicit per-bond colors were not provided.

Default: (0.6, 0.6, 0.6)

property coloring_mode

Selects how the color of each bond is determined. Available modes:

BondsVis.ColoringMode.Uniform: Use the specified color value to render all bonds.

BondsVis.ColoringMode.ByBondType: Use each bond type’s color to render the bonds.

BondsVis.ColoringMode.ByParticle: Adopt the colors of the particles connect by the bonds.

Note

If the Bonds object being rendered contains the Color property, then the visual element will directly use these explicit per-bond RGB values for rendering the bonds. The coloring_mode parameter is ignored in this case.

Default: BondsVis.ColoringMode.ByParticle

property flat_shading

Boolean flag that activates a flat-shaded representation of the bonds instead of the normal cylinder representation.

Default: False

property width

The display width of bonds (in natural length units).

Default: 0.4

class ovito.vis.ColorLegendOverlay

Base: ovito.vis.ViewportOverlay

This layer renders a color legend over the viewport image, which helps the audience recognize the meaning of depicted object colors. You should add this ViewportOverlay to the Viewport.overlays or Viewport.underlays list of the viewport you use for rendering:

from ovito.vis import ColorLegendOverlay, Viewport
from ovito.qt_compat import QtCore

vp = Viewport(type=Viewport.Type.Top)

legend = ColorLegendOverlay(
    title = 'Potential energy per atom',
    alignment = QtCore.Qt.AlignmentFlag.AlignLeft | QtCore.Qt.AlignmentFlag.AlignTop,
    orientation = QtCore.Qt.Orientation.Vertical,
    offset_y = -0.04,
    font_size = 0.12,
    format_string = '%.2f eV')
vp.overlays.append(legend)

Specifying the color map source

Most importantly, you need to specify which color scheme the legend is supposed to display. There currently are three kinds of color map sources one can use for a legend:

The color map of a ColorCodingModifier used in the current scene.

The color map of a visual element that supports pseudo-color mapping, e.g. SurfaceMeshVis, VoxelGridVis, TrajectoryVis, or VectorVis.

The discrete colors of a typed property representing different particle types, bond types, etc.

To display the color spectrum of a color coding modifier, including text labels indicating the corresponding numeric value range, set the legend’s modifier field to point to the ColorCodingModifier:

modifier = ColorCodingModifier(property='peatom')
pipeline.modifiers.append(modifier)

legend.modifier = modifier

If you have set up a visual element in your scene that supports pseudo-color mapping, e.g. a VoxelGridVis visualizing some grid property using pseudo-colors, then you can associate it with the color legend by assigning it to the color_mapping_source field:

# Load a VASP volumetric charge density file:
pipeline = import_file('input/CHGCAR.nospin.gz')
pipeline.add_to_scene()

# Configure the VoxelGridVis element responsible for displaying the charge density grid:
grid_vis = pipeline.compute().grids['charge-density'].vis
grid_vis.enabled = True
grid_vis.color_mapping_property = 'Charge density' # Grid property to visualize using pseudo-colors
grid_vis.color_mapping_interval = (0.02186, 0.05465)

# Use the VoxelGridVis as color map source for the legend:
legend.color_mapping_source = grid_vis

To display the discrete colors of a typed Property, specify the source particle or bond property as follows:

legend.property = 'particles/Particle Type'

See the documentation of the property parameter for more information.

property alignment

Selects the corner of the viewport where the color bar is displayed (anchor position). This must be a valid Qt.AlignmentFlag value as shown in the code example above.

Default: QtCore.Qt.AlignmentFlag.AlignHCenter | QtCore.Qt.AlignmentFlag.AlignBottom

property aspect_ratio

The aspect ratio of the color bar. Larger values make it more narrow.

Default: 8.0

property background_color

The color of the background panel. Only used if background_enabled is set.

Default: (1.0, 1.0, 1.0)

New in version 3.8.0.

property background_enabled

Enables the painting of a color legend background. A filled panel will be drawn behind the legend to better distinguish the legend from the cluttered 3d scene in the background.

Default: False

New in version 3.8.0.

property border_color

The line color of the border painted around the color map. This is used only if border_enabled is set.

Default: (0.0, 0.0, 0.0)

property border_enabled

Enables the painting of a border line around color map.

Default: False

property color_mapping_source

The DataVis element to be used as color map source by this viewport layer. Set this to the SurfaceMeshVis, VoxelGridVis, TrajectoryVis, or VectorVis element whose color map the legend should display.

Example:

# Add modifier to the pipeline which generates particle trajectory lines:
modifier = GenerateTrajectoryLinesModifier(only_selected=False)
pipeline.modifiers.append(modifier)
modifier.generate()

# Configure the modifier's TrajectoryVis element to apply a color mapping to the lines:
modifier.vis.color_mapping_property = 'Time'
modifier.vis.color_mapping_interval = (0, pipeline.source.num_frames-1)

# Add a color legend and link it to the TrajectoryVis element to display its color map.
vp.overlays.append(ColorLegendOverlay(color_mapping_source=modifier.vis))

Default: None

New in version 3.7.9.

property font

A string with comma-separated parameter values describing the font to be used for rendering the text labels of the viewport layer. The string must follow the specific form understood by the QFont.fromString() method, for example 'Arial,10,-1,5,75,0,0,0,0,0,Bold'.

Note that the font size parameter (10 in the example specification above) will be ignored by the viewport layer, because the size of text labels is already controlled by the font_size parameter.

property font_size

The relative size of the font used for text labels.

Default: 0.1

property format_string

The format string used with the sprintf() function to generate the text representation of floating-point values. You can change this format string to control the number of displayed decimal places.

Literal text may be incorporated into the format string to include physical units, for example, and HTML text formatting is supported.

Default: '%g'

property label1

Sets the text string displayed at the upper end of the bar. If empty, the end_value of the ColorCodingModifier is used.

The label supports HTML text formatting.

Default: ''

property label2

Sets the text string displayed at the lower end of the bar. If empty, the start_value of the ColorCodingModifier is used.

The label supports HTML text formatting.

Default: ''

property label_size

The relative size of the font used for the tick labels. Size given relative to font_size.

Default: 0.6

property legend_size

Controls the overall size of the color bar relative to the output image size.

Default: 0.3

property modifier: The ColorCodingModifier for which the color legend should be rendered.

property offset_x

This parameter allows to displace the color bar horizontally from its anchor position. The offset is specified as a fraction of the output image width.

Default: 0.0

property offset_y

This parameter allows to displace the color bar vertically from its anchor position. The offset is specified as a fraction of the output image height.

Default: 0.0

property orientation

Selects the orientation of the color bar. This must be a valid Qt.Orientation value as shown in the code example above.

Default: QtCore.Qt.Orientation.Horizontal

property outline_color

The text outline color. This is used only if outline_enabled is set.

Default: (1.0, 1.0, 1.0)

property outline_enabled

Enables the painting of a font outline to make the text easier to read.

Default: False

property property

Specifies the path to the typed Property for which a discrete color legend should be rendered.

The specified path tells the legend where to find the particle or bond property whose discrete types it should display. Generally, the selected property may be dynamically produced by the current data Pipeline and may not exist yet at the point when you set up the ColorLegendOverlay. That’s why you have to reference it by name instead of specifying the Property object directly.

The path specifies where to find the selected property within the nested containers that make up the DataCollection produced by the current pipeline. It consists of a sequence of DataObject.identifier strings separated by slashes. The last entry in the path is simply the name of the Property to be displayed by the legend.

Examples:

# Display the different structural types identified by PolyhedralTemplateMatchingModifier:
legend.property = 'particles/Structure Type'

# Display the list of bond types in the system:
legend.property = 'particles/bonds/Bond Type'

In case there are multiple data pipelines in the current scene, the legend will automatically pick the first pipeline that yields a DataCollection containing the selected property.

Default: ''

property rotate_title

Enables the vertical orientation of the title, i.e. text orientation parallel to the color legend, if the legend’s orientation is set to QtCore.Qt.Vertical. Otherwise this option is ignored and the title text will be rendered horizontally.

Default: False

property text_color

The RGB color used for text labels.

Default: (0.0, 0.0, 0.0)

property ticks_enabled

Enables the painting of tick marks and labels on the color map.

Default: False

New in version 3.8.0.

property ticks_spacing

Defines the tick spacing along the (continuous) color scale. Requires ticks_enabled to be set. The standard value of 0 activates automatic tick placement based on the input value range.

Default: 0

New in version 3.8.0.

property title

The text displayed next to the color bar. If this string is empty, the title of the source Property object is used.

The title label supports HTML text formatting.

Default: ''

class ovito.vis.CoordinateTripodOverlay

Base: ovito.vis.ViewportOverlay

Displays a coordinate tripod in rendered images. You can attach an instance of this class to a viewport by adding it to the viewport’s overlays collection:

from ovito.vis import CoordinateTripodOverlay, Viewport
from ovito.qt_compat import QtCore

# Create the overlay.
tripod = CoordinateTripodOverlay()
tripod.size = 0.07
tripod.alignment = QtCore.Qt.AlignmentFlag.AlignRight | QtCore.Qt.AlignmentFlag.AlignBottom
tripod.style = CoordinateTripodOverlay.Style.Solid

# Attach overlay to a newly created viewport.
viewport = Viewport(type=Viewport.Type.Perspective, camera_dir=(1,2,-1))
viewport.overlays.append(tripod)

property alignment

Selects the corner of the viewport where the tripod is displayed (anchor position). This must be a valid Qt.AlignmentFlag value value as shown in the example above.

Default: QtCore.Qt.AlignmentFlag.AlignLeft | QtCore.Qt.AlignmentFlag.AlignBottom

property axis1_color

RGB display color of the first axis.

Default: (1.0, 0.0, 0.0)

property axis1_dir

Vector specifying direction and length of first axis, expressed in the global Cartesian coordinate system.

Default: (1.0, 0.0, 0.0)

property axis1_enabled

Enables the display of the first axis.

Default: True

property axis1_label

Text label for the first axis.

Default: "x"

property axis2_color

RGB display color of the second axis.

Default: (0.0, 0.8, 0.0)

property axis2_dir

Vector specifying direction and length of second axis, expressed in the global Cartesian coordinate system.

Default: (0.0, 1.0, 0.0)

property axis2_enabled

Enables the display of the second axis.

Default: True

property axis2_label

Text label for the second axis.

Default: "y"

property axis3_color

RGB display color of the third axis.

Default: (0.2, 0.2, 1.0)

property axis3_dir

Vector specifying direction and length of third axis, expressed in the global Cartesian coordinate system.

Default: (0.0, 0.0, 1.0)

property axis3_enabled

Enables the display of the third axis.

Default: True

property axis3_label

Text label for the third axis.

Default: "z"

property axis4_color

RGB display color of the fourth axis.

Default: (1.0, 0.0, 1.0)

property axis4_dir

Vector specifying direction and length of fourth axis, expressed in the global Cartesian coordinate system.

Default: (0.7071, 0.7071, 0.0)

property axis4_enabled

Enables the display of the fourth axis.

Default: False

property axis4_label

Label for the fourth axis.

Default: "w"

property font

A string with comma-separated parameter values describing the font to be used for rendering the text labels of the viewport layer. The string must follow the specific form understood by the QFont.fromString() method, for example 'Arial,10,-1,5,75,0,0,0,0,0,Bold'.

Note that the font size parameter (10 in the example specification above) will be ignored by the viewport layer, because the size of text labels is already controlled by the font_size parameter.

property font_size

The font size for rendering the text labels of the tripod. The font size is specified in terms of the tripod size.

Default: 0.4

property line_width

Controls the width of axis arrows. The line width is specified relative to the tripod size.

Default: 0.06

property offset_x

This parameter allows to displace the tripod horizontally. The offset is specified as a fraction of the output image width.

Default: 0.0

property offset_y

This parameter allows to displace the tripod vertically. The offset is specified as a fraction of the output image height.

Default: 0.0

property outline_color

The outline color for text labels. This is used only if outline_enabled is set.

Default: (1.0, 1.0, 1.0)

property outline_enabled

Enables the painting of a font outline to make the axis labels easier to read.

Default: False

property size

Scaling factor controlling the overall size of the tripod. The size is specified as a fraction of the output image height.

Default: 0.075

property style

Selects the visual style of the coordinate axis tripod. Supported values are:

CoordinateTripodOverlay.Style.Flat (default)

CoordinateTripodOverlay.Style.Solid

class ovito.vis.DataVis

Abstract base class for visualization elements that are responsible for the visual appearance of data objects in the visualization. Some DataObjects are associated with a corresponding DataVis element (see DataObject.vis property), making them visual data objects that appear in the viewports and in rendered images.

See the ovito.vis module for the list of visual element types available in OVITO.

property enabled

Boolean flag controlling the visibility of the data. If set to False, the data will not be visible in the viewports or in rendered images.

Default: True

property title

A custom title string assigned to the visual element, which will show in the pipeline editor of OVITO.

Default: ''

class ovito.vis.DislocationVis

Base: ovito.vis.DataVis

Controls the visual appearance of dislocation lines extracted by a DislocationAnalysisModifier. An instance of this class is attached to every DislocationNetwork data object.

See also the corresponding user manual page for more information on this visual element.

property burgers_vector_color

The color of Burgers vector arrows.

Default: (0.7, 0.7, 0.7)

property burgers_vector_scaling

The scaling factor applied to displayed Burgers vectors. This can be used to exaggerate the arrow size.

Default: 1.0

property burgers_vector_width

Specifies the width of Burgers vector arrows (in length units).

Default: 0.6

property coloring_mode

Selects the coloring mode for dislocation lines. Supported modes are:

DislocationVis.ColoringMode.ByDislocationType (default)

DislocationVis.ColoringMode.ByBurgersVector

DislocationVis.ColoringMode.ByCharacter

property line_width

Controls the display width (in units of length of the simulation) of dislocation lines.

Default: 1.0

property shading

The shading style used for the lines. Possible values:

DislocationVis.Shading.Normal (default)

DislocationVis.Shading.Flat

property show_burgers_vectors

Boolean flag that enables the display of Burgers vector arrows.

Default: False

property show_line_directions

Boolean flag that enables the visualization of line directions.

Default: False

class ovito.vis.OSPRayRenderer

This is one of the software-based rendering backends of OVITO, which can generate images with higher fidelity than the standard OpenGLRenderer. Typically, you create an instance of this class and pass it to the Viewport.render_image() or Viewport.render_anim() methods.

OSPRay can render scenes with ambient occlusion lighting, semi-transparent objects, and depth-of-field focal blur. For technical details of the supported rendering algorithms and parameters, see the www.ospray.org website. See also the corresponding user manual page for more information on this rendering engine.

property ambient_brightness

Controls the radiance of the ambient light.

Default: 0.8

property ambient_light_enabled

Enables the ambient light, which surrounds the scene and illuminates it from infinity with constant radiance.

Default: True

property aperture

The aperture radius controls how blurred objects will appear that are out of focus if dof_enabled is set.

Default: 0.5

property denoising_enabled

Enables the application of a denoising filter to the rendered image to reduce Monte Carlo noise inherent to stochastic ray tracing methods like path tracing.

Default: True

property direct_light_angular_diameter

Specifies the apparent size (angle in radians) of the default directional light source. Setting the angular diameter to a value greater than zero yields soft shadow.

Default: numpy.radians(10.0)

property direct_light_enabled

Enables the default directional light source that is positioned behind the camera and is pointing roughly along the viewing direction. The brightness of the light source is controlled by the direct_light_intensity parameter.

Default: True

property direct_light_intensity

The intensity of the default directional light source. The light source must be enabled by setting direct_light_enabled.

Default: 1.0

property dof_enabled

Enables the depth-of-field effect (focal blur). Only objects exactly at the distance from the camera specified by the focal_length will appear sharp when depth-of-field rendering is enabled. Objects closer to or further from the camera will appear blurred. The strength of the effect is controlled by the aperture parameter.

Default: False

property focal_length

Only objects exactly at this distance from the camera will appear sharp when dof_enabled is set. Objects closer to or further from the camera will appear blurred.

Default: 40.0

property material_shininess

Specular Phong exponent value for the default material. Usually in the range between 2.0 and 10,000.

Default: 10.0

property material_specular_brightness

Controls the specular reflectivity of the default material.

Default: 0.02

property max_ray_recursion

The maximum number of recursion steps during raytracing. Normally, 1 or 2 is enough, but when rendering semi-transparent objects, a larger recursion depth is needed.

Default: 10

property refinement_iterations

The OSPRay renderer supports a feature called adaptive accumulation, which is a progressive rendering method. During each rendering pass, the rendered image is progressively refined. This parameter controls the number of iterations until the refinement stops.

Default: 4

property samples_per_pixel

The number of raytracing samples computed per pixel. Larger values can help to reduce aliasing artifacts.

Default: 2

property sky_albedo

Controls the ground reflectance affecting the sky-sun light source. The light source must be enabled first by setting sky_light_enabled. Valid parameter range is [0.0 - 1.0].

Default: 0.3

property sky_brightness

The intensity of the sky-sun light source. The light source must be enabled first by setting sky_light_enabled.

Default: 2.0

property sky_light_enabled

Enables the sky/sun light source that mimics the light coming from the sky and the sun in an outdoor scene. The brightness of the sky is controlled by the sky_brightness parameter.

Default: False

property sky_turbidity

Controls atmospheric turbidity due to particles affecting the sky-sun light source. The light source must be enabled first by setting sky_light_enabled. Valid parameter range is [1.0 - 10.0].

Default: 3.0

class ovito.vis.OpenGLRenderer

This is the default rendering backend used by the Viewport.render_image() and Viewport.render_anim() functions. It also serves in the OVITO desktop application for the real-time display of the 3d scene in the interactive viewport windows. The OpenGL renderer uses your computer’s GPU graphics hardware to accelerate the generation of images. See the corresponding user manual page for more information.

Enabling OpenGL support

This rendering backend requires an environment where OpenGL graphics support is available. Standalone Python scripts typically run in a headless environment, e.g. a text-based terminal without graphics support. This prevents the OpenGLRenderer from initializing an OpenGL context and an offscreen framebuffer to render into. A call to Viewport.render_image() will raise an error in this case, and you have to take one of the following steps to enable OpenGL graphics support – or altogether avoid the problem by using one of the software-based rendering backends instead.

The ovito Python module, if imported by a Python script running in an external Python interpreter, sets up a headless environment by default, in which OpenGL rendering is not available. A proper graphics environment can be explicitly requested in two ways (starting with OVITO 3.7.10):

Setting the environment variable OVITO_GUI_MODE=1 prior to importing the ovito package or any of its sub-packages:

You can set the variable either externally, before or while launching your Python script program:
```
OVITO_GUI_MODE=1 python3 <your_script.py>
```
or within the Python program itself by including the following lines before the first import ovito statement at the top of your .py file:
```
import os
os.environ['OVITO_GUI_MODE'] = '1' # Request a session with OpenGL support
```
Create a Qt application object with GUI support before importing the ovito module:

The standard behavior of the ovito module is to create a global QCoreApplication object during module import, which is only suitable for headless operation, e.g., file I/O and pipeline computations, but not sufficient for OpenGL-based rendering. If, however, a global Qt application object already exists at the time the ovito module is loaded, then OVITO will use that pre-existing application object. For example:
```
# Make the program run in the context of the graphical desktop environment.
import PySide6.QtWidgets
app = PySide6.QtWidgets.QApplication() 

from ovito.vis import *
vp = Viewport()
vp.render_image(renderer=OpenGLRenderer())
```
Note

Other Python packages imported by your Python script may also be using the Qt cross-platform toolkit (e.g. Matplotlib’s Qt backend). That means such a third-party package may also set up a global Qt application object, which will subsequently be shared with the ovito module. Furthermore, if you are executing your Python script in a graphical IDE such as Spyder, which itself is based on the Qt framework, then a global application instance may already be present at the time the Python script is launched.

Linux/Unix systems (including WSL2)

On Linux/Unix systems, an X11 or Wayland display server is required for OpenGL graphics. When you request a graphics session with one of the methods described above, the Qt framework will attempt to establish a connection to the X11/Wayland server. If this fails, e.g., because the DISPLAY environment variable is not set correctly, Qt reports an error and the program will quit with the following message:

qt.qpa.xcb: could not connect to display 
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Remote servers and HPC clusters, which are typically accessed via SSH terminals, often do not provide a running graphical desktop environment that would allow the use of OpenGL functions by OVITO. In such a headless environment it may still be possible to provide a virtual X server to the Python application, e.g., using the xvfb-run wrapper command:

OVITO_GUI_MODE=1 xvfb-run python3 <your_script.py>

property antialiasing_level

A positive integer controlling the level of supersampling. If 1, no supersampling is performed. For larger values, the image in rendered at a higher resolution and then scaled back to the output size to reduce aliasing artifacts.

Default: 3

class ovito.vis.ParticlesVis

Base: ovito.vis.DataVis

This type of visual element is responsible for rendering particles and is attached to every Particles data object. You can access the element through the vis field of the data object and adjust its parameters to control the visual appearance of particles in rendered images:

from ovito.io import import_file
from ovito.vis import ParticlesVis

pipeline = import_file("input/simulation.dump")
pipeline.add_to_scene()

vis_element = pipeline.compute().particles.vis
vis_element.shape = ParticlesVis.Shape.Square

See also the corresponding user manual page for more information on this visual element.

property radius

The standard display radius of particles. This value is only used if no per-particle or per-type radii have been set. A per-type radius can be set via ParticleType.radius. An individual display radius can be assigned to each particle by setting the Radius particle property, e.g. using the ComputePropertyModifier.

Default: 1.2

property scaling

Global scaling factor that is applied to every particle being rendered.

Default: 1.0

property shape

The kind of shape to use when rendering the particles. Supported modes are:

ParticlesVis.Shape.Sphere (default)

ParticlesVis.Shape.Box

ParticlesVis.Shape.Circle

ParticlesVis.Shape.Square

ParticlesVis.Shape.Cylinder

ParticlesVis.Shape.Spherocylinder

Mode Sphere includes ellipsoid and superquadric particle geometries, which are activated by the presence of the Aspherical Shape and Superquadric Roundness particle properties. Mode Box renders cubic as well as non-cubic boxes depending on the presence of the Aspherical Shape particle property.

Note that this parameter controls the standard shape to be used for all particles. You can override this default setting on a per-particle type basis by setting the ParticleType.shape property to a different value.

class ovito.vis.PythonViewportOverlay

Base: ovito.vis.ViewportOverlay

This type of viewport overlay runs a custom Python script function every time an image of the viewport is rendered. The user-defined script function can paint arbitrary graphics on top of the three-dimensional scene.

Note that instead of using a PythonViewportOverlay it is also possible to directly manipulate the image returned by the Viewport.render_image() method before saving the image to disk. A PythonViewportOverlay is only necessary when rendering animations or if you want the overlay to be usable from in the graphical program version.

You can attach the Python overlay to a viewport by adding it to the viewport’s overlays collection:

from ovito.vis import PythonViewportOverlay, Viewport

# Create a viewport:
viewport = Viewport(type = Viewport.Type.Top)

# The user-defined function that will paint on top of rendered images:
def render_some_text(args: PythonViewportOverlay.Arguments):
    args.painter.drawText(10, 10, "Hello world")

# Attach overlay function to viewport:
viewport.overlays.append(PythonViewportOverlay(function = render_some_text))

The user-defined Python function must accept a single argument (named args in the example above). The system will pass in an instance of the Arguments class to the function, which contains various state information, including the current animation frame number and the viewport being rendered as well as a QPainter object, which the function should use to issue drawing calls.

class Arguments

This data structure is passed to the user-defined render() function of the viewport overlay by the system. It carries context information about the frame being rendered and provides utility methods for projecting points from 3d to 2d space. Most importantly, it gives access to the painter object, which should be used by the render() function to issue drawing commands.

property fov: The field of view of the viewport’s camera. For perspective projections, this is the frustum angle in the vertical direction (in radians). For orthogonal projections this is the visible range in the vertical direction (in world units).

property frame: The animation frame number being rendered (0-based).

property is_perspective: Flag indicating whether the viewport uses a perspective projection or parallel projection.

property painter: The QPainter object, which provides painting methods for drawing on top of the image canvas.

property proj_tm: The projection matrix. This 4x4 matrix transforms points from camera space to screen space.

project_point(world_xyz)

Projects a point, given in world-space coordinates, to screen space. This method can be used to determine where a 3d point would appear in the rendered image.

Note that the projected point may lay outside of the visible viewport region. Furthermore, for viewports with a perspective projection, the input point may lie behind the virtual camera. In this case no corresponding projected point in 2d screen space exists and the method returns None.

Parameters: world_xyz – The (x,y,z) coordinates of the input point
Returns: A (x,y) pair of pixel coordinates; or None if world_xyz is behind the viewer.

project_size(world_xyz, r)

Projects a size from 3d world space to 2d screen space. This method can be used to determine how large a 3d object, for example a sphere with the given radius r, would appear in the rendered image.

Additionally to the size r to be projected, the method takes a coordinate triplet (x,y,z) as input. It specifies the location of the base point from where the distance is measured.

Parameters

world_xyz – The (x,y,z) world-space coordinates of the base point
r – The world-space size or distance to be converted to screen space

Returns

The computed screen-space size measured in pixels.

property scene: The current three-dimensional Scene being rendered. Provides access to all visible data pipelines.

property size: A tuple containing the width and height of the viewport image being rendered (in pixels). This may be a sub-region of the output image when rendering a multi-viewport layout.

property view_tm: The affine camera transformation matrix. This 3x4 matrix transforms points/vectors from world space to camera space.

property viewport: The Viewport being rendered.

property function

A reference to the Python function to be called every time the viewport is repainted or when an output image is rendered.

The user-defined function must accept exactly one argument as shown in the example above. The system will pass an Arguments object to the function, providing various contextual information on the current frame being rendered.

Implementation note: Exceptions raised within the custom rendering function are not propagated to the calling context.

Default: None

class ovito.vis.SimulationCellVis

Base: ovito.vis.DataVis

Controls the visual appearance of the simulation cell. An instance of this class is attached to the SimulationCell object and can be accessed through its vis field. See also the corresponding user manual page for this visual element.

The following example script demonstrates how to change the display line width and rendering color of the simulation cell loaded from an input simulation file:

from ovito.io import import_file

pipeline = import_file("input/simulation.dump")
pipeline.add_to_scene()

cell_vis = pipeline.source.data.cell.vis
cell_vis.line_width = 1.3
cell_vis.rendering_color = (0.0, 0.0, 0.8)

property line_width

The width of the simulation cell line (in simulation units of length).

Default: 0.14% of the simulation box diameter

property render_cell

Boolean flag controlling the cell’s visibility in rendered images. If False, the cell will only be visible in the interactive viewports.

Default: True

property rendering_color

The line color used when rendering the cell.

Default: (0.0, 0.0, 0.0)

class ovito.vis.SurfaceMeshVis

Base: ovito.vis.DataVis

Controls the visual appearance of a SurfaceMesh object, which is typically generated by modifiers such as ConstructSurfaceModifier or CreateIsosurfaceModifier. See also the corresponding user manual page for more information on this visual element.

property cap_color

The RGB display color of the cap polygons at periodic boundaries.

Default: (0.8, 0.8, 1.0)

property cap_transparency

The level of transparency of the displayed cap polygons. The valid range is 0.0 – 1.0 (fully opaque to fully transparent).

Default: 0.0

property clip_at_domain_boundaries

Controls whether the mesh gets clipped at non-periodic cell boundaries during visualization. This option plays a role only if the mesh extends beyond the boundaries of the finite domain of the SurfaceMesh; it does not apply to intersections of the surface with periodic boundaries of the simulation domain (see pbc), at which the surface mesh always gets wrapped back into primary cell image for visualization.

If the mesh extends beyond the (non-periodic) domain boundaries, you can use this option to restrict the display of the mesh to those parts that are located inside the domain.

../_images/surface_mesh_vis_clipping_off.png — Clipping off

../_images/surface_mesh_vis_clipping_on.png — Clipping on

Default: False

New in version 3.8.0.

property color_mapping_gradient

The color gradient for mapping scalar property values taken from the selected color_mapping_property to corresponding RGB color values (color transfer function). See the ColorCodingModifier.gradient parameter for a list of available color gradient types.

Default: ColorCodingModifier.Rainbow()

property color_mapping_interval

Specifies the range of input values from the selected color_mapping_property getting mapped to corresponding RGB values by the selected color_mapping_gradient. The tuple defines the start and end of the linear interval that is translated to pseudo-colors by the color map. Input property values not within of the interval get mapped to the marginal colors of the selected color map.

Default: (0.0, 0.0)

property color_mapping_mode

Controls how the color of the surface is computed. Using pseudo-coloring you can visualize a local property of the surface.

Available modes:

SurfaceMeshVis.ColorMappingMode.Uniform: Uses surface_color for rendering the entire surface with a constant color (disables local pseudo-coloring).

SurfaceMeshVis.ColorMappingMode.Vertex: Colors the surface based on a local property associated with the surface’s vertices.

SurfaceMeshVis.ColorMappingMode.Face: Colors the surface based on a local property associated with the surface’s faces.

SurfaceMeshVis.ColorMappingMode.Region: Colors the surface based on a local property associated with the surface’s regions.

Default: SurfaceMeshVis.ColorMappingMode.Uniform

Note

This setting has no effect if the vertices, faces or regions of the SurfaceMesh have explicit colors associated with them, i.e., if the Color property exists in one of these property containers.

property color_mapping_property

The name of the property to be used for coloring the mesh to visualize the local values of this property on the surface. If the Property has several components, then the name must be followed by a component name, e.g. 'Orientation.X'. Whether the property is taken from the vertices, faces, or regions of the SurfaceMesh being rendered is determined by the selected color_mapping_mode.

Numeric values from the source property are mapped to corresponding RGB-based pseudo-colors by first normalizing them according to the specified color_mapping_interval and then applying the selected color_mapping_gradient.

Note that, if the Color property is defined on the surface’s vertices, faces, or regions, then the visual element directly uses these explicit RGB values to render the surface. No color mapping takes place in this case and the color_mapping_property, color_mapping_mode and surface_color parameters are all ignored.

Default: ''

property highlight_edges

Activates the highlighted rendering of the polygonal edges of the mesh.

Default: False

property reverse_orientation

Flips the orientation of the surface. This affects the generation of cap polygons as well.

Default: False

property show_cap

Controls the visibility of cap polygons, which are created at the intersection of the surface mesh with the domain boundaries. This option has an effect only if the surface mesh being rendered is closed, which means there are well-defined “interior” and “exterior” regions of space separated by the surface manifold.

Default: True

See also

SurfaceMeshTopology.is_closed

property smooth_shading

Enables smooth shading of the triangulated surface mesh.

Default: True

property surface_color

The RGB display color of the surface mesh. Used only if color_mapping_mode is set to uniform coloring.

Default: (1.0, 1.0, 1.0)

property surface_transparency

The level of transparency of the displayed surface. The valid range is 0.0 – 1.0 (fully opaque to fully transparent).

Default: 0.0

class ovito.vis.TachyonRenderer

This is one of the software-based rendering backends of OVITO. Tachyon is an open-source raytracing engine integrated into OVITO.

An instance of this class can be passed to the Viewport.render_image() or Viewport.render_anim() methods.

Tachyon can render scenes with ambient occlusion lighting, semi-transparent objects, and depth-of-field focal blur. See the corresponding user manual page for more information on this rendering backend.

property ambient_occlusion

Enables ambient occlusion shading. Enabling this lighting technique mimics some of the effects that occur under conditions of omnidirectional diffuse illumination, e.g. outdoors on an overcast day.

Default: True

property ambient_occlusion_brightness

Controls the brightness of the sky light source used for ambient occlusion.

Default: 0.8

property ambient_occlusion_samples

Ambient occlusion is implemented using a Monte Carlo technique. This parameters controls the number of samples to compute. A higher sample count leads to a more even shading, but requires more computation time.

Default: 12

property antialiasing

Enables supersampling to reduce aliasing effects.

Default: True

property antialiasing_samples

The number of supersampling rays to generate per pixel to reduce aliasing effects.

Default: 12

property aperture

Controls the aperture of the camera, which is used for depth-of-field rendering.

Default: 0.01

property depth_of_field

This flag enables depth-of-field rendering.

Default: False

property direct_light

Enables the parallel light source, which is positioned at an angle behind the camera.

Default: True

property direct_light_intensity

Controls the brightness of the directional light source.

Default: 0.9

property focal_length

Controls the focal length of the camera, which is used for depth-of-field rendering.

Default: 40.0

property shadows

Enables cast shadows for the directional light source.

Default: True

class ovito.vis.TextLabelOverlay

Base: ovito.vis.ViewportOverlay

Displays a text label in a viewport and in rendered images. You can attach an instance of this class to a viewport by adding it to the viewport’s overlays collection:

from ovito.vis import TextLabelOverlay, Viewport
from ovito.qt_compat import QtCore

# Create the overlay:
overlay = TextLabelOverlay(
    text = 'Some text',
    alignment = QtCore.Qt.AlignmentFlag.AlignHCenter | QtCore.Qt.AlignmentFlag.AlignBottom,
    offset_y = 0.1,
    font_size = 0.03,
    text_color = (0,0,0))

# Attach the overlay to a newly created viewport:
viewport = Viewport(type = Viewport.Type.Top)
viewport.overlays.append(overlay)

Text labels can display dynamically computed values. See the text property for an example.

property alignment

Selects the corner of the viewport where the text is displayed (anchor position). This must be a valid Qt.AlignmentFlag value as shown in the example above.

Default: QtCore.Qt.AlignmentFlag.AlignLeft | QtCore.Qt.AlignmentFlag.AlignTop

property font

A string with comma-separated parameter values describing the font to be used for rendering the text labels of the viewport layer. The string must follow the specific form understood by the QFont.fromString() method, for example 'Arial,10,-1,5,75,0,0,0,0,0,Bold'.

Note that the font size parameter (10 in the example specification above) will be ignored by the viewport layer, because the size of text labels is already controlled by the font_size parameter.

property font_size

The font size, which is specified as a fraction of the output image height.

Default: 0.02

property format_string

The format string used with the sprintf() function to generate the text representation of global attributes (only floating-point values). You can change this format string to control the number of decimal places shown and switch between exponential and regular notation, for example.

Default: '%.6g'

property offset_x

This parameter allows to displace the label horizontally from its anchor position. The offset is specified as a fraction of the output image width.

Default: 0.0

property offset_y

This parameter allows to displace the label vertically from its anchor position. The offset is specified as a fraction of the output image height.

Default: 0.0

property outline_color

The text outline color. This is used only if outline_enabled is set.

Default: (1.0, 1.0, 1.0)

property outline_enabled

Enables the painting of a font outline to make the text easier to read.

Default: False

property source_pipeline: The Pipeline that is queried to obtain the attribute values referenced in the text string. See the text property for more information.

property text

The text string to be rendered.

The string can contain placeholder references to dynamically computed attributes of the form [attribute], which will be replaced by their actual value before rendering the text label. Attributes are taken from the pipeline output of the Pipeline assigned to the overlay’s source_pipeline property.

The following example demonstrates how to insert a text label that displays the number of currently selected particles:

from ovito.io import import_file
from ovito.vis import TextLabelOverlay, Viewport
from ovito.modifiers import ExpressionSelectionModifier

# Import a simulation dataset and select some atoms based on their potential energy:
pipeline = import_file("input/simulation.dump")
pipeline.add_to_scene()
pipeline.modifiers.append(ExpressionSelectionModifier(expression="peatom > -4.2"))

# Create the overlay. Note that the text string contains a reference
# to an output attribute of the ExpressionSelectionModifier.
overlay = TextLabelOverlay(text="Number of selected atoms: [ExpressionSelection.count]")
# Specify the source of dynamically computed attributes.
overlay.source_pipeline = pipeline

# Attach overlay to a newly created viewport:
viewport = Viewport(type=Viewport.Type.Top)
viewport.overlays.append(overlay)

You can embed HTML and CSS markup elements in the string to further control the formatting and styling of the text. Note that only a subset of the HTML standard is supported.

Default: "Text label"

property text_color

The text rendering color.

Default: (0.0, 0.0, 0.5)

class ovito.vis.TrajectoryVis

Base: ovito.vis.DataVis

Controls the visual appearance of particle trajectory lines. An instance of this class is attached to every TrajectoryLines data object.

You typically create trajectory lines by inserting the GenerateTrajectoryLinesModifier into a data pipeline. The modifier owns a TrajectoryVis element, which is used for visualizing the generated trajectory lines. You can access it through the modifier’s vis field.

property color

The uniform color to be used for rendering the trajectory lines. This parameter is ignored if pseudo-coloring of the lines has been activated by setting a color_mapping_property.

Default: (0.6, 0.6, 0.6)

property color_mapping_gradient

The color gradient used to map scalar property values from the selected color_mapping_property to corresponding RGB output values (also called color transfer function). See the ColorCodingModifier.gradient parameter for a list of available color gradient types.

Default: ColorCodingModifier.Rainbow()

property color_mapping_interval

Specifies the range of input values from the selected color_mapping_property getting mapped to corresponding RGB values by the selected color_mapping_gradient. The tuple defines the start and end of the linear interval that is translated to pseudo-colors by the color map. Input property values not within of the interval get mapped to the marginal colors of the selected color map.

Default: (0.0, 0.0)

property color_mapping_property

The name of the TrajectoryLines property to be used for pseudo-coloring the lines according to the scalar values of this property. If the Property consists of several vector components, then the name must be followed by a specific component name, e.g. 'Velocity.Z'.

Typically, this parameter should be set to the name of the particle property which was sampled during line tracing by the GenerateTrajectoryLinesModifier. See its sample_particle_property parameter for an example.

Numeric values from the selected source property are mapped to corresponding RGB values by first normalizing them according to the specified color_mapping_interval and then applying the selected color_mapping_gradient.

Note

If the TrajectoryLines object being rendered has a property named Color, then this explicit line coloring is used. No color mapping takes place in this case, and the color_mapping_property and color parameters of the visual element are ignored.

Default: ''

property shading

The shading style used for trajectory lines. Possible values:

TrajectoryVis.Shading.Normal

TrajectoryVis.Shading.Flat (default)

property upto_current_time

If True, trajectory lines are only rendered up to the particle positions at the current animation time. Otherwise, the complete trajectory lines are displayed.

Default: False

property width

The display width of trajectory lines.

Default: 0.2

property wrapped_lines

If True, the continuous trajectory lines will automatically be wrapped back into the simulation box during rendering. Thus, they will be shown as several discontinuous segments if they cross periodic boundaries of the simulation box.

Default: False

class ovito.vis.TriangleMeshVis

Base: ovito.vis.DataVis

Controls the visual appearance of a TriangleMesh. See also the corresponding user manual page for more information on this visual element.

property backface_culling

Controls whether triangle faces facing away from the viewer are not rendered.

Default: False

property color

The uniform RGB color of the triangle mesh, which is used for rendering if the mesh’s faces or vertices have no local colors associated with them. RGB color components must be in the range 0–1.

Default: (0.85, 0.85, 1.0)

property highlight_edges

Highlights the polygonal edges of the mesh by rendering a wireframe lines along those edges that have been marked as visible.

Default: False

property transparency

The degree of semi-transparency of the rendered mesh. Valid parameter range is 0.0 – 1.0.

Default: 0.0

class ovito.vis.VectorVis

Base: ovito.vis.DataVis

This kind of visual element renders arrow glyphs for visualizing vectorial data stored in a Property object. See also the corresponding user manual page for more information.

A vector property is any Property array with data type float and three components per element. The VectorVis element supports visualization of vector properties that are stored of the following PropertyContainer types: Particles, Bonds, SurfaceMesh.vertices, SurfaceMesh.faces, and VoxelGrid.

The standard particle properties Force, Displacement, Dipole, and Velocity already have an existing VectorVis element attached to them, which is disabled by default. You must enable it for the arrow glyphs to be displayed, e.g.:

pipeline = import_file('input/simulation.dump')
pipeline.add_to_scene()
vector_vis = pipeline.compute().particles.forces.vis
vector_vis.enabled = True  # This activates the display of arrow glyphs
vector_vis.color = (1,0,0)

In this example, the atomistic forces were loaded as particle property named Force from the imported simulation file, Parameters such as color, width, and flat_shading of the VectorVis element control the visual appearance of the arrow glyphs in rendered images.

Some modifiers in OVITO dynamically add new vector properties to particles. For instance, the CalculateDisplacementsModifier creates the Displacement property and automatically attaches a VectorVis element to it in case you want to visualize the displacements. The visual element is part of the modifier in this case:

modifier = CalculateDisplacementsModifier()
pipeline.modifiers.append(modifier)
modifier.vis.enabled = True  # This activates the display of displacement vectors
modifier.vis.flat_shading = False

If you are writing your own modifier function to compute a vector property, and you want to visualize that property using arrow glyphs, you need to construct a VectorVis element and attach it to the newly created Property object. For example:

def modify(frame, data, vector_vis=VectorVis(alignment=VectorVis.Alignment.Center, color=(1.0, 0.0, 0.4))):

    # Add a new vector property to the particles:
    vector_data = numpy.random.random_sample(size=(data.particles.count, 3))
    property = data.particles_.create_property('My Vector Property', data=vector_data)

    # Attach the visual element to the output property:
    property.vis = vector_vis  

Setting up the visual element as an additional parameter of the modify() function provides two advantages: Only a single instance is created, which survives multiple invocations of the modifier function, and OVITO Pro displays the element’s parameter panel in the UI.

property alignment

Controls the positioning of the arrows glyphs with respect to the base points, e.g., the particle positions. Possible values:

VectorVis.Alignment.Base (default)

VectorVis.Alignment.Center

VectorVis.Alignment.Head

property color

The uniform display color of arrow glyphs. This parameter is not used if pseudo-color mapping is enabled through the color_mapping_property option or when the Vector Color property was set for the particles.

Default: (1.0, 1.0, 0.0)

property color_mapping_gradient

The color gradient used to map scalar property values from the selected color_mapping_property to corresponding RGB output values (color transfer function). See the ColorCodingModifier.gradient parameter for a list of available color gradient types.

Default: ColorCodingModifier.Rainbow()

property color_mapping_interval

Specifies the range of input values from the selected color_mapping_property getting mapped to corresponding RGB values by the selected color_mapping_gradient. The tuple defines the start and end of the linear interval that is translated to pseudo-colors by the color map. Input property values not within of the interval get mapped to the marginal colors of the selected color map.

Default: (0.0, 0.0)

property color_mapping_property

The name of a scalar property to be used for coloring the vector glyphs. If the Property has several components, then the name must be followed by a component name, e.g. 'Displacement.Z'.

Numeric values from the selected source property are mapped to corresponding RGB values by first normalizing them according to the specified color_mapping_interval and then applying the selected color_mapping_gradient.

Note that, if a Particles object is being rendered that has a property named Vector Color, then these explicit per-particle colors will be used for rendering the vector glyphs. No color mapping takes place in this case and the color_mapping_property and color parameters of the visual element are ignored.

Default: ''

property flat_shading

Switches between a flat rendering style for the arrows and a three-dimensional representation.

Default: True

property offset

Additional offset by which all arrows are displaced. This can be used to move the arrows in front of or behind the particles and avoid occlusions.

Default: (0.0, 0.0, 0.0)

property reverse

Boolean flag which reverves the direction the arrow glyphs.

Default: False

property scaling

The uniform scaling factor applied to arrow glyphs.

Default: 1.0

property transparency

The level of semi-transparency for rendering the arrows. The valid parameter range is 0.0 – 1.0 (fully opaque to fully transparent).

Default: 0.0

property width

Controls the width of arrows (in simulation units of length).

Default: 0.5

class ovito.vis.Viewport

A viewport is a “window” to the three-dimensional scene, showing the scene from the point of view of a virtual camera.

The virtual camera’s position and orientation are given by the camera_pos and camera_dir properties. Additionally, the type field allows you to switch between perspective and parallel projection modes or reset the camera to one of the standard axis-aligned orientations (top, left, front, etc.). The zoom_all() method repositions the camera automatically such that the entire scene becomes fully visible within the viewport. See also the documentation of the Adjust View dialog of OVITO to learn more about these camera-related settings.

After the viewport’s virtual camera has been set up, you can render an image or movie using the render_image() and render_anim() methods. For example:

from ovito.io import import_file
from ovito.vis import Viewport, TachyonRenderer

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

vp = Viewport(type = Viewport.Type.Ortho, camera_dir = (2, 1, -1))
vp.zoom_all()
vp.render_image(filename='output/simulation.png', 
                size=(320, 240), 
                renderer=TachyonRenderer())

Furthermore, so-called overlays may be added to a viewport. Overlays are function objects that draw additional two-dimensional graphics or text on top of or behind the rendered scene, e.g. coordinate axes or a color legend. See the documentation of the overlays and underlays lists for more information.

property camera_dir: The viewing direction vector of the viewport’s camera.

property camera_pos: The position of the viewport’s camera in the three-dimensional scene.

property camera_up

Direction vector specifying which coordinate axis will point upward in rendered images. Set this parameter to a non-zero vector in order to rotate the camera around the viewing direction and align the vertical direction in rendered images with a different simulation coordinate axis. If set to (0,0,0), then the upward axis is determined by the current user settings set in OVITO’s application settings dialog (z-axis by default).

Default: (0.0, 0.0, 0.0)

create_jupyter_widget(antialiasing=True, picking=False, vr_scale=0.0, layout=ipywidgets.Layout(width='400px', height='200px')) → ipywidgets.DOMWidget

Creates an interactive widget for embedding in a Jupyter notebook, which displays the 3d scene as seen through this virtual viewport. The method returns an interactive notebook element, which accepts mouse inputs similar to the viewport windows of the OVITO desktop application. It may be necessary to call display in order to show the widget:

vp = Viewport(type=Viewport.Type.Perspective, camera_dir=(0.5, 1.0, -0.4))
vp.zoom_all()
widget = vp.create_jupyter_widget(picking=True)
display(widget)

The Jupyter widget returned by this method is permanently linked to this Viewport instance. Any changes you subsequently make to the non-visual Viewport, for example, setting its camera_pos or camera_dir, will be reflected by the visual viewport widget. Vice versa do all user interactions with the viewport widget update the corresponding fields of the Viewport object.

Important

This method requires the ipywidgets Python package. Please install this package in the Python interpreter used by your Jupyter environment.

Parameters

antialiasing (bool) – Enables multisample anti-aliasing to reduce jagged edges, which appear during WebGL rasterization.
picking (bool) – Enables object picking. When hovering the mouse cursor over an object, the widget will display the object’s properties as text.
vr_scale (float) – Enables VR support (WebXR browser interface) if set to a positive value. The parameter value specifies the ratio of 1 length unit of the simulation model and 1 meter in VR space. It thus controls the apparent size (scaling) of the model in virtual reality mode. For example, if object dimensions are specified in terms of nanometers in the simulation model, then a vr_scale value of 0.2 would let a 1 nanometer sphere appear 20 centimeters large in virtual reality space.
layout (ipywidgets.Layout) – The layout attribute for the new Jupyter widget.

Returns

ipywidgets.DOMWidget

The layout attribute lets you control the size of the widget, e.g.:

from ipywidgets import Layout
widget = vp.create_jupyter_widget(layout=Layout(width='100%', height='400px'))

Caution

This method is still under active development and not fully functional yet. Expect these (known) limitations:

Changes you make to the scene or the viewport camera do not automatically trigger a refresh of the viewport widget. You need to explicitly call widget.refresh() to update the widget display whenever you change the scene.

Semi-transparent objects will likely be rendered incorrectly.

Viewport layers are not supported yet.

These limitations will be resolved in a future update of the OVITO Python module. Please support the development of this new feature and report any issues you may encounter in our issue tracker or in the OVITO forum.

New in version 3.7.9.

create_qt_widget(parent=None)

Creates an interactive visual widget displaying the three-dimensional scene as seen through this virtual viewport. The method creates an interactive window accepting mouse inputs from the user similar to the viewport windows of the OVITO desktop application. You can use this method to develop custom user interfaces based on the Qt cross-platform framework that integrate OVITO’s functionality and display the output of a data pipeline.

Parameters: parent – An optional Qt widget that should serve as parent of the newly created viewport widget.
Returns: A new QWidget displaying the three-dimensional scene as seen through the virtual viewport.

The Qt widget returned by this method is linked to this Viewport instance. Any changes your Python script subsequently makes to the non-visual Viewport instance, for example setting camera_pos or camera_dir, will automatically be reflected by the visual viewport widget. Vice versa will interactions of the user with the viewport widget automatically lead to changes of the corresponding fields of the Viewport instance.

The following short example program demonstrates the use of the create_qt_widget() method. Please see the Qt for Python documentation for more information on how to create graphical user interfaces using the Qt framework.

ovito.vis

`ovito.vis`