HepRApp Users Home Page

• Release Notes
• Introduction
• Installing and Starting
• Checking Your Java Version or Installing a new Java
• Basic Operation
  • Main Toolbar
  • Orientation Toolbar
  • View Popup Menu
  • File Menu
  • Options Menu
  • Window Menu
  • Help Menu
• Advanced Features
  • Labels
  • Cuts
  • Selecting Server Data
  • Startup Options
• To Make Your Own Server
• Technical Details
• Additional Features Coming Soon
• For More Information
• Send us your Feedback
• For BaBar Users (but all of the above sections are for all users, not just BaBar):
  • In Case of BaBar Server Problems
  • BaBar Server Status Page

Release Notes

30 March 2007 - Version 3.15.0

Major New Release - Many Improvements - details

27 May 2005 - Version 3.14.1

Bug Fixes and Usability Improvements - details

18 March 2005 - Version 3.14.0

Major New Release - Many Improvements - details

Introduction

HepRApp, the original HepRep Data Browsing Application, is a Java application that was developed to let physicists visualize particles interacting with matter (a "single event display" in the language of High Energy Physics applications). Just as HepRep has proven to be a useful general way to represent certain kinds of geometry and data, HepRApp is a general purpose browser for that data. Current uses include High Energy Physics, Space Physics, Shielding Studies and Medical Physics.

HepRApp accepts HepRep data both from XML files and from HepRep-enabled HepEventServers. This data may be particle physics events, Geant4 detector geometries or some other hierarchical graphics data. The data may be either HepRep version 1 or HepRep version 2. The data source may be another process on the same computer as HepRApp or it may be a server an ocean away.

• For the BaBar collaboration, HepRApp communicates via CORBA architecture to a pool of Unix HepEventServers (written in C++) and managed by the JProcMan process management system.
• The GLAST collaboration has implemented their own HepEventServer (as a GUADI service), also using CORBA and C++.
• The Geant4 Simulation Tooklit provides HepRep file output as one of the standard visualization drivers (just use /vis/open HepRepFile, no special external libraries are needed). HepRApp can then open these files either from the local filesystem or from a URL. Data read from servers can also be saved to this file format for later read-in without a server.

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.

Users are encouraged to install and run HepRApp on their desktop machines rather than running it via x-windows from remote Unix systems. HepRApp will work either way, but the best performance comes when it runs on the desktop.

A few more historical and technical details are provided in a later section of this document.

Installing and Starting

• Download the file.
  http://www.slac.stanford.edu/~perl/HepRApp/HepRApp.jar
• Some web browsers rename the "jar" file into a "zip" file. Check to make sure your downloaded file is really named "HepRApp.jar", and fix the name if necessary.
• If you have Linux, Mac or Cygwin (a kind of shell on Windows), you probably also have a nice download utility called "wget". You can use this to download the file without the file name getting changed. To use it, just type:

     wget http://www.slac.stanford.edu/~perl/HepRApp/HepRApp.jar
  

• Put the HepRApp.jar file whereever you please.
• You can move the jar file whereever you want, rename it, copy it, whatever. It will work wherever you choose to put it.
• To uninstall the application, just delete the file.
• To upgrade the application, just replace the file with a new version.

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.

• If your system doesn't know what to do with a jar file, try associating jar files with the command "java -jar"
• If that doesn't work, run the application from the command line by typing: java -jar HeRApp.jar
• If none of that works, you probably don't have an appropriate Java version. See Checking Your Java Version or Installing a new Java.

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). 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 "user.properties" that will be created in the directory from which you ran HepRApp.

If you would like to run with a step by step tutorial showing exactly what output you should see at each step, try the tutorial that was written for Geant4 users: Geant4 Visualization Tutorial using the HepRApp HepRep Browser

BaBar users may want to check out another step by step tutorial that was written specifically for them: Using the event display

Otherwise, see the section below on Basic Operation.

Checking Your Java Version or Installing a new Java

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.

If you don't already have the appropriate Java:

• You can obtain Windows, Sun or Linux versions of Java free from Sun at http://java.sun.com/javase/downloads/index.jsp
  • If you just want to run Java programs, the minimum package you should take is the one called "Java Runtime Environment (JRE)".
  • If you also want to be able to make your own Java programs (not something you need to do for HepRApp), you may want to take the development kit, "JDK". You do not also need the JRE since JDK includes the JRE.

