| Geant4 User's Guide For Application Developers Visualization

8.4 Controlling Visualization from Commands

This section describes just a few of the more commonly used visualization commands. For the complete list of commands and options, see the Control...UICommands section of this user guide.

For simplicity, this section assumes that the Geant4 executable was compiled incorporating the DAWNFILE and the OpenGL-Xlib drivers. For details on creating an executable for visualization see Section 8.2 .

#### 8.4.1 Scene, scene handler, and viewer

In using the visualization commands, it is useful to know the concept of "scene", "scene handler", and "viewer". A "scene" is a set of visualizable raw 3D data. A "scene handler" is a graphics-data modeler, which processes raw data in a scene for later visualization. And a "viewer" generates images based on data processed by a scene handler. Roughly speaking, a set of a scene handler and a viewer corresponds to a visualization driver.

The steps of performing Geant4 visualization are explained below, though some of these steps may be done for you so that in practice you may use as few as just two commands (such as /vis/open OGLIX plus /vis/drawVolume) The seven steps of visualization are: :
Step 1. Create a scene handler and a viewer.
Step 2. Create an empty scene.
Step 3. Add raw 3D data to the created scene.
Step 4. Attach the current scene handler to the current scene.
Step 5. Set camera parameters, drawing style (wireframe/surface), etc.
Step 6. Make the viewer execute visualization.
Step 7. Declare the end of visualization for flushing.

These seven steps can be controlled explicitly to create multiple scenes and multiple viewers, each with its own set of parameters, with easy switching from one scene to another. But for the most common case of just having one scene and one viewer, many steps are handled implicitly for you.

#### 8.4.2 Create a scene handler and a viewer: `/vis/open` command

Command "`/vis/open`" creates a scene handler and a viewer, which corresponds to Step 1.

- Command
  `/vis/open [driver_tag_name]`
- Argument
  A name of (a mode of) an available visualization driver.
- Action
  Create a visualization driver, i.e. a set of a scene hander and a viewer.
- Example: Create the OpenGL-Xlib driver with its immediate mode
  `Idle> /vis/open OGLIX`
- Additional notes
  For immediate viewers, such as OGLIX, your geometry will immediately be rendered in the new GL window
  How to list available driver_tag_name:
  `Idle> help /vis/open`
  or
  `Idle> help /vis/sceneHandler/create`
  The list is, for example, displayed as follows:
  .....
  `Candidates : DAWNFILE OGLIX OGLSX`
  .....
- For additional options, see the Control...UICommands section of this user guide.

#### 8.4.3 Create an empty scene: `/vis/scene/create` command

Command "`/vis/scene/create`" creates an empty scene, which corresponds to Step 2.

- Command
  `/vis/scene/create [scene_name]`
- Argument
  A name for this scene. Created for you if you don't specify one.

#### 8.4.4 Visualization of a physical volume: `/vis/drawVolume` command

Command "`/vis/drawVolume`" adds a physical volume to the scene. It also does some of the other steps, if you haven't done them explicitly. It takes care of steps 2, 3, 4 and 6. Command "`/vis/viewer/flush`" should follow in order to do the final Step 7.

- Commands
  `/vis/drawVolume [physical-volume-name]`
  `.....`
  `Idle> /vis/viewer/flush`
- Argument
  A physical-volume name. The default value is "world", which is omittable.
- Action
  Creates a scene consisting of the given physical volume and asks the current viewer to draw it. The scene becomes current. Command "`/vis/viewer/flush`" should follow this command in order to declare end of visualization.
- Example: Visualization of the whole world with coordinate axes
  `Idle> /vis/drawVolume`
  `Idle> /vis/scene/add/axes 0 0 0 500 mm`
  `Idle> /vis/viewer/flush`

#### 8.4.5 Visualization of a logical volume: `/vis/specify` command

Command "`/vis/specify`" visualizes a logical volume. If allows you to control how much details is shown and whether to show booleans, voxels and readout geometries. It also does some of the other steps, if you haven't done them explicitly. It takes care of steps 2, 3, 4 and 6. Command "`/vis/viewer/flush`" should follow the command in order to do the final Step 7.

- Command
  `/vis/specify [logical-volume-name][depth-of-descent] [booleans-flag] [voxels-flag] [readout-flag]`
- Argument
  A logical-volume name.
- Action
  Creates a scene consisting of the given logical volume and asks the current viewer to draw it. The scene becomes current.
- Example (visualization of a selected logical volume with coordinate axes)
  `Idle> /vis/specify Absorber`
  `Idle> /vis/scene/add/axes 0 0 0 500 mm`
  `Idle> /vis/scene/add/text 0 0 0 mm 40 -100 -200 LogVol:Absorber`
  `Idle> /vis/viewer/flush`

