SLAC logo HepRApp logo
Geant4 Visualization Tutorial using the HepRApp HepRep Browser


This tutorial is designed for anyone who wants to learn HepRApp Visualization for Geant4.

The tutorial can be used on its own, but gives the most comprehensive introduction to Geant4 visualization when used as part of the following full set of documents:

When you run Geant4 visualization using

   /vis/open HepRepFile
Your output comes in a graphics file in a format called HepRep (for High Energy Physics REPresentables). This visualization tutorial will show you how to use the HepRApp HepRep Browser to view that HepRep file (or an equivalent file included with this tutorial - see details later).

HepRApp is written as 100 percent pure Java to provide a true "runs anywhere" capability. It is currently being used on all versions of Windows (from Windows 95 to XP and Vista), Linux, Unix and Mac OSX. HepRApp, and the HepRep graphics protocol, are general purpose tools that can read data from many sources (such as the BaBar collaboration's offline and live data servers and the GLAST collaboration's Gaudi services).

Complete instructions on installation and operation of the HepRApp HepRep Browser, along with many additional references, can be found at the HepRApp Users Home Page. But this present document should have enough instructions to get you going.

The .heprep File

HepRApp's input is something called a .heprep file. The .heprep file is a plain text file format that contains a full 3D description of what is to be drawn (geometry, trajectories, hits, markers - depending on what you chose to add from Geant4) plus visualization attributes (such as color and linestyle) and an extensible set of additional physics attributes (such as momentum, particle name and energy).

You don't really need to understand the details of the .heprep file format to use HepRApp, but in case you are interested:

The .heprep file format is fairly easy to understand just by looking at it. Here are some lines from one example:

<heprep xmlns=""
  xmlns:xsi="" xsi:schemaLocation="HepRep.xsd">
  <layerorder="Detector, Event, CalHit, Trajectory, TrajectoryPoint, Hit"/>
  <typetree name="G4GeometryTypes" version="1.0">
    <type name="Detector">
      <attvalue name="Layer" showLabel="NONE" type="String" value="Detector"/>
      <attdef category="Physics" desc="Logical Volume" extra="" name="LVol"/>
      <attdef category="Physics" desc="Material Name" extra="" name="Material"/>
      <type name="Detector/World">
        <type name="Detector/World/Calorimeter">
          <type name="Detector/World/Calorimeter/Layer">
            <type name="Detector/World/Calorimeter/Layer/Lead">
  <typetree name="G4EventTypes" version="1.0">
    <type name="Event">
      <attvalue name="Layer" showLabel="NONE" type="String" value="Event"/>
      <type name="Event/Trajectory">

If you have not yet produced your own HepRep file, this might be a good time to do so.

You can also skip running Geant4 for now and instead find a copy of Geant4 example A01's HepRep file here (this version differs from the one you would have created yourself only in that this version has been compressed using gzip - this saves a factor of about 20 in space and can still be read directly by WIRED3, no need to unzip).

The commands to generate a .heprep file from a typical example such as example A01 are:

  /vis/open HepRepFile
  /run/beamOn 1
At the first "/vis/viewer/flush", a .heprep file is produced that contains only detector geometry.
At the "/run/beamOn 1", a second .heprep file is produced that contains geometry plus trajectories and hits. This file is produced because the "/run/beamOn" automatically does a "/vis/viewer/flush".

Other commands that might be useful are discussed in this document's section called Further Resources. Ignore any commands related to setting camera views, lighting or surface style. Those commands are only relevant to an immediate visualization driver such as OpenGL. When you work with a driver such as HepRepFile that has a 3D file format, you set these things later, from the visualization application, HepRApp.

Installing and Starting

The installation instructions are taken from the HepRApp Users Home Page in April 2007. If significant time has passed since that date, or if you just want more detailed information, please check back with that original source.

Nothing could be simpler than installing HepRApp. The application comes as one simple file, HepRApp.jar.

If you are on Mac or Windows (or some other systems that have automatic association of jar files with Java), just click on this file to start the application.

The first time you run HepRApp, it will immediately open the "Select Group" menu. This is where you can specify whether HepRApp should run with any special settings for known groups (currently the BaBar and GLAST experimental collaborations). As a Geant4 user, you should just select the option called "Standard".

You can also revisit this setting at any time from the Options menu. The setting you make here, along with many other settings you make as you work in HepRApp, will be stored in a file called "" that will be created in the directory from which you ran HepRApp.

If all is well at this point, procede to the HepRApp Tour for Geant4 Users.

If the application did not start correctly, there is probably a problem with your version of Java. Read the next section right here.