Additional notes for Linux users:

• Run the self extractor via:

     ./j2sdk....bin
  

• Add Java to your path:

     setenv PATH /usr/local/java/j2sdk.../bin:$PATH 
  

Basic Operation

The Main Toolbar

• To view data from a .heprep file (as opposed to a server), select either "Open HepRep File..." or "Open HepRep URL..." to open data on the local file system or over the web.
  For example, try the following URL to see some BaBar event data:

     http://www.slac.stanford.edu/~perl/heprep1xml/BaBar_Example1.heprep.gz
  

  or the following URL to see a Geant4 simulation toolkit example:

     http://www.slac.stanford.edu/~perl/heprep1xml/G4Data1.heprep.gz
  

  If you are viewing other .heprep data files, you may find some in which there appears to be nothing in the view window. It may simply be that the data is off screen. Try clicking on the "Fit in Window" button at the lower left side of the view window
  

  You can specify an entire directory of HepRep xml files at one time. The files will all then appear in the Open Data Dialog (and you then select any one file by clicking on the file name).
  For URL files, the URL must end with a slash ("/") to indicate that this URL is a directory.
  For example, try the following URL to see a variety of example heprep files:

     http://www.slac.stanford.edu/~perl/heprep1xml/
  

  For Local files, just select the directory in the dialog box, and then hit OK.

  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:

  • Specifying a file property in your user.properties file, by including a line such as:

       file=c:\jp\slac\geant4\G4VisTutorial\G4HepRAppTutorial\G4Data1.heprep
       or
       file=http://www.slac.stanford.edu/~perl/heprep1xml/G4Data1.heprep.gz
    

  • Or running HepRApp from the command line with the file property specified right there:

       java -jar HepRApp.jar -file c:\jp\slac\geant4\G4VisTutorial\G4HepRAppTutorial\G4Data1.heprep
       or
       java -jar HepRApp.jar -file http://www.slac.stanford.edu/~perl/heprep1xml/G4Data1.heprep.gz
    

• If you are using the "-group babar" version, you will also have a set of servers available. The open data dialog will contain the line "Event Display Servers for BaBar at SLAC". Click on the plus sign to the left of this line. The list of known servers will then appear.
  • Click on the plus sign next to a server description to select a server of that type.
  • The tree should open to reveal that this server has a "Default Event ID". That first event will then be selected.
  • Some servers have no default event ID. In their case you will see no event until you specify an event yourself using the "Specify Event ID..." button. We provide a default event ID wherever possible so that when the first user tries to use the server, it has already undergone much of the slow startup phase of the first event reconstruction. The first event that you load may take up to five minutes to appear (depending on whether the relevant event databases were already in cache or whether they need to be staged). Subsequent events will load more quickly.
  • Other features of the Open Data Dialog are discussed in the Selecting Server Data section of this document.

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

• If reading from a file, the data will be reread from the file.
• If reading from a server, the server will be asked to resend the data.

The previous and next event buttons read the next data from your chosen data source.

• If reading from a file, this will be the next or previous file in the directory. (Geant4 users will find this a quick way to see each new picture as they generate it). 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.
• If reading from a server, this will tell the server to go to the next or previous data (if the server does not support one or both of these options, the relevant button will be greyed out).

The up and down buttons navigate up and down lists of specific event IDs.

• These buttons are enabled only when you are
  • getting data from a server
  • AND have imported an event id list
• Event ID lists are discussed in the section on Selecting Server Data.

The AutoUpdate button lets you continually update to new data.

• If reading from a file, new data will be continuously read from the current directory.
• If reading from a server, new data will be continuously requested from the server.
• The autoUpdate rate can be adjusted by going to the "Options" menu's "Update Rate...".

The New View button creates a new view window.

• You can then adjust the layout of the various windows by clicking and dragging on their corners or by using the Window Menu.
• The new window will initially be a clone of whatever window was selected previously.
• Thereafter, changes to one of these windows (orientation, visibility, etc.) will not affect the other.
• When you go to new data, all windows will update to the new data.

The Data Visibility Control button turns on and off the data visibility tree (which is turned on by default).

