The Belle II Event Display
Contents
11. The Belle II Event Display#
See also
evdisp.belle2.org for a live event display of the data-taking in real time.
11.1. Starting the display#
The Belle II event display is invoked with b2display
.
You can use it to explore any Belle II File Format files.
You must use a full release, and it is usually
recommended to use the same release that was used to create the file you want
to explore. If you are working remotely, you will need to connect with
xforwarding or start a vncserver
(if permitted by your institute).
$ b2setup <any release>
$ b2file-metadata-show /path/to/your/mdst.root
$ # read the metadata and find the release number
$ b2setup release-xx-yy-zz
$ b2display /path/to/your/mdst.root
See also
11.1.1. b2display
: Run the event display (opens an xwindow)#
Usage:
b2display input_file.root
Show data in given input file using the event display.
You can also open multiple files using wildcards, though you have to pass the string with wildcards to b2display to prevent expansion by the shell, e.g.
b2display "my/files/mdst_*.root".
Using .sroot files, and http://
or root://
URLs is also possible.
Configuration of the display can be changed from the defaults by editing
display/examples/display.py. See output of basf2 -m Display
for available
options.
11.3. Visualised objects#
- Geometry
By default, a simplified geometry is shown. See the last paragraph for instructions on how to disable it or show the full geometry instead. The default can be changed using the
fullGeometry
module parameter. With the full geometry shown, you can also set the level of detail by changing the VisLevel setting of Eve tab → ‘Geometry scene’ → ‘Top’ (then you should see it in the bottom panel). The default value of VisLevel will e.g. hide most of the KLM structure, which might be interesting to you.- MC info (MCParticles, SimHits)
MCParticles are coloured depending on their PDG value (pions in gray, kaons in red, electrons in blue, muons in cyan, protons in yellow, photons in bright green and others in magenta), SimHits share the colour of their parent particle. By enabling the Assign hits to primaries option, you can hide particles generated by Geant4 and have hits instead assigned to their primary mother particles.
By default, only particles that produced hits in the detector are shown, with the exception of primary particles. This can be changed using the Show all primaries, Show all charged and Show all neutrals options.
MCParticles shown as dashed lines use only their starting position and momentum plus creation vertices of any secondaries, and may thus be wildly inaccurate. If the
trajectoryStore
parameter ofFullSim
is used (e.g. set to 2), the real trajectories are plotted and MCParticles are shown as solid lines.- Track candidates & reconstructed hits
This shows track candidates produced by track finders with their associated hits in light blue, as well as reconstructed hits in the tracking detectors not assigned to a track candidate (in violet). Supported hits are PXDClusters, SVDClusters, and CDCHits. If the
useClusters
parameter is set to False, PXDTrueHits and SVDTrueHits will be shown instead of clusters.- Tracks, vertices, clusters
Fitted tracks are shown as lines between green points generated using genfit’s track extrapolation, the reco hits are shown as well in yellow, for the CDC as tiny drift cylinders. GFRaveVertex objects are shown as yellow error ellipsoids, plus a dot in the center (for increased visibility). ECLClusters are red blocks representing energy – if MC info is shown, they should overlap with the MC photons (thin green lines).
11.4. Window management#
Eve allows some advanced window management operations. To access them, expand the small green bar above the view you want to modify by clicking on it.
The Actions menu then gives you access to different operations. All important ones are found at the very top:
SwapWindowWithCurrent swaps this view with the currently selected view, which is selected by anywhere in it.
UndockWindow moves this view into its own window, so it can be freely moved around, or shown in fullscreen.
DestroyWindow removes this view entirely until the display is restarted.
11.5. Troubleshooting#
Unfortunately, the event display is a bit susceptible to xforwarding problems and graphics driver issues (on both the local and remote machines). Please report bugs and ask questions if you encounter problems (tag them with “b2display”).
Here are some common issues:
OpenGL errors, e.g. “GL Error invalid operation” indicate problems with your video drivers. Try upgrading your drivers (On Ubuntu, try
jockey-text -l
to list available drivers.)On some systems with intel GPUs, as well as on VirtualBox, the accelerated drivers may produce crashes (you’ll see a stack trace ending in, e.g.,
i965_dri.so
). Settingexport LIBGL_ALWAYS_SOFTWARE=1
before starting the display may help.VMWare VMs also suffer from the same problem, but the workaround (see last point) doesn’t help there. VirtualBox seems to be more suitable here (it also supports reading hard disk images created by VMWare).
Mac is sometimes particularly problematic. You need to install Xquartz and enable iglx.
defaults write org.macosforge.xquartz.X11 enable_iglx -bool true
See also
CMS have a helpful twiki page listing some further things that might go wrong.
See also
Questions tagged with b2display on questions.belle2.org.
11.6. Module documentation#
The display package contains two important modules. Here is their full module documentation.
- AsyncDisplay#
Starts the Display module asynchronously (with buffered input). Note that the buffer is limited in size and not all events can be passed to the display once it is full. (Configurable using ‘discardOldEvents’ param).
- Package
display
- Library
libdisplay.so
- Parameters
- assignHitsToPrimaries (bool, default=False)
If true, hits created by secondary particles (after scattering, decay-in-flight, …) will be assigned to the original primary particle.
- automatic (bool, default=False)
Non-interactively save visualisations for each event. Note that this still requires an X server, but you can use the ‘Xvfb’ dummy server by running basf2 using ‘xvfb-run -s “-screen 0 640x480x24” basf2 …’ to run headless.
- customGeometryExtractPath (str, default=’’)
Path to custom file with geometry extract.
- deleteVolumes (list(str), default=[])
List of volumes to be deleted. The volume and all its daughters will be deleted completely. Uses Regular Expressions (RE)! If the expression starts with ‘#’, only daughters are removed (# is removed for RE)
- discardOldEvents (bool, default=True)
Discard old events when buffer is full. If false, the main process will wait until there is enough space in the buffer. (i.e. synchronous operation)
- fullGeometry (bool, default=False)
Show full geometry instead of simplified shapes. Further details can be enabled by changing the VisLevel option for Eve -> Scenes -> Geometry Scene -> Top_1.
- hideObjects (list(str), default=[])
Objects which are to be hidden (can be manually re-enabled in tree view). Names correspond to the object names in the ‘Event’. (Note that this won’t work for objects somewhere deep in the tree, only for those immediately below ‘Event’.)
- hideSecondaries (bool, default=False)
If true, secondary MCParticles (and hits created by them) will not be shown.
- hideVolumes (list(str), default=[])
List of volumes to be hidden (can be re-enabled in Eve panel / Geometry scene. The volume and all its daughters will be hidden.
- options (str, default=’MH’)
Drawing options for RecoTracks, a combination of DHMP. See EVEVisualization::setOptions or the display.py example for an explanation.
- playOnStartup (bool, default=False)
When launching the event display, immediately start advancing through events. Useful for control room uses etc.
- showARICHHits (bool, default=False)
If true, ARICHHit objects will be shown.
- showAllPrimaries (bool, default=True)
If true, all primary MCParticles will be shown, regardless of wether hits are produced.
- showCDCHits (bool, default=False)
If true, CDCHit objects will be shown as drift cylinders (shortened, z position set to zero).
- showCharged (bool, default=True)
If true, all charged MCParticles will be shown, including secondaries (implies disabled assignHitsToPrimaries). May be slow.
- showKLM2dHits (bool, default=True)
If true, KLMHit2d objects will be shown in the display.
- showMCInfo (bool, default=True)
Show Monte Carlo information (MCParticles, SimHits)
- showNeutrals (bool, default=True)
If true, all neutral MCParticles will be shown, including secondaries (implies disabled assignHitsToPrimaries). May be slow.
- showRecoTracks (bool, default=False)
If true, track candidates (RecoTracks) and reconstructed hits will be shown in the display.
- showTrackLevelObjects (bool, default=True)
If true, fitted Tracks, GFRave Vertices and ECLCluster objects will be shown in the display.
- showTriggerObjects (bool, default=False)
If true, CDCHit objects will be assigned to trigger segments and trigger tracks will be shown.
- Display#
Interactive visualisation of Monte Carlo, intermediate and reconstructed objects, plus geometry. See https://confluence.desy.de/display/BI/Software+/EventDisplay for detailed documentation.
- Package
display
- Library
libdisplay.so
- Parameters
- assignHitsToPrimaries (bool, default=False)
If true, hits created by secondary particles (after scattering, decay-in-flight, …) will be assigned to the original primary particle.
- automatic (bool, default=False)
Non-interactively save visualisations for each event. Note that this still requires an X server, but you can use the ‘Xvfb’ dummy server by running basf2 using ‘xvfb-run -s “-screen 0 640x480x24” basf2 …’ to run headless.
- customGeometryExtractPath (str, default=’’)
Path to custom file with geometry extract.
- deleteVolumes (list(str), default=[])
List of volumes to be deleted. The volume and all its daughters will be deleted completely. Uses Regular Expressions (RE)! If the expression starts with ‘#’, only daughters are removed (# is removed for RE)
- fullGeometry (bool, default=False)
Show full geometry instead of simplified shapes. Further details can be enabled by changing the VisLevel option for Eve -> Scenes -> Geometry Scene -> Top_1.
- hideObjects (list(str), default=[])
Objects which are to be hidden (can be manually re-enabled in tree view). Names correspond to the object names in the ‘Event’. (Note that this won’t work for objects somewhere deep in the tree, only for those immediately below ‘Event’.)
- hideSecondaries (bool, default=False)
If true, secondary MCParticles (and hits created by them) will not be shown.
- hideVolumes (list(str), default=[])
List of volumes to be hidden (can be re-enabled in Eve panel / Geometry scene. The volume and all its daughters will be hidden.
- options (str, default=’MH’)
Drawing options for RecoTracks, a combination of DHMP. See EVEVisualization::setOptions or the display.py example for an explanation.
- playOnStartup (bool, default=False)
When launching the event display, immediately start advancing through events. Useful for control room uses etc.
- showARICHHits (bool, default=False)
If true, ARICHHit objects will be shown.
- showAllPrimaries (bool, default=True)
If true, all primary MCParticles will be shown, regardless of wether hits are produced.
- showCDCHits (bool, default=False)
If true, CDCHit objects will be shown as drift cylinders (shortened, z position set to zero).
- showCharged (bool, default=True)
If true, all charged MCParticles will be shown, including secondaries (implies disabled assignHitsToPrimaries). May be slow.
- showKLM2dHits (bool, default=True)
If true, KLMHit2d objects will be shown in the display.
- showMCInfo (bool, default=True)
Show Monte Carlo information (MCParticles, SimHits)
- showNeutrals (bool, default=True)
If true, all neutral MCParticles will be shown, including secondaries (implies disabled assignHitsToPrimaries). May be slow.
- showRecoTracks (bool, default=False)
If true, track candidates (RecoTracks) and reconstructed hits will be shown in the display.
- showTrackLevelObjects (bool, default=True)
If true, fitted Tracks, GFRave Vertices and ECLCluster objects will be shown in the display.
- showTriggerObjects (bool, default=False)
If true, CDCHit objects will be assigned to trigger segments and trigger tracks will be shown.