Checking Your Java Version or Installing a new Java

HepRApp requires Java version 1.4.1 or greater, and your Java MUST NOT Be one called libgcj.

You can check the version number by typing the following from a terminal window (or on Windows, a command or cygwin window):

   java -version

If the response includes the words "libgcj", watch out, this is not a real Java version. Rather, it is a minimal version that some Linux distributions include as a place-holder for a real Java. While it may be sufficient to run some simple web applets, it is not sufficient to run serious Java applications such as HepRApp.

Some users of Ubuntu Linux have reported problems with Java version 1.6. They suggested to upgrade to 1.7.

If you don't already have the appropriate Java:

Additional notes for Linux users:

HepRApp Tour for Geant4 Users

The Main Toolbar

Use the Open Data button to select some data.
You should see a new window as follows:
Open Data Dialog

You can also use the "-file" startup to have HepRApp start right off with a particular heprep file (either from local disk or from the web). You do this either by:

Use the reload button to reread data that may have changed.

If you are reading files from disk (rather than a URL), you can always quickly go to the next file produced by Geant4 by hitting the right arrow button at the top of the window. This "next event" button always gets the next .heprep or .heprep.gz file alphabetically in the current file's directory. Since each new picture produced from Geant4 has a sequential heprep file name, this button gets you the next Geant4 picture. Note that it will be the next or previous file of the exact same file extension. Thus if there is a mix of .heprep and .heprep.gz files, it will skip some of those files.

You may notice that the web accessible files have the suffix ".heprep.gz" whereas the version you make directly from Geant has just ".heprep". This is because HepRApp can accept gzipped HepRep files as easily as unzipped HepRep files. Unzipped HepRep is an easy format for people to read and, if necessary, edit (it is an XML format), but the files can get very large. GZipping solves this problem, compressing the files to about five percent of their original size.

Regardless of how you open the file, you should end up with an image as follows :

The other options on the File Chooser are not relevant to this G4 tutorial but are discussed in detail in the HepRApp Users Home Page.

Orientation Toolbar

The bottom of the view window contains the Orientation Toolbar. These buttons control zoom, rotate and translation functions (later you will learn how to also control these with various mouse drag operations).

the rest of the orientation toolbar

The following shows a rotation around the screen's horizontal axis.

Orientation Actions in the Popup View Menu

To select from among some standard views, place the cursor into the window that contains the event display and hit the right mouse button (Macintosh users, hit control and mouse button). You should see a new window as follows:

Then select "Orientation Actions", which will give the following submenu:

Use these options to select standard views or reset to the initial view. "Top View", for example, will give you the following:

which will make a little more sense if you then hit the "Fit to Window" button:

So you then see the following:
The rest of the popup view menu will be discussed later.

Data Visibility Tree

use the Data Visibility Tree to toggle on and off visibility of data and detector elements.
A tree will appear at the right side of the main window. Widen the main window a little by dragging on the window's right side. You should then see the following:

Interaction Between View Window and Data Visibility Tree

Picking on objects in the view window can cause them to highlight in the Data Visibility Tree, and the opposite is also true.


HepRApp can label any object with any of its HepRep attributes. For example, the label could appear as follows:

Labelling follows the flexible scheme envisioned in the HepRep standard. For example, if there is a Track that has a Transverse Momentum of 3.143 GeV, you can choose to

Labels are anchored to whatever point of the object appears closest to a screen edge. This has the desireable affect that when you zoom in on a track, while the end of the track may fall off the screen, the label will slide along the track, remaining on the screen, unless the track falls completely off the screen.

You can reposition labels by hand if you need to.

Labels can be controlled from a Label Control Dialog or from startup options.


HepRApp can hide objects based on cuts that you provide. For example, you could cut out all calorimeter clusters that have less than some specified energy. Cuts can be based on any HepRep attribute.

Cuts can be controlled from a Cut Control Dialog or from startup options.