• The tree appears at the right side of the main window.
• Click on the plus signs to expand the tree.
• Click on the check marks to toggle items visible or invisible.
• If you see no change when you turn an item on, expand that part of the tree and turn on the items deeper within the tree.
• For HepRep1 data, all of the control is from a single tree.
• For HepRep2 data, control is from a pair of trees.
  • The Type Tree controls all instances of a given type
  • The Instance Tree controls individual instances of a given type
• If you have more than one view window open, options such as "Highlight" will appear as two choices, one to highlight only in the current view window, another to highlight in all view windows.
• To see a popup menu with more tree manipulation options, position the cursor over a part of the tree and hit the right mouse button (Macintosh users, hit control and mouse button).
  
• The contents of the popup menu depends on what kind of object has been selected.
• The popup menu includes options to expand or turn on an entire tree structure with a single action. But be careful of using this in very complex geometries. Turning on the entire tree for the detailed BaBar detector geometry, for example, loads far more geometry than most users will want, and takes significant time and memory (up to 198M of memory and about 4 CPU minutes to load on a PentiumII 400 MHz).
• The popup menu includes options to select which items should be highlighted in the view windows (one can also have the inverse effect, picking objects in the view window to have them highlighted in the Data Visibility Tree).
• The data visibiliity popup menu also includes options to control labels and control cuts (all discussed later).

The Orientation Toolbar

• Reset restores all options to their default values.
• Fit To Window adjusts scaling to make the entire image fit the window. Try this right away to make the entire example fit the current window. You should then see the following:
• Zoom In and Zoom Out.
• Center the image.
• Rotate the image around the axis perpendicular to the screen.
• Translate the image left or right.
• Rotate the image around the screen's vertical axis. You can either click on the little arrows on either side of the slider or you can click and drag the slider.
• Additional tools along the right side of the window allow translation up or down and rotation around the screen's horizontal axis.
• Orientation can also be controlled by the mouse, which controls various parameters depending on what mouse function you have specified from the View Popup menu discussed below.

The View Popup Menu

• Orientation Actions lets you select standard views or reset to the initial view.
  
  • Auto Rotate causes the view to continuously rotate around the vertical screen axis. Startup options can be used to control the rotation speed and to constrain the rotation within a particular set of angles.
  • Auto Fly rotates just like Auto Rotate but also makes the view continuously zoom and unzoom, creating a continuous flying effect. Startup options can be used to control the flight speed and minimum and maximum zoom.
• Orientation Toolbar lets you turn off and on the toolbar at the bottom of the view window.
  
• Projection lets you control what sort of projection is done.
  
  The HepRApp HepRep Browser can perform many specialized projections that distort the visualized space in useful ways. Some of the most useful projections in addition to the default Parallel projection are
  • FishEye
    a projection in which you can select what percentage of the screen space is given to the inner versus the outer detectors. The mouse will default to control this new variable, known as "alpha", and the Mouse Function menu will now show more options, such that the mouse can control either this new "alpha" variable or can control any of the standard variables (scaling, translation, rotation).
  • Z-FishEye
    a projection in which you can control what percentage of screen space is given to low Z versus high Z parts of the detector (no effect will be visible from the beam view, select side or top views instead). The mouse will default to control this new variable, known as "alpha", and the Mouse Function menu will now show more options, such that the mouse can control either this new "alpha" variable or can control any of the standard variables (scaling, translation, rotation).
  • Rho-Z
    the detector is cut along a plane of constant phi angle. All elements above this plane are collapsed together on the top half of the display, all elements below this plane are collapsed together on the bottom half of the display. The mouse will default to control this new variable, known as "phi0", and the Mouse Function menu will now show more options, such that the mouse can control either this new "phi0" variable, or a degree of FishEye projection, or any of the standard variables (scaling, translation, rotation).
