ovito.vis

This module contains classes related to data visualization and rendering.

Rendering:

Render engines:

Data visualization:

Viewport overlays:

class ovito.vis.BondsDisplay
Base class:ovito.vis.Display

Controls the visual appearance of particle bonds. An instance of this class is attached to every Bonds data object.

color

The display color of bonds. Used only if use_particle_colors == False.

Default:(0.6, 0.6, 0.6)
shading

The shading style used for bonds. Possible values:

  • BondsDisplay.Shading.Normal (default)
  • BondsDisplay.Shading.Flat
use_particle_colors

If True, bonds are assigned the same color as the particles they are adjacent to.

Default:True
width

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

Default:0.4
class ovito.vis.CoordinateTripodOverlay

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

import ovito
from ovito.vis import CoordinateTripodOverlay

# Create an overlay.
tripod = CoordinateTripodOverlay()
tripod.size = 0.07

# Attach overlay to the active viewport.
viewport = ovito.dataset.viewports.active_vp
viewport.overlays.append(tripod)

Note

Some properties of this class interface have not been exposed and are not accessible from Python yet. Please let the developer know if you would like them to be added.

alignment

Selects the corner of the viewport where the tripod is displayed. This must be a valid Qt::Alignment value.

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
line_width

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

Default:0.06
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
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
size

The scaling factor that controls the size of the tripod. The size is specified as a fraction of the output image height.

Default:0.075
class ovito.vis.DislocationDisplay
Base class:ovito.vis.Display

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

burgers_vector_color

The color of Burgers vector arrows.

Default:(0.7, 0.7, 0.7)
burgers_vector_width

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

Default:1.0
shading

The shading style used for the lines. Possible values:

  • DislocationDisplay.Shading.Normal (default)
  • DislocationDisplay.Shading.Flat
show_burgers_vectors

Boolean flag that enables the display of Burgers vector arrows.

Default:False
show_line_directions

Boolean flag that enables the visualization of line directions.

Default:False
class ovito.vis.Display

Abstract base class for display setting objects that control the visual appearance of data. DataObjects may be associated with an instance of this class, which can be accessed via their display 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
class ovito.vis.OpenGLRenderer

The standard OpenGL-based renderer.

This is the default built-in rendering engine that is also used by OVITO to render the contents of the interactive viewports. Since it accelerates the generation of images by using the computer’s graphics hardware, it is very fast.

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.ParticleDisplay
Base class:ovito.vis.Display

Controls the visual appearance of particles.

radius

The default display radius of particles. This setting only takes effect if no per-particle or per-type radii are defined.

Default:1.2
shape

The display shape of particles. Possible values:

  • ParticleDisplay.Shape.Sphere (default)
  • ParticleDisplay.Shape.Box
  • ParticleDisplay.Shape.Circle
  • ParticleDisplay.Shape.Square
  • ParticleDisplay.Shape.Cylinder
  • ParticleDisplay.Shape.Spherocylinder
class ovito.vis.PythonViewportOverlay

This overlay type can be attached to a viewport to run a Python script every time an image of the viewport is rendered. The Python script can execute arbitrary drawing commands to paint on top of the rendered image.

Note that an alternative to using the PythonViewportOverlay class is to directly manipulate the static image returned by the Viewport.render() method before saving it to disk.

You can attach a Python overlay to a viewport by adding an instance of this class to the viewport’s overlays collection:

import ovito
from ovito.vis import PythonViewportOverlay

# Define a function that paints on top of the rendered image.
def render_overlay(painter, **args):
    painter.drawText(10, 10, "Hello world")

# Create the overlay.
overlay = PythonViewportOverlay(function = render_overlay)

# Attach overlay to the active viewport.
viewport = ovito.dataset.viewports.active_vp
viewport.overlays.append(overlay)
function

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

The function must have a signature as shown in the example above. The painter parameter passed to the user-defined function contains a QPainter object, which provides painting methods to draw arbitrary 2D graphics on top of the image rendered by OVITO.

Additional keyword arguments are passed to the function in the args dictionary. The following keys are defined:

  • viewport: The Viewport being rendered.
  • render_settings: The active RenderSettings.
  • is_perspective: Flag indicating whether projection is perspective or parallel.
  • fov: The field of view.
  • view_tm: The camera transformation matrix.
  • proj_tm: The projection matrix.

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

