PyVista API

GEMC uses PyVista to visualize detector geometry directly from Python. Geometry can be viewed interactively, exported as a .vtksz file for web-based display, or rendered as a screenshot.

Import the API from pyvista_api:

from pyvista_api import GMesh, pvmeshes_from_gmeshes, set_yz_view_x_into_screen

The GMesh Class

GMesh is the core object for building visualizable volumes. Every instance requires a unique name and a PyVista mesh. All other parameters are optional:

Example:

import pyvista as pv
from pyvista_api import GMesh

sphere_gm = GMesh(
    name="sphere",
    mesh=pv.Sphere(radius=0.7, theta_resolution=32, phi_resolution=32),
    mother="box",
    material="G4_Pb",
    color="tomato",
    opacity=0.85,
    position=(0.0, 0.0, 1.2),
    rotation=(0.0, 0.0, 0.0),
)

Supported Primitive Shapes

GMesh meshes are automatically converted to Geant4 solids when published via GVolume.from_gmesh(). The mapping is determined by the mesh bounding geometry:

Sphere detection takes priority over cylinder since both share “round in XY” bounding-box geometry.

Display Styles

The display appearance of a GVolume (created via from_gmesh or directly) is controlled by three attributes:

Style 1 — Solid (default)

volume.style = 1
volume.opacity = 1.0

Style 0 — Wireframe

Renders only the characteristic edges of the shape, extracted using extract_feature_edges at a 30° dihedral threshold. Triangulated shapes (cylinders, spheres) show clean geometric outlines rather than every triangle edge.

volume.style = 0

Style 2 — Cloud

A semi-transparent surface is shown together with an 8000-point cloud sampled from the surface.

volume.style = 2

visible = 0 — Container / Envelope

Setting visible = 0 makes the volume nearly transparent (opacity 0.05, wireframe only). Use this for container or world volumes that should not dominate the scene:

world.visible = 0   # NOT world.style = 0

Rotations

GMesh uses intrinsic ZYX Euler angles: the angles (rx, ry, rz) are applied sequentially in the order X → Y → Z about the local frame axes, giving the rotation matrix:

R = Rx(rx) · Ry(ry) · Rz(rz)

Parent-to-world transforms are accumulated recursively through the volume hierarchy, so a child volume’s world position is T_parent + R_parent × T_local.

Example — 35° rotation about Z:

GMesh(
    name="rotated_box",
    mesh=pv.Cube(x_length=1.2, y_length=0.4, z_length=1.2),
    mother="box",
    rotation=(0.0, 0.0, 35.0),   # (rx, ry, rz) in degrees
)

Standalone PyVista Rendering

pvmeshes_from_gmeshes resolves the full parent-child hierarchy (position + rotation) and returns (mesh, color, opacity) tuples ready for direct PyVista rendering, without a Geant4 backend:

import pyvista as pv
from pyvista_api import GMesh, pvmeshes_from_gmeshes, set_yz_view_x_into_screen

gmeshes = make_basic_shapes()
pvmeshes = pvmeshes_from_gmeshes(gmeshes)

p = pv.Plotter()
for mesh, color, opacity in pvmeshes:
    p.add_mesh(mesh, color=color, opacity=opacity, show_edges=True)

p.add_axes_at_origin(xlabel="X", ylabel="Y", zlabel="Z")
set_yz_view_x_into_screen(p, distance=10.0)
p.show()

set_yz_view_x_into_screen(p, distance) positions the camera so that +Z points right on screen and +X points into the screen.

CLI Flags

These flags are accepted by any Python geometry script that uses autogeometry:

./detector.py -pv                        # interactive window
./detector.py -pvvtk detector -pvz 0.02  # export vtksz

To generate an offscreen screenshot via the Geant4 renderer:

./detector.py                   # build geometry (creates gemc.db)
gemc detector.yaml -n=10 \
  -g4view="[{driver: TOOLSSG_OFFSCREEN, segsPerCircle: 200}]" \
  -g4camera="[{phi: -10*deg, theta: 250*deg}]"
# output: gemc_run_0.png

Publishing to Geant4

To use a GMesh in a full GEMC simulation, convert it to a GVolume and publish it:

from gconfiguration import autogeometry
from gvolume import GVolume

cfg = autogeometry("myexperiment", "mydetector")

for gm in make_shapes():
    gv = GVolume.from_gmesh(gm)
    gv.publish(cfg)

GVolume.from_gmesh automatically:

• Detects the Geant4 solid type from the mesh bounding geometry
• Sets mother = "root" if gm.mother is None
• Transfers color, opacity, position, and rotation from the GMesh
• Sets visible = 0 if opacity <= 0.01

python API

Pass -h for additional command line options:

options:
  -h, --help            show this help message and exit
  -f, --factory FACTORY
						ascii, sqlite
  -v, --variation VARIATION
                        Set variation name
  -r, --run RUN         Set run number
  -sql, --dbhost DBHOST
                        SQLite filename or MYSQL host
  -pv, --pyvista        Show geometry using pyvista (needs pyvista)
  -pvb, --pvb, --pyvista-background
                        Use PyVista BackgroundPlotter (needs pyqt6 pyvistaqt)
  -pvw, --width WIDTH   Set plotter width
  -pvh, --height HEIGHT
						Set plotter height
  -pvx, --x X           Set plotter x position
  -pvy, --y Y           Set plotter y position
  -axes, --add_axes_at_zero

If you have pyvista (see also install pyvista), you can use the -pv and -pvb options to display the setup without having to run GEMC