Skip to content

Visuals Overview

High-performance rendering in Datoviz is based on the concept of visuals — GPU-accelerated primitives such as points, lines, images, and 3D meshes. Each visual represents a collection of items of a specific type, rendered in a single batch for maximum efficiency.

Datoviz is designed to render millions of visual items at interactive framerates, assuming items in a visual share the same transformation (e.g., coordinate space). This makes the grouping and batching model crucial to understand.

Note

Some visuals overlap in functionality, each offering different trade-offs in flexibility and performance. Try out similar visuals to find the one that best suits your needs.

Available visuals

Basic
🔺 Basic: Low-level Vulkan primitives: points, line strips, triangles, etc.
Pixel
🟦 Pixel: Individual pixels with custom position, size, and color (for rasters, point clouds, etc.).
Point
⚪ Point: Borderless circular discs (for simple scatter plots with minimal styling).
Marker
✳️ Marker: Symbols with predefined (circle, square, cross, etc.) or custom (SVG, bitmap) shapes and optional borders.
Segment
➖ Segment: Line segments with arbitrary width and customizable caps (no arrows nor dashes for now).
Path
➰ Path: Continuous polylines with optional variable thickness, optionally closed (no arrows nor dashes for now).
Image
🖼️ Image: User-facing 2D images (RGBA or single-channel with colormap) anchored in world space.
Glyph
🔤 Glyph: Minimally-customizable text (to be improved in future versions).
Mesh
🧊 Mesh: Triangulations in 2D or 3D, used for polygons or surface meshes, with optional lighting, texture, contour, wireframes (isolines documented soon).
Mesh
🧊 Sphere: 3D spheres with lighting.
Volume
🌫️ Volume: Basic volume rendering for dense 3D scalar fields (RGBA or single-channel with colormap).

Data model: items and groups

Each visual manages a collection of items. The definition of an item depends on the visual type:

  • Pixel, Point, Marker: 1 item = 1 point or marker
  • Segment: 1 item = 1 line segment
  • Path: 1 item = 1 point in a polyline (multiple disjoint paths can be batched)
  • Image: 1 item = 1 image
  • Glyph: 1 item = 1 character, grouped into strings by position
  • Mesh: 1 item = 1 vertex (connectivity defined by faces, a separate list of indices)
  • Sphere: 1 item = 1 3D sphere
  • Volume: 1 item = the full volume (typically only 1)

A given visual instance has many items that share:

  • The same visual type
  • The same visual options (for example, mesh visual with lighting support)
  • The same data transformation (specific to a panel)

This model is key to Datoviz's performance: many visual instances are submitted in a single GPU draw call, with tight memory layout and no redundant state changes.

Positioning data: 3D NDC

All visuals expect positions in 3D Normalized Device Coordinates (NDC), where each axis ranges from -1 to +1.

For 2D rendering, simply set the Z coordinate to 0 and use a 2D camera or interaction mode (e.g. pan-zoom). This keeps your data in the XY plane while leveraging the full GPU pipeline.

Working with visuals

All visuals are created using the app.visual_name() functions:

visual = app.point(position=..., color=..., size=...)

Attributes can also be set or modified as follows:

visual.set_position(position)
visual.set_color(color)
...

The position is usually an (N, 3) NumPy array (automatically cast to float32, which the GPU expects), and color is an (N, 4) array of RGBA values in the 0–255 range, automatically cast to uint8.

Visuals must then be added to a panel:

panel.add(visual)

Enabling depth testing

In 3D visualizations, you can control whether visual elements are rendered with or without depth testing:

visual.set_data(..., depth_test=True)
  • depth_test=True: Items respect the 3D depth buffer (closer points appear in front)
  • depth_test=False: Items are rendered in the order they are submitted

Culling and front face

Warning

This section of the documentation has not been written yet.

For more details, see each visual's documentation page.