# `ovito.vis`

This module contains classes related to data visualization and rendering.

Rendering:

> - `Viewport`

Rendering engines:

> - `OpenGLRenderer`

> - `TachyonRenderer`

> - `OSPRayRenderer`

Data visualization elements:

> - `DataVis` (base class for all visual elements)

> - `BondsVis`

> - `DislocationVis`

> - `ParticlesVis`

> - `SimulationCellVis`

> - `SurfaceMeshVis`

> - `TrajectoryVis`

> - `TriangleMeshVis`

> - `VectorVis`

Viewport overlays:

> - `ViewportOverlay` (base class for all overlay types)

> - `ColorLegendOverlay`

> - `CoordinateTripodOverlay`

> - `PythonViewportOverlay`

> - `TextLabelOverlay`

class `ovito.vis.``BondsVis`
  Base class

    `ovito.vis.DataVis`

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

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

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

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

      modifier = CreateBondsModifier(cutoff = 2.8)
      modifier.vis.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 the `Color` bond property 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 uniform `color` is used. If the bond property named `Color` 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.``ColorLegendOverlay`
  Base class

    `ovito.vis.ViewportOverlay`

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

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

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

  property `font_size`

    The relative size of the font used for text labels.

    Default

      0.1

  property `format_string`

    The format string used with the sprintf() function to generate the text representation of floating-point values. You can change this format string to control the number of 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 the `ColorCodingModifier` is used.

    Default

      ‘’

  property `label2`

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

    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.``CoordinateTripodOverlay`
  Base class

    `ovito.vis.ViewportOverlay`

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

      from ovito.vis import CoordinateTripodOverlay, Viewport
      from 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.0, 0.0)`

  property `axis1_enabled`

    Enables the display of the first axis.

    Default

      `True`

  property `axis1_label`

    Text label for the first axis.

    Default

      `"x"`

  property `axis2_color`

    RGB display color of the second axis.

    Default

      `(0.0, 0.8, 0.0)`

  property `axis2_dir`

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

    Default

      `(0.0, 1.0, 0.0)`

  property `axis2_enabled`

    Enables the display of the second axis.

    Default

      `True`

  property `axis2_label`

    Text label for the second axis.

    Default

      `"y"`

  property `axis3_color`

    RGB display color of the third axis.

    Default

      `(0.2, 0.2, 1.0)`

  property `axis3_dir`

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

    Default

      `(0.0, 0.0, 1.0)`

  property `axis3_enabled`

    Enables the display of the third axis.

    Default

      `True`

  property `axis3_label`

    Text label for the third axis.

    Default

      `"z"`

  property `axis4_color`

    RGB display color of the fourth axis.

    Default

      `(1.0, 0.0, 1.0)`

  property `axis4_dir`

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

    Default

      `(0.7071, 0.7071, 0.0)`

  property `axis4_enabled`

    Enables the display of the fourth axis.

    Default

      `False`

  property `axis4_label`

    Label for the fourth axis.

    Default

      `"w"`

  property `font`

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

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

  property `font_size`

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

    Default

      `0.4`

  property `line_width`

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

    Default

      `0.06`

  property `offset_x`

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

    Default

      `0.0`

  property `offset_y`

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

    Default

      `0.0`

  property `size`

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

    Default

      `0.075`

  property `style`

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

    > - `CoordinateTripodOverlay.Style.Flat` (default)

    > - `CoordinateTripodOverlay.Style.Solid`

class `ovito.vis.``DataVis`

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

  property `enabled`

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

    Default

      `True`

  property `title`

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

    Default

      `''`

class `ovito.vis.``DislocationVis`
  Base 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.

  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`

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

    > - `DislocationVis.ColoringMode.ByDislocationType` (default)

    > - `DislocationVis.ColoringMode.ByBurgersVector`

    > - `DislocationVis.ColoringMode.ByCharacter`

  property `line_width`

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

    Default

      `1.0`

  property `shading`

    The shading style used for the lines. Possible values:

    > - `DislocationVis.Shading.Normal` (default)

    > - `DislocationVis.Shading.Flat`

  property `show_burgers_vectors`

    Boolean flag that enables the display of Burgers vector arrows.

    Default

      `False`

  property `show_line_directions`

    Boolean flag that enables the visualization of line directions.

    Default

      `False`

