SLAC logo WIRED logo
Geant4 Workshop Visualization Tutorial using the WIRED Event Display

Introduction

This tutorial has been updated for use at the October 2003 Fermilab Geant4 Tutorial, but is also designed for use by anyone else who wants to learn WIRED Visualization for Geant4.

This 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:

The basic Geant 4 Tutorial had users run a basic Geant 4 job contained in

   geant4/source/examples/extended/analysis/A01

This job produced various kinds of output including a graphics file in a format called HepRep (for High Energy Physics REPresentables). This visualization tutorial will show you how to use the WIRED Event Display to view that HepRep file (or an equivalent file included with this tutorial - see details later).

WIRED is a 100 percent pure Java application that can run anywhere that Java version 1.4.1 or newer is installed. It is currently being used on all versions of Windows (from Windows 95 to the latest), Linux, Unix and Mac OSX. WIRED, 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 EGS shower simulation program).

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


The .heprep File

WIRED'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 WIRED, 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="http://www.freehep.org/HepRep"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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">
            </type>
          </type>
        </type>
      </type>
    </type>
  </typetree>
  <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 run the A01 tutorial, this might be a good time to do so. You will then have a file called:
geant4\examples\extended\analysis\A01\G4Data1.heprep

You can also skip running Geant4 for now and instead find a copy of this 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 WIRED, no need to unzip).

The commands from that example that generated the .heprep file were:

../bin/$G4SYSTEM/A01app
/vis/open HepRepFile
/vis/scene/create
/vis/scene/add/volume
/vis/sceneHandler/attach
/vis/viewer/flush
/vis/scene/add/trajectories
/vis/scene/add/hits
/tracking/storeTrajectory 1
/run/beamOn 1

The output appears as soon as the /run/beamOn is complete since an update command is included in this example's RunAction class. If you run some other example and find that the event doesn't draw automatically at the end of the run, just issue the following command:
   /vis/viewer/flush

You can even put this command into a macro file and then cause this macro to be called at the end of each event by adding the macro name to the run command, as in:
   /run/beamOn 1 my.mac

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 DAWN that has a 3D file format, you set these things later, from the visualizaton application, DAWN.


Installation

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

Users are encouraged to install and run WIRED on their desktop machines rather than running it via x-windows from central Unix systems. Wired will work either way, but the best performance comes when it runs on the desktop (and this frees central Unix CPUs for more suitable work).

Installing Java

Start by making sure you have an appropriate version of Java on your system, a version number of 1.4.1 or greater. You can check the version number by typing the following from a command or cygwin window:
   java -version

If you don't already have the appropriate Java:

Installing WIRED

Note that the WIRED installer does not make any changes to your registry or other system files. You can always remove WIRED by just deleting the single directory structure into which WIRED is installed. So don't worry - give it a try on any machine.

To download WIRED, copy a single file of about 7M to your own directory (it doesn't matter where you put it, the install procedure will later ask you where you really want to install WIRED). Take the file from:

Open a command window and go to the directory where install.class is located. Before you actually run the installer, note one thing:

Now run the installer by typing the following command:

   java -cp . install

If you are running through x-windows, the install procedure may have trouble getting the correct fonts to show the install dialog boxes. You can instead just skip the dialog boxes by typing:

   java -cp . install /p
The result will be as if you had selected all of the default options. Wired will be installed to the directory "Wired".

Running WIRED

Starting WIRED

The executable is in Wired's bin directory. Run it by typing:
   wired

There are large number of additional startup options that most users will never need.

Additional Notes for Cygwin, Linux, Windows ME, Windows 98 and Windows 95 Users

You should see an empty WIRED window as follows:
Empty WIRED Image

Event Chooser

Use the Event Chooser to select some data. You should see a new window as follows:
Event Chooser

You can also use the "-file" startup option to have WIRED start right off with a particular heprep file (either from local disk or from the web). Examples might be:

   wired -file wired -file c:\jp\slac\geant4\G4VisTutorial\G4WIREDTutorial\G4Data0.heprep
   wired -file /afs/mydir/mysubdir/G4Data0.heprep.gz
   wired -file http://www.slac.stanford.edu/~perl/heprepxml/G4Data0.heprep.gz


And 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 event's directory. Since each new event produced from Geant4 has a sequential heprep file name, this button gets you the next Geant4 event.

You may notice that the CD and web accessible files have the suffix ".heprep.gz" whereas the version you make directly from Geant has just ".heprep". This is because WIRED 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 SLAC WIRED 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:

Again use the "Fit To Window" button to make the entire image fit in the window. The rest of the popup view menu will be discussed later.

Event Visibility Control

use the Event Visibility Control 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 Event Visibility Tree

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

Specialized Projections

The WIRED Event Display can perform many specialized projections that distort the detector 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 Popup View menu (the menu you get by right clicking on the view window) and selecting "Orientation Actions"..."Reset". 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.
Then from the "Window" menu, select "Tile" to lay out the two views as follows:

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

Printing

To print the selected view directly to a printer (as a bitmapped image), click on the printer icon. Your regular system printer selection dialog will then take over. For many higher quality print options, including vector PostScript, select the Popup View 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 last five buttons at the top of the WIRED window are not relevant to data from HepRep files. They are only used when the HepRep data is read directly from a server (moving up and down prearranged event lists, moving to the next event or previous event and automatically moving through a sequence of events). To try using WIRED to look at events from the BaBar collaboration's HepRep servers, see the SLAC WIRED Home Page.

Additional Items in the Popup View Menu


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:
../bin/$G4SYSTEM/A01app
/vis/open HepRepFile
/vis/scene/create
/vis/scene/add/volume
/vis/sceneHandler/attach
/vis/viewer/flush
/vis/scene/add/trajectories
/vis/scene/add/hits
/tracking/storeTrajectory 1
/run/beamOn 1

Further Resources


Joseph Perl

13 October 2003