• Mouse Function lets you control what the mouse will do.
  
  • By default, the mouse controls scaling (click near the center of the picture and drag outward to zoom in, do the opposite to zoom out), but the mouse can also be set to control translation, rotation or to work as a pick (in which case a pop-up will appear with the attributes of the picked objects and the Data Visibility Tree will expand and highlight to show you what objects have been picked).
  • The four options, PickRectange, PickWedge, PickCircle and PickPolygon define four different ways that you can click and drag to specify a pick area.
    • Mouse Function...PickRectagle
      click and drag. A rectagle will be defined. Everything in that rectangle will be picked.
    • Mouse Function...PickWedge
      click and drag. A wedge centered on the screen center will be defined. Everything in that wedge will be picked.
    • Mouse Function...PickCircle
      click and drag. A circle centered on the intiial pick position will be defined. Everything in that circle will be picked.
    • Mouse Function...PickPolygon
      click on several points in a row. A polygon made of of those points will be defined. Everything in that polygon will be picked.
  • To pick more than one object at a time (for example to highlight two different tracks), pick the first one normally, then hold down the control key while you pick the second one.
  • To clear the highlighting, pick on any empty part of the view.
  • If any of the objects you pick happen to have an attribute named "Lab(px,py,pz,E)", HepRApp will assume this is a particle momentum expressed as a four-vector. It will then show the Invariant Mass Sum of the selected objects at the top of the attribute pop-up. For example:
    
  • Highlighting can also be controlled from the Data Visibility Tree. Right click on items in that tree to see these highlighting options. They include the ability to highlight a picked item in all views rather than just one view.
  • Mouse Function...PickToMeasure
    click and drag. A line will be defined and its length will be reported. (Remember that, as the mouse knows nothing about the coordinate into or out of the screen, the measurement you are getting is just the component in the screen plane.)
  • Mouse Function...PickToOffsetLabel
    see details in later section on labels
  • Mouse Function...Show Attributes
    uncheck this to turn off the attribute popup feature.
  • Mouse Function...Highlight in Data Visibility Tree
    uncheck this to make picked items no longer highlight in the data visibility tree.
  • Mouse Function...Transform View (if object has info)
    if this if checked, picking on an object that contains view angle attributes (hints about the best angle to view that item) will cause the view to transform appropriately. If you pick an object that contains no such special view attributes, the view will be left unchanged.
  • Mouse Function...Show Daughters (if object has info)
    if this if checked, picking on an object that contains information about what tracks are its daughters will cause the daugthers to be displayed and highlit. If you pick an object that contains no such special daughter attributes, the view will be left unchanged.
• Drawing Options lets you control additional details
  
  • Show Shadows
    controls whether objects are drawn with contrasting drop shadows.
  • AntiAlias
    applies a smoothing algorithm that reduces the "stair-step" effect on angled lines.
  • Always use FastMode
    gives faster redrawing performance at the expense of some features. All lines will be drawn at single pixel width. Filled areas will be left unfilled. AntiAlias will be turned off. If this option is not selected, FastMode is only used while you are in the middle of a drag operation.
  • Show Status
    draws a status box in the top right corner of the view window. This box contains view information that varies depending on the current mouse mode (scaling, translation, rotation).

The File Menu

• Open Data...
  • is the same as hitting the Open Data button discussed above.
• Reload Data...
  • is the same as hitting the Reload Data button discussed above.
• Save as Local Data...
  • is useful when you have been reading data from a server, but would like to keep the data on your local disk for server-free access in the future. The HepRep data that came from the server is stored as a HepRep XML file suitable for reading back in using the Open Data dialog's "Open HepRep File..." or "Open HepRep URL.." options.
  • All parts of the data that have been read from the server will be written out to this file, whether they are currently visible or not. Parts of the data that you have never viewed will not be in memory (data is downloaded from the server only as needed), so these parts will not be written to the HepRep XML file.
  • HepRepXML files can be greatly compressed using gzip (they typically compress down to about five percent of original size). There is no need to unzip the files before reading them back in to HepRApp.
• Export Graphics...
  • saves the view to various common graphics formats:
  • Vector Graphics Formats:
    • Encapsulated PostScript (.eps, .epi, .epsi., epsf)
    • MacroMedia Flash File Format (.swf)
    • Portable Document Format (.pdf)
    • PostScript (.ps)
    • Scalable Vector Graphics (.svg, .svgz)
    • Windows Enhanced Metafile (.emf)
  • Bitmapped Graphic Formats:
    • GIF Image
    • RAW Image
    • PPM Image
    • BMP Image
    • JPEG Image
    • PNG Image
    • WBMP Image
  • For each format, once you have selected the format you should then click the "Options..." button to the right of the format name. This brings up a panel of options appropriate for that graphics format (letting you adjust options such as background colors, transparency, whether to include a preview image, etc.).
  • This impressive selection of output formats and detailed options is made possible by the FreeHEP VectorGraphics Package.
  • Preferred formats for publication quality images are the vector formats.
  • Startup options autoSaveGraphics, autoSaveGraphicsFormat and autoSaveGraphicsFileName can be used to cause exports to happen automatically as each new event is displayed. When coupled with autoUpdate, this can allow you to have HepRApp continuously save new images. You can see the complete set of available options by looking at http://www.slac.stanford.edu/~perl/HepRApp/default.properties. Copy the relevant properties into your user.properties file and then start HepRApp.
