Skip to content

Visualization helpers

pyvoro2.viz3d

Optional 3D visualization helpers.

This module provides a small set of convenience functions for visualizing pyvoro2 outputs using py3Dmol (a Python wrapper around 3Dmol.js).

The dependency is intentionally optional to keep pyvoro2 lightweight.

Install with:

.. code-block:: bash

pip install "pyvoro2[viz]"

or:

.. code-block:: bash

pip install py3Dmol

Notes

  • The functions here are best-effort helpers meant for interactive exploration. They are not a full-featured rendering pipeline.
  • The helpers are designed around the dictionaries returned by :func:pyvoro2.compute and :func:pyvoro2.ghost_cells.
  • All coordinates are treated as Cartesian. For periodic domains, you can optionally wrap each cell geometry so that its site lies inside the primary domain (see :func:view_tessellation).

VizStyle dataclass

Styling options for visualization helpers.

add_axes(view, *, origin=(0.0, 0.0, 0.0), length=1.0, line_width=2.0, label_font_size=12, color_x='0xff0000', color_y='0x00aa00', color_z='0x0000ff')

Add simple Cartesian axes (x, y, z) as three lines + labels.

add_cell_wireframe(view, cell, *, color='0x1f77b4', line_width=2.5)

Add a single cell wireframe (edges of polygonal faces).

add_domain_wireframe(view, domain, *, color='0x000000', line_width=2.5)

Draw the domain boundary as a wireframe.

add_sites(view, points, *, labels=None, color='0x777777', radius=0.093, label_color='0x000000', label_background='0xffffff', label_font_size=8)

Add generator sites as spheres, optionally with text labels.

add_tessellation_wireframe(view, cells, *, color='0x1f77b4', line_width=2.5, cell_ids=None)

Add wireframes for multiple cells.

add_vertices(view, vertices, *, labels=None, color='0xff7f0e', radius=0.04, label_color='0x000000', label_background='0xffffff', label_font_size=7)

Add vertex markers as small spheres, optionally with labels.

make_view(*, width=640, height=480, background='0xffffff')

Create a py3Dmol view.

view_tessellation(cells, *, domain=None, show_sites=True, show_site_labels=True, max_site_labels=200, show_domain=True, show_axes=True, axes_length=None, wrap_cells=False, cell_ids=None, show_vertices=False, show_vertex_labels='auto', max_vertex_labels=200, style=None, width=640, height=480, zoom=True)

Create a py3Dmol view of a tessellation.

Parameters

cells: Output of :func:pyvoro2.compute or :func:pyvoro2.ghost_cells. For wireframe rendering, cells must include both vertices and faces.

You may also pass the result of :func:`pyvoro2.normalize_vertices` or
:func:`pyvoro2.normalize_topology` to enable vertex markers/labels using
global vertex ids.

domain: If provided, draws the domain wireframe. wrap_cells: If True and domain is periodic, translate each cell by an integer lattice vector so that its site lies in the primary domain. This is purely a visualization convenience. show_vertex_labels: One of "off", "auto" (default), or "on".

Vertex labels require **global vertex ids**, which are only available
when you pass a :class:`~pyvoro2.normalize.NormalizedVertices` or
:class:`~pyvoro2.normalize.NormalizedTopology` object.

* ``"off"``: never show vertex labels.
* ``"auto"``: show labels only when global ids are available; if there
  are many vertices, labels are truncated silently to keep the scene readable.
* ``"on"``: show labels when global ids are available; warns when labels
  are truncated.

:::

This module is optional and requires the py3Dmol dependency.

Install with:

pip install "pyvoro2[viz]"