class `ovito.vis.``OSPRayRenderer`

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

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

  property `ambient_brightness`

    Controls the radiance of the ambient light.

    Default

      `0.8`

  property `ambient_light_enabled`

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

    Default

      `True`

  property `aperture`

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

    Default

      `0.5`

  property `denoising_enabled`

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

    Default

      `True`

  property `direct_light_angular_diameter`

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

    Default

      `numpy.radians(10.0)`

  property `direct_light_enabled`

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

    Default

      `True`

  property `direct_light_intensity`

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

    Default

      `1.0`

  property `dof_enabled`

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

    Default

      `False`

  property `focal_length`

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

    Default

      `40.0`

  property `material_shininess`

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

    Default

      `10.0`

  property `material_specular_brightness`

    Controls the specular reflectivity of the default material.

    Default

      `0.02`

  property `max_ray_recursion`

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

    Default

      `10`

  property `refinement_iterations`

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

    Default

      `4`

  property `samples_per_pixel`

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

    Default

      `2`

  property `sky_albedo`

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

    Default

      `0.3`

  property `sky_brightness`

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

    Default

      `2.0`

  property `sky_light_enabled`

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

    Default

      `False`

  property `sky_turbidity`

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

    Default

      `3.0`

class `ovito.vis.``OpenGLRenderer`

  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

class `ovito.vis.``ParticlesVis`
  Base class

    `ovito.vis.DataVis`

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

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

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

      vis_element = pipeline.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 the `Radius` particle property, e.g. using the `ComputePropertyModifier`.

    Default

      1.2

  property `shape`

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

    > - `ParticlesVis.Shape.Sphere` (default)

    > - `ParticlesVis.Shape.Box`

    > - `ParticlesVis.Shape.Circle`

    > - `ParticlesVis.Shape.Square`

    > - `ParticlesVis.Shape.Cylinder`

    > - `ParticlesVis.Shape.Spherocylinder`

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

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

class `ovito.vis.``PythonViewportOverlay`
  Base class

    `ovito.vis.ViewportOverlay`

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

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

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

      from ovito.vis import PythonViewportOverlay, Viewport

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

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

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

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

  class `Arguments`

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

    property `fov`

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

    property `frame`

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

    property `is_perspective`

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

    property `painter`

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

    property `proj_tm`

      The projection matrix. This 4x4 matrix transforms points from camera space to screen space.

    `project_point`(world_xyz)

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

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

      Parameters

        world_xyz – The (x,y,z) coordinates of the input point

      Returns

        A (x,y) pair of pixel coordinates; or `None` if world_xyz is behind the viewer.

    `project_size`(world_xyz, r)

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

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

      Parameters

        - world_xyz – The (x,y,z) world-space coordinates of the base point

        - r – The world-space size or distance to be converted to screen-space

      Returns

        The computed screen-space size measured in pixels.

    property `scene`

      The current three-dimensional `Scene` being rendered, 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 `viewport`

      The `Viewport` being rendered.

  property `function`

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

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

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

    Default

      `None`

