The TriD Event Viewer for MINOS
Nathaniel Tagg
First version November 2002
Update: March 2003
"TriD" is a pretty horrible name invented under time pressure that is
supposed to mean Three-Dimensional (Tri- D-). This viewer is based
directly on the OpenGL framework (rather than on the ROOT interface)
and so works best when operated with hardware 3D acceleration (which
has become both cheap and plentiful these days). It uses Brett
Viren's Midad package for it's underling interface to the Loon core
software, but is built ground-up to be an independent event viewer.
The current feature set includes:
- View strips or UV strip intersections in glorious full color 3D
- Standard U/V 2D view
- View hits by physical electronics location
- View hist by PMT pixel/PMT/Mux box location
- Interactive histograms for time, charge, etc
- Animation
- Bare-bones printing (not very useful.. I suggest screen captures)
- Bare-bones window managment and customization
- Fast hit selection and user feedback
Package Requirements:
- A relatively fast processor. (I run on a 1 GHz laptop very smoothly)
- An X server with either a fast graphics card (with installed drivers)
or a fast processor for software rendering
- Standard Loon
- Up-to-date Midad
- StupidGeometry (an associated package with TriD, may be phased out)
Contents:
Some Definitions
How To Set Up TriD
Step 1: Get the code
Step 2: Figure out
how you're going to use it
Step 3: Ensure
OpenGL is installed
Step 4: Compile
Step 5a: Running the executable
The Static Binary
Step 5b: Running from a script
and loon
Step 6: Share and Enjoy
General Features
Tips and tricks
TriD Menu Options
Animation...
Windows:
Midad Controls
Detector Page
UV Page
Crate Page
PMT Page
Color Histogram
Transparency Histogram
Click on an area below to get information on that view:
Some Definitions:
Lost? Here are some buzz-words.
OpenGL: A high-level API for programming 2d and 3d graphics
applications. OpenGL gives a cross-platform standard by which you can
do sofisticated graphics in a hardware-independent way, allowing
software to work across operating systems and on many different
graphics cards.
X Server: A program that draws X windows. Note that the server
is the machine you have in front of you; this is counterintuitve. With,
say, a database system, the server will usually be the remote machine.
In X, the server is the local machine.
X Client: A program that requests windows from an X Server to
draw things. In our case, the X Client program is Loon.
DRI: Direct Rendering Interface. This is an optional part of
your X-Server that will allow OpenGL to draw using you neeto 3d
hardware acceleration. Without this, OpenGL will revert to slower
software rendering, which is not very good.
GLX An extention to the X11R6 graphics protocol that allows
OpenGL commands to be piped from the client to the server. This code
must be built into both the X server and the X client to make
everything work. Typically, 'built into the X client' means that
the correct shared libraries are used by the client.
HOWTO setup TriD
Step 1: Get the code
Make a test release. Get the packages:
- Midad
- TriD
- StupidGeometry (Used by trid as a fast replacement
for UgliGeometry)
Step 2: Figure
out how you're going to use it
There are two ways you can run Loon: Locally and remotely.
Local use is when the cable on your monitor plugs into the video
card on the machine that is running Loon. This is when, for
instance, you're running Loon on your laptop, or on your very own
desktop. It is NOT the case if you are running ssh to some other
boxen, running Exceed or some other X server software, or otherwise are
not sitting in physical proximity to the CPU running the Loon code.
Remote use is where you are using an X server on the computer in
front of you that is connected to a remote computer. This is
frequently how we work if we are using a communal department computer
or a farm. You may be connected through a ssh tunnel or through a
XDMCP server, or whatever.. if you are not sitting at the same
computer, it's remote.
Why do we care? Well, most graphics under unix are X11-based..
draw a line here, print some text in this font, or (rarely) blit this
bitmap to the screen. With 3-d graphics, this basic set of
commands needs to be extended. There is a good, standardized
protocol for this called GLX (OpenGL under X). For TriD to work
nicely, it means you have to have GL and GLX working on both your X
server and your X client. We'll get this working in the next step.
For now, just work out:
a) whether you're running locally or remotely
b) if you're running remotely, what your local and remote operating
systems are
Step 3: Ensure
some kind of OpenGL is installed.
You will need the OpenGL headers installed on your system to compile,
and you will need OpenGL libraries to run.
In particular, you will need:
<some_include_path>/GL/gl.h
<some_include_path>/GL/glu.h
<some_include_path>/GL/glx.h
<some_library_path>/libGL.so
<some_library_path>/libGLU.so
On most systems <some_include_path> is your X11 include path
(/usr/X11/include) and <some_library_path> is usually /usr/lib or
/usr/X11R6/lib.
Having these files means you can compile.. but the system may not work
to your liking. Start the compile and then follow the flowchart below.
If you do not have these files, you'll need to get them. Consult this
flowchart:
I am running LOON locally... I am running LOON remotely
...under Linux ... on a remote Linux machine
.. under some other OS ... on a remote SGI machine
... on a remote Sun/Solaris machine, or other
Running Locally under Linux
You will need to install OpenGL libraries. This can either be a
free (as in speech) implimentation called Mesa, or can be a set of
proprietary drivers and libraries. You will also want to have an
up-to-date version of XFree86 installed, preferably version 4.2 or
higher. This is standard on newer distrubutions (RedHat 8.x,
Mandrake 8 or 9, etc.).
Mesa is available in the usual RPM repositories. You will want the most
recent version available. You will need both Mesa and the
Mesa-devel packages (so you get the header files).
Proprietary drivers are available from nVidia at nVidia.com.
These are excellent if you have an nVidia graphics card.
Running Locally Under Some Other Unix
Get your sysadmin to install OpenGL libraries. I can't much help
you here. However, most UNIX implimentations are designed for
high-end workstation work, which often involves 3D design, so
everything should be supported.
Running Remotely Under Linux
See above about running locally.
The caveat is that you MUST have an up-to-date XFree86.
However, you don't need the OpenGL libraries installed in system
space; you can install them in your $INSTALLATION directory.
Because you will not be using the hardware on your big fat linux
box, you don't need any particular make of drivers or libraries;
anything will do. You can, for instance, download and install the
nVidia driver libraries and header files. Alternatively, you can
download and install the Mesa stuff, too.
Running Remotely Under SGI
Silicon Graphics invented the whole GLX thing, and have been
some of the main movers and shakers behind OpenGL in general. You
should have no problem.
Running Remote Under Sun/Solaris or
other
Beats me. I think that most workstation Unicies like Solaris
fully support the OpenGL standards, but you'll have to talk to your
support person to get the libraries installed.
Step 4: Compile
To the usual
prompt $ gmake
in your test release.
Step 5a: Running the Executable
The TriD/stat subdirectory will build a binary called "tridshar".
This binary does not work like the usual root/loon libraries, but is
much simpler.
It can be run from anywhere. It needs to either have
SRT_PUBLIC_ENV or SRT_PRIVATE_ENV set, or you can set:
prompt $ setenv TRID mytestdir/TriD/fonts
Any one of these will do; this is to allow TriD to find it's font files.
To run the executable, simply do:
prompt $ tridshar F00009850_0000.mdaq.root
C00031416_0000.tdaq.root
or whatever files tickle your fancy. The executable has a
built-in job control path that looks to see if CandDigits have been
created and creates them if they haven't. It then looks to see if the
data is Far Detector data.. if so, it looks to see if a
DeMuxDigitList is available.. if not, it runs a package called
DemuxFast, which is a cut-down version of Mark Thompson's "Cambridge"
demultiplexer (which has the virtue of being fast and fairly accurate).
Therefore, any file may be run on it:
- Far Detector mdaq files
- Far Detector cand.root files (that have CandDigits)
- CalDet tdaq files
- CalDet cand.root files
Note that reroot files won't work, although files that have been
generated by RerootToRawDataModule probably will.
Caldet data from both detector electronics will be properly decoded.
Near detector data hasn't been tested yet. It probably won't look
right if it does work. But then again, there's no REAL near
detector, so stop whining.
In addition, TriD attempts to play a dirty trick: if there is a file
called PlexData.root in the fonts directory, it will attempt to load
this file in. This file can contain a PlexLoanPool object, with
one or more Plex maps (possibly with hacked validity dates).
These plex objects load much faster than the database can, and so will
speed up the viewing process somewhat. The calibration database cannot
be tricked in this way, and so the calibration data will continue to
load through the slower database mechanism.
The Static Binary
It is possible to build a static binary. To do this, you need to
perform these steps:
prompt $ cd $ROOTSYS
prompt $ make static
<wait a few minutes>
prompt $ srt_setup SRT_QUAL=profile
prompt $ msrt build (or cd $MINOS_SOFT/minossoft/dev; make all)
prompt $ cd <test dir>
prompt $ make TriD.all
<wait and watch your disk crunch.. linking the static binary
can take ~8 minutes and many MB of memory>
Optional:
prompt $ strip bin/Linux2.4-GCC_3_2-profile/tridstat
This creates a statically linked binary "tridstat" that can be used
exactly as above.
This binary is useful because it will work on any system with the same
software installation, but does not require Loon, ROOT, or any of the
external libraries, although it will still require the X and OpenGL
libs. It will never break when you install new software; you can
copy the static binary to a permanent location and it will continue to
work. It takes up only 20MB when stripped (plus font files).
You WILL still need to have your TSQL environment variables set to
query a database, unless the data you're looking at is already in
demuxed CandDigit form. However, this can work over a network, so
you don't have to have MySQL installed locally.
Step 5b: Running from a
script
The script trid.C can be used to make TriD jump through it's hoops.
TriD requires CandDigits to work. I usually use TriD by
running a Loon job over the raw data file to make CandDigit candidates,
and writing those out. If you want to run on raw data, you'll
need to include CandDigit::Reco and (for FarDet data) your favourite
demultiplexer.
trid.C:
// trid.C
// Script for viewing 3d images with TriD.
// Requires: Midad (Fall 2002 version), TriD,
StupidGeometry
//
// I prefer to make a file with canddigits and
RawDigits,
// using cand_digit_out.C in the example macros.
//
// Then I run: loon trid.C digits.root
// and enjoy the fun. (Note: no -q switch!)
//
// Nathaniel Tagg, Oct, 2002
//void trid()
{
gStyle->SetPalette(1,0);
gSystem->Load("libMidadMultiPage");
gSystem->Load("libStupidGeometry");
gSystem->Load("libTriD");
JobC* jc = new JobC;
Mint* mint = new Mint(*jc);
PageDisplay* pd = mint->SpawnDisplay();
// Make the windows. This is a
complete list of the TriD windows available.
// They are not all equally useful.
pd->AddPage("TridDetector");
pd->SpawnSinglePage("TridUV");
pd->SpawnSinglePage("TridPmt");
pd->SpawnSinglePage("TridCrate");
pd->SpawnSinglePage("TridHisto");
pd->SpawnSinglePage("TridTransHisto");
// Uncomment this to see the standard Midad display
//pd->AddPage("Multi");
jc->Path.Create("default","");
jc->Input.Set("Streams=DaqSnarl,Cand");
jc->Path("default").Run(1);
// The TridControl object is a singleton which
// controls most of the functionality of the display
TridControl* tc = TridControl::Instance(pd);
// This line will move the windows around to however you
// saved them last time.
tc->RestoreWindowGeometries();
};
prompt $ loon trid.C my_digit_data_file.root
Step 6: Share and Enjoy
Play around. See the next section for how to use the important
features.
General Features
Using the mouse:
Moving the mouse:
If the mouse is moved over an object, the object is 'picked'.
It becomes highlighted. Any other objects in every other
view that share any of the same CandDigits will also highlight.
Put it over a strip in the Detector view and the associated PMT
and pixel will highlight in the PMT view, and the associated electroncs
channel will highlight as well.
Selection:
Click the first mouse button to select or deselect objects.
Selected objects will highlight as above. In addition, any
relelvant views will automatically re-multiplex the selected hits. That
is: click on a PMT, and all the strips that could be associated with
that PMT's hits will be shown in the Detector view.
Rotation:
Click and drag with the left mouse button to rotate the 3D views.
Clicking and dragging on the 2D views with the left mouse button
will allow you to pan.
Panning:
Click and drag with the right mouse button on any view to pan the view
(i.e. move it around from side to side).
Zooming:
Zooming is most easily done with the mouse wheel, if you have it
configured to work with your X server (i.e. buttons 4 and 5).
Push the mouse wheel forward to zoom in, back to zoom out.
If your mouse wheel doesn't work, you can click and drag with the
middle mouse button to zoom. Dragging towards the center of the
window will zoom out. Dragging from the center out will zoom in.
(Think of it as grabbing part of the detector and moving it where
you want it.) If you have only two mouse buttons, you can usually
'emulate' the middle button by clicking both the left and right buttons
simultaneously.
Tips and tricks
TriD Menu Options
Page Menus
Pages/Trid Pmt Map/View:
You can select a 3D view for this window, which
is only for eye candy. The graph heights represent charges.
Usually the 2D view is good enough for us regular folk.
Pages/Trid Crate Map/View:
You can select a 3D view for this window, which is only for
eye candy. The graph heights represent charges. Usually the 2D
view is good enough for us regular folk.
Pages / Trid U-V Projection / View:
You can select a 3D view for this window, which is only for
eye candy. The graph heights represent charges. Usually the 2D
view is good enough for us regular folk.
Pages / Trid U-V Projection / Best Demux Only:
This is on my default. Turning this option off will cause the display
to show all the possible demultiplex possibilities for every hit (i.e.
the event is not demultiplexed at all).
Pages / TriD Detector / View / 2D (Orthographic)
Projects the image orthographically, i.e. without
perspective. This is useful only in certain orientations.. for
instance, rotating the detector to (theta,phi)=0, which will show all
strips and intersections as a projection in Z. Usually this just
looks bad.
Pages / TriD Detector / View / 3D
This is the default view mode.
Pages / TriD Detector / View / Stereoscopic
This view mode shows two representations of the
detector side-by-side from slightly different viewing angles. The
two views are rotated such that it is like the view from two eyes
several meters across. By focusing each eye onto each image, you
can see the detector in glorious three dimensions. This works
exactly like an old stereoscope, or a ViewMaster.
Pages / TriD Detector / View / Crosseyed
Projects the image orthographically, i.e. without
perspective. This is useful only in certain orientations.. for
instance, rotating the detector to (theta,phi)=0, which will show all
strips and intersections as a projection in Z. Usually this just
looks bad.
Pages / TriD Detector / Show Strips
Pages / TriD Detector / Show Intersections
Pages / TriD Detector / Show Lone Strips
Each of these menu items can be checked. Strips and Intersections
are as described above; one or both may be shown (although the
intersections are difficult to see when strips are plotted)). Lone
Stripsallows strips that have no valid intersections to be plotted
(when one is plotting intersections but not strips generally). This is
useful, for instance, for seeing veto shield hits in conjunction with
intersections.
Pages / TriD Detector / Exaggerate Strip Width
Pages / TriD Detector / Exaggerate Strip Thickness
Thickness is the size of a strip in the Z direction; width is the
size of the strip perpendicular to it's length along the plane.
These options are on be default, and double the apparent size of
each strip. This allows for easier viewing of the (normally very small)
strips. Each doubles the apparent strip sizes.
Pages / Trid Detector / Best Demux Only:
This is on my default. Turning this option off will cause the display
to show all the possible demultiplex possibilities for every hit (i.e.
the event is not demultiplexed at all).
Views Menu
Views / Digit Text
Brings up a text window that displays mouse-over information for
the currently 'picked' hit. Putting the mouse over any model on
the screen will bring up a complete list of information about the
CandDigits that comprise that model.
TriD Menu
TriD / Animation.
This menu option brings up a dialog box: 
Start/Stop Animation: Does just that.Time: The time (in
nanoseconds) currently being displayed. All hits with times earlier
than this are currently shown.
Display Rate (fps): The rate, in frames per second, that TriD
will attempt to refresh displays. 10 fps is conservative on tested
systems.
Animate View Angle: When checked, causes any 3D windows to spin
around the Y-axis
View Speed: Rate at which 3D windows spin about the Y-axis (in
reveloutions per second)
Animate Event: When checked, the hits animate. As the time
advances, hits appear.
Use Time Window: FIXME: Not yet implimented
Time Window: FIXME
From/To: The time range, in nanoseconds, that the event will
animate through. Most events are less than 150 ns long.
Event Speed (ns/s): The rate at which the event will appear on
the screen; a value of 2 means that 2 nanoseconds of data will appear
for each second of real time.
TriD / Color Modes / ...
Changes the what colour represents in all TriD views. For instance:
Charge (pe): Each object will be drawn with
the sum of photoelectrons that make it up. (i.e. a PMT in the PMT map
will show the sum of all photoelectrons on that tube.)
Charge (adc counts): Each object's colour will represent the
sum of ADC counts (pedestal subtracted for NearDet).
Mean Time (raw): Each object's color represents the mean time
for all hits in the object. (I.e. for a strip in FarDet, this is the
average of each end's time.) This value is in nanoseconds, but is
uncalibrated for time offsets.
Mean Time (t0): As above, but calibrated for time offsets
(t0's)
Earliest Time (raw): The earilest hit in the object,
uncalibrated for offsets.
Eariiest Time (ns): The earilest hit in the object, including
t0 offsets.
Occupancy: The number of CandDigits that go into the
object. For the Far detector, this is the number of hits. (i.e.
for a strip, one or two). For the near detector, this is the
total number of QIE buckets that were not sparsified.
TriD / Trans Modes / ...
As above, but controlling the transparency of the object
rather than the color.
TriD / Histograms / ...
There is one menu item here for each open TriD view. You may choose
to histogram any of the windows (each of which will have a different
makeup of model objects.. i.e. strips in the Detector view, or PMT
pixels for the PMT view). This does not change the scale, only
the histogram contents.
TriD / Show Underscale
TriD / Show Overscale
These options are selected by default. When they are
deselected, any models that are over/under scale on the histogram are
no longer shown.
Example: Select charge in PEs from the menu. Drag the color histogram
left so that the scale starts at 5 pe. Then deselect the 'Show
Underscale' option (make it un-ticked). Now, all strips with less
than 5 pe of charge are no longer drawn. Reselect the menu option
to show them again. This is useful for (for example) eliminating
cross-talk hits from your view.
TriD / Use Stupid Geometry (faster)
This option is on by default. It tells TriD to use the
StupidGeometry package to determine the detector geometry.
Although not accurate or definative, this allows rendering
quickly. If deselected, TriD will revert to using UgliGeometry.
Note however that when this is done, UgliGeometry will load
(causing Loon to load the DB tables for the current context, which can
take a couple of minutes.) StupidGeometery is probably good
enough for most applications.
TriD / Save Window Geometries
TriD / Restore Window Geometries
When these items are chosen, TriD will save or restore the
window positions to the users' preferences. These preferences are
kept in $HOME/.tridrc, in this form:
Trid.WindowGeom.Midad:
440x120+0+0
Trid.WindowGeom.TridUV:
816x205+0+732
Trid.WindowGeom.TridPmt:
455x195+0+116
Trid.WindowGeom.TridDetector:
569x565+471+11
Trid.WindowGeom.TridColorHisto:
516x209+0+561
Trid.WindowGeom.TridTransHisto:
532x156+0+576
Trid.WindowGeom.TridCrate:
458x267+0+309
The geometry string is a standard X-string, and includes window
decorations (i.e. title bar, widgets, etc).