The type of value tested can be either integer, float or string as long as it matches the type of value of the relevant HepRep attribute (which can be seen from the attribute popup or by using the labelling feature.

Whenever cuts are in force, the cut will be listed in the lower right corner of the view window, and this list will be included in any exported graphics.

Specialized Projections

The HepRApp HepRep Browser can perform many specialized projections that distort the visualized space in useful ways. Because some of these projections assume a cylindrical detector design, read in a more appropriate detector geometry file before proceeding with the tutorial.

When the image appears, reset to standard scale and rotation by using the Reset button at the lower left corner of the view window. Also, undo any left over picking information by picking on an empty area of the image. You should end up with an image as follows:

The image shows a simplified rendition of the BaBar detector with real data from the collision of an electron with a positron at the PEPII accelerator at SLAC.

A good example of a specialized projection is the "FishEye Projection". From the Popup View menu, select "Projection"..."FishEye". You should then see the following:

The FishEye has distorted the space such that the inner parts of the detector are exanded while the outer parts of the detector are compressed. This can be superior to a standard zoom since, while it allows a close inspection of the inner area, it still allows one to correlate inner detector data with outer detector data.

With the specialized projection comes a specialized mouse function. Try clicking the mouse near the center of the image and then dragging outward. The FishEye quality will be enhanced (you have altered the FishEye's "alpha" parameter), such as in the following:

Two more examples of projections are:

Return to the Parallel Projection before continuing with the tutorial.

Multiple View Windows

To open additional view windows, click the "New View" button.
You will then see two views as follows:

You can then control the views separately. The following example shows four views:
Each view has its own Data Visibility Tree. The visibility tree that is shown at the right always corresponds to the currently selected view.


To print the selected view directly to a printer (as a bitmapped image), click on the File Menu's "Print..." option. Your regular system printer selection dialog will then take over. For many higher quality print options, including vector PostScript, select the File Menu's "Export Graphics...".

Additional Mouse Functions

You have already seen the mouse used for picking objects to see their attributes, and for adjusting the FishEye projection's alpha parameter. The Popup View Menu's "Mouse Function" menu lets you also configure the mouse in other ways:

Additional Buttons on the Top Button Bar

The up and down buttons are not relevant to data from HepRep files. They are only used when navigating events from a HepEventServer. See details in the HepRApp Users Home Page.

The Auto Update button causes HepRApp to automatically cycle through HepRep files in the current directory. It is equivalent to repeatedly pressing the next event button. You can adjust the update rate from the Options Menu.

Additional Items in the Popup View Menu

Allocating More Memory to HepRApp

By default, Java will only allocate 250M of memory to HepRApp. This can be too small for complex visualizations.

To tell Java to allocate more memory, run java from the command line with the "-mx" option.

For example, the following will allocate 1000M of memory:

  java -jar -mx1000M HepRApp.jar

Environment Variables to Control How Geant4 Produces HepRep Files

By default, the Geant4 HepRepFile driver will write a file called G4Data0.heprep to the current directory.
Each subsequent file will have a file name like G4Data1.heprep, G4Data2.heprep, etc.

Geant4 visualization supports a concept called "culling", by which certain parts of the detector can be made invisible.

G4RichTrajectory: Getting More Pickable Information from the Trajectory Step Points

By default, Geant4 Trajectories are drawn as polylines with no specific symbols for step points. But you can specify additional commands to make trajectories include dots for step points and you can adjust the size and color of these dots. Sample commands are:
   /vis/modeling/trajectories/generic-0/default/setLineColour blue
   /vis/modeling/trajectories/generic-0/default/setDrawLine false
   /vis/modeling/trajectories/generic-0/default/setDrawAuxPts true
   /vis/modeling/trajectories/generic-0/default/setDrawStepPts true
   /vis/modeling/trajectories/generic-0/default/setStepPtsSize 5
   /vis/modeling/trajectories/generic-0/default/setAuxPtsSize 5
   /vis/modeling/trajectories/generic-0/default/setAuxPtsColour yellow
   /vis/modeling/trajectories/generic-0/default/setStepPtsColour red
   /vis/modeling/trajectories/generic-0/default/setStepPtsColour red
   /vis/modeling/trajectories/generic-0/default/setStepPtsType circles

By default, these step points will not have any HepRep attributes. Picking on these points in HepRApp will not give you any specific information about those points.

But with a slightly different form of the command

you can tell Geant4 to generate points that contain a wealth of additional HepRep information. Just use:
   /vis/scene/add/trajectories rich
The cost is that the HepRep file will now be larger (and Geant4 will run slightly more slowly, since it has to write this additional information). But now each step point will have extra information that will be displayed when you pick on the point in HepRApp: For more details on use of Rich Trajectories, and the other /vis/modeling and /vis/filtering commands, see Geant4 Advanced Visualization (ppt, pdf)

Recap of Geant4 Commands Used in this Tutorial

If you need to quickly repeat the commands to generate the .heprep file, it may be helpful to cut and paste a set of commands from this list:
  /vis/open HepRepFile
  /run/beamOn 1

Further Resources

Documents in this Visualization Tutorial Set:

Other Resources:

Joseph Perl

10 November 2009