edepViewer

An external event viewer for edep-sim.

Overview:

edepViewer visualizes events from edepsim with the minimal drawing details necessary while providing as much access to the information generated by edepsim as possible. Quality visualizations should be produced with almost no configuration, but tools are provided to customize event navigation, which objects are drawn, and how edepsim objects are interpretted.

Installation:

edepViewer uses a CMake build system, so you will need at least CMake 3.5.1 to build the source code.

1. Install the versions of the dependencies listed below. In particular, Dear ImGui needs to be installed from source for now.
2. Choose the build options you want to use from below and use them to create the Makefiles needed for the build with "cmake /path/to/src/ [-Doption1 -Doption2 ...]" in a build area that is not the source directory.
   CMake should make you aware of any missing dependencies.
3. Make sure edep-sim is set up for running by sourcing its' setup.sh script. This should set environment variables EDEP_ROOT and EDEP_TARGET to point to where edepsim is installed. Alternatively, newer edep-sim versions will be automatically detected by CMake if they are installed in a root-user-owned directory.
4. "make install" this package. Currently, gcc and Clang 5.0 compilers are supported on Linux systems, and Clang (version?) is supported on OS X.
5. You are ready to run edepViewer with "[CMAKE_INSTALL_PREFIX/bin/]GLFWApp". You will need to set up edepsim with its' setup.sh script every time you want to run edepViewer.

Using the Viewer:

1. Run "GLFWApp": Usage: GLFWApp [configuration.yaml one_edep_file.root another_edep_file.root ...]

   • If no files are provided on the command line, gets the default.yaml configuration file from the installation directory and pops up a GUI to choose one ROOT file to view. ROOT file should contain keys for the tree and geometry used by edep-sim.

   • If any file names are provided on the command line, the application will not use the default configuration file. If just a configuration file is provided, the application should still prompt the user for an edep-sim input file with a GUI.

   • configuration.yaml: Provide a yaml configuration file.
     Take a look at the default file, default.yaml, in conf. Requires a top-level node called "config" and child nodes "drawer" and "services".
     "drawer" must have child nodes "global" and "event" for the two types of drawing algorithms. "event" and "global" child nodes are the class names for drawing algorithms you want to use without namespaces.

   • one_edep_file.root: File name to be given to TFile::Open() This means that local files and several kinds of remote files are supported. I have found xrootd particularly useful for streaming large files I want to view from remote servers. You may list more than one root file.

2. The main viewer GUI should pop up as a new window:

   1. Click and drag in the main viewer area on the left to view the first edep-sim event from different angles.
      Zoom in and out with a scroll wheel.
      Move in the plane orthogonal to the camera direction with the arrow keys. Click on an object to highlight it both in the main viewer area and in the list-tree.

   2. Go to the next event or a specific event with the control bar at the top of the GUI.
      Select a new file to view with the "File" button.
      Take a screenshot with the "Print" button. Reload the event, possibly undoing cuts, with the "Reload" button. It should not be needed often.

   3. Interact with the viewer and object metadata in more detail from the list-tree pane on the right.
      The Viewer pane can change the background color and provides finer control over the camera.

3. Object list-trees:

   1. There is one list-tree for each type of object drawn. Each list-tree provides columns of metadata for the objects of that type in the current tree.

   2. The "Draw" column toggles whether each object is drawn individually. Togling drawing for an object does not toggle drawing for its' children.

   3. The text entry at the top of each list-tree pane is the Cut Bar. Type in the Cut Bar to specify a condition for an object to be drawn:

   • Each metadata column in a scene is identified by an index. Since the "draw" column is column 0, the first metadata column is labelled 1. Specify a column value in a cut with "@" as in "@2 != neutron".

   • Column values can be compared to any alpha-numeric value with the operators "==", "!=", "<", and ">". The Cut Bar should ignore cuts that try to compare numeric values to text columns and vice-versa.

   • The cut bar is not yet smart enough to apply the order of operations correctly, so all comparison expressions should be enclosed in parentheses. "@2 != neutron" is OK, but "@2 != neutron && @3 > 5" should have no effect because it is an error. Replace the second example with "(@2 != neutron) && (@3 > 5)".

   • The results of boolean expressions are treated as booleans and can be combined with the "&&" and "||" operators. The strings "true" and "false" are interpretted as booleans when they appear in cuts.
     So, a cut of "false" will completely stop drawing a scene.

   • Objects removed by the Cut Bar are removed from the list-tree along with their children. The children may still be drawn if they pass the applied cut.

CMake has lots of useful options for configuring the build, so I have listed a few that I use frequently when working with this package:

CMAKE_INSTALL_PREFIX Set the /path/for/installation/. Default seems to be /usr/local for me on Ubuntu 16.04. Will install in CMAKE_INSTALL_PREFIX/bin, CMAKE_INSTALL_PREFIX/lib, CMAKE_INSTALL_PREFIX/include, and CMAKE_INSTALL_PREFIX/conf.

CMAKE_BUILD_TYPE Could be Debug to install with symbols for a debugger like gdb or Build for slightly more optimization.

IMGUI_DIR The location of the Dear IMGUI source code. Might just embed Dear IMGUI in the future, so this option may go away.

This package also supports CPack, so you can "make package" if you need a tarball.

Dependencies:

CMake 3.5.1 Build system that handles dependencies between files within edepViewer.

edep-sim The package that produces the files that edepViewer reads.
Defines the objects that edepViewer knows how to read.

Dear IMGUI v1.60 Pure-OpenGL Graphical User Interface used for information and control widgets. Should be completely OS-independent. The GLFW OpenGL3 example from Dear IMGUI is embedded in this project.

ROOT 6 Also a dependency of edep-sim, but I use it for file IO and a few other odd utilities that help me deal with edep-sim files more easily. Notably provides first step in geometry tesselation at the moment.

glm Vector operations for interfacing with opengl.

yaml-cpp 0.6.0 Full-featured YAML parser with a c++ interface. Version 0.6.0 is supposed to avoid depending on Boost.

glad This source distribution includes code generated by the glad tool. glad handles some details of working with opengl on multiple plateforms.

GLFW3 Currently the only implemented window system. Should work on Linux and OS X systems. Windows may be supported, but hasn't been tested yet. Any window system that supports Dear IMGUI supports edepViewer.

Acknowledgements:

I learned a lot about CMake and deploying an object from the source code of edep-sim.
Several of the ROOT website's examples helped me to learn to use TTreeReader, and the documentation of ROOT classes has been extremely useful when developing this project. I used the gtkmm tutorial to get started with writing the interface for this application.
Dear IMGUI's examples helped me migrate from gtkmm to Dear IMGUI to make edepViewer platform-independent. I learned nearly everything I know about opengl from learnopengl.com.