G4/vis ToolsSG drivers

The visualization system of Geant4 11.x comes with the ToolsSG drivers.

These drivers use the scene graph logic found in the classes under:


(sg being for "scene graph").

These classes are themselves a subpart of the softinex/inlib and exlib thesaurus of code accumulated for long at Orsay (at LAL before 2020 and now at the IJCLab) to help doing visualization and data analysis for various projects. (The namespaces inlib and exlib had been changed to "tools" when importing classes within Geant4 to avoid clashes with apps using both Geant4 and straight softinex). This scene graph way of doing visualization is borrowed from the great OpenInventor developed by Silicon Graphics Incs in the 1980's. The idea is that a data representation is done by creating a scene graph which is a tree of "nodes". For example a tree has in general a first tools::sg::ortho (or sg::perecpective) camera node specifying a camera projection (position, orientation and depth of view), some sg::matrix node permitting to position an object in a 3D space and then some shape nodes as sg::cube, sg::cylinder or sg::vertices (a node handling a set of points, lines, segments or triangles) used to represent a piece of detector or tracks.

Whence having built a scene graph, the rendering is done, typically after having received some expose event in a drawing area window, by applying a "render_action" that traverses the scene graph and asks to the nodes the actions that will be passed to a specific graphics engine. For example a shape node (cube, sphere, polyhedron), when traversed, will give to the render_action the graphics primitives (points, lines, segments, triangles) representing that shape. A camera node will give a projection matrix, a matrix node will give a model matrix. A common graphics engine being GL-ES, we have the tools::sg::GL_action class that does that for GL-ES on macOS, Linux and Windows. We have also various render_action to do offscreen rendering (gl2ps_action using gl2ps and zb_action to render in an in memory z buffer). In softinex we have also a exlib::wasm::render to render in WebAssembly using WebGL and a exlib::metal::render to render within macOS/Cocoa/Metal, but these are not yet used in Geant4/vis.

In Geant4/vis, the ToolsSG directory contains code to create a viewer within various windowing systems, codes which are declared as "drivers" in the vis system. In G4/11.0, there are the TOOLSSG_QT_GLES, TOOLSSG_XT_GLES to create a viewing area ready for GL-ES rendering if using the GUI toolkits Qt or Xt/Motif (activated through the G4UIQt, G4UIXt classes), and TOOLSSG_X11_GLES, TOOLSSG_WINDOWS_GLES to create a GL-ES viewing area straigh on X11 or Windows windowing systems.

From a user point of view, typical commands to create a ToolsSG viewer are:

    /vis/sceneHandler/create TSG scene-handler-tsg
    /vis/viewer/create scene-handler-tsg viewer-tsg 600x600-0+0

or with the compound command:

    /vis/viewer/open TSG 600x600-0+0

Someone can specify straight a TOOLSSG_[QT,XT,X11,WINDOWS]_GLES name driver, but if specifying "TSG", the G4/vis system will pick the "right one", according to the kind of GUI context which is around (in general Qt for now).

Obviously, these drivers must have been built when building/installing Geant4. With the G4 cmake system, this is done by specifying the cmake flag:


If so, cmake will trigger the build of a specific ToolsSG driver according which GUI is specified (in general it is Qt for now, G4/Qt being built with -DGEANT4_USE_QT=ON).

Whence a ToolsSG viewer is created, the rest of the vis commands triggering the representation of a piece of detector or a track are the same commands than other drivers. For example, as could be found in the examples/basic/B1/vis.mac:

    # Draw geometry:
    # Draw smooth trajectories at end of event:
    /vis/scene/add/trajectories smooth

On a technical point of view, the G4ToolsSceneHandler class is the place where tools::sg nodes are created according each Geant4/vis primitive type (G4Polyhedron, G4Polyline, G4Text, etc...).

/vis/tsg commands

ToolsSG comes with commands of its own.



permits to write the content of the current ToolsSG viewer in a file at various formats. Default file is out.eps and default format is gl2ps_eps. Available formats in 11.0 are:

    gl2ps_eps: gl2ps producing eps
    gl2ps_ps:  gl2ps producing ps
    gl2ps_pdf: gl2ps producing pdf
    gl2ps_svg: gl2ps producing svg
    gl2ps_tex: gl2ps producing tex
    gl2ps_pgf: gl2ps producing pgf
    zb_ps: tools::sg offscreen zbuffer put in a PostScript file.

An example of usage is:

    /vis/tsg/export gl2ps_pdf out.pdf

Another command is:


It permits to print the available keys used to customize a ToolsSG plotter. This command is more documented in the ToolsSG plotting section.