For more options, see the Control...UICommands section of this user guide.

#### 8.4.6 Visualization of trajectories: `/vis/scene/add/trajectories` command

Command "`/vis/scene/add/trajectories`" adds trajectories to the current scene. Note that this automatically issues "`/tracking/storeTrajectory 1`" so that trajectories are stored (by default they are not). The visualization is performed with the command "`/run/beamOn`" unless you have non-default values for /vis/scene/endOfEventAction or /vis/scene/endOfRunAction (described below).

- Command
  `/vis/scene/add/trajectories [drawing-mode]`
- Action
  The command adds trajectories to the current scene. Trajectories are drawn at end of event when the scene in which they are added is current.
- Example: Visualization of trajectories
  `Idle> /vis/scene/add/trajectories`
  `Idle> /run/beamOn 10`
- Additional note 1
  See the section Enhanced Trajectory Drawing for details on how to control how trajectories are color-coded.
- Additional note 2
  In examples/novice/N03, command "`/vis/scene/add/trajectories`" need not be executed, since the C++ method `G4Trajectory::DrawTrajectory()` is explicitly described in the event action. Therefore the command need not be executed though (G)UI.

For more options, see the Control...UICommands section of this user guide.

#### 8.4.7 Visualization of hits: `/vis/scene/add/hits` command

Command "`/vis/scene/add/hits`" adds hits to the current scene, assuming that you have a hit class and that the hits have visualization information. The visualization is performed with the command "`/run/beamOn`" unless you have non-default values for /vis/scene/endOfEventAction or /vis/scene/endOfRunAction (described above).

#### 8.4.8 HepRep Attributes for Hits

The HepRep file formats, HepRepFile and HepRepXML, attach various attributes to hits such that you can view these attributes, label trajectories by these attributes or make visibility cuts based on these attributes. Examples of adding HepRep attributes to hit classes can be found in examples /extended/analysis/A01 and /extended/runAndEvent/RE01.

For example, in example RE01's class RE01CalorimeterHit.cc, available attributes will be:

- Hit Type
- Track ID
- Z Cell ID
- Phi Cell ID
- Energy Deposited
- Energy Deposited by Track
- Position
- Logical Volume

You can add additional attributes of your choosing by modifying the relevant part of the hit class (look for the methods GetAttDefs and CreateAttValues).

#### 8.4.9 Basic camera workings: `/vis/viewer/` commands

Commands in the command directory "`/vis/viewer/`" set camera parameters and drawing style of the current viewer, which corresponds to Step 5. Note that the camera parameters and the drawing style should be set separately for each viewer. They can be initialized to the default values with command "`/vis/viewer/reset`". Some visualization systems, such as the VRML and HepRep browsers also allow camera control from the standalone graphics application.

Just a few of the camera commands are described here. For more commands, see the Control...UICommands section of this user guide.

- Command
  `/vis/viewer/set/viewpointThetaPhi [theta] [phi] [deg|rad]`
- Arguments
  Arguments "theta" and "phi" are polar and azimuthal camera angles, respectively. The default unit is "degree".
- Action
  Set a view point in direction of (theta, phi).
- Example: Set the viewpoint in direction of (70 deg, 20 deg)
  `Idle> /vis/viewer/set/viewpointThetaPhi 70 20`
- Additional notes
  Camera parameters should be set for each viewer. They are initialized with command "`/vis/viewer/reset`".

- Command
  `/vis/viewer/zoom [scale_factor]`
- Argument
  The scale factor. The command multiplies magnification of the view by this factor.
- Action
  Zoom up/down of view.
- Example: Zoom up by factor 1.5
  `Idle> /vis/viewer/zoom 1.5`
- Additional notes
  Camera parameters should be set for each viewer. They are initialized with command "`/vis/viewer/reset`".
  A similar pair of commands, scale and scaleTo allow non-uniform scaling (i.e., zoom differently along different axes). For details, see the Control...UICommands section of this user guide.

- Command
  `/vis/viewer/set/style [style_name]`
- Arguments
  Candidate values of the argument are "wireframe" and "surface". ("w" and "s" also work.)
- Action
  Set a drawing style to wireframe or surface.
- Example: Set the drawing style to "surface"
  `Idle> /vis/viewer/set/style surface`
- Additional notes
  The style of some geometry components may have been forced one way or the other through calls in compiled code. The set/style command will NOT override such force styles.
  Drawing style should be set for each viewer. The drawing style is initialized with command "`/vis/viewer/reset`".

#### 8.4.10 Declare the end of visualization for flushing: `/vis/viewer/flush` command

- Command
  `/vis/viewer/flush`
- Action
  Declare the end of visualization for flushing.
