renaming function to avoid library conflict (discovered in test/generators/TUHKMgen)
[u/mrichter/AliRoot.git] / MUON / READMEmchview.txt
0145e89a 1// $Id$
3/*! \page README_mchview Tracker visualisation program
9016a84e 5A visualisation program, \link mchview.cxx mchview \endlink, is now available to display, in two dimensions
0145e89a 6 (3D visu being done within the EVE framework), the tracker chambers.
8\section mchview_install Installing the program
9016a84e 10\em mchview should be installed together with the rest of AliRoot. Two points should be noted though.
11 \em mchview is using two external files to run properly. One is a resource file $HOME/.mchviewrc, used
0145e89a 12 to "configure" the program and keep some history of the user interaction with it (e.g. the list of recent
13 data sources used). The other one is a Root file, padstore.root (default name, can be changed with the resource file),
14 which contains lots of precomputed information (like the contours that are being displayed, the geometry transformations,
9016a84e 15 etc...). By default, \em mchview will look for this file in the current directory. If it's not there, it will
0145e89a 16 ask if it's OK to create it. Be warned that this will take a while (but is only done once).
9016a84e 17 If you install a new version of \em mchview, it is recommended to delete this file first, before lauching \em mchview again.
0145e89a 18
19\section mchview_navigation Navigating the display
9016a84e 21When starting \em mchview (and after the padstore.root file has been created for the first time),
0145e89a 22you'll be presented with two tabs. The first one allow to navigate within the detector, and the
23second one to select data sources to be displayed.
24The first tab offers a global view of the 10 tracking chambers. On the right you'll see
25 a color palette (used in the display of data sources, see later). On the top (from left to right) are
26 navigation buttons (backward and forward), and radio buttons to select the kind of view you'd like : you can
27 view things for a given cathode or for a given plane. Note that in some instances those buttons maybe inactive.
28On the bottom are three groups of radio buttons, labelled "responder", "outline" and "plot", followed by data source buttons (see later) :
29 Each group will contain a number of buttons corresponding to different view levels of the detector (e.g. detection element, manu, buspatch, etc...).
9016a84e 30 In \em mchview jargon, what is displayed on screen is called a "painter". The meaning of responder, outline and plot is as follow :
0145e89a 31
32 - responder (only one selected at a time) is the type of painter that responds to mouse events. When you mouse over responder painters, they'll
33 be highlighted (bold yellow line around them), and some information about them will be displayed in the top right corner.
34 If you click on a responder painter, a new view will open to show only this painter. If you meta-click (button2 on a mouse, or alt-click on a Mac for instance)
35 on a responder painter, a new view will open, showing the clicked painter and its "dual" (the other cathode or other plane, depending on how the first one
36 was defined).
38 - outline (multiple selection possible) indicates which painter(s) should be outlined. When starting the program, only manus are outlined, but you
39 can outline the detection elements, the chambers, etc...
41 - plot (see later about plotting and data sources) indicates at which level you want to see the data.
43On the bottom left is a group button used to select which data source should be displayed (empty until you select a data source, see next section).
44Next to it will be a list of buttons to select exactly what to plot from a data source (once you've selected a data source only).
46Note that whenever you click on a painter and get a new view, you get use the navigation buttons (top left) to go forward and backward, as in
9016a84e 47a web browser for instance. Note also that the \em mchview menu bar contains a "History" menu where you can see (and pick a view) all the views that were opened.
0145e89a 48
49Even before selecting something to plot, at this stage you could use the program to familiarize yourself with the detector structure (aka mapping).
51\section mchview_datasource Specifying the data source
9016a84e 53The second tab of the \em mchview allows to select one or several data sources.
0145e89a 54Each data source, in turn, will provide one or more "things" to be plotted.
55The number of "things" actually depends on the data source.
56For instance, a raw data source will allow to plot the mean and the sigma of the pad charges.
58Be warned that this part of the program is likely to evolve, as you'll for sure notice that the interface is quite crude for the moment.
60From top to bottom, you'll see group of frames used to :
62- select from a list of recently used source
8741815f 64- select a raw data source (either by typing in its full pathname, or opening a file dialog).
10eb3d17 65The second line in this group is to specify that you want to calibrate the data. Check one of the calibrate buttons, and specify the
8741815f 66location of the OCDB to be used. If that field is not empty (and the corresponding entry is correct, of course),
67the raw data will be calibrated.
68The last line in that group is a single check button, to instruct the program to produce histograms of the data (see \ref mchview_histogramming)
0145e89a 69
70- select an OCDB data source (pedestals, gains, capacitances)
72In all the frames, once you've selected or entered the needed information, you'll click on the "Create data source" button,
73and a new data source line will appear in the bottom of that tab (and in also in the first tab, that data source will now
74be selectable for plotting). Each data source line indicates the short name of the data source, the full path, and a list of buttons to run, stop, rewind and
75remove. Run/Stop/Rewind is only selectable for data sources where the notion of event means something (e.g. for pedestals it won't).
8741815f 76The short name of the data source is as follow :
78- RAW# : raw data for run #
79- RAW(#) : raw data for simulated run (where run number is always 0, so # here is the number of such data sources opened at the same time)
80- HRAW# (or HRAW(#)) : as above, but with histogramming turned on
49419555 81- (H)CALZ# (or (H)CALZ(#)): as above, but for data where pedestal subtraction has been done (and no gain correction whatsoever)
82- (H)CALG# : for data where pedestal subtraction and gain correction has been applied (but no channel-per-channel capacitance correction done)
83- (H)CALC# : for data where pedestal subtraction and full gain correction (including channel-dependent capacitance correction) applied
0145e89a 84
9016a84e 85Note that all the file paths can be local ones or alien ones, if you have a correctly installed alien, and you use a short wrapped to call the \em mchview program.
0145e89a 86For instance :
9016a84e 87<pre>
0145e89a 88alias mchl $HOME/mchview.alien
9016a84e 89</pre>
0145e89a 90
91where mchview.alien is a little script :
9016a84e 92<pre>
0145e89a 93#!/bin/sh
0145e89a 94test=`alien-token-info | grep -c expired`
0145e89a 95if [ $test -gt 0 ]; then
96 echo "Token expired. Getting a new token"
97 alien-token-destroy
98 alien-token-init
99elif [ ! -e /tmp/gclient_env_$UID ]; then
100 echo "Getting a token"
101 alien-token-init
0145e89a 103if [ ! -e /tmp/gclient_env_$UID ]; then
104 echo "No token. Exiting"
105 exit
0145e89a 107source /tmp/gclient_env_$UID
0145e89a 108export alien_API_USER=youralienuserid # only needed if different from your local username
0145e89a 109mchview $*
9016a84e 110</pre>
0145e89a 111
8741815f 112\section mchview_histogramming Histogramming
114Starting at version 0.9 of the \em mchview program, you can now produce histograms of the raw adc values, while running over the
115data. For this you have to check the "histogram" button when creating the data source. Please note that turning on the histogram will slow down
116a bit the data reading.
117Histograms produced by the program are as compact as possible in order to fit in memory (so they are *not* plain TH1 objects).
118Plain TH1 objects are produced later on (on request only), and should be deleted as soon as possible (you have to realize that
1191 million TH1 of 4096 channels has no chance to fit in memory...)
10eb3d17 120Access to the histograms can be done through the GUI, using the right click on any painter.
121For extra flexibily, you can also use the root prompt (of the \em mchview program itself).
8741815f 122First get the data object, and then ask the data object to create the histogram(s) you want. Remember to delete those histograms as soon
123as you no longer need them :
126AliMUONPainterRegistry* reg = AliMUONPainterRegistry::Instance();
128AliMUONVTrackerData* data = reg->FindDataSource("HRAW(1)");
129TH1* h = data->CreateChannelHisto(707,1025,63);
131delete h;
132h = data->CreateManuHisto(707,1025);
136You can get histograms for all levels (except PCB) : channel, manu, bus patch, detection element, chamber. See AliMUONVTrackerData doc. for the methods.
10eb3d17 138\section mchview_savingprinting Saving and printing
0145e89a 139
10eb3d17 140From the File menu of the \em mchview application, you can use SaveAs and PrintAs popups to respectively save the current data sources (meaning you can quit
141the program and start again with the same filled data sources, without having to rerun on the source) and print the current display.
142Printing needs a little bit of polishing (e.g. getting a nice and descriptive title would help a lot), but it's better than nothing.
143Note that the \em mchview application now has a \em --use option to reload a previously saved .root file (same effect as using the File/Open menu).
145\section mchview_warnings Important warnings. Please read.
0145e89a 146
0145e89a 148
149In principle, you could have several raw data sources running at the same time. This is NOT currently working. You can have several data sources opened
150 at the same time, but not running at the same time. (this has to do with AliRawReader not being thread-safe for the moment).
152Once you have one or more data sources added, you can go back to first tab and start looking at the data ;-)
9016a84e 154This chapter is defined in the READMEmchview.txt file.
0145e89a 156*/