• Print...
  • sends the selected view directly to a printer (as a bitmapped image). Your regular system printer selection dialog will then take over. If you want more flexibility, including the ability to save your view as true vector graphics, use the "Export Graphics..." menu item instead.
• Exit...
  • ends your HepRApp session. Various properties such as the current size and position of your HepRApp window will be saved to your the file user.properties for reuse at your next session (unless you have indicated that you don't want this behavior by setting the property lockPropertiesFile to true).
  • Closing the main HepRApp window or ending the application with Ctrl-C has the same effect as "Exit...". Your properties will still be saved and any servers will be cleanly detached just as if you had used the "Exit..." menu item.

The Options Menu

• Visibility Tree
  • toggles on and off the Data Visibility Tree discussed earlier.
• Label Control ...
  • brings up the Label Control Dialog discussed later.
• Cut Control ...
  • brings up the Cut Control Dialog discussed later.
• Server Property Control ...
  • brings up the Server Property Control Dialog discussed later.
• Toolbar
  • controls whether the main toolbar is shown and whether it should contain images, text or both.
• Update Rate...
  • lets you control the rate at which the auto update feature discussed above loads new data.
• Specify Group
  • lets you set HepRApp to have specific behaviors appropriate to a particular group of users.
  • The same effect can be obtained by specifying a "-group" property in the command line or by including a "-group" property in the user.properties file.
  • Group properties override HepRApp's default properties. User properties in turn override both group and default properties.
• Look and Feel
  • lets you select which Java "look and feel" is used.

The Window Menu

• New View
  • creates a new view window.
  • You can then adjust the layout of the various windows by clicking and dragging on their corners or by using other options in this Window Menu.
  • The new window will initially be a clone of whatever window was selected previously.
  • Thereafter, changes to one of these windows (orientation, visibility, etc.) will not affect the other.
  • When you go to new data, all windows will update to the new data.
• Tile
  • arranges all existing windows in a way that the entire available space is covered with no windows overlapping.
• Cascade
  • arranges all existing windows in a way that each window partially overlaps the previous window.
• Close
  • closes the currently selected window.
• Widen
  • expands the width of the currently selected window the maximum width available.
• Iconize All
  • iconizes all windows.
• Restore All
  • restores all iconized windows.
• Arrange Icons
  • arranges the icons.
• specific window names
  • the bottom of this menu includes toggles for each of the current windows. HepRApp can have any number of view windows.

The Help Menu

• Quick Guide...
  • takes you to the HepRApp Basic Operation Guide.
• HepRApp Home Page...
  • takes you to this page, the HepRApp Home Page.
• Show Server Logs...
  • takes you to the log pages of the currently connected HepEventServer (if you are connected to one). You may want to view these logs if you are having problems getting a reasonable response from the server (see the problems section later in this document).
• About HepRApp...
  • tells you the current version number.

Advanced Features

Labels

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

• have no label
• have the label "P_T 3.143 Gev"
• have the label "Transverse Momentum 3.143 GeV"
• or even just "3.143".

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.

• From the View Popup Menu, Select "Mouse Function..."
• Select "Pick to Offset Label"
• Click and drag over a label to select which label to move.
• The selected label will highlight. Everything else will be grayed out.
• Click and drag a second time to actually move the selected label.
• Note that you are actually storing an offset, such that if you then zoom or rotate the image, the label will move. It is the new offset you created that will remain constant.
• If you subsequently "Export Graphics", the new offset will still be used.
• Note that if you turn the data type off and then back on (from the Data Visibility Tree), your new offset will be lost and the label will return to the automatically computed initial position.

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

• To get to the Label Control Dialog:
  • Select "Label Control..." from the Options Menu.
  • Or, to see a version of the label control dialog that is focused on just a particular data type, pick on an object in the main view window (while the View Popup Menu's "Mouse Function"..."Show Attributes" option is on). Then, from the resulting attribute popup, select "Label Control..."
    
    The label control dialog will appear.
  • Or, right click on an object in the Data Visibility Tree, and from the resulting menu, select "Label Control..."
  Either way, the Label Control Dialog will appear.
• To control labels from a startup option:
  java -jar HepRApp.jar -label "KalmanTrk:nSvt:13;KalmanTrk:nDch:13;" -group babar -server cm1data
  where the syntax is "TypeName:AttributeName:Flag;" and the flag is an integer bitmap composed by adding up:
  • 1 for the short name (such as P_T)
  • 2 for the long name (such as Transverse Momentum)
  • 4 for the value
  • 8 for the units (such as GeV)
  So, for example:
  • 13 would give "P_T 3.124 GeV"
  • 14 would give "Transverse Momentum 3.124 GeV"
  • 4 would give "3.124"
  You can always override this initial label setting by the interactive label control.
• Some servers or HepRep xml data can already contain flags to control labelling.
  You can always override this server default by specifying a startup option or by the interactive label control.

Cuts

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

• To get to the Cut Control Dialog:
  • Select "Cut Control..." from the Options Menu.
  • Or, to see a version of the cut control dialog that is focused on just a particular data type, pick on an object in the main view window (while the View Popup Menu's "Mouse Function"..."Show Attributes" option is on). Then, from the resulting attribute popup, select "Cut Control..."
    
  • Or, right click on an object in the Data Visibility Tree, and from the resulting menu, select "Cut Control..."
  Either way, the Cut Control Dialog will appear.
  • Type in a cut value in either the "equals" area or the "min" or "max" area,
  • Then, while the cursor is still in that area, hit the "enter" key.
  • To remove a cut, remove the value and again hit the "enter" key.
• To set cuts from a startup option:
  java -jar HepRApp.jar -cut "EmcCluster:E>0.5;"
  where the syntax is one of either:
  • "TypeName:AttributeName>MinValue;"
  • "TypeName:AttributeName<MaxValue;"
  • "MinValue<TypeName:AttributeName<MaxValue;"
  • "TypeName:AttributeName=Value;"
  You can always override this initial cut by the interactive cut control.

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.

Selecting Server Data

• "Specify ProcMan..." lets you specify an alternate Server Process Manager. This is a service on some other host that tells HepRApp about an available pool of HepEventServers. The service must use the JProcMan process management system.
• "Specify Server..." lets you specify individual HepEventServers. These are servers not managed by Server Process Managers. Individual servers should follow the HepEventServer event server protocol.
• An overview of how Process Managers, HepEventServers and HepRApp fit together can be seen at A Component Approach to HEP Event Displays. However you start your servers, what HepRApp needs to know about is the URL of a particular file that is created by this HepEventServer or JProcMan. That one file tells HepRApp everything else it needs to know to connect to these servers. See details later on how to run your own server.
• "Specify Event ID..." lets you specify a particular event ID. For BaBar, this takes the form of a collection name, then a space, then an event number (either an ordinal number or a hex event ID).
  Here's a little more background on BaBar Event IDs:
  • The BaBar Event ID shown by HepRApp has three parts:
    CollectionName OrdinalNumber HexID
  • The HexID (referred to within BaBar as the real EventID) is the most persistent form of event id. It encodes the time that the event was detected by the BaBar online. A given event may then appear in one or more event collections (a raw form of the event, a later reconstruction collection, a re-reconstruction collection, and so forth). Thus to uniquely identify a particular reconstruction version of an event, one needs both the CollectionName and the HexID.
  • The OrdinalNumber is just the ordinal position at which this event appears in the given collection. Thus the event from some particular collision may appear as ordinal number 505 in one collection, ordinal number 101 in some more refined collection, etc.
  • You can tell HepRApp to go to a particular event either by
    • CollectionName OrdinalNumber (the fastest way, since the database allows random access by this method) or by
    • CollectionName HexID (slower in practice, since the event display server has to actually start at the head of the collection and read through the tag part of every event until it finds a match for this HexID).
  • So, for example, you could have either of these ids:
    • /groups/AllEvents/0001/5200/P10.2.3fV01fb/00015222/cb001/allevents 102
    • /groups/AllEvents/0001/5200/P10.2.3fV01fb/00015222/cb001/allevents bb628236/fc66038
  • HepRApp will always show all three parts when it comes back with the actual event.
• "Import ID List File..." and "Import ID List URL..." let you specify a list of Event IDs to bring into the open data dialog. Each line of such a list is a single event ID such as you would supply to the "Specify Event ID..." dialog described above. You then just click on a specific event ID to view that event or use the up and down arrows in the main HepRApp menu to go up or down one event in this list. The left and right arrows continue to work as usual, going to the next or previous event in the normal data sequence as opposed to going up or down the event ID list.
• "Search ID List..." lets you search various forms of data catalogs to find useful data collection names. The search may work through a search servlet or may just search for matches within a particular file (found as a local file or a URL).
  • If an appropriate servlet exists for the current server, the servlet option will already be checked in the above dialog. Just enter a search term and hit OK (for example, for the BaBar analboot2 server, try entering "isMulti").
  • If no servlet is known for the current server, you will have to first select one of the three search method options. Another dialog will then ask you to specify a search servlet, a local file or a URL to search.
  • Once you have specified the search method, enter a term in the main search dialog and hit OK.
• "Copy ID to User List..." appends the current event ID to a new Event ID list. This list is saved to your current directory under the name "UserEventIDList.txt". When you complete your HepRApp session, you can rename this list and bring it back into HepRApp later using the "Import ID List File..." or "Import ID List URL..." options.
• "Mark ID for Deletion" is used to remove an event ID from your user event ID list. The next time you change events, this marked event will be deleted from the list.
• "Save as Local Data..." takes the HepRep data that you are currently viewing from a HepEventServer and saves that data to a local HepRep xml file suitable for viewing offline.
  • You can later read in this data with the "Open HepRep File..." or "Open HepRep URL..." options.
  • Note also that you can compress this data using gzip, cutting its file size by roughly a factor of 20. Then later you can read this data back in as a gzipped file without ever having to unzip it.

Startup Options

The first time you start HepRApp, a properties file is created in the current directory:

   user.properties

HepRApp stores various values in this file so that it can remember some of your settings (size and location of the main HepRApp window, directory from which you last read a HepRep file, etc.). You can edit this file to add addtional startup options.

You may notice that some of the stored values have ":" replaced by "\:". This just occcurs because Java saves properties using ISO 8859-1 character encoding. If you write properties files by hand, you can go with or without these extra slashes.

You can prevent HepRApp from overwriting your properties file by setting the property "lockPropertiesFile" to true.

The complete list of available startup options, along with their default values and explanatory comments is described at:
    http://www.slac.stanford.edu/~perl/HepRApp/default.properties

To change any of those defaults, copy the corresponding line into your user.properties file. Your value will override the default. Take care not to modify the default file itself (if you find that you have done that, replace it with a fresh copy from the above link).

Note that some option values are case sensitive (for example, projection name must be Perspective, not perspective).

If you run HepRApp from the command line, you can also specify these options there, for example:

   java -jar HepRApp -fullScreen true

Each option is preceded by a dash and follwed by a value. You may string together as many of these options as you wish (there is no order-dependence).

For boolean options, if you leave out the value it has the same effect as setting the value to true, for example:

   java -jar HepRApp -fullScreen

Options provided on the command line are in effect only for the current session.

One special option which can be used only from the command line is "-opt". Use this to specify an alternate properties file (instead of user.properties), as in:

   java -jar HepRApp -opt myspecial.properties

To Make Your Own Server

Although BaBar already has many production event display servers, individual BaBar users may want to run their own servers to look at a special database, to run special reconstruction code or to develop the server itself. For details, see: Running Your Own Event Display Server, Rapidly! or contact the BaBar Event Display maintainers at wiredces@slac.stanford.edu.

Historical and Technical Details

Wired3 grew out of earlier WIRED event display work at CERN (originally a web applet, WIRED stood for World-Wide Web Interactive Remote Event Display). With the addition at SLAC of the HepRep Generic Interface Definition for HEP Event Display Representables and the HepEventServer Generic Design for HEP Event Data Servers, WIRED become Wired3 - a generic, experiment-independent HepRep browser that can serve many different user communities.

HepRApp can communicate via CORBA or XML architectures to a variety of servers which provide HepRep format data through the HepEventServer event server protocol. Pools of such servers may be managed using the JProcMan process management system. An overview of how all of these components fit together can be seen at A Component Approach to HEP Event Displays.

HepRApp uses the unique projection engine originally developed for Wired (rather than a conventional hardware graphics engine) to allow creation of specialized, often non-linear, projections of interest to physicists. A special layering model insures that certain data such as raw hits are always layered on top of their associated found tracks no matter what orientation the view is presented in. The work is analogous to how a cartographer layers data on a map to maximize the presentation of useful information.

Additional Features Coming Soon

Some highlights of work going on at this moment are:

• Richer set of cut controls
• Change color based on attributes
• Edit or annotate the display

For a complete description of the functionality we eventually intend to achieve, see:

• Requirements Document for the New BaBar Event Display, presented at the HEPVis workshop in Janary 1998.
• HepRep: a Generic Interface Definition for HEP Event Display Representables

For More Information

• HepRep: a Generic Interface Definition for HEP Event Display Representables
  How HepRApp asks for information about an event.
• HepEventServer: a Generic Design for HEP Event Data Servers
  How HepRApp attaches to a server and advances that server to a particular event.
• JProcMan: a Java-Based Process Management System
  Used to manage pools of HepEventServers in a production environment.
• A Component Approach to HEP Event Displays
  Shows how HepRApp, HepRep, HepEventServer and JProcMan work together to provide flexible solutions.
• Screen Shots of the HepRApp Event Display
• PowerPoint talk on How to Extend the BaBar Event Display Server
  This is a little out of date, but is a good introduction to the general ideas. (Run the presentation in slide show mode, use mouse clicks to move through the animations, click on any hyperlinks that appear)
• Requirements Document for the New BaBar Event Display
  Very little of this document is actually specific to BaBar. Most experiments will have similar requirements, and it is these requirements which HepRep and HepEventServer ultimately meet.
• Architecture Considerations for BaBar WIRED
• Geant4 Visualization Tutorial using the HepRApp HepRep Browser
  This is a step-by-step HepRApp tutorial specifically written for Geant4 users
• Using the event display
  This is a step-by-step HepRApp tutorial specifically written for BaBar users.

Send us your Feedback

• General questions about the HepRApp client or HepRep, HepEventServer or JProcMan should be sent to
  perl@slac.stanford.edu.
• Specific issues about BaBar Event Display Servers should go to the BaBar Event Display maintainers:
  wiredces@slac.stanford.edu.
• BaBar users may also post issues to the HyperNews group
  BaBar Graphics
• Geant4 users may also post issues to the HyperNews group
  Geant4 Visualization

In Case of BaBar Server Problems

If a server goes down, you will be given the option to browse the server logs. The tail of the log should show you something about why the server failed. You can also check the server logs at any time by clicking on the Help menu's "Browse Server Logs" option or directly viewing the Server Status Page.

You can ask for a new server of the same kind by first clicking on the minus sign next to the server description (which closes that part of the tree) and then again clicking on the plus sign next to the server description.

Please consider the following possible problems before assuming this is a problem with the HepRApp system itself:

• Server Machines: these standard SLAC interactive machines may be having system problems
• BaBar Database Problems: the databases may be down for a scheduled outage or may be having other problems
• BaBar Missing Data: the data you have requested may not be on disk and may require a significant amount of time to stage
• BaBar Reconstruction Version Differences: the event display may show a different number of tracks or clusters than you have seen in some other track or cluster lists. Keep in mind that the results will be specific to the particular release that was used in this reconstruction. The specific releases can be seen by checking the Server Status Page.

• SLAC Computing Outages and Changes
• BABAR Computing Environment
• Preliminary/unconfirmed bugs, problems, frustrations, fixes
• Physics Analysis
• BdbSOS
• KanSOS

Most suspected BaBar event display server crashes turn out to actually be crashes that would occur in any equivalent BaBar interactive analysis job. So please, if you have the time, try an equivalent analysis job (using the same release as the server) to check if this problem is really specific to the event display servers.

Having said all that, we really do want to hear from you if there are any problems. Please contact us through the above feedback links.