ovito.vis
¶
This module contains classes related to data visualization and rendering.
Rendering:
Render engines:
Data visualization:
Display
(base class of all display classes below)BondsDisplay
DislocationDisplay
ParticleDisplay
SimulationCellDisplay
SurfaceMeshDisplay
VectorDisplay
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 from PyQt5 import QtCore # Create an overlay. tripod = CoordinateTripodOverlay() tripod.size = 0.07 tripod.alignment = QtCore.Qt.AlignRight ^ QtCore.Qt.AlignBottom # 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 value as shown in the example above.
Default: PyQt5.QtCore.Qt.AlignLeft ^ PyQt5.QtCore.Qt.AlignBottom
-
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 everyDislocationNetwork
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:
DislocationDisplay.ColoringMode.ByDislocationType
(default)DislocationDisplay.ColoringMode.ByBurgersVector
DislocationDisplay.ColoringMode.ByCharacter
-
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 theirdisplay
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.
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 thepovray_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
-
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.
ParticleDisplay
¶ Base class: ovito.vis.Display
This object controls the visual appearance of particles.
An instance of this class is attached to the
Position
ParticleProperty
and can be accessed via itsdisplay
property.For example, the following script demonstrates how to change the display shape of particles to a square:
from ovito.io import import_file from ovito.vis import ParticleDisplay node = import_file("simulation.dump") node.add_to_scene() particle_display = node.source.particle_properties.position.display particle_display.shape = ParticleDisplay.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 aRadius
ParticleProperty
, e.g. using theComputePropertyModifier
.Default: 1.2
-
shape
¶ The display shape of particles. Possible values are:
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 theViewport.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
: TheViewport
being rendered.render_settings
: The activeRenderSettings
.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 theViewport
class to control various aspects such as the resolution of the generated image. TheRenderSettings
object contains arenderer
, 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.POVRayRenderer
– A rendering backend that invokes the external POV-Ray raytracing program.
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
isCUSTOM_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 thecustom_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
,TachyonRenderer
andPOVRayRenderer
classes for the list of parameters specific to each rendering backend.
-
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
SimulationCell
objects.The following script demonstrates how to change the line width of the simulation cell:from ovito.io import import_file node = import_file("simulation.dump") node.add_to_scene() node.source.cell.display.line_width = 1.3
-
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.
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
-
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.
TachyonRenderer
¶ This is one of the software-based rendering backends of OVITO. Tachyon is an open-source raytracing engine integrated into OVITO.
It can render scenes with ambient occlusion lighting, semi-transparent objects, and depth-of-field focal blur.
-
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
-
-
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:import ovito from ovito.vis import TextLabelOverlay from PyQt5 import QtCore # Create an 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 overlay to the active viewport. viewport = ovito.dataset.viewports.active_vp 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. This must be a valid Qt.Alignment value as shown in the example above.
Default: PyQt5.QtCore.Qt.AlignLeft ^ PyQt5.QtCore.Qt.AlignTop
-
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. 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. The offset is specified as a fraction of the output image height.
Default: 0.0
-
outline_color
¶ The text outline color. This is only used 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_node
¶ The
ObjectNode
whose modification pipeline is queried for dynamic attributes that can be referenced in the text string. See thetext
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 theObjectNode
assigned to the overlay’ssource_node
property.The following example demonstrates how to insert a text label that displays the number of currently selected particles:
import ovito from ovito.io import import_file from ovito.vis import TextLabelOverlay from ovito.modifiers import SelectExpressionModifier # Import a simulation dataset and select some atoms based on their potential energy: node = import_file("simulation.dump") node.add_to_scene() node.modifiers.append(SelectExpressionModifier(expression = 'peatom > -4.2')) # Create the overlay. Note that the text string contains a reference # to an output attribute of the SelectExpressionModifier. overlay = TextLabelOverlay(text = 'Number selected atoms: [SelectExpression.num_selected]') # Specify source of dynamically computed attributes. overlay.source_node = node # Attach overlay to the active viewport. viewport = ovito.dataset.viewports.active_vp viewport.overlays.append(overlay)
Default: “Text label”
-
text_color
¶ The text rendering color.
Default: (0.0,0.0,0.5)
-
-
class
ovito.vis.
VectorDisplay
¶ Base class: ovito.vis.Display
Controls the visual appearance of vectors (arrows).
An instance of this class is attached to particle properties like for example the
Displacement
property, which represent vector quantities. It can be accessed via thedisplay
property of theParticleProperty
class.For example, the following script demonstrates how to change the display color of force vectors loaded from an input file:
from ovito.io import import_file from ovito.vis import VectorDisplay node = import_file("simulation.dump") node.add_to_scene() vector_display = node.source.particle_properties.force.display vector_display.color = (1.0, 0.5, 0.5)
-
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 following 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. IfNone
, the global settings are used (given byDataSet.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 contains a non-empty string. Alternatively, you can save the returned QImage explicitly using itssave()
method. This gives you the opportunity to paint additional graphics on top of the image before saving it. For example:from ovito import * from ovito.vis import * from PyQt5.QtGui import QPainter # Let OVITO render an image of the active viewport. vp = dataset.viewports.active_vp rs = RenderSettings(size = (320,240), renderer = TachyonRenderer()) 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
andORTHO
) 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 theDataSet
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. TheViewportConfiguration
object also manages theactive
and themaximized
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
-