sgio.plot_sg_pyvista#

sgio.plot_sg_pyvista(sg: StructureGene, *, scalars: str | None = 'property_id', show_edges: bool = True, show_local_axes: bool = False, max_local_axes: int = 500, local_axis_scale: float | None = None, output_html: str | Path | None = None, show: bool = False, widgets: bool = False) → pyvista.Plotter#

Plot one structure gene with PyVista.

This is the single-SG PyVista entry point. It hides the mesh extraction and returns the native plotter for further PyVista customization. If local axes are shown, its HTML output also includes the browser-native axis legend and view-control help.

Parameters:

  • sg (StructureGene) – Structure gene containing the mesh to render.

  • scalars (str, optional) – Array used to color the mesh. "property_id" (the default) uses a discrete property color map and legend without a scalar bar. Other arrays use PyVista’s regular scalar rendering. Pass None to leave the mesh uncolored.

  • show_edges (bool, optional) – Show mesh edges. Default is True.

  • show_local_axes (bool, optional) – Draw sampled element-local y1/y2/y3 arrows. Default is False.

  • max_local_axes (int, optional) – Maximum number of cells receiving local-axis glyphs. Default is 500.

  • local_axis_scale (float, optional) – Glyph length in mesh coordinate units.

  • output_html (str or pathlib.Path, optional) – Optional self-contained interactive HTML output.

  • show (bool, optional) – Open PyVista’s desktop window before returning. Default is False.

  • widgets (bool, optional) – Add desktop checkbox widgets for local axes, faces, edges, and nodes. Widgets require a live PyVista window and cannot be exported to an offline HTML file. Default is False.

Returns:

Plotter containing the SG mesh and optional local-axis glyphs.

Return type:

pyvista.Plotter

Raises:

  • TypeError – If sg is not a StructureGene.

  • ValueError – If sg has no mesh or plotting options are invalid.

  • ImportError – If the optional pyvista dependency is not installed.