Geant4 User's Guide
For Application Developers
Getting Started with Geant4

2.10 How to Visualize the Detector and Events

2.10.1 Introduction

This section briefly explains how to perform Geant4 Visualization. The description here is based on the sample program examples/novice/N03. More details are given in Section 8 "Visualization". Example macro files can be found in examples/novice/N03/visTutor/exN03VisX.mac.

2.10.2 Visualization Drivers

The Geant4 visualization system was developed in response to a diverse set of requirements:

Quick response to study geometries, trajectories and hits
High-quality output for publications
Flexible camera control to debug complex geometries
Tools to show volume overlap errors in detector geometries
Interactive picking to get more information on visualized objects

No one graphics system is ideal for all of these requirements, and many of the large software frameworks into which Geant4 has been incorporated already have their own visualization systems, so Geant4 visualization was designed around an abstract interface that supports a diverse family of graphics systems. Some of these graphics systems use a graphics library compiled with Geant4, such as OpenGL, while others involve a separate application, such as WIRED or DAWN.

You need not use all visualization drivers. You can select those suitable to your purposes. In the following, for simplicity, we assume that the Geant4 libraries are built (installed) with the "OpenGL-Xlib driver" and the "DAWNFILE driver" incorporated.

In order to use the DAWNFILE driver, you need Fukui Renderer DAWN, which is obtainable from the following Web site: http://geant4.kek.jp/GEANT4/vis.

In order to use the the OpenGL drivers, you need the OpenGL library, which is installed in many platforms by default. You also need to set an environmental variable G4VIS_BUILD_OPENGLX_DRIVER to 1 in building (installing) Genat4 libraries, and also set another environmental variable G4VIS_USE_OPENGLX to 1 in compiling your Geant4 executable. You may also have to set an environmental variable OGLHOME to the OpenGL root directory. For example,

     setenv G4VIS_BUILD_OPENGLX_DRIVER 1
     setenv G4VIS_USE_OPENGLX 1
     setenv OGLHOME /usr/X11R6

Some other visualization drivers depending on external libraries are also required to set the similar environmental variables, G4VIS_BUILD_DRIVERNAME_DRIVER and G4VIS_USE_DRIVERNAME, to 1. All visualization drivers independent of external libraries, e.g. DAWNFILE and VRMLFILE drivers, need not such setting. (But you must prepare a proper visualization manager class and a proper main() function, anyway. See below.)

For all visualization drivers available in your Geant4 executable, the C-pre-processor flags G4VIS_USE_DRIVERNAME are automatically set by config/G4VIS_USE.gmk in compilation. Similarly, for all visualization drivers incorporated into the Geant4 libraries, the C-pre-processor flags G4VIS_BUILD_DRIVERNAME_DRIVER are automatically set by config/G4VIS_BUILD.gmk in installation.

2.10.3 How to Incorporate Visualization Drivers into an Executable

You can realize (use) visualization driver(s) you want in your Geant4 executable. These can only be from the set installed in the Geant4 libraries. You will be warned if the one you request is not available.

In order to realize visualization drivers, you must instantiate and initialize a subclass of G4VisManager that implements the pure virtual function RegisterGraphicsSystems(). This subclass must be compiled in the user's domain to force the loading of appropriate libraries in the right order. The easiest way to do this is to use G4VisExecutive, a provided class with included implementation. G4VisExecutive is sensitive to the G4VIS_USE... variables mentioned above.

If you do wish to write your own subclass, you may do so. You will see how to do this by looking at G4VisExecutive.icc. A typical extract is:

     ...
       RegisterGraphicsSystem (new G4DAWNFILE);
     ...
     #ifdef G4VIS_USE_OPENGLX
       RegisterGraphicsSystem (new G4OpenGLImmediateX);
       RegisterGraphicsSystem (new G4OpenGLStoredX);
     #endif
     ...

If you wish to use G4VisExecutive but register an additional graphics system, XXX say, you may do so either before or after initializing:

     visManager->RegisterGraphicsSytem(new XXX);
     visManager->Initialize();

An example of a typical main() function is given below.

2.10.4 Writing the `main()` Method to Include Visualization

Now we explain how to write a visualization manager and the main() function for Geant4 visualization. In order that your Geant4 executable is able to perform visualization, you must instantiate and initialize your Visualization Manager in the main() function. The typical main() function available for visualization is written in the following style:

 //----- C++ source codes: main() function for visualization
 #ifdef G4VIS_USE
 #include "G4VisExecutive.hh"
 #endif

 .....

 int main(int argc,char** argv) {

 .....

   // Instantiation and initialization of the Visualization Manager
 #ifdef G4VIS_USE
   // visualization manager
   G4VisManager* visManager = new G4VisExecutive;
   visManager->Initialize();
 #endif

 .....

   // Job termination
 #ifdef G4VIS_USE
   delete visManager;
 #endif

 .....

   return 0;
 }

 //----- end of C++

Source listing 2.10.1
The typical main() routine available for visualization.

In the instantiation, initialization, and deletion of the Visualization Manager, the use of the macro G4VIS_USE is recommended. This is set unless the environment variable G4VIS_NONE is set. This allows one easily to build an executable without visualization, if required, without changing the code (but remember you have to force recompilation whenever you change the environment). Note that it is your responsibility to delete the instantiated Visualization Manager by yourself. A complete description of a sample main() function is described in examples/novice/N03/exampleN03.cc.

2.10.5 Sample Visualization Sessions

In this section we present typical sessions of Geant4 visualization. You can test them with the sample program geant4/examples/novice/N03. Run a binary executable "exampleN03" without an argument, and then execute the commands below in the "Idle>" state. Explanation of each command will be described later. (Note that the OpenGL-Xlib driver and the DAWNFILE driver are incorporated into the executable, and that Fukui Renderer DAWN is installed in your machine. )

