BaBar Event Display

Last modified: Fri June 09 2000

This site has a European Mirror.
Quick directions for running in release 8.6.3x from the database.
We also have a picture archive under construction.

This page contains practical documentation on the BaBar Event Display. It is meant to be a tutorial and an index to relevant web pages and documents.

The BaBar graphics code is contained in several packages available within the BaBar software repository. The packages have been developing and will continue to develop. We will try to keep you as up-to-date as possible through this web page on changes in functionality. Feedback is welcome*.

This tutorial is a quick but informed start on viewing event display graphics; it will provide enough information to help you do some advanced things if you so desire, without bogging down the beginner (we hope).

Glossary and Basic Structure

Running the BaBar Event Display

An example Walkthrough
Physics contents of the Displays
Present Representations in
TrkGra, SvtGra, DchGra, DrcGra, EmcGra, IfrGra.

Building Graphics Applications.

Glossary and Basic Structure

Warning: - Xxx is used throughout these pages to indicate the set of detector-specific packages, with the Xxx itself referring to the three-letter monikers of the various systems: Trk, Svt, Dch, Drc, Emc, Ifr. XxxGra must be read as TrkGra, SvtGra, etc.

The Graphics packages, GraDisplay and XxxGra, define standard Framework modules. Standalone applications can be used or built, or the graphics modules can be included in the path of your application.

The full graphics structure relies on (mostly) abstract classes defined in GraBase and GraModel. Concrete classes are defined in XxxGra packages with minimal interdependancies. GraModel also contains the definitions of concrete classes for global projections.

The basic elements are the following:

Observer: Basic structural unit (class GraObserver).
One or several types of Observers can be defined using a GraObsFactory. One or several Observers of the same type can be created from a given Factory.
Each Observer can drive a display window, or several Observers can work together to create a display window. For example, the GraDisplay application has one display window containing an Observer for each of the subsystems.

Observers can be edited, created, (dis)activated from the Graphical User Interface (GUI).

