D0 GROUP LEVEL 3
ONLINE LESSONS

Episode XIX: Using L3Display

Contents

• Introduction
• How to display your tool's results or how to write a Rep
• Running L3Display
• Example screenshots

Introduction

L3Display is a package based on the d0ve display. The code is located in the CVS package d0ve_l3. d0ve is a visualization package designed for debugging of reconstruction code, written by Toby Burnett and Andy Haas. It defines a 3-d display of lines, surfaces, and character data, and implements a default wire-frame viewer with keyboard control of orientation, perspective, and magnification of four independent views, which can be displayed simultaneously or individually. It allows the user run the program as a framework package. Also, the user can stop the program from his own code, and display final or intermediate results from e.g. a tool or algorithm.

What is being displayed, is given by the DisplayList of the singleton d0ve object (i.e. the display). The DisplayList contains the representations (or Reps) of the objects to be displayed. A representation is something that tells the display how to draw an object. For example, the representation of a track maybe something that tells d0ve to connect the hits with a line. What the user has to do is to make sure the DisplayList contains the representations that he/she wants displayed. L3Display is set up to help with that, by providing a number of example Reps of the DebugInfo (see online lesson 16) of some tools and adding those Reps to the DisplayList. However, there’s only a very limited number of Reps available, so it’s very likely the user will have write his/her own Rep(s). Secondly, L3Display gets the information to be put on the DisplayList (the DebugInfo) from the L3DebugChunk, which holds generally only the final results of the tool, no intermediate steps. If intermediate steps within the algorithm need to be displayed, the user will have to modify the DisplayList from his/her own code. I have appended a short note about that at the end of the next section.

How to display your tool’s results -- or how to write a Rep

We take the example of L3TMuoUnpack, the muon unpacking tool. The results of the tool are stored in the tool’s DebugInfo, called L3TMuoUnpackDebugInfo. The representation class is called L3TMuoUnpackDebugInfoRep and lives in the d0ve namespace (all by convention). L3TMuoUnpackDebugInfoRep has to inherit from DisplayRep, and it has to implement/overload three methods.

• void setEvent(const Event& event)

The results of L3TMuoUnpack are three sets of hits: PDTHits, MDTHits and MSCHits. To display these, I chose to give L3TMuoUnpackDebugInfoRep three datamembers: one vector of PDTHitReps, one vector of MDTHitReps, and one vector of MSCHitReps. The setEvent method, that the user has to implement, gets the DebugInfo from the L3DebugChunk, and fills the vectors of HitReps, using the hits in the DebugInfo.

The HitRep classes are predefined in the package d0ve_muon, together with representations for MuoSegment, MuoTrack, MuoMCTrack and more. Reps for other datatypes or detector-elements are defined in d0ve_smt, d0ve_caldis, d0ve_vertex and d0ve_cft. Also, for more general Reps, like Box, Circle and Point, see the package d0ve_rep.

• void update()

This is the function that actually draws the object on the display. That can be done in two ways:

• By calling append() on the Reps that your Rep is composed of. For example: L3TMuoUnpackDebugInfoRep calls append() on every HitRep in the vectors it contains.
• By plotting the object yourself: Using the move_to(x,y,z) and line_to(x,y,z) to draw. See the class d0ve_l3/L3TrackRep for an example.
• void clear()

Remove all the information from the old event. For L3TMuoUnpackDebugInfoRep, this means clearing of the vectors of Reps.

When you're done writing your Rep, you'll have to modify L3Display to actually use it. For an example of all the step, see L3Display.hpp, but here are the steps you have to take:

• Add your Rep to the L3Display object as a member (see L3Display.hpp)
• Add to the constructor of L3Display the addition of your Rep to the DisplayList
• Add to the processEvent method of L3Display a call to the setEvent method of your Rep.
• Modify L3DisplayParams ( header and source) to add the RCP parameters

As said, it is also possible to display intermediate results within an algorithm. To do this, the user has take the following steps:

• At the start of the run (i.e. in the constructor of the package or tool), create a Rep for the objects to be displayed, and add it to the DisplayList (for an example see constructor of d0ve_l3/L3Display).
• At the point where the program should stop, call some method on your Rep that makes sure the Rep object contains the updated information. This is the equivalent of the setEvent method in L3TMuoUnpackDebugInfoRep.
• Call d0ve->pause().

Running L3Display

The d0ve package is composed of three elements:

1. The framework package D0veSetup, that clears the window and resets the DisplayList.
2. All packages modifying the DisplayList, such as L3Display or d0ve_muon. Or perhaps a package containing a user algorithm that modifies the DisplayList.
3. The framework package D0veEndSetup, that draws everything on the DisplayList on the display by calling the update method of all Reps, and call d0ve-pause(). The pause interval is determined by user settings. The user can set a time that the program should wait at every event.

If you want to use the program L3Display, first create it by creating a release area, addpkg’ing the package d0ve_l3 and do ‘gmake d0ve_l3.all’. Then cd to the bin area of d0ve_l3 and call ‘runL3Display’. This will make softlinks to all the files needed by the program: default triggerlist, tools.rcp, filters.rcp, run configuration, etc. Then it will start the program using the framework RCP RcpL3Display.rcp that’s in that bin area.

You can recenter the display by clicking on it, zoom with page-up and page-down, rotate with smaller-than and greater-than signs.

The program will run tsim_l3, and tsim_l3 will run the tools and filters as determined by the triggerlist. It will also write out DebugInfo for the tools it runs. In the default setup L3Display will read back the DebugInfo for the muon unpacking tool L3TMuoUnpack and the muon local tracking tool L3TMuoLocal, and display the results for each event.

Example screenshots

Below are some links to displays of results of L3TMuoCentralMatch. This is a tool that finds tracks in the muon system, predicts a region in the central tracker and tries to match it with a track from the central tracker. In the following pictures, the silicon disks are shown in green, the barrels in blue, the muon detector in grey. The central track is blue, the region is orange and the muon track is green.

• This picture shows the muon track exiting to the left, and the silicon detector with the central track and predicted region in the center
• Zoomed in on the central part of the previous picture
• A side view
• A 3-dim view of the full detector

Finally, if you have any questions, contact me.