2.10.5.1 `Visualization of detector components`

The following session visualizes detector components with the OpenGL-Xlib driver and then with the DAWNFILE driver. The former exhibits minimal visualization commands to visualize detector geometry, while the latter exhibits customized visualization (visualization of a selected physical volume, coordinate axes, texts, etc).

###################################################
#  vis1.mac:
#    A Sample macro to demonstrate visualization 
#    of detector geometry.
#
#  USAGE: 
#   Save the commands below as a macro file, say, 
#   "vis1.mac", and execute it as follows:
#
#   % $(G4BINDIR)/exampleN03
#   Idle> /control/execute vis1.mac
#############################################

#############################################
# Visualization of detector geometry 
#  with the OGLIX (OpenGL Immediate X) driver
#############################################

# Invoke the OGLIX driver: 
#  Create a scene handler and a viewer for the OGLIX driver
/vis/open OGLIX

# Visualize the whole detector geometry 
#  with the default camera parameters.
#  Command "/vis/drawVolume" visualizes the detector geometry,
#  and command "/vis/viewer/flush" declares the end of visualization.
#  (The command /vis/viewer/flush  can be omitted for the OGLIX 
#   and OGLSX drivers.)
#  The default argument of "/vis/drawVolume" is "world".
/vis/drawVolume
/vis/viewer/flush

#########################################
# Visualization with the DAWNFILE driver
#########################################

# Invoke the DAWNFILE driver 
#  Create a scene handler and a viewer for the DAWNFILE driver
/vis/open DAWNFILE

# Bird's-eye view of a detector component (Absorber)
#  drawing style: hidden-surface removal
#  viewpoint  : (theta,phi) = (35*deg, 45*deg), 
#  zoom factor: 1.1 of the full screen size
#  coordinate axes:
#     x-axis:red,  y-axis:green,  z-axis:blue
#     origin: (0,0,0),  length: 500 mm
#
/vis/viewer/reset
/vis/viewer/set/style          surface
/vis/viewer/zoom               1.1 
/vis/viewer/set/viewpointThetaPhi  35 45
/vis/drawVolume                Absorber 
/vis/scene/add/axes            0 0 0 500 mm
/vis/scene/add/text            0 0 0 mm  40 -100 -140   Absorber 
/vis/viewer/flush

# Bird's-eye view of the whole detector components
#  * "/vis/viewer/set/culling global false" makes the invisible 
#    world volume visible.
#    (The invisibility of the world volume is set 
#     in ExN03DetectorConstruction.cc.)
/vis/viewer/set/style     wireframe
/vis/viewer/set/culling   global false
/vis/drawVolume
/vis/scene/add/axes       0 0 0 500 mm
/vis/scene/add/text       0 0 0 mm 50 -50 -200   world
/vis/viewer/flush
################### END of vis1.mac ###################

2.10.5.2 `Visualization of events`

The following session visualizes events (tajectories) with the OpenGL-Xlib driver and then with the DAWNFILE driver. The former exhibits minimal visualization commands to visualize events, while the latter exhibits customized visualization. Note that the run action and event action classes should be described properly. (See, for example, the following classes:
"examples/novice/N03/src/ExN03RunAction.cc", "examples/novice/N03/src/ExN03EventAction.cc").

###################################################
#  vis2.mac:
#    A Sample macro to demonstrate visualization 
#    of events (trajectories).
#
#  USAGE: 
#   Save the commands below as a macro file, say, 
#   "vis2.mac", and execute it as follows:
#
#   % $(G4BINDIR)/exampleN03
#   Idle> /control/execute vis1.mac
#############################################

#####################################################
# Store particle trajectories for visualization
/tracking/storeTrajectory 1
#####################################################

########################################################
# Visualization with the OGLSX (OpenGL Stored X) driver
########################################################

# Invoke the OGLSX driver 
#  Create a scene handler and a viewer for the OGLSX driver
/vis/open OGLSX

# Create an empty scene and add detector components to it
/vis/drawVolume

# Add trajectories to the current scene
#  Note: This command is not necessary in, e.g., 
#        examples/novice/N03, since the C++ method DrawTrajectory() 
#        is described in the event action.
#/vis/scene/add/trajectories

# Set viewing parameters
/vis/viewer/reset
/vis/viewer/set/viewpointThetaPhi  10 20

# Visualize one it.
/run/beamOn 1

##########################################################
# Visualization with the DAWNFILE driver
##########################################################

# Invoke the DAWNFILE driver 
#  Create a scene handler and a viewer for the DAWNFILE driver
/vis/open DAWNFILE

# Create an empty scene and add detector components to it
/vis/drawVolume

# Add trajectories to the current scene
#  Note: This command is not necessary in exampleN03,
#        since the C++ method DrawTrajectory() is 
#        described in the event action.
#/vis/scene/add/trajectories

# Visualize plural events (bird's eye view)
#  drawing style: wireframe
#  viewpoint  : (theta,phi) = (45*deg, 45*deg) 
#  zoom factor: 1.5 x (full screen size)
/vis/viewer/reset
/vis/viewer/set/style  wireframe
/vis/viewer/set/viewpointThetaPhi   45 45
/vis/viewer/zoom        1.5
/run/beamOn             2

# Set the drawing style to "surface" 
#  Candidates: wireframe, surface
/vis/viewer/set/style  surface

# Visualize plural events (bird's eye view) again
#  with another drawing style (surface)
/run/beamOn             2

################### END of vis2.mac ###################

2.10.6 For More Information on Geant4 Visualization

See the Visualization part of this user guide.

About the authors