Some Observers are of a special "Selection" type (class GraObsSelection): they are meant to display Selected Objects. They are updated, optionally automatically, when the Selected Event Objects change.
Drawers: elementary, abstract classes, instanciated in the XxxGra packages as XxxGraDetDrawers, XxxGraEvtDrawers and XxxGraSelDrawers .
One or more Drawers, from one or more XxxGra packages, can be registered in an given GraObsFactory. They define which objects will be accessed by the Observers of that type and their representations.
- GraDetDrawers make use of DetectorModel descriptions of detector elements, to draw their outlines.
- GraEvtDrawers make use of GraDataReader and concrete classes XxxGraDataReader, to provide access to XxxData.
- GraSelDrawers are special GraEvtDrawers for display of Selected Objects.
The Drawer actions (objects to display) are switched on/off from tcl or from GUI.
Representation: A representation is a way of depicting physical information in terms of 3-D visualizable shapes.
Examples:
- one can represent a charged particle track as a helix or as a series of line segments in a polyline.
- one can represent Hits on Tracks (HOT's) as circles whose radius is proportional to the drift distance or position error
- one can represent "hits" in the electromagnetic calorimeter as boxes whose "front" face is that of a hit crystal, and whose length is proportional to the energy deposited in the crystal ("porcupine" representation).
- one can represent DIRC hits as the hexagonal front face of the hit PMT's
See this document for information on creating and adding your own representation.
Projection: A projection is a map (not necessarily 1-to-1) for translating one set of xyz coordinates to another set of xyz coordinates.
Examples:
- the RZ projection folds the detector and event elements around the beam axis.
- the Fisheye projection changes the radial distance of points from the origin, giving a view in which points close to the origin become relatively more visible.
The projection can be chosen from tcl or GUI.

See this document for information on creating and adding your own projection.
Model: the sets of Drawers, Representations, Projections, etc., and BaBar data (more correctly, the means for directly accessing the physics event information), make up the Model. A model is the basic component for the Graphics Applications.
Selection: graphics objects can be selected from GUI, by picking, dragging the mouse or text input.
Event objects they represent can then be accessed for dump or selective displays.

Running the Graphics Applications

Setup

Basics Before You Begin

You should be working on a computer carrying full BaBar software releases, including the ability to add packages through Software Release Tools (SRT). The console at which you are working must be capable of X-window displays.
(Note. Currently, there is free X-server software available for Macs and Windows-based PCs. You can find it at: http://www.microimages.com/)

Setting up the DISPLAY

The environment variable DISPLAY determines where your graphics will be displayed. It is likely that this variable is already defined correctly for you, particularly if you use ssh. Type

printenv DISPLAY

If a non-empty string is returned, odds are good that your DISPLAY environment variable is set correctly. If this is the case, you can skip the rest of this section.

Here we assume you have already defined BFARCH correctly. Since you will be making a graphical display (requiring at this point an X-windowing system), you need also to have the DISPLAY environment variable set. You must first know the internet or IP address of the machine in front of you. Once you do, type:



setenv DISPLAY myHost.myDomain.topDomain:0

or, if you have bash or ksh, type:


export DISPLAY=myHost.myDomain.topDomain:0

where myHost.myDomain.topDomain represents your display machine's internet or IP address.

Note: if you are working from a public x-terminal at SLAC and running at a different site, you may need to run the mxconns program. Please see its man page at SLAC.

Minimum Package Setup

Running the BaBar Event Display is like running any other BaBar Framework application. It requires essentially the same SRT environment and startup procedure as Beta, eg. (see the Beta Tutorial for detailed instructions).

To run the Graphics Applications, you must first establish a workdir from which to work. Do the following:


newrel -t 8.1.0 myGra810    (This establishes a main directory for your work 
			    and establishes which release you will use 
			    (8.1.0 in this example).  myGra810 can be whatever 
			    name you choose for the directory.)
cd myGra810
addpkg workdir
cd workdir
gmake setup

Data access

You must now establish the data file on which you will run. You may run the event display either from a simulation (.xdr) output file, from the Event Store Database, or from online-created XTC files.

You may have either a bbsim.xdr file in your workdir working directory or a link named bbsim.xdr pointing to an actual .xdr file. The graphics applications will also look in the PARENT directory if the requested file is not found in your workdir.

xdr file input
It is the default input of Graphics applications.
Event Store DataBase input
Will be implemented through the standard Bdb/Bear/Beta interface like Beast tape input.
Presently, working version in DrcGra (rel 6.5.2)

Starting the Graphics Applications

The BaBar Graphics (Event Display) application GraDisplayApp is built by default with each BaBar software release. It contains all the various data and detector representations.
The smaller, faster, detector-specific applications , SvtGraApp , DchGraApp , DrcGraApp , EmcGraApp , IfrGraApp and TrkGraApp are no longer included in the releases. They must be locally built using standard SRT tools.

They are available for your use as standalone Framework-based programs or as modules to include in your own application.

The `disprun` script

Beginning with BaBar Release 6.3.1, there is a script file in the workdir directory which will simplify the running of all of the display applications. The script is called disprun. This script can be used to run either a default version of an application or to run a version that you have built yourself. disprun looks first in RELEASE/bin/$BFARCH/ for your executable and runs the version there if it is available. If you have not built your own executable, disprun runs the default executable in PARENT/bin/$BFARCH.

The disprun command must be executed from your workdir.

To simply get a help listing, issue the following command:


  disprun help

The syntax for using the command is


  disprun [-exe exe_app_name] [-in tcl_scriptfile] [help]

Examples:

To run the default GraDisplayApp program, simply do the following:


   disprun
       This is absolutely equivalent to the following line:


   disprun -exe GraDisplayApp -in GraDisplay/script.tcl

To run the detector specific applications XxxGraApp (once locally built), type:


   disprun -exe XxxGraApp -in ./RELEASE/XxxGra/xxxgra.tcl

Running Graphics Applications with releases prior to 6.3.0

For running Graphics Applications with releases prior to 6.3.0, type:


   source GraDisplay/setup.csh	      (or setup.sh if using bash or ksh) 
  ./$BINREL/bin/$BFARCH/GraDisplayApp GraDisplay/script.tcl

with $BINREL defined as RELEASE or PARENT whether you have built the application locally or not, respectively.
For running detector specific applications, type:


   source GraDisplay/setup.csh	      
  ./RELEASE/bin/$BFARCH/XxxGraApp RELEASE/XxxGra/xxxgra.tcl

Working with the Event Display

Tailoring your Event Display

Once the graphics application is launched, several windows will open up on your screen, display windows and control panels. The display windows are the windows of the default Observers, and displayed objects are those set by the initializing tcl script. - see this document for more information.

Full customization of your Event Display is possible either from tcl (from a file or from direct input), or from the Graphical User Interface (GUI).

Moving through Events, Skipping Events and Exiting

Like in any Framework application, event processing is specified by the tcl command: ev begin -nev nn where nn is an integer number of events greater than or equal to 1.

From the graphics module, you move through events by clicking the continue button of the GraModule panel.
If you process event by event (ev begin -nev 1, repeatedly ), the Continue button makes the application leave the graphics module and return to the Framework.
If you ask for more than one event (nn >1), you must browse through all of the requested events until a tcl prompt appears in the original terminal window.

To skip events, you may use your favorite recipe. An example of a skip (tcl) procedure is given here

To exit, click on the terminal window at the tcl prompt and type "exit".

Hints, diseases and missing options

The Babar Event Display is a moving project. Feedback is most welcome.

Known weaknesses of the present version are the following:

no storing of GUI-tailored configurations (unless hand-typing the corresponding tcl settings, if any)
no possibility for reassigning attributes (color, thickness,...) of graphics objects from GUI
no GUI driven selection procedure on the basis of EventObj data (eg., selection on track momentum, selection of associated objects,...). The present selections are hard coded in the SelectedObs and GraDataFilter classes.
minimal user online help and no feedback on error
some displays are very slow (eg., Drc Tubes, Emc Crystals,...)
... (see the BaBar Event Display presentation at HepVis 98, for a full list of requirements, some of which are filled)
Bugs in the present releases (6.5.2):
- displays of reconstructed tracks are presently missing when reading Beast tapes

Future developments

The Babar Event Display will evolve toward a client-server structure for better functionalities and performance.

Part of the present procedures will become obsolete. This will affect mainly the Graphics interface, but neither the data representations, nor the basic Observer/Drawers structure.

Contents