Default:None
output

The output text generated when compiling/running the Python function. Contain the error message when the most recent execution of the custom rendering function failed.

script

The source code of the user-defined Python script that defines the render() function. Note that this property returns the source code entered by the user through the graphical user interface, not the callable Python function.

If you want to set the render function from an already running Python script, you should set the function property instead as demonstrated in the example above.

class ovito.vis.RenderSettings

Stores settings and parameters for rendering images and movies.

A instance of this class can be passed to the render() function of the Viewport class to control various aspects such as the resolution of the generated image. The RenderSettings object contains a renderer, which is the rendering engine that will be used to generate images of the three-dimensional scene. OVITO comes with two different rendering engines:

  • OpenGLRenderer – An OpenGL-based renderer, which is also used for the interactive display in OVITO’s viewports.
  • TachyonRenderer – A software-based, high-quality raytracing renderer.

Usage example:

rs = RenderSettings(
    filename = 'image.png',
    size = (1024,768),
    background_color = (0.8,0.8,1.0)
)
rs.renderer.antialiasing = False
dataset.viewports.active_vp.render(rs)
background_color

Controls the background color of the rendered image.

Default:(1,1,1) – white
custom_range

Specifies the range of animation frames to render if range is CUSTOM_INTERVAL.

Default:(0,100)
filename

A string specifying the file path under which the rendered image or movie should be saved.

Default:None
generate_alpha

When saving the generated image to a file format that can store transparency information (e.g. PNG), this option will make those parts of the output image transparent that are not covered by an object.

Default:False
range

Selects the animation frames to be rendered.

Possible values:
  • RenderSettings.Range.CURRENT_FRAME (default): Renders a single image at the current animation time.
  • RenderSettings.Range.ANIMATION: Renders a movie of the entire animation sequence.
  • RenderSettings.Range.CUSTOM_INTERVAL: Renders a movie of the animation interval given by the custom_range attribute.
renderer

The renderer that is used to generate the image or movie. Depending on the selected renderer you can use this to set additional parameters such as the anti-aliasing level.

See the OpenGLRenderer and TachyonRenderer classes for a list of renderer-specific parameters.

size

The size of the image or movie to be generated in pixels.

Default:(640,480)
skip_existing_images

Controls whether animation frames for which the output image file already exists will be skipped when rendering an animation sequence. This flag is ignored when directly rendering to a movie file and not an image file sequence. Use this flag when the image sequence has already been partially rendered and you want to render just the missing frames.

Default:False
class ovito.vis.SimulationCellDisplay
Base class:ovito.vis.Display

Controls the visual appearance of SimulationCellObject data objects.

line_width

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

Default:0.14% of the simulation box diameter
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
rendering_color

The line color used when rendering the cell.

Default:(0, 0, 0)
class ovito.vis.SurfaceMeshDisplay
Base class:ovito.vis.Display

Controls the visual appearance of a surface mesh computed by the ConstructSurfaceModifier.

cap_color

The display color of the cap polygons at periodic boundaries.

Default:(0.8, 0.8, 1.0)
cap_transparency

The level of transparency of the displayed cap polygons. Valid range is 0.0 – 1.0.

Default:0.0
show_cap

Controls the visibility of cap polygons, which are created at the intersection of the surface mesh with periodic box boundaries.

Default:True
smooth_shading

Enables smooth shading of the triangulated surface mesh.

Default:True
surface_color

The display color of the surface mesh.

Default:(1.0, 1.0, 1.0)
surface_transparency

The level of transparency of the displayed surface. Valid range is 0.0 – 1.0.

Default:0.0
class ovito.vis.TachyonRenderer

This is the software-based raytracing renderer of OVITO.

It can render scenes with ambient occlusion lighting and semi-transparent objects.

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

ambient_occlusion_brightness

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

Default: 0.8

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

antialiasing

Enables supersampling to reduce aliasing effects.

Default: True

antialiasing_samples

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

Default: 12

direct_light

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

Default: True

direct_light_intensity

Controls the brightness of the directional light source.

Default: 0.9

shadows

Enables cast shadows for the directional light source.

Default: True

