Background:

0) Who is to blame for this?
1) What is the ATLAS HEPVis Visualization System?
2) What is v-atlas? How do I run it?
3) What is in v-atlas?
4) What is the status of v-atlas features and bugs?

General:

5) How do I interact with the display?
6) Can I get online help?

Geometry:

7)   How do I view the geometry of ATLAS?
8)   How do I reveal the hidden details?
9)   How to I hide details I no longer want to see?
10)  How may I iconize a volume?
11)  How may I restore an iconized volume?
12)  How can I obtain the name and composition of a selected volume?
13)  How can I obtain the geometrical parameters of a selected volume?
14)  May I know the mass of a selected volume?
15)  May I know the copy number (for simulation) of a selected volume?
16)  Can I dump the entire GeoModel description of a volume and its sub-tree?
17)  Why is only one section of the  liquid argon barrel accordion
     visible in the display?
18)  Why is the liquid argon endcap "spanish fan" not visible?
19)  Which detector configuration is rendered by v-atlas?  How
     can I change the detector configuration?

Measurement:

20)  How can I create and move the virtual metre stick?

Monte Carlo Truth Information:

21)  How can I see MC particles?
22)  What determines the trajectories I see?
23)  Can I get the parameters of MC particles?
24)  Can I cut on kinematic quantities?
25)  Can I make my particles show up in different colors?

Display of Tracking System Hits:

26)  How can I see hits in the detector?
27)  Why do I see hits that do not appear to lie upon tracks?

Display of Calorimeter Hits:

28)  How can I display the LAr hits and the Tile Calorimeter hits?
29)  How do I interpret the display?
30)  Can I obtain information from the hits?

Importation of Extra Input:

31)  How can I display extra visual information on top of the display?
32)  Can I display VRML from G4 together with the GeoModel description of ATLAS?
33)  What if I just have a file of some points (such as conversion electron positions)
     to display?

Data Browser:

34) How can I browse the data?
35) Why do some objects on the input file not appear on the object list
    in the data browser window?
36) Why do some objects not print when they are selected?
37) Why do some objects say "State Secret?" when queried.

Extending:

38)  Will you let me put MY stuff into your display?
39)  What steps are involved in extending the display?

0) Who is to blame for this?

Joe Boudreau (boudreau@pitt.edu) and Vakho Tsulaia (Vakhtang.Tsulaia@cern.ch).

1) What is the ATLAS Hepvis Visualization System?

2) What is v-atlas? How do I run it?

A script called v-atlas runs the visualization system for most users.  It is invoked by typing "v-atlas [filename]".  If the filename is provided then event data from the file may be co-displayed along with the detector pieces. The script can be invoked from anywhere.  One must first source a setup file, like this:

source /some/where/AtlasGeometryCommon/GeoModelDisplay/*/cmt/setup.sh

After typing v-atlas [filename] a screen appears on your screen and you are ready to start interacting with the geometry.  This package works best locally. Frequent users are advised to get a local release of ATLAS software plus a local replica of the detector description database.

3) What is in v-atlas?

Answer:

a) A browser for the geometry.
b) A virtual ruler, meter stick, and 10m stick, for measuring objects.
c) A display of tracking detector simulated hits.
d) A display of the calorimeter simulated hits.
e) A display of Monte Carlo Truth information.
f) A data browser.
g) A mechanism for importing input in .wrl, .iv format
g) Display of "tracking surfaces" (courtesy of Andreas Salzburger).
h) Display of reconstructed tracks. (courtesy of Andreas Salzburger)
i) A "template" system, designed as a model for user extensions.

We will discuss these more broadly in the sections below, but note that the  system is designed for extension.  Item (i) is a template for user extensions. It runs within v-atlas and gives instructions for extending v-atlas.  Items  (g) and (h) are extensions which have been provided by the tracking group,  largely for their own purposes.  They are not at present covered in this document.

4) What is the status of v-atlas features and bugs?

5) How do I interact with the display?

The display is shown in the figure below.  Circled in the diagram is the Launch Menu,  the Run/Event Selection Boxes, the Forward Arrow Key, the Navigation Grabber and the Selection Arrow, the Seek Tool, the ViewAll Tool, and the Perspective Tool. The X-rotation, Y-rotation and Dolly thumbwheels, visible in the drawing, are pretty obvious and we will not bother to describe them here.
  

The basic interaction with the display consists of three tasks:

1.  Enable specific display features. v-atlas consists of independent loadable modules. Each does different things.  They are enabled by selecting them from the "Launch" menu.  When selected, a dedicated menu appears in the menu bar. The one most relevant to the display of  the detector is called the "Geometry System".  It's described more  fully below.  After that system is launched one can selectively turn  the subsystems on or off.

2) Selecting Events. This can be done in several ways.  You can type the run and event number in  the run/event selection boxes (remember to hit return).  The program seeks the specified event.  Note, it can only go forward, not backward.  Alternately, you can click sequentially through events by using the Forward Arrow Key.

3) Changing the camera angle and position. There are two main interaction modes, Navigation and Selection.  One toggles between these two modes by choosing either the Navigation Grabber (see the diagram) or the Selection Arrow.  When in Navigation mode, the mouse buttons can be used to navigate the view:

Both Dolly and the Rotation functions operate with respect to the so-called point-of-rotation axis.  This point can be chosen with the Seek Tool. The  Perspective Tool toggles "central perspective", and can be useful when attempting to generate projective views.  

An extensive viewer preference sheet is available by clicking the Right Mouse Button within the display area. 

Additional information is available.  There is a help card on Examiner (the default viewer), but also on Walk, Fly, Plane viewers, on the Common Features of Viewers and on the Color Editor (used for example to edit the background color).

6) Can I get on-line help? 

Yes, each module can print out a short help page.  You have to choose What is this Menu About? from the modules' menu. 

Geometry:

7) How do I view the geometry of ATLAS?

The Geometry of ATLAS can be displayed and interactively queried through the Geometery System.  One must start v-atlas and then choose the Geometry system from the Launch menu.  This causes a new Geometry Menu to appear in the Menu Bar. From within the Geometry Menu, you can choose to display different pieces of the detector.   These can be turned off at a later time if desired.

The Beampipe, three components of the Inner detector plus Inner Detector Services, LAr Barrel, LAr Endcap, Tile Calorimeter, several components of the muon system, can all be individually toggled.  We forsee to add another  toggle button for other cavern infrastructure.

The geometry system shows the geometry as it exists in the transient detector store.  This is the geometry which is presented to all ATLAS processes, most notably simulation and reconstruction.

8) How do I reveal hidden details?

The geometry is organized hierarchically and you can navigate it.  To switch between a volume in the geometry hierarchy and its children, insure first that the display is in Selection Mode.  In this mode, the cursor is shaped like an arrow.  Simply place the Arrow Cursor over the desired volume and click the  Left Mouse Button,  while holding down the Control Key. The volume will be  replaced by its children.

9) How do I hide details I no longer want to see?

The navigation procedure of item #9 can be reversed.  To collapse a set of  child volumes, replacing them by their parent, position the Arrow Cursor over one of the child volumes and click the Left Mouse Button while holding down  the Shift Key. This requires that the display be in Selection Mode (see Item #5).

10) How may I iconize a volume?

There are two ways you may iconize a volume when the display is in Selection Mode (Item 5).  Iconization removes the volume from the display.  (It can later be restored if desired).  To iconize a volume, position the Arrow Cursor over the volume and click the Left Mouse Button while holding down the "Z" key.  This zaps the volume.  Alternately, from the Geometry Menu, choose "Zap on Selection". In this mode, every volume selected with the Left Mouse Button is zapped, until the Zap feature is deactivated.

Iconized volumes go into the Iconized Volume List, in the Filter Panel next to the Run and Event Selection Boxes.

11) How may I restore an iconized volume?

An iconized volume may be restored by double clicking the volume in the Iconized Volume List.  It can also be restored by pressing Enter when the desired volume in the Iconized Volume List is highlighted.  The highlight can be changed either by using up/down arrows within the Iconized Volume list or by selecting with the mouse.  The entire list can be de-iconized by holding down Enter when any item in the Iconized Volume List is selected.

12) How can I obtain the name and composition of an object?

The display must be in Selection Mode (Item #5).  Then, ordinary selection of the volumes with the Left Mouse Button prints the name of the logical volume in the Text Box.  For example THIS IMAGE shows the muon toroids.  One of the volumes has been selected..it's on top, an outline shown in red.  In the Text Box you can read the words:

===> Selected Node: BTBevelledLongTube/Iron

The logical volume name is BTBevelledLongTube.  It's composition is Iron.

Note, the TextBox tends to get shrunk but it can be interactively lengthened if necessary by grabbing onto one of the Control Points.

13) How can I obtain the geometrical parameters of an object? 

As usual the display must be in Selection Mode (Item #5).  There are two kinds of geometrical parameters of interest.  First, the parameters of the shape itself; and second, the parameters of the shape's positioning within the parent volume.

The shape parameters can be obtained by turning on the Print Shape on Selection option from within the Geometry Menu.  If for example you select the liquid argon barrel cryostat, the object will be highlighted in red and in the Text Box, the following output appears:

===> Selected Node: LAr::Barrel::Cryostat::MotherVolume/Air
 =========> Pcon: Start phi = 0.000000 Delta phi = 6.283185
   Plane 0: RMin=1149.800000 RMax=2890.000000 Z=-3530.000000
   Plane 1: RMin=1149.800000 RMax=2890.000000 Z=-2850.000000
   Plane 2: RMin=1149.800000 RMax=2250.000000 Z=-2849.000000
   Plane 3: RMin=1149.800000 RMax=2250.000000 Z=2849.000000
   Plane 4: RMin=1149.800000 RMax=2890.000000 Z=2850.000000
   Plane 5: RMin=1149.800000 RMax=2890.000000 Z=3530.000000

Note, certain shapes (particularly Boolean volumes) do not have a meaningful dump.

The translation parameters can also be obtained by enabling Print Translation on Selection.  At presently, there is no way to dump rotations.

14) May I know the mass of a selected object?

Yes.  For this you should enable Print Mass on Selection from the Geometry  Menu.  Then, when you select objects the Mass will be printed in the Text Box.  Both "inclusive" and "exclusive" masses are printed.

Inclusive:  includes all children. 
Exclusive:  includes only the selected volume.

The inclusive volume can be greater than or less than the exclusive mass.  For example an aluminium tube in which a gas volumes was placed has an inclusive mass less than the exclusive mass. 

WARNING:  the calculation is now failing in some cases for Boolean volumes, or volumes that contain Boolean volumes.  Further debugging of this feature is needed.

15)  May I know the copy number (for simulation) of a selected volume?

Yes, you need to turn on the Print Copy Number On Selection feature. 

16)  Can I dump the entire GeoModel description of a volume and its sub-tree?

Yes.  You need to enable the feature Print Tree On Selection.  The feature dumps the GeoModel description.  This dump can be extremely long so use with care.

We selected a MDT station (that's in the muon chambers); here we reproduce a small sample of the ensuing dump:

===> Selected Node: Station/Air
   VOLUME(Station)
   NAME: 2+NAMETAG: DED01 dedcomponent+TRANSFORM+VOLUME(DedModuleSkin)
         VOLUME(DedModulehoneycomb)
   NAME: 1103+SERIAL DENOMINATOR:: RPC15 rpccomponent+TRANSFORM+VOLUME(RpcModule)
      TRANSFORM+VOLUME(RPC_AL_extsuppanel)
            VOLUME(RPC_honeyc_extsuppanel)
      NAME: 1+TRANSFORM+VOLUME(Rpclayer)
         TRANSFORM+TRANSFORM+VOLUME(RPC_StripPanelCuSkin)
               VOLUME(RPC_StripPanelFoam)
         TRANSFORM+TRANSFORM+VOLUME(RPC_StripPanelCuSkin)
               VOLUME(RPC_StripPanelFoam)
         TRANSFORM+TRANSFORM+NAME: 0+VOLUME(gas volume)
            NAME: 1+VOLUME(gazGap)
         TRANSFORM+TRANSFORM+NAME: 10+VOLUME(gas volume)
            NAME: 1+VOLUME(gazGap)
         TRANSFORM+VOLUME(RpcPet)
         TRANSFORM+TRANSFORM+VOLUME(RPC_StripPanelCuSkin)
               VOLUME(RPC_StripPanelFoam)
         TRANSFORM+TRANSFORM+VOLUME(RPC_StripPanelCuSkin)
               VOLUME(RPC_StripPanelFoam)
      TRANSFORM+VOLUME(RPC_AL_midsuppanel)
            VOLUME(RPC_honeyc_midsuppanel)
    ..

17)  Why is only one section of the  liquid argon barrel accordion
     visible in the display?

The LAr Barrel has a very compact description in terms of GeoModel, but when it is translated into graphical objects it consumes far too much memory for most displays.  So we have limited the display.  The way we do that is by sending a special message to the LAr detector tool ONLY TO BE USED FOR VISUALIZATION limiting the number of volumes.  

Those lines are here, in a python file called GeoModelDisplay.py, and they are also in GeoG4Display.py.  The first is used by v-atlas to display the detector only and the second to display the detector plus event data:

GeoModelSvc = Service( "GeoModelSvc" )
GeoModelSvc.LArDetectorTool.BarrelCellVisLimit = 50

18) Why is the liquid argon endcap "Spanish Fan" not visible?

The liquid argon endcap "Spanish Fan" does not have a visual representation. Visualization of the fan was once considered unimportant by the LAr community.  This is possibly even still the case.  G4 uses a special volume to describe the Spanish Fan.  This volume appears to have a notion of "in" and "out" without really having a  parameterized surface.

The Spanish Fan could be implemented later if time is found. 

19)  Which detector configuration is rendered by v-atlas?  How can I change the detector configuration?

The Rome Initial layout is configured in the python scripts used by v-atlas.  In both GeoModelDisplay.py and GeoG4Display.py, one finds the following lines:

DetDescrVersion = "Rome-Initial"
include( "AtlasGeoModel/SetGeometryVersion.py" )
include( "AtlasGeoModel/GeoModelInit.py" )

The Version Flag Rome-Initial will ultimately not be needed when the detector description configuration is taken from the input file.  We will phase this in during March 2005, not only for Visualization but for all of detector description.

When no input data is available we forsee the ability to pass a tag for a  frozen ATLAS DB configuration to the v-atlas program. 

Measurement

20)  How can I create and move the virtual metre stick?

Virtual rulers, meter sticks, and ten meter sticks are available.  These can be picked up and moved alongside of objects in the display to determine their size.

To obtain one of these tools, choose the Measurement System from the Launch Menu.  A new Measurement Menu appeares.  Choose one of the three tools from that menu.

You can move the meter stick in several ways.  Each case requires that the display be in Selection Mode (see Item #5).

Monte Carlo Truth Information:

21)  How can I see MC particles?

Monte Carlo particles are rendered by the Monte Carlo system.  To invoke it, choose MCTrack system from the Launch menu.  When an event is read, the particles become visible.  This will include particles that come from the event generator as well as particles generated by interactions with the detector material.  The picture below shows the cascade of MC truth particles generated by an electron interacting with the  detector.  In this picture, the charged tracks (electrons an positrons) are blue and the neutral tracks (photons) are white.

22)  What determines the trajectories I see?

The trajectories are integrated in the magnetic field.  The integration takes into  account the bending but does not include energy loss or multiple scattering. 

23)  Can I get the parameters of MC particles?

Click on a track.  The selected track is highlighted.  In the text box, you will see some output that looks like this:

e+  McTrack Number= -11   Pt= 210.622   Eta= 0.985499

Note that the Pt units are MeV.  (You are thinking:  why don't I just label it?  OK, you are right and I will..)

24)  Can I cut on kinematic quantities?

Yes, the MCTrack Menu has a preference sheet that allows you to restrict the range of particles in transverse momentum Pt, Eta, and Phi.  Note again that the units of Pt are MeV.

Note, particles past Eta = 3 are not visible because usually there is a big mess out there.... (That's the present status... is it satisfactory? maybe not).

25)  Can I make my particles show up in different colors?

From within the McTrack Menu, choose the "Generated" button.  This opens a preference page allowing you to attribute different color and style attributes for different tracks.

Most of the color/style attributes are inherited.  Only if the box next to the particle type is checked will they be overridden.  Thus, an electron is a lepton is a charged particle, so unless the check box next to "electron" is selected, the electrons will inherit all properties from charged particle or from lepton. 

The colors are mixed.  Checking each of "R", "G" and "B" arranges for the particles to be drawn white. Available styles are solid, dashed, blink, and none.  Selecting "none"causes the particle and subtypes to be invisible.

Display of Tracking System Hits

26)  How can I see hits in the detector?

Enable the HitDisplay Menu from the Launch Menu.  This menu is very simple and lets you indepedently turn on/off hits from the Pixels (they will be blue), SCT (they will be white) TRT (red), and four muons subsystems (MDT=white, RPC=red, TGC=purple, CSC=yellow).  THIS PLOT shows a shower which began in the SCT and THIS ONE shows a shower in TRT.  The strange looking track has only 4 MeV!

27)  Why do I see hits that do not appear to lie upon tracks?

That depends:

You are looking at Geantinos==> there is a bug.  Don't be shocked, after all, this  display program is designed to find bugs.  Hopefully it lets you find bugs elsewhere and not merely in the display.

You are looking at Muons, Electrons, Pions....==> Most likely the reason is that during the simulation process your primary particle has showered, produced secondaries, or long-range photons, and these have interacted elsewhere in the detector.  Not all of the secondaries are recorded.

In the future we may extend this system to display (optionally) only the hits which are on recorded tracks.  That's something that can be done using truth information.

Display of Calorimeter Hits:

28)  How can I display the LAr hits and the Tile Calorimeter hits?

The "Calo" system should be selected from the Launch Menu.  This causes the Calo Menu to appear in the Menu bar.  The Calo Menu controls the display of both Liquid Argon and Tile Calorimeter sim-hits; the liquid Argon comprises the Electromagnetic Barrel, the Electromagnetic Endcap, the Hadronic Endcap, and the Forward Calorimeter. 

29)  How do I interpret the display?

The above picture shows an electromagnetic splash in the calorimeter and the picture immediately below shows a closeup.  Two kinds of objects are present.  The pseudo-projective blue tower is a  sim-hit which above a threshold of 10 MeV--these are enabled by selecting "LAr Energy" from the Calo menu.    The black plane is a sim-hit with less than 10 MeV.   These can be  switched on by choosing "LAr Cells" from the Calo Menu.

A similar display exists also for the Tile Cal.  The Menu Items are named in a similar fashion.

30)  Can I obtain information from the hits?

LAr Energy Hits (the blue towers) , when selected, print the energy deposited.  The LAr Cells (the black surfaces) are not selectable. 

Importation of Extra Input:

31)  How can I display extra visual information on top of the display?

v-atlas is not only a viewer, it is also a browser!  You can co-display any input in the following formats:

Other files can be converted to one of these, but we are not experts. 

You need to choose the Extra Input System from the Launch Menu.  An "Extra Input" menu appears in the Menu Bar.  This menu lets you choose one or more input files for display. It also allows you to toggle that information in the display, in case you want to get rid of it. 

The picture below depicts a daring aviator on an thrilling flight through the muon  systems, as you can see this opens Pandora's box to all kinds of silliness, so please restrain yourself;  you can perhaps tell that I am barely able to do so myself!

We had to insert the following line to scale the Aviator:

Scale {
scaleFactor 1000 1000 1000
       }

32) Can I display VRML from G4 together with the GeoModel description of ATLAS?

Yes.  Simply obtain a G4 VRML file.  Co-display it with whatever you like in v-atlas
by following the instructions in Item 31.  G4 units are the same as those in ATLAS
so you will not need to rescale.

33)  What if I just have a file of some points (such as conversion electron positions) to display?

The best way to get this into the program is to format it as an open inventor or vrml. We have provided a template for this; it will be printed in the Text Box when you choose the What is the Menu About? option from the Extra Input system.  We won't repeat this  message here.

Below is a picture of the positions of some recent G4 failures which is co-displayed upon the geometry.  It has been generated using this technique.

34) How can I browse the data?

v-atlas has a data browser built in.  It is enabled using the "Banks" system.  (Apologies are made for the non-OO terminology!!! Old farts still have to make a living!!) A list of banks appears in a browser window.  If you click on one of them, a formatted dump appears in the text window.

35) Why do some objects on the input file not appear on the object list in the data browser window?

It appears that job options files are needed even to detect objects on the input file.  So the authors have not been exhaustive about putting all the job options they need in the python scripts used by v-atlas.  Please contact us with specific requests if you feel this is hampering your discovery of the Higgs Boson or other species of particle not too far beyond the standard model.

36) Why do some objects not print when they are selected?

We need to put a few lines within the "Banks system" to print out the contents of objects we want to browse.  This would have been easy if all objects had a required print method, but they do not, and many of the objects do not print themselves.  So, in some cases we have had to write the formatted dump for these objects ourselves.  Obviously, we have put the effort mostly into the objects we care about, and those are mostly the objects used within simulation.

37) Why do some objects say "State Secret" when queried?

Because I cannot figure out what in the world these banks contain or how to parse them. If you know---please let us know.

Extending:

38)  Will you let me put MY stuff into your display?

Yes. We would love to have tracking experts writing a tracking display, jet reco experts writing a jet display.  We think that your expertise in visualizing YOUR objects in the way that YOU want to see them is valuable... Valuable enough for the whole collaboration to profit. 

39)  What steps are involved in extending the display?

The architecture of the display is simple.  Each system running within the display is totally independent.  Two classes are needed, one for system (that's the piece that generates the  view and manages user interaction) and a controller.  Many examples can be seen within  the two packages HITDISPLAY and GEOMODELGRAPHICS.

To ease the task, we have created a so-called TemplateSystem, which does little more than flash a cone + sphere on alternate events.  However the What is this Menu About? button prints a set of detailed instructions on how to turn the TemplateSystem into a HiggsSystem.

Visualization has been defined as the translation of  abstraction into geometry.  The abstractions we normally translate are those that live in the ATLAS detector store:  hits, fields, vertices, missing energy.  There is no need to document them here.  The geometry into which we translate those hits is captured in two important program libraries:

Anybody wishing to extend this system is advised to read the documentation for those two  application libraries.