class `ovito.vis.``SimulationCellVis`
  Base 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. 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

    `ovito.vis.DataVis`

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

  property `cap_color`

    The 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 as well.

    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.``TachyonRenderer`

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

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

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

  property `ambient_occlusion`

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

    Default

      `True`

  property `ambient_occlusion_brightness`

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

    Default

      0.8

  property `ambient_occlusion_samples`

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

    Default

      12

  property `antialiasing`

    Enables supersampling to reduce aliasing effects.

    Default

      `True`

  property `antialiasing_samples`

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

    Default

      12

  property `aperture`

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

    Default

      0.01

  property `depth_of_field`

    This flag enables depth-of-field rendering.

    Default

      `False`

  property `direct_light`

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

    Default

      `True`

  property `direct_light_intensity`

    Controls the brightness of the directional light source.

    Default

      0.9

  property `focal_length`

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

    Default

      40.0

  property `shadows`

    Enables cast shadows for the directional light source.

    Default

      `True`

class `ovito.vis.``TextLabelOverlay`
  Base class

    `ovito.vis.ViewportOverlay`

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

      from ovito.vis import TextLabelOverlay, Viewport
      from 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`

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

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

  property `font_size`

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

    Default

      `0.02`

  property `format_string`

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

    Default

      `'%.6g'`

  property `offset_x`

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

    Default

      `0.0`

  property `offset_y`

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

    Default

      `0.0`

  property `outline_color`

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

    Default

      `(1.0, 1.0, 1.0)`

  property `outline_enabled`

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

    Default

      `False`

  property `source_pipeline`

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

  property `text`

    The text string to be rendered.

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

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

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

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

        # Create the overlay. Note that the text string contains a reference
        # to an output attribute of the ExpressionSelectionModifier.
        overlay = TextLabelOverlay(text = 'Number of selected atoms: [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.``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.

  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.``TriangleMeshVis`
  Base class

    `ovito.vis.DataVis`

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

  property `color`

    The uniform rendering color of the triangle mesh, which is used in case the mesh faces and vertices have no local color information assigned. RGB components must be in the range 0–1.

    Default

      `(0.85, 0.85, 1.0)`

  property `highlight_edges`

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

    Default

      `False`

  property `transparency`

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

    Default

      0.0

class `ovito.vis.``VectorVis`
  Base class

    `ovito.vis.DataVis`

  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. the `Force` and the `Displacement` 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` and `Displacement`, OVITO automatically creates and attaches a `VectorVis` element to these properties and you can access it through their `vis` 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 corresponding `Property` data object in the source data collection of the pipeline.

  Some modifiers dynamically generate new vector particle properties. For instance, the `CalculateDisplacementsModifier` generates the `Displacement` property and will automatically attach a new `VectorVis` 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 the `Property` 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 `offset`

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

    Default

      `(0.0, 0.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 `transparency`

    The level of semi-transparency for rendering the arrows. Valid parameter range is 0.0 – 1.0.

    Default

      0.0

  property `width`

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

    Default

      0.5

class `ovito.vis.``Viewport`

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

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

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

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

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

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

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

  property `camera_dir`

    The viewing direction vector of the viewport’s camera.

  property `camera_pos`

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

  property `camera_up`

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

    Default

      `(0.0, 0.0, 0.0)`

  `create_widget`(parent=None)

    Creates a visual widget for displaying the three-dimensional scene in an interactive window. It may be used in a Python script to display a simulation dataset on screen and build grapical user interfaces. The method craete an interactive window accepting mouse inputs from the user similar to the viewport windows found in the OVITO desktop application.

    Parameters

      parent – An optional Qt widget that should serve as parent of the newly created viewport widget.

    Returns

      A new QWidget displaying the three-dimenensional scene as seen through the virtual viewport.

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

    Note: This method has experimental status and is currently available only in the OVITO package for Anaconda. It will not work when being called from a script running in the ovitos interpreter or when using the PyPI/pip OVITO package! Please contact the OVITO developer if you are interested in the broader application of this function.

    The following example program demonstrates the use of the `create_widget()` method. Please see the Qt for Python documentation for general information on how to build graphical user interfaces with the Qt framework.

        import sys
        import os
        from PySide2.QtWidgets import QApplication

        # Create global Qt application object.
        app = QApplication(sys.argv)

        # Note: Need to import the OVITO modules after the QApplication object
        # has been created. Otherwise, OVITO would automatically create a
        # QCoreApplication object, which doesn't allow us to display GUI widgets.
        from ovito.io import import_file
        from ovito.vis import Viewport

        # Import data and populate visualization scene.
        pipeline = import_file('input/simulation.dump')
        pipeline.add_to_scene()

        # Create a virtual Viewport to the scene.
        vp = Viewport(type=Viewport.Type.Perspective, camera_dir=(2, 1, -1))

        # Create a visible GUI widget for the Viewport.
        widget = vp.create_widget()
        widget.resize(500, 400)
        widget.setWindowTitle('OVITO Viewport Demo')
        widget.show()
        vp.zoom_all()

        # Run the main Qt event loop.
        sys.exit(app.exec_())

  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`

    The list of `ViewportOverlay` objects currently attached to this viewport. Overlays render two-dimensional graphics on top of the three-dimensional scene. See the following overlay types for more information:

    > - `TextLabelOverlay`

    > - `ColorLegendOverlay`

    > - `CoordinateTripodOverlay`

    > - `PythonViewportOverlay`

    To attach a new overlay to the viewport, use the list’s `append()` method:

        from ovito.vis import Viewport, CoordinateTripodOverlay

        vp = Viewport(type = Viewport.Type.Ortho)
        tripod = CoordinateTripodOverlay(size = 0.07)
        vp.overlays.append(tripod)

    The viewport also has an `underlays` list. `ViewportOverlay` objects inserted into that list will be rendered behind the 3d objects of the scene.

  `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, crop=False)

    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.

      - crop – This option cuts away border areas of the rendered image filled with the background color; the resulting image may thus turn out smaller than the requested size.

    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:

    > - `OpenGLRenderer`

    > - `TachyonRenderer`

    > - `OSPRayRenderer`

    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 its `save()` 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 projections 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.

  property `underlays`

    The list of `ViewportOverlay` objects currently attached to this viewport. They render two-dimensional graphics behind the three-dimensional scene. See the `overlays` list for further information.

  `zoom_all`(size=640, 480)

    Repositions the viewport camera such that all objects in the scene become completely visible. The current orientation (`camera_dir`) of the viewport’s camera is maintained but the `camera_pos` and `fov` parameters are adjusted by this method.

    Parameters

      size – Size in pixels of the image that is going to be renderer from this viewport. This information is used to compute the aspect ratio of the viewport rectangle into which the visible objects should be fitted. The tuple should match the size argument being passed to `render_image()`.

    Note that this method uses an axis-aligned bounding box computed at frame 0 of the loaded trajectory enclosing all visible objects to position the viewport camera. Make sure to call `Pipeline.add_to_scene()` prior to this method to insert some visible object(s) to the scene first.

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` and `ColorLegendOverlay`.

  property `enabled`

    Controls whether the overlay gets rendered. An overlay can be hidden by setting its `enabled` property to `False`.

    Default

      `True`