[u/mrichter/AliRoot.git] / EVE / README

EVE - Event Visualization Environment
=====================================

EVE is composed of:
1. small application kernel;
2. graphics classes with editors and OpenGL renderers;
3. CINT scripts that extract data, fill graphics classes and register
   them to the application.

The framework is still evolving ... some things might not work as expected.


Usage
=====

1. Initialize ALICE environment.

2. Spawn 'alieve' executable and invoke the alieve_init.C macro, for example:

To load first event from current directory:
   # alieve  alieve_init.C 
To load 5th event from directory /data/my-pp-run:
   # alieve 'alieve_init.C("/data/my-pp-run", 5)' 
Interactively:
   # alieve
   root[0] .L alieve_init.C
   root[1] alieve_init("/somedir")

3. Use GUI or CINT command-line to invoke further visualization macros.

4. To navigate the events use macros 'event_next.C' and 'event_prev.C'.
   These are equivalent to the command-line invocations:
   root[x] Alieve::gEvent->NextEvent()
or
   root[x] Alieve::gEvent->PrevEvent()
The general form to go to event via its number is:
   root[x] Alieve::gEvent->GotoEvent(<event-number>)

See files in EVE/alice-macros/ from the ROOT browser that is spawned
automatically with the application. They can be executed directly from
the browser (by dpouble-clicking on their icon) or via standard ROOT's
macro execution methods using '.x' and '.L'. If you want to pass the
arguments to the macros, use '.L' as this gives you automatic tab
completion.

For specific uses you can copy them and edit them to suit your needs.


Directory structure
===================

EVE is split into two modules: REVE (ROOT part, not dependent on
AliROOT) and ALIEVE (ALICE specific part). For the time being both
modules are kept in AliROOT CVS.

Alieve/ and Reve/ -- sources

macros/		  -- macros for bootstraping and internal steering
alice-macros/	  -- macros for ALICE visualization
alica-data/	  -- data files used by ALICE macros
test-macros/      -- macros for tests of specific features; usually one needs
                     to copy and edit them

bin/, Makefile and make_base.inc are used for stand-alone build of the
packages.


Examples
========

1. Run the interface for visual scanning:

alieve -mode 2 trackcount_init.C


Notes
=====

1. Problems with macro-execution
--------------------------------

A failed macro-execution can leave CINT in a poorly defined state that
prevents further execution of macros. For example:

  Exception Reve::Exc_t: Event::Open failed opening ALICE ESDfriend from
  '/alice-data/coctail_10k/AliESDfriends.root'.

  root [1] Error: Function MUON_geom() is not defined in current scope  :0:
  *** Interpreter error recovered ***
  Error: G__unloadfile() File "/tmp/MUON_geom.C" not loaded  :0:

'gROOT->Reset()' helps in most of the cases.

This has been fixed for most cases.
Commit	Line	Data
	1	EVE - Event Visualization Environment
	2	=====================================
	3
	4	EVE is composed of:
	5	1. small application kernel;
	6	2. graphics classes with editors and OpenGL renderers;
	7	3. CINT scripts that extract data, fill graphics classes and register
	8	them to the application.
	9
	10	The framework is still evolving ... some things might not work as expected.
	11
	12
	13	Usage
	14	=====
	15
	16	1. Initialize ALICE environment.
	17
	18	2. Spawn 'alieve' executable and invoke the alieve_init.C macro, for example:
	19
	20	To load first event from current directory:
	21	# alieve alieve_init.C
	22	To load 5th event from directory /data/my-pp-run:
	23	# alieve 'alieve_init.C("/data/my-pp-run", 5)'
	24	Interactively:
	25	# alieve
	26	root[0] .L alieve_init.C
	27	root[1] alieve_init("/somedir")
	28
	29	3. Use GUI or CINT command-line to invoke further visualization macros.
	30
	31	4. To navigate the events use macros 'event_next.C' and 'event_prev.C'.
	32	These are equivalent to the command-line invocations:
	33	root[x] Alieve::gEvent->NextEvent()
	34	or
	35	root[x] Alieve::gEvent->PrevEvent()
	36	The general form to go to event via its number is:
	37	root[x] Alieve::gEvent->GotoEvent(<event-number>)
	38
	39	See files in EVE/alice-macros/ from the ROOT browser that is spawned
	40	automatically with the application. They can be executed directly from
	41	the browser (by dpouble-clicking on their icon) or via standard ROOT's
	42	macro execution methods using '.x' and '.L'. If you want to pass the
	43	arguments to the macros, use '.L' as this gives you automatic tab
	44	completion.
	45
	46	For specific uses you can copy them and edit them to suit your needs.
	47
	48
	49	Directory structure
	50	===================
	51
	52	EVE is split into two modules: REVE (ROOT part, not dependent on
	53	AliROOT) and ALIEVE (ALICE specific part). For the time being both
	54	modules are kept in AliROOT CVS.
	55
	56	Alieve/ and Reve/ -- sources
	57
	58	macros/ -- macros for bootstraping and internal steering
	59	alice-macros/ -- macros for ALICE visualization
	60	alica-data/ -- data files used by ALICE macros
	61	test-macros/ -- macros for tests of specific features; usually one needs
	62	to copy and edit them
	63
	64	bin/, Makefile and make_base.inc are used for stand-alone build of the
	65	packages.
	66
	67
	68	Examples
	69	========
	70
	71	1. Run the interface for visual scanning:
	72
	73	alieve -mode 2 trackcount_init.C
	74
	75
	76	Notes
	77	=====
	78
	79	1. Problems with macro-execution
	80	--------------------------------
	81
	82	A failed macro-execution can leave CINT in a poorly defined state that
	83	prevents further execution of macros. For example:
	84
	85	Exception Reve::Exc_t: Event::Open failed opening ALICE ESDfriend from
	86	'/alice-data/coctail_10k/AliESDfriends.root'.
	87
	88	root [1] Error: Function MUON_geom() is not defined in current scope :0:
	89	* Interpreter error recovered *
	90	Error: G__unloadfile() File "/tmp/MUON_geom.C" not loaded :0:
	91
	92	'gROOT->Reset()' helps in most of the cases.
	93
	94	This has been fixed for most cases.