ovito.vis

This module contains classes related to data visualization and rendering.

Rendering:

Rendering engines:

Data visualization elements:

Viewport overlays:

class ovito.vis.Viewport

A viewport represents a virtual “window” to the three-dimensional scene, showing the objects in the scene from a certain view point, which is determined by the viewport’s camera.

The virtual camera’s position and orientation are controlled by the camera_pos and camera_dir fields. 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 that are also found in the graphical version of OVITO. The zoom_all() method repositions the camera automatically such that the entire scene becomes fully visible within the view.

After the viewport 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 assigned to a viewport. Overlays are function objects that paint additional two-dimensional content on top of the rendered scene, e.g. a coordinate axis tripod or a color legend. See the documentation of the overlays property for more information.

camera_dir

The viewing direction vector of the viewport’s camera.

camera_pos

The position of the viewport’s camera in the three-dimensional scene.

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 of viewport overlay objects that are attached to this viewport. Overlays render graphical content on top of the three-dimensional scene. See the following classes for more information:

To attach a new overlay to the viewport, use the append() method:

from ovito.vis import Viewport, CoordinateTripodOverlay

vp = Viewport(type = Viewport.Type.Ortho)
tripod = CoordinateTripodOverlay(size = 0.07)
vp.overlays.append(tripod)
render_anim(filename, size=(640, 480), fps=10, background=(1, 1, 1), renderer=None, range=None, every_nth=1)

Renders an animation sequence.

Parameters:
  • filename (str) – The filename under which the rendered animation should be saved. Supported video formats are: .avi, .mp4, .mov and .gif. Alternatively, an image format may be specified (.png, .jpeg). In this case, a series of image files will be produced, one for each frame, which may be combined into an animation using an external video encoding tool of your choice.
  • size – The resolution of the movie in pixels.
  • fps – The number of frames per second of the encoded movie. This determines the playback speed of the animation.
  • background – An RGB triplet in the range [0,1] specifying the background color of the rendered movie.
  • renderer – The rendering engine to use. If none is specified, either OpenGL or Tachyon are used, depending on the availablity of OpenGL in the script execution context.
  • range – The interval of frames to render, specified in the form (from,to). Frame numbering starts at 0. If no interval is specified, the entire animation is rendered, i.e. frame 0 through (FileSource.num_frames-1).
  • every_nth – Frame skipping interval in case you don’t want to render every frame of a very long animation.
Returns:

True if successful; False if operation was canceled by the user.

See also the render_image() method for a more detailed discussion of some of these parameters.

render_image(size=(640, 480), frame=0, filename=None, background=(1, 1, 1), alpha=False, renderer=None)

Renders an image of the viewport’s view.

Parameters:
  • size – A pair of integers specifying the horizontal and vertical dimensions of the output image in pixels.
  • frame (int) – The animation frame to render. Numbering starts at 0. See the FileSource.num_frames property for the number of loaded animation frames.
  • filename (str) – The filename under which the rendered image should be saved (optional). Supported output formats are: .png, .jpeg and .tiff.
  • background – A triplet of RGB values in the range [0,1] specifying the background color of the rendered image.
  • alpha – If true, the background is made transparent so that the rendered image may later be superimposed on a different backdrop. When using this option, make sure to save the image in the PNG format in order to preserve the transparency information.
  • renderer – The rendering engine to use. If none is specified, either OpenGL or Tachyon are used, depending on the availablity of OpenGL in the script execution context.
Returns:

A QImage object containing the rendered picture; or None if the rendering operation has been canceled by the user.

Populating the scene

Before rendering an image using this method, you should make sure the three-dimensional contains some visible objects. Typically this involves calling the Pipeline.add_to_scene() method on a pipeline to insert its output data into the scene:

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

Selecting the rendering engine

OVITO supports several different rendering backends for producing pictures of the three-dimensional scene:

Each of these backends exhibits specific parameters that control the image quality and other aspect of the image generation process. Typically, you would create an instance of one of these renderer classes, configure it and pass it to the render_image() method:

vp.render_image(filename='output/simulation.png', 
                size=(320,240),
                background=(0,0,0), 
                renderer=TachyonRenderer(ambient_occlusion=False, shadows=False))

Note that the OpenGLRenderer backend may not be available when you are executing the script in a headless environment, e.g. on a remote HPC cluster without X display and OpenGL support.

Post-processing images

If the filename parameter is left unspecified, the method does not save the rendered image to disk. This gives you the opportunity to paint additional graphics on top before saving the QImage using its save() method:

from ovito.vis import Viewport, TachyonRenderer
from PyQt5.QtGui import QPainter

# Render an image of the three-dimensional scene:
vp = Viewport(type=Viewport.Type.Ortho, camera_dir=(2, 1, -1))
vp.zoom_all()
image = vp.render_image(size=(320,240), renderer=TachyonRenderer())

# Paint on top of the rendered image using Qt's drawing functions:
painter = QPainter(image)
painter.drawText(10, 20, "Hello world!")
del painter

# Save image to disk:
image.save("output/image.png")

As an alternative to the direct method demonstrated above, you can also make use of a PythonViewportOverlay to paint custom graphics on top of rendered images.

type

Specifies the projection type of the viewport. The following standard modes are available:

  • Viewport.Type.Perspective
  • Viewport.Type.Ortho
  • Viewport.Type.Top
  • Viewport.Type.Bottom
  • Viewport.Type.Front
  • Viewport.Type.Back
  • Viewport.Type.Left
  • Viewport.Type.Right

The first two types (Perspective and Ortho) allow you to set up custom views with arbitrary camera orientations.

zoom_all()

Repositions the viewport camera such that all objects in the scene become completely visible. The camera direction is maintained by the method.

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. See the OVITO user documentation for more information on this rendering engine.

Note that this renderer requires OpenGL graphics support, and Python scripts may be running in environments where it is not available. A typical example for such situations are remote SSH connections, which can prevent OVITO from accessing the X window and OpenGL systems. In this case, the OpenGL renderer will refuse to work and you have to use one of the software-based rendering engines instead. See the Viewport.render_image() method.

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

Abstract base class for visualization elements that are reponsible 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.

Visual elements produced by a data pipeline can be accessed using the Pipeline.get_vis() method.

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

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

# Create the overlay.
tripod = CoordinateTripodOverlay()
tripod.size = 0.07
tripod.alignment = QtCore.Qt.AlignRight ^ QtCore.Qt.AlignBottom

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

Selects the corner of the viewport where the tripod is displayed. This must be a valid Qt.Alignment value value as shown in the example above.

Default:PyQt5.QtCore.Qt.AlignLeft ^ PyQt5.QtCore.Qt.AlignBottom
axis1_color

RGB display color of the first axis.

Default:(1.0, 0.0, 0.0)
axis1_dir

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

Default:(1,0,0)
axis1_enabled

Enables the display of the first axis.

Default:True
axis1_label

Text label for the first axis.

Default:“x”
axis2_color

RGB display color of the second axis.

Default:(0.0, 0.8, 0.0)
axis2_dir

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

Default:(0,1,0)
axis2_enabled

Enables the display of the second axis.

Default:True
axis2_label

Text label for the second axis.

Default:“y”
axis3_color

RGB display color of the third axis.

Default:(0.2, 0.2, 1.0)
axis3_dir

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

Default:(0,0,1)
axis3_enabled

Enables the display of the third axis.

Default:True
axis3_label

Text label for the third axis.

Default:“z”
axis4_color

RGB display color of the fourth axis.

Default:(1.0, 0.0, 1.0)
axis4_dir

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

Default:(0.7071, 0.7071, 0.0)
axis4_enabled

Enables the display of the fourth axis.

Default:False
axis4_label

Label for the fourth axis.

Default:“w”
behind_scene

This option puts the overlay behind the three-dimensional scene, i.e. as an “underlay” instead of an “overlay”. If set to to true, objects in the scene will occclude the overlay content.

Default:False
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

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

Default:0.075
class ovito.vis.PythonViewportOverlay

This type of viewport overlay runs a custom Python script function every time an image of the viewport is being 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):
    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 is the type of data structure passed by the system to the user-defined render() function of the viewport overlay. It holds various context information about the frame being rendered and provides utility methods for projecting points from 3d to 2d space.

dataset

The current DataSet, which provides access to the data pipelines in the scene being rendered.

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

frame

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

is_perspective

Flag indicating whether the viewport uses a perspective projection or parallel projection.

painter

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

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.

size

A tuple with the width and height of the image being rendered in pixels.

view_tm

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

viewport

The Viewport being rendered.

behind_scene

This option puts the overlay behind the three-dimensional scene, i.e. making it an “underlay” instead of an “overlay”. If set to to true, three-dimensional objects in the scene will occclude the graphics rendered by the overlay.

Default:False
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.TextLabelOverlay

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 PyQt5 import QtCore

# Create the overlay:
overlay = TextLabelOverlay(
    text = 'Some text', 
    alignment = QtCore.Qt.AlignHCenter ^ QtCore.Qt.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.

alignment

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

Default:PyQt5.QtCore.Qt.AlignLeft ^ PyQt5.QtCore.Qt.AlignTop
behind_scene

This option puts the overlay behind the three-dimensional scene, i.e. as an “underlay” instead of an “overlay”. If set to to true, objects in the scene will occclude the overlay content.

Default:False
font_size

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

Default:0.02
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
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
outline_color

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

Default:(1.0,1.0,1.0)
outline_enabled

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

Default:False
source_pipeline

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

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: [SelectExpression.num_selected]')
# 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)
Default:“Text label”
text_color

The text rendering color.

Default:(0.0,0.0,0.5)
class ovito.vis.SimulationCellVis
Base class: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.

The following example script demonstrates how to change the line width of the simulation cell:

from ovito.io import import_file
from ovito.vis import SimulationCellVis

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

cell_vis = pipeline.get_vis(SimulationCellVis)
cell_vis.line_width = 1.3
cell_vis.rendering_color = (0.0, 0.0, 0.8)
line_width

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

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.SurfaceMeshVis
Base class:ovito.vis.DataVis

Controls the visual appearance of a SurfaceMesh object, which is typically generated by modifiers such as ConstructSurfaceModifier or CreateIsosurfaceModifier.

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
reverse_orientation

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

Default:False
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.DislocationVis
Base class: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.

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
indicate_character

Controls how the display color of dislocation lines is chosen.Possible values:

  • DislocationVis.ColoringMode.ByDislocationType (default)
  • DislocationVis.ColoringMode.ByBurgersVector
  • DislocationVis.ColoringMode.ByCharacter
line_width

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

Default:1.0
shading

The shading style used for the lines. Possible values:

  • DislocationVis.Shading.Normal (default)
  • DislocationVis.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.OSPRayRenderer

This is one of the software-based rendering backends of OVITO. OSPRay 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.

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 OVITO user documentation for more information on this rendering engine.

ambient_brightness

Controls the radiance of the ambient light.

Default:0.8
ambient_light_enabled

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

Default:True
aperture

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

Default:0.5
default_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 will result in soft shadows when the rendering backend uses stochastic sampling (which is only the case for the Path Tracer backend).

Default:0.0
default_light_intensity

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

Default:3.0
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 default_light_intensity parameter.

Default:True
dof_enabled

Enables the depth-of-field effect. Only objects exactly at the distance from the camera specified by the focal_length will appear sharp when depth-of-field rendering is active. Objects closer to or further from the camera will appear blurred.

Default:False
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
material_shininess

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

Default:10.0
material_specular_brightness

Controls the specular reflectivity of the default material.

Default:0.05
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:20
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:8
samples_per_pixel

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

Default:4
class ovito.vis.ParticlesVis
Base class:ovito.vis.DataVis

This element controls the visual appearance of particles.

An instance of this class is attached to the ParticleProperty named Position and can be accessed through its vis field:

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

pipeline = import_file("input/simulation.dump")
pipeline.add_to_scene()
vis = pipeline.get_vis(ParticlesVis)
vis.shape = ParticlesVis.Shape.Square
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 ovito.data.ParticleType.radius. An individual display radius can be assigned to particles by creating a Radius ParticleProperty, e.g. using the ComputePropertyModifier.

Default:1.2
shape

The display shape of particles. Possible values are:

  • ParticlesVis.Shape.Sphere (default)
  • ParticlesVis.Shape.Box
  • ParticlesVis.Shape.Circle
  • ParticlesVis.Shape.Square
  • ParticlesVis.Shape.Cylinder
  • ParticlesVis.Shape.Spherocylinder
class ovito.vis.VectorVis
Base class:ovito.vis.DataVis

Controls the visual appearance of vector arrow elements.

A VectorVis element is typically attached to a ParticleProperty that represents a three-dimensional vector quantity, for example the Displacement property or the Force property.

The parameters of this class control the visual appearance of the arrow elements that are rendered at each particle to visualize the vector values. If you have imported a vector particle property named either Force, Dipole or Displacement from a simulation file, you can subsequently access the attached VectorVis object through the property’s vis field:

pipeline = import_file('input/simulation.dump')
pipeline.add_to_scene()
vector_vis = pipeline.get_vis(VectorVis)
vector_vis.color = (1,0,0)

Modifiers that output vector particle properties, e.g. the CalculateDisplacementsModifier, typically manage their own VectorVis element, which can be accessed directly:

modifier = CalculateDisplacementsModifier()
pipeline.modifiers.append(modifier)
modifier.vis.enabled = True
modifier.vis.shading = VectorVis.Shading.Flat
alignment

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

  • VectorVis.Alignment.Base (default)
  • VectorVis.Alignment.Center
  • VectorVis.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:

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

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

Default:0.5
class ovito.vis.BondsVis
Base class:ovito.vis.DataVis

A visualization element for rendering bonds between particles. An instance of this class is attached to the BondProperty named Topology.

The parameters of this class control the visual appearance of bonds. If you have imported a simulation file containing bonds, you can subsequently access the BondsVis object attached to the Topology bond property through its vis field:

pipeline = import_file('input/bonds.data.gz', atom_style='bond')
bonds_vis = pipeline.get_vis(BondsVis)
bonds_vis.width = 0.4

If you are creating bonds within OVITO using a modifier, such as the CreateBondsModifier, the BondsVis element is typically managed by the modifier:

modifier = CreateBondsModifier(cutoff = 2.8)
modifier.vis.shading = BondsVis.Shading.Flat
pipeline.modifiers.append(modifier)
color

The uniform display color of bonds. This value is only used if use_particle_colors is false and if the Color BondProperty is not defined.

Default:(0.6, 0.6, 0.6)
shading

Controls the shading style of bonds. Possible values:

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

If set to True, bonds are rendered in the same color as the particles they are incident to. Otherwise, a uniform color is used. If the BondProperty named Color is defined, then the per-bond colors are used in any case.

Default:True
width

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

Default:0.4
class ovito.vis.TrajectoryVis
Base class:ovito.vis.DataVis

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

color

The display color of trajectory lines.

Default:(0.6, 0.6, 0.6)
shading

The shading style used for trajectory lines. Possible values:

  • TrajectoryVis.Shading.Normal
  • TrajectoryVis.Shading.Flat (default)
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
width

The display width of trajectory lines.

Default:0.2
class ovito.vis.POVRayRenderer

This is one of the rendering backends of OVITO.

POV-Ray (The Persistence of Vision Raytracer) is an open-source raytracing program. The POV-Ray rendering backend streams the scene data to a temporary file, which is then processed and rendered by the external POV-Ray program. The final rendered image is read back into OVITO.

The rendering backend requires the POV-Ray executable to be installed on the system. It will automatically look for the executable povray in the system path. If the executable is not in the default search path, its location must be explicitly specified by setting the povray_executable attribute.

For a more detailed description of the rendering parameters exposed by this Python class, please consult the official POV-Ray documentation.

antialiasing

Enables supersampling to reduce aliasing effects.

Default:True
aperture

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

Default:1.0
blur_samples

Controls the maximum number of rays to use for each pixel to compute focus blur (depth-of-field).

Default:1.0
depth_of_field

This flag enables focus blur (depth-of-field) rendering.

Default:False
focal_length

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

Default:40.0
interpupillary_distance

Controls interpupillary distance (eye separation) for stereoscopic rendering. This setting is only used if the omni_stereo option has been set.

Default:0.5
omni_stereo

This flag enables omni­directional stereo projection for stereoscopic 360-degree VR videos and images. Note that this requires POV-Ray 3.7.1 or newer. The eye separation distance is controlled by the interpupillary_distance parameter.

Default:False
povray_executable

The absolute path to the external POV-Ray executable on the local computer, which is called by this rendering backend to render an image. If no path is set, OVITO will look for povray in the default executable search path.

Default:""
quality_level

The image rendering quality parameter passed to POV-Ray.

Default:9
radiosity

Enables radiosity light calculations.

Default:False
radiosity_raycount

The number of rays that are sent out whenever a new radiosity value has to be calculated.

Default:50
show_window

Controls whether the POV-Ray window is shown during rendering. This allows you to follow the image generation process.

Default:True
class ovito.vis.ColorLegendOverlay

Renders a color legend for a ColorCodingModifier on top of the three-dimensional scene. You can attach an instance of this class to a Viewport by adding it to the viewport’s overlays collection:

from ovito.io import import_file
from ovito.vis import ColorLegendOverlay, Viewport
from ovito.modifiers import ColorCodingModifier
from PyQt5.QtCore import Qt

# Prepare a data pipeline containing a ColorCodingModifier:
pipeline = import_file("input/simulation.dump")
color_mod = ColorCodingModifier(particle_property = 'peatom')
pipeline.modifiers.append(color_mod)
pipeline.add_to_scene()

# Configure the viewport overlay and link it to the ColorCodingModifier:
overlay = ColorLegendOverlay(
    modifier = color_mod,
    title = 'Potential energy per atom:', 
    alignment = Qt.AlignLeft ^ Qt.AlignTop,
    orientation = Qt.Vertical,
    offset_y = -0.04,
    font_size = 0.12,
    format_string = '%.2f eV')

# Attach the overlay to a Viewport that is going to be used for rendering:
viewport = Viewport(type = Viewport.Type.Top)
viewport.overlays.append(overlay)
alignment

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

Default:PyQt5.QtCore.Qt.AlignHCenter ^ PyQt5.QtCore.Qt.AlignBottom
aspect_ratio

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

Default:8.0
behind_scene

This option puts the overlay behind the three-dimensional scene, i.e. as an “underlay” instead of an “overlay”. If set to to true, objects in the scene will occclude the overlay content.

Default:False
font_size

The relative size of the font used for text labels.

Default:0.1
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 decimal places or add units to the numeric values, for example.

Default:‘%g’
label1

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

Default:‘’
label2

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

Default:‘’
legend_size

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

Default:0.3
modifier

The ColorCodingModifier for which the color legend should be rendered.

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

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

Default:PyQt5.QtCore.Qt.Horizontal
outline_color

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

Default:(1.0,1.0,1.0)
outline_enabled

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

Default:False
text_color

The RGB color used for text labels.

Default:(0.0,0.0,0.0)
title

The text displayed next to the color bar. If empty, the name of the input property selected in the ColorCodingModifier is used.

Default:‘’
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 OVITO user documentation for more information on this rendering engine.

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
aperture

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

Default:0.01
depth_of_field

This flag enables depth-of-field rendering.

Default:False
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
focal_length

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

Default:40.0
shadows

Enables cast shadows for the directional light source.

Default:True