- Additional notes
  Command "`/vis/viewer/flush`" should follow "`/vis/drawVolume`", "`/vis/specify`", etc in order to complete visualization. It corresponds to Step 7.
  The flush is done automatically after every /run/beamOn command unless you have non-default values for /vis/scene/endOfEventAction or /vis/scene/endOfRunAction (described above).

#### 8.4.11 End of Event Action and End of Run Action: `/vis/viewer/endOfEventAction` and `/vis/viewer/endOfEventAction` commands

By default, a separate picture is created for each event. You can change this behavior to accumulate multiple events, or even multiple runs, in a single picture.

- Command
  `/vis/scene/endOfEventAction [refresh|accumulate]`
- Action
  Control how often the picture should be cleared.
  `refresh` means each event will be written to a new picture.
  `accumulate` means events will be accumulated into a single picture. Picture will be flushed at end of run, unless you have also set `/vis/scene/endOfRunAction accumulate`
- Additional note
  You may instead choose to use update commands from your BeginOfRunAction or EndOfEventAction, as in early examples, but now the vis manager ia able to do most of what most users require through the above commands.

- Command
  `/vis/scene/endOfRunAction [refresh|accumulate]`
- Action
  Control how often the picture should be cleared.
  `refresh` means each run will be written to a new picture.
  `accumulate` means runs will be accumulated into a single picture. To start a new picture, you must explicitly issue `/vis/viewer/refresh`, `/vis/viewer/update` or `/vis/viewer/flush`

#### 8.4.12 HepRep Attributes for Trajectories

The HepRep file formats, HepRepFile and HepRepXML, attach various attributes to trajectories such that you can view these attributes, label trajectories by these attributes or make visibility cuts based on these attributes. If you use the default Geant4 trajectory class, from /tracking/src/G4Trajectory.cc, available attributes will be:

- Track ID
- Parent ID
- Particle Name
- Charge
- PDG Encoding
- Momentum 3-Vector
- Momentum magnitude
- Number of points

You can add additional attributes of your choosing by modifying the relevant part of G4Trajectory (look for the methods GetAttDefs and CreateAttValues). If you are using your own trajectory class, you may want to consider copying these methods from G4Trajectory.

#### 8.4.13 How to save a visualized views to PostScript files

Most of the visualization drivers offer ways to save visualized views to PostScript files (or Encapsulated PostScript (EPS) files) by themselves.

The DAWNFILE driver, which co-works with Fukui Renderer DAWN, generates "vectorized" PostScript data with "analytical hidden-line/surface removal", and so it is well suited for technical high-quality outputs for presentation, documentation, and debugging geometry. In the default setting of the DAWNFILE drivers, EPS files named "`g4_00.eps, g4_01.eps, g4_02.eps`,..." are automatically generated in the current directory each time when visualization is performed, and then a PostScript viewer "`gv`"is automatically invoked to visualize the generated EPS files.

For large data sets, it may take time to generate the vectorized PostScript data. In such a case, visualize the 3D scene with a faster visualization driver beforehand for previewing, and then use the DAWNFILE drivers. For example, the following visualizes the whole detector with the OpenGL-Xlib driver (immediate mode) first, and then with the DAWNFILE driver to generate an EPS file `g4_XX.eps` to save the visualized view:

    # Invoke the OpenGL visualization driver in its immediate mode
    /vis/open OGLIX

    # Camera setting
    /vis/viewer/set/viewpointThetaPhi 20 20

    # Camera setting
    /vis/drawVolume
    /vis/viewer/flush

    # Invoke the DAWNFILE visualization driver
    /vis/open DAWNFILE

    # Camera setting
    /vis/viewer/set/viewpointThetaPhi 20 20

    # Camera setting
    /vis/drawVolume
    /vis/viewer/flush

This is a good example to show that the visualization drivers are complementary to each other.

In the OpenInventor drivers , you can simply click the "Print" button on their GUI to generate a PostScript file as a hard copy of a visualized view.

The OpenGL-Motif driver also has a menu to generate PostScript files. It can generate either vectorized or rasterized PostScript data. In generating vectorized PostScript data, hidden-surface removal is performed, based on the painter's algorithm after dividing facets of shapes into small sub-triangles.

The WIRED3 HepRep Browser and WIRED4 JAS Plug-In can generate a wide variety of bitmap and vector output formats including PostScript and PDF.

#### 8.4.14 Culling

"Culling" means to skip visualizing parts of a 3D scene. Culling is useful for avoiding complexity of visualized views, keeping transparent features of the 3D scene, and for quick visualization.

Geant4 Visualization supports the following 3 kinds of culling:

- Culling of invisible physical volumes
- Culling of low density physical volumes.
- Culling of covered physical volumes by others