class ovito.vis.VectorDisplay
Base class:ovito.vis.Display

Controls the visual appearance of vectors (arrows).

alignment

Controls the positioning of arrows with respect to the particles. Possible values:

  • VectorDisplay.Alignment.Base (default)
  • VectorDisplay.Alignment.Center
  • VectorDisplay.Alignment.Head
color

The display color of arrows.

Default:(1.0, 1.0, 0.0)
reverse

Boolean flag controlling the reversal of arrow directions.

Default:False
scaling

The uniform scaling factor applied to vectors.

Default:1.0
shading

The shading style used for the arrows. Possible values:

  • VectorDisplay.Shading.Normal (default)
  • VectorDisplay.Shading.Flat
width

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

Default:0.5
class ovito.vis.Viewport

A viewport defines the view on the three-dimensional scene.

You can create an instance of this class to define a camera position from which a picture of the three-dimensional scene should be generated. After the camera has been set up, you can render an image or movie using the viewport’s render() method:

vp = Viewport()
vp.type = Viewport.Type.PERSPECTIVE
vp.camera_pos = (100, 50, 50)
vp.camera_dir = (-100, -50, -50)

rs = RenderSettings(size=(800,600), filename="image.png")
vp.render(rs)

Note that the four interactive viewports in OVITO’s main window are instances of this class. If you want to manipulate these existing viewports, you can access them through the DataSet.viewports attribute.

camera_dir

The viewing direction vector of the viewport’s camera. This can be an arbitrary vector with non-zero length.

camera_pos

The position of the viewport’s camera. For example, to move the camera of the active viewport in OVITO’s main window to a new location in space:

dataset.viewports.active_vp.camera_pos = (100, 80, -30)
fov

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

overlays

A list-like sequence of viewport overlay objects that are attached to this viewport. See the CoordinateTripodOverlay and PythonViewportOverlay classes for more information.

render(settings=None)

Renders an image or movie of the viewport’s view.

Parameters:settings (RenderSettings) – A settings object, which specifies the resolution, background color, output filename etc. of the image to be rendered. If None, the global settings are used (given by DataSet.render_settings).
Returns:A QImage object on success, which contains the rendered picture; None if the rendering operation has been canceled by the user.

The rendered image of movie will automatically be saved to disk when the RenderSettings.filename attribute has been set to a non-empty string. Alternatively, the returned QImage object can be saved explicitly from the script. You may even paint additional graphics on top of the image before saving it. For example:

from ovito import *
from ovito.vis import RenderSettings
from PyQt5.QtGui import QPainter

# Let OVITO render an image of the active viewport.
vp = dataset.viewports.active_vp
rs = RenderSettings(size = (320,240))
image = vp.render(rs)

# Paint something on top of the rendered image.
painter = QPainter(image)
painter.drawText(10, 20, "Hello world!")
del painter

# Save image to disk.
image.save("image.png")
title

The title string of the viewport shown in its top left corner (read-only).

type

The type of projection:

  • Viewport.Type.PERSPECTIVE
  • Viewport.Type.ORTHO
  • Viewport.Type.TOP
  • Viewport.Type.BOTTOM
  • Viewport.Type.FRONT
  • Viewport.Type.BACK
  • Viewport.Type.LEFT
  • Viewport.Type.RIGHT
  • Viewport.Type.NONE

The first two types (PERSPECTIVE and ORTHO) allow you to set up custom views with arbitrary camera orientation.

zoom_all()

Repositions the viewport camera such that all objects in the scene become completely visible. The camera direction is not changed.

class ovito.vis.ViewportConfiguration

Manages the viewports in OVITO’s main window.

This list-like object can be accessed through the viewports attribute of the DataSet class. It contains all viewports in OVITO’s main window:

for viewport in dataset.viewports:
    print(viewport.title)

By default OVITO creates four predefined Viewport instances. Note that in the current program version it is not possible to add or remove viewports from the main window. The ViewportConfiguration object also manages the active and the maximized viewport.

active_vp

The viewport that is currently active. It is marked with a colored border in OVITO’s main window.

maximized_vp

The viewport that is currently maximized; or None if no viewport is maximized. Assign a viewport to this attribute to maximize it, e.g.:

dataset.viewports.maximized_vp = dataset.viewports.active_vp