Introduction
An event viewer is necessarily graphically intensive. This makes it impractical, or at least very inconvenient, to use the event display over X11 forwarding.
At time of writing, many larsoft users are using the code over ssh due to the large overhead and complexity of larsoft installation.
To deal with this, event display has been broken into 2 parts. Part 1 is the Landed art module which extracts information of use to the event display from the normal art/root data files. Part 2 is the LANDED app with no art or even root dependencies which performs the actual event display and can run on essentially any computer with trivial installation.
Art Module: Landed
Introduction
Landed is an art module first introduced into larsoft v05_12_00 which reads data from the art root files and makes it available to the LANDED app. It can do this in one of 2 ways. 1: Write out an eddb file which can be read by the LANDED app. 2: Send event information immediately to the LANDED app over a unix socket.
The eddb file format is just an sqlite relational database file with cross-linked tables for information which may be of interest in the event display. The detector geometry (in VRML form) is also included in the file so that LANDED can (within reason) be used for multiple detector designs without modification.
Usage: eddb file
- Create a fhicl file to convert your chosen root file(s). There is an example here for the far detector: "landed.fcl" and another for SBND: "landed_sbnd.fcl".
- Use the "lar" command to run the conversion art job as you would any other.
- Copy the resulting eddb file to your local machine
Usage: unix socket
- Launch the LANDED app and run the socket server (Ctrl-S or File menu).
- Create a fhicl file to stream your chosen root file(s).
- Use the "lar" command to run the art job as you would any other.
Installing the LANDED app
The LANDED app does not depend on the presence of obscure or cutting edge tools or libraries and should build rather simply on a wide variety of Linux machines
Building on Mac is a little more complex and on Windows very much more. I intend to provide binaries for all platforms for which there is interest, starting with mac and windows
- Landed for Windows 7 or later
- Landed for MacOS 10.6 (Snow Leopard) or later
- Landed for RHEL6/SL6/SLC6/Centos6
- Landed Source
If your mac objects to the app for security reasons, the solution is to set 'Allow Apps from "Anywhere"' in the security section of system preferences, run the landed app once, then restore the security setting. After that the problem should not recur.
To build from source should just be a matter of running "make install" in the extracted source directory.
The default installation destination is $HOME/bin. To install to somewhere other than $HOME, "make install prefix=INSTALLDIR".
The LANDED app depends on QT4 (with the sqlite3 plug-in), sqlite3 and zlib. Building also depends on the headers for these (-dev or -devel packages). These are usually available on SL6 workstations and most other Linux distributions. If not, they're rather trivial for an administrator to install with yum or apt. Basic testing indicates that it also builds against QT5, but there's no advantage to this as it does not use any functionality added for QT5.
Also, performance will suffer considerably if you don't have an accelerated graphics driver installed and configured on your machine. Watch out in particular for the nouveau nvidia drivers from which direct rendering is missing in SL6/Centos6/RHEL6, although it is present in SL7. I recommend the nvidia drivers from elrepo for SL6.
Using the LANDED app
Running the LANDED app
- Linux: Type 'landed'.
- Mac: Double-click LANDED.app wherever you dropped it
- Windows: Click on the Start Menu item
Loading an eddb file
Run the LANDED app and then choose 'Open' from the 'File' menu or hit 'Ctrl-O' (Cmd-O on Mac). Also, double-click on the file to open should work straight away on Mac and Windows. It's not hard to set up from Linux either.
The UI Layout
On the left, there is the choice of 4 displays. The 3D is the most involved and the bulk of the documentation below refers to that. The 3 2D projections are often clearer not only because they are less cluttered but because they are focused on the TPC active volume.
On the right you can switch between 3 lists: Track Segments, Hits and Detector components. They're fairly self explanatory, but it's worth mentioning that if you select a hit or track in their respective list, it gets highlighted in all 4 displays. Also, if you double-click a hit or track in their list, the 3D display will jump to it.
I would have thought that most of the controls and menu options not discussed below are rather intuitive, but I'm quite happy to add documentation on request.
3D Viewing Modes
There are several viewing modes on the 'View' menu.
There is a full screen mode, Cmd/Ctrl+F to get in or out of this mode.
You can choose show the detector as a wire-frame, in full, or both or neither. The default is to show the detector wire-frame.
3D Navigation
Navigation is achieved by holding down the left mouse button over the display and dragging.
There are 3 primary navigation modes: 'Move', 'Pan', and 'Zoom/Twist'. These are accessible from the buttons at the bottom of the window, or from the 'Navigation' menu.
- Move: shift the detector left/right or up/down;
- Pan: rotate the detector about the vertical or horizontal axis;
- Zoom/Twist: shift the detector forward/back or rotate about the depth axis.
'Origin' is a special mode which allows the user to change the centre of rotation. It is useful to move this to the centre of the part of the event/geometry which is of interest. Then this will stay in the centre of the view when using 'Pan' navigation mode.
Point the mouse at a piece of the detector geometry and it will be identified by the display of some text in the bottom right of the display. If you don't want to see it, double-right-click on it or uncheck it in the detector components list. Right clicking on a Hit, Track or piece of detector geometry will highlight it in the corresponding list. All TPC wires are hidden by default.
The keyboard arrow keys can be used to navigate if you prefer.
Alternatively, there are keyboard shortcuts which work without switching modes
| Key | Action |
|---|---|
| A | Move left |
| D | Move right |
| W | Move up |
| S | Move down |
| E | Pan left |
| T | Pan right |
| R | Pan up |
| F | Pan down |
| G | Twist left |
| J | Twist right |
| Y | Zoom in |
| H | Zoom out |
| U | Shrink origin sphere |
| O | Enlarge origin sphere |
| I | Move origin out |
| K | Move origin in |
If you find that the keyboard shortcuts are not working, it's probably because the 'focus' is not on the 3d display. Hit 'Tab' to shift the focus, or click on the 3d display.