In order that one or all types of the above culling are on, i.e., activated, the global culling flag should also be on.

Table 8.4.1 summarizes the default culling policies.

Culling Type | Default Value
global | ON
invisible | ON
low density | OFF
covered daughter | OFF
Table 8.4.1 The default culling policies.

The default threshold density of the low-density culling is 0.01 g/cm3.

The default culling policies can be modified with the following visualization commands. (Below the argument `flag` takes a value of `true` or `false`.)

         # global
         /vis/viewer/set/culling  global  flag

         # invisible
         /vis/viewer/set/culling  invisible  flag

         # low density
         #   "value" is a proper value of a treshold density
         #   "unit" is either g/cm3, mg/cm3 or kg/m3
         /vis/viewer/set/culling  density  flag  value  unit

         # covered daughter
         /vis/viewer/set/culling  coveredDaughters  flag     density

The HepRepFile graphic system will, by default, include culled objects in the file so that they can still be made visible later from controls in the HepRep browser. If this behavior would cause files to be too large, you can instead choose to have culled objects be omitted from the HepRep file. See details in the HepRepFile Driver section of this user guide.

#### 8.4.15 Cut view

#### Sectioning

"Sectioning" means to make a thin slice of a 3D scene around a given plane. At present, this function is supported by the OpenGL drivers. The sectioning is realized by setting a sectioning plane before performing visualization. The sectioning plane can be set by the command,

         /vis/viewer/set/sectionPlane on x y z units nx ny nz

where the vector (x,y,z) defines a point on the sectioning plane, and the vector (nx,ny,nz) defines the normal vector of the sectioning plane. For example, the following sets a sectioning plane to a yz plane at x = 2 cm:

         Idle> /vis/viewer/set/sectionPlane  on  2.0  0.0  0.0  cm  1.0  0.0  0.0

#### Cutting away

"Cutting away" means to remove a half space, defined with a plane, from a 3D scene.

- Cutting away is supported by the DAWNFILE driver "off-line". Do the following:
  - Perform visualization with the DAWNFILE driver to generate a file `g4.prim`, describing the whole 3D scene.
  - Make the application "DAWNCUT" read the generated file to make a view of cutting away.
  See the following WWW page for details: http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWNCUT.html.

- Alternatively, add up to three cutaway planes:

           /vis/viewer/addCutawayPlane 0 0 0 m 1 0 0
           /vis/viewer/addCutawayPlane 0 0 0 m 0 1 0
           ...

  and, for more that one plane, you can change the mode to
  - (a) "add" or, equivalently, "union" (default) or
  - (b) "multiply" or, equivalently, "intersection":

           /vis/viewer/set/cutawayMode multiply

  To de-activate:

           /vis/viewer/clearCutawayPlanes

  OpenGL supports this feature.

#### 8.4.16 Tutorial macros

The followings are tutorial macros in the directory `examples/novice/N03/visTutor/`:

- exN03Vis0.mac:
  A basic macro for visualization of detector geometry and events using OpenGL in Immediate mode and DAWN.
- exN03Vis1.mac:
  A basic macro for visualization of detector geometry using OpenGL in Stored mode and DAWN.
- exN03Vis2.mac:
  A basic macro for visualization of detector geometry and events using OpenGL in Stored mode and DAWN.
- exN03Vis3.mac:
  A basic macro for demonstrating various drawing styles using OpenGL in Immediate mode and DAWN.
- exN03Vis4.mac:
  An example of visualizing specific logical volumes using OpenGL in Immediate mode and DAWN.
- exN03Vis5.mac:
  A basic macro for visualization of detector geometry and events using OpenInventor on Unix.
- exN03Vis6.mac:
  A basic macro for visualization of detector geometry and events using VRML.
- exN03Vis7.mac:
  A macro to demonstrate "batch" visualization to generate PostScript files with the DAWNFILE driver
- exN03Vis8.mac:
  A macro to demonstrate creation of a "multi-page" PostScript file with the DAWNFILE driver
- exN03Vis9.mac:
  A basic macro for visualization of detector geometry and events using OpenGL for Windows.
- exN03Vis10.mac:
  A basic macro for visualization of detector geometry and events using OpenInventor on Windows.
- exN03Vis11.mac:
  A basic macro for visualization of detector geometry and events using OpenGL in Stored Motif mode and DAWN.
- exN03Vis12.mac and exN03Vis12.loop:
  A basic macro for demonstrating time slicing.
- exN03Vis13.mac and exN03Vis13.loop:
  Time development of an electrmagnetic shower.
- exN03Tree0.mac:
  A macro to demonstrate ASCII tree.
- exN03Tree1.mac:
  A macro to demonstrate GAG tree.

Next section
Back to contents