MCVIEW

mcview is a Python program which allows you to look at HepMC GenEvent final
state particles as 3D vectors. It was mainly written for the hell of it, as a
side-effect of interfacing HepMC to Python for other purposes (see the pyhepmc
package at https://pypi.python.org/pypi/pyhepmc/).


PREREQUISITES

* vpython's "visual" module

This is the 3D system that mcview uses. It's available through the Debian/Ubuntu
packaging system as python-visual. Sadly *not* available on PyPI.

* pyhepmc

This deals with the interfacing of HepMC to Python, via the SWIG system.


INSTALLING IT

The usual "python ./setup.py install --prefix=/path/to/install" recipe... or
just copy the file! Get in touch if you have trouble.


RUNNING IT

In principle, running mcview should just be a matter of calling the mcview
script. The command takes the name of a HepMC IO_GenEvent format dump file as an
argument:

> mcview path/to/events.hepmc

You also need to make sure that libHepMC is picked up by the runtime linker -
this may require something like this:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<HEPMCINSTALLPREFIX>/lib
(making sure to substitute for the contents of angle brackets). If you can run
"python -m hepmc" successfully, then mcview should work.


CONTROLLING THE VIEW

Assuming all is well, you should now have a window with an event display in
it. This includes 3 blue arrows as a reference (left-handed) Cartesian basis, a
rudimentary beam pipe made of blue rings, and coloured lines representing the
momenta of final state particles in the current event.

The display responds to some user input:

* To rotate the display in 3D, hold down the right mouse button and move the mouse;
* To zoom in and out, hold down L & R mouse buttons and move the mouse up or down;
* To see the next event, press "n" or the space bar.
* The particle momentum vectors are all anchored at the interaction point and the lengths are
  proportional to log(|p_3|). To toggle the scaling between this "logified" measure
  and the raw |p_3| measure, press "l" (you'll find that some vectors become enormous
  and totally dominate the view in the "raw" mode)
* To toggle displaying the beams, press "b"
* To quit, press "ESC"

If you keep pressing for new events, at some point the event file will end. When
this happens, hepmcview will continue to display


BUGS AND TODOS

As a flippant personal project, hepmcview is probably buggy and certainly
incomplete. Notifying me of problems -- or even better, fixing them and sending
me the patch! -- would be greatly appreciated.