ovito.vis
¶
This module contains classes related to data visualization and rendering.
Rendering:
Rendering engines:
Data visualization elements:
DataVis
(base class for all visual elements)
Viewport overlays:
ViewportOverlay
(base class for all overlay types)
-
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
andcamera_dir
fields. Additionally, thetype
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. Thezoom_all()
method repositions the camera automatically such that the entire scene becomes fully visible within the view. See also the documentation of the Adjust View dialog of OVITO to learn more about the role of these settings.After the viewport’s virtual camera has been set up, you can render an image or movie using the
render_image()
andrender_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 draw additional two-dimensional content on top of the rendered scene, e.g. a coordinate axis tripod or a color legend. See the the
overlays
property 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)
-
property
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).
-
property
overlays
¶ A list of
ViewportOverlay
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.0, 1.0, 1.0), 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.
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.0, 1.0, 1.0), 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 file path 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 – This option makes the background 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 generated transparency information.
renderer – The rendering engine to use. If set to
None
, either OpenGL or Tachyon are used, depending on the availablity of OpenGL in the current execution context.
- Returns
A QImage object containing the rendered picture.
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 a 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 omitted, 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 later using itssave()
method:from ovito.vis import Viewport, TachyonRenderer from PySide2.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.
-
property
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
andOrtho
) 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.
-
property
-
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 corresponding user manual page 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.-
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
-
property
-
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 correspondingDataVis
element (seeDataObject.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
''
-
property
-
class
ovito.vis.
CoordinateTripodOverlay
¶ - Base class
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 PySide2 import QtCore # Create the overlay. tripod = CoordinateTripodOverlay() tripod.size = 0.07 tripod.alignment = QtCore.Qt.AlignRight ^ QtCore.Qt.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. This must be a valid Qt.Alignment value value as shown in the example above.
- Default
PySide2.QtCore.Qt.AlignLeft ^ PySide2.QtCore.Qt.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)
-
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,1,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,1)
-
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_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
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.
PythonViewportOverlay
¶ - Base class
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 theViewport.render_image()
method before saving the image to disk. APythonViewportOverlay
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 theArguments
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.-
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, including all visible data pipelines.
-
property
size
¶ A tuple with the width and height of the image being rendered in pixels.
-
property
view_tm
¶ The affine camera transformation matrix. This 3x4 matrix transforms points/vectors from world space to camera space.
-
property
-
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.
TextLabelOverlay
¶ - Base class
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 PySide2 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.-
property
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
PySide2.QtCore.Qt.AlignLeft ^ PySide2.QtCore.Qt.AlignTop
-
property
font_size
¶ The font size, which is specified as a fraction of the output image height.
- Default
0.02
-
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 thetext
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 thePipeline
assigned to the overlay’ssource_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”
-
property
text_color
¶ The text rendering color.
- Default
(0.0,0.0,0.5)
-
class
ovito.vis.
ViewportOverlay
¶ Abstract base class for viewport overlays, which render two-dimensional graphics on top of (or behind) the three-dimensional scene. Examples are
CoordinateTripodOverlay
,TextLabelOverlay
andColorLegendOverlay
.-
property
behind_scene
¶ This option allows to put the overlay behind the three-dimensional scene, i.e. it becomes an “underlay” instead of an “overlay”. If set to
True
, objects of the three-dimensional scene will occclude the graphics of the overlay.- Default
False
-
property
enabled
¶ Controls whether the overlay gets rendered. An overlay can be hidden by setting its
enabled
property toFalse
.- Default
True
-
property
-
class
ovito.vis.
SimulationCellVis
¶ - Base class
Controls the visual appearance of the simulation cell. An instance of this class is attached to the
SimulationCell
object and can be accessed through itsvis
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)
-
class
ovito.vis.
SurfaceMeshVis
¶ - Base class
Controls the visual appearance of a
SurfaceMesh
object, which is typically generated by modifiers such asConstructSurfaceModifier
orCreateIsosurfaceModifier
. See also the corresponding user manual page for this visual element.-
property
cap_color
¶ The 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. Valid range is 0.0 – 1.0.
- Default
0.0
-
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.
- Default
False
-
property
show_cap
¶ Controls the visibility of cap polygons, which are created at the intersection of the surface mesh with periodic box boundaries.
- Default
True
-
property
smooth_shading
¶ Enables smooth shading of the triangulated surface mesh.
- Default
True
-
property
surface_color
¶ The display color of the surface mesh.
- Default
(1.0, 1.0, 1.0)
-
property
surface_transparency
¶ The level of transparency of the displayed surface. Valid range is 0.0 – 1.0.
- Default
0.0
-
class
ovito.vis.
ColorLegendOverlay
¶ - Base class
Renders a color legend for a
ColorCodingModifier
on top of the three-dimensional scene. You can attach an instance of this class to aViewport
by adding it to the viewport’soverlays
collection:from ovito.io import import_file from ovito.vis import ColorLegendOverlay, Viewport from ovito.modifiers import ColorCodingModifier from PySide2.QtCore import Qt # Prepare a data pipeline containing a ColorCodingModifier: pipeline = import_file("input/simulation.dump") color_mod = ColorCodingModifier(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, which is going to be used for image rendering: viewport = Viewport(type = Viewport.Type.Top) viewport.overlays.append(overlay)
-
property
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
PySide2.QtCore.Qt.AlignHCenter ^ PySide2.QtCore.Qt.AlignBottom
-
property
aspect_ratio
¶ The aspect ratio of the color bar. Larger values make it more narrow.
- Default
8.0
-
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 decimal places or add units to the numeric values, for example.
- Default
‘%g’
-
property
label1
¶ Sets the text string displayed at the upper end of the bar. If empty, the
end_value
of theColorCodingModifier
is used.- Default
‘’
-
property
label2
¶ Sets the text string displayed at the lower end of the bar. If empty, the
start_value
of theColorCodingModifier
is used.- Default
‘’
-
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
PySide2.QtCore.Qt.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
text_color
¶ The RGB color used for text labels.
- Default
(0.0,0.0,0.0)
-
property
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.
ParticlesVis
¶ - Base class
This type of visual element is responsible for rendering particles and is attached to every
Particles
data object. You can access the element through thevis
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.source.data.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 theRadius
particle property, e.g. using theComputePropertyModifier
.- Default
1.2
-
property
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
This type of visual element is responsible for rendering arrows to visualize per-particle vector quantities. An instance of this class is typically attached to a
Property
data object that represents a vectorial quantity, e.g. theForce
and theDisplacement
particle properties. See also the corresponding user manual page for a description of this visual element.The parameters of the vector visual element let you control the visual appearance of the arrows in rendered images. For the standard particle properties
Force
,Dipole
andDisplacement
, OVITO automatically creates and attaches aVectorVis
element to these properties and you can access it through theirvis
field:pipeline = import_file('input/simulation.dump') pipeline.add_to_scene() vector_vis = pipeline.source.data.particles.forces.vis vector_vis.color = (1,0,0) vector_vis.enabled = True # This activates the display of arrows
In the example above, the
Force
particle property was loaded from the input simulation file, and the code accesses the correspondingProperty
data object in the source data collection of the pipeline.Some modifiers dynamically generate new vector particle properties. For instance, the
CalculateDisplacementsModifier
generates theDisplacement
property and will automatically attach a newVectorVis
element to it. In this case, the visual element is managed by the modifier and may be configured as needed:modifier = CalculateDisplacementsModifier() pipeline.modifiers.append(modifier) modifier.vis.enabled = True # This activates the display of displacement vectors modifier.vis.shading = VectorVis.Shading.Flat
If you write your own modifier function in Python for computing a vector particle property, and you want to visualize these vectors as arrows, you need to create the
VectorVis
element programmatically and attached it to theProperty
generated by your user-defined modifier function. For example:from ovito.vis import VectorVis import numpy # Set up the visual element outside of the modifier function: vector_vis = VectorVis( alignment = VectorVis.Alignment.Center, color = (1.0, 0.0, 0.4)) def my_modifier_function(frame, data): vector_data = numpy.random.random_sample(size=(data.particles.count, 3)) my_prop = data.particles_.create_property('My Property', data=vector_data) my_prop.vis = vector_vis # Attach the visual element to output property
-
property
alignment
¶ Controls the positioning of arrows with respect to the particles. Possible values:
VectorVis.Alignment.Base
(default)VectorVis.Alignment.Center
VectorVis.Alignment.Head
-
property
color
¶ The display color of arrows.
- Default
(1.0, 1.0, 0.0)
-
property
reverse
¶ Boolean flag controlling the reversal of arrow directions.
- Default
False
-
property
scaling
¶ The uniform scaling factor applied to vectors.
- Default
1.0
-
property
shading
¶ The shading style used for the arrows. Possible values:
VectorVis.Shading.Normal
(default)VectorVis.Shading.Flat
-
property
width
¶ Controls the width of arrows (in natural length units).
- Default
0.5
-
class
ovito.vis.
BondsVis
¶ - Base class
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 thevis
field of the bonds data object, which is part in the data collection managed by the pipeline’ssource
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. theCreateBondsModifier
, theBondsVis
element is managed by the modifier:modifier = CreateBondsModifier(cutoff = 2.8) modifier.vis.shading = BondsVis.Shading.Flat pipeline.modifiers.append(modifier)
-
property
color
¶ The uniform display color of bonds. This value is only used if
use_particle_colors
is false and if theColor
BondProperty
is not defined.- Default
(0.6, 0.6, 0.6)
-
property
shading
¶ Controls the shading style of bonds. Possible values:
BondsVis.Shading.Normal
(default)BondsVis.Shading.Flat
-
property
use_particle_colors
¶ If set to
True
, bonds are rendered in the same color as the particles they are incident to. Otherwise, a uniformcolor
is used. If theBondProperty
namedColor
is defined, then the per-bond colors are used in any case.- Default
True
-
property
width
¶ The display width of bonds (in natural length units).
- Default
0.4
-
class
ovito.vis.
TrajectoryVis
¶ - Base class
Controls the visual appearance of particle trajectory lines. An instance of this class is attached to every
TrajectoryLines
data object.-
property
color
¶ The display color of trajectory lines.
- Default
(0.6, 0.6, 0.6)
-
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.
DislocationVis
¶ - Base class
Controls the visual appearance of dislocation lines extracted by a
DislocationAnalysisModifier
. An instance of this class is attached to everyDislocationNetwork
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_width
¶ The scaling factor applied to displayed Burgers vectors. This can be used to exaggerate the arrow size.
- Default
1.0
-
property
indicate_character
¶ Controls how the display color of dislocation lines is chosen.Possible values:
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. OSPRay is an open-source raytracing system integrated into OVITO.
An instance of this class can be passed to the
Viewport.render_image()
orViewport.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
was set.- Default
0.5
-
property
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
-
property
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
-
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
default_light_intensity
parameter.- Default
True
-
property
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
-
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.05
-
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
20
-
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
8
-
property
samples_per_pixel
¶ The number of raytracing samples computed per pixel. Larger values can help to reduce aliasing artifacts.
- Default
4
-
property
-
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. See also the corresponding user manual page for more information on this rendering backend.
-
property
antialiasing
¶ Enables supersampling to reduce aliasing effects.
- Default
True
-
property
aperture
¶ Controls the aperture of the camera, which is used for depth-of-field rendering.
- Default
1.0
-
property
blur_samples
¶ Controls the maximum number of rays to use for each pixel to compute focus blur (depth-of-field).
- Default
1.0
-
property
depth_of_field
¶ This flag enables focus blur (depth-of-field) rendering.
- Default
False
-
property
focal_length
¶ Controls the focal length of the camera, which is used for depth-of-field rendering.
- Default
40.0
-
property
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
-
property
omni_stereo
¶ This flag enables omnidirectional 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
-
property
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
""
-
property
quality_level
¶ The image rendering quality parameter passed to POV-Ray.
- Default
9
-
property
radiosity
¶ Enables radiosity light calculations.
- Default
False
-
property
radiosity_raycount
¶ The number of rays that are sent out whenever a new radiosity value has to be calculated.
- Default
50
-
property
show_window
¶ Controls whether the POV-Ray window is shown during rendering. This allows you to follow the image generation process.
- Default
True
-
property
-
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()
orViewport.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
-
property