---> See the bottom of this page to download the necessary zip file. <---

GeantToVTK - Adam L. Lyon

Fermilab Scientific Computing Division & Muon g-2

January 2016 Version 1.4

View Geant ( geometry and event files with ParaView (

ParaView is an open source tool to visualize data (many times from simulations involving Supercomputers). See the link abovefor more information and to download. ParaView is based on the VTK toolkit ( Kitware ( and maintains ParaView and VTK under grants from the Department of Energy and others.

ParaView's "killer" features (to me) are:

  • Very fast manipulation of a visualization scene (e.g. rotating, panning, zooming). ParaView is fast when other tools are frustratingly slow
  • The ability to overlay visualizations from many different data sources
  • It is written to do 3D - many operations are built in, such as slicing, clipping, making iso-volumes and contours
  • Built in ability to visualize scalar and vector fields with a variety of methods (heat maps, stream lines, glyphs)
  • Ability to handle time varying data with animations
  • Extremely sophisticated control of color and opacity

Some preliminary instructions are below.

Go to to download the ParaView program. For the ParaView Guide (manual), go to and download the community edition PDF, or buy the book or check it out from the Fermilab library (the printed book has some extra examples and are not necessary to learn ParaView).

0 Revision Notes

GeantToVTK 1.4

  • Added the Normalize a multi-block dataset filter. Needed for fast rendering in ParaView v5. See instructions in section 2.2.3.

GeantToVTK 1.3

  • Added a reader that can load events from a HepREPXML file and overlay events in the same display (this is not possible from the regular event reader). See section 2.1.3.
  • Various bug fixes and removal of spurious messages
  • Added some scripts (see section 5)

1 Installation instructions

Download the file.

Unzip the GeantToVTK zip file into some directory ( cd someDirectory ; unzip /path/to/ ) .

NEW (as of v1.2) You must configure the GeantToVTKPlugin.xml file by cd'ing into the GeantToVTK-1.4 directory and running


Note that this bakes in the current directory into the xml file so that ParaView can find python scripts. This means that you must not move these files to a different directory.

Launch ParaView. From the menu select Tools -> Manage Plugins...

On the new dialog box press the Load New... button. For the Files of type selector choose Server Manager XML.

Now navigate to and choose the GeantToVTKPlugin.xml file.

The dialog box should now show GeantToVTKPlugin at the bottom as Loaded. If you want to auto-load this plugin every time you start ParaView (a good idea), then click the expansion triangle and click on the Auto Load checkbox. If you don't do this step, you will have to repeat loading the plugin every time you start ParaView.

Now close the dialog box.

2 Using the Plugin

The plugin enables ParaVew to read Geant HeprepXML files. You should have a working Geant installation compiled so that it uses the ZLIB library (so that it can write out zip files). See the Geant installation guide for more information.

Run your simulation so that it produces HeprepXML files (note that these are Heprep v2 files). To do so, have the following in your vis.mac or similar file,

/vis/open HepRepXML
/vis/heprep/appendGeometry false

The last line tells Geant to only write out the geometry.heprep file once, instead of appending that information to every event file.

Once you run the simulation, you should have a file named similar to .

You can now tell ParaView to load the contents of this file following instructions below.

If you didn't configure your Geant to build with ZLIB, then you will get individual .heprep files. You can load them individually by following the instructions below but choosing the individual .heprep file and the appropriate reader. But, it will be more convenient to construct a zip file yourself of those files and then use the readers as intended (this will give you, for example, the ability to cycle through events using the ParaView "VCR" controls). When constructing your zip file, be sure to rename the geometry file as "geometry.heprep" and the event files as "event-NNNNN.heprep" where NNNNN is the event number with zeros in front.

2.1 Loading a HeprepXML zip file

Start ParaView with the GeantToVTKPlugin loaded (see "Installation instructions" above). If you checked the "Auto Load" box, then the plugin is already loaded. You can always check by selecting from the menu Tools -> Manage Plugins... and looking for GeantToVTKPlugin with "Loaded" next to it. If it is not there or is not loaded, then you probably moved the installation directory and ParaView can no longer find the Plugin. Install it again as per instructions above.

Now from the menu select File -> Open. Navigate and choose your file. A More than one reader... dialog box will appear. You must choose which contents to read from the zip file by choosing the reader. See the following sections.

Note: If you want to load the geometry and events, just do one and then select the file again with File -> Open and do the other.

Do not use File -> Recent Files because that will remember the reader was used last and it will not give you the option to choose again.

Note: You must press the Apply button after choosing a reader and setting parameters. Nothing will display unless you press Apply.

2.1.1 Loading the Geant geometry

From the More than one reader... dialog box that appeared, select View geometry in Geant4 HeprepXML file. The ParaView pipeline will update with the name of the file and a new Properties box will appear. In general, the default properties should be sufficient, except when reading in a full Mu2e geometry file (see below). You can press the highlighted Apply button to load the geometry. It may take several seconds to load the geometry, and on a Mac you may see a spinning beach ball for a short period of time.

Here are the meanings of the properties:

Exclude World Box: Most Geant4 geometry hierarchies start with a box representing the "World". In general, this opaque box gets in the way of seeing the apparatus, so by default it is excluded.

Honor Visibility: You Geant code can set visibility attributes for geometry volumes. These attributes are specified in the HeprepXML file. Checking this box will tell the reader to pay attention to those attributes and not include geometry volumes that are not meant to be visible (daughter volumes that are visible are still included).

Regular Expression: You may want to select volumes that have or contain a particular name. You can put a regular expression in this text box and only geometry items that match will be included. For example, if you only want to view the Muon g-2 Ring Arc #4, then you can put \[04\] into the regular expression box. The full path of a volume is its name, so in general daughter volumes will be included.

Invert Regular Expression: If this box is checked, then choose volumes that do NOT match the regular expression. This box allows you to exclude volumes. For example, the full Mu2e apparatus description includes thousands of uninteresting Gas volumes (and in fact there are so many that ParaView will run out of memory). You can exclude them by putting Gas in the Regular Expression box and checking this Invert Regular Expression box. You can exclude the Mu2e building with the following regular expression


and clicking this "Invert" box.

Path name format: The plugin creates a vtkMultiBlockDataSet with the geometry hierarchy. The block names are the names of the "path" to the geometry. You can alter this name by adding other metadata. This feature is more useful for events and is described more fully in section 2.1.3 below.

Verbose: Display uninteresting (to you) debugging information.

Note - see section 2.2.3 for an important plugin to speed up rendering.

2.1.2 Loading the Geant events (viewing one at a time)

From the More than one reader... dialog box that appeared, select View events in Geant4 HeprepXML file. Click on the highlighted Apply button to load the events. You can then use the ParaView "VCR" buttons to cycle through the events (you can only see one event at a time). There are several parameters you can set.

Only Trajectories: Both trajectories and hits are in the HeprepXML file. Generally, the hits are difficult to view and can slow down the display. This setting, which only imports trajectories and ignores the hits, is the default.

Path name format: The plugin creates a vtkMultiBlockDataSet with the event hierarchy (just a flat list of particles). The names in the vtkMultiBlockDataSet will just say things like "Event/Trajectory". You can add metadata to these names so that you can distinguish particles in the Multi-block inspector. The format is a Python format descriptor (see ) where names in braces correspond to metadata in the HeprepXML file. The metadata names seem to change for different versions of Geant. You can determine these names by loading the events (without changing this parameter) and looking at the drop down color list. The metadata names will be there. For example, If you want names like "Event/Trajectory mu+", then, use {path} {PN} (for a particular version of Geant).

Test Expression: This parameter allows you to set cuts on what events are included in the visualization. Enter a conditional expression. For example,

Energy > 200


name == "e-" and Energy < 50

The variable names and their meanings depend on the version of Geant you are running. To determine names, you can load one event and look at the color drop down box. You can use those items in this parameter. It may also be useful to look at the event-NNNNN.heprep file itself (you will have to unzip the zip file first).

This Test Expression parameter is useful if an event has so many tracks that ParaView is very slow to display them.

Note that there is a new script in v1.3 that can help you write test expressions. See /path/to/geantToVtk/scripts/ . If you run this script with regular python on a HeprepXML .zip file, it will examine the first event and show you a few trajectories with metadata and values. For example,

python ~/ParaView/GeantToVTK-1.4/scripts/

Color (Color): ?  (e.g. 1.00, 0.00, 0.00, 1.00)
PID (int): Parent ID  (e.g. 1)
PN (?): Particle Name  (e.g. e-)
Ch (double): Charge  (e.g. -1)
PDG (int): PDG Encoding  (e.g. 11)
IKE (double): Initial kinetic energy  (e.g. 1.41532)
IMom (?): Initial momentum  (e.g. -1.20025 -0.54183 1.30974 MeV)
IMag (double): Initial momentum magnitude  (e.g. 1.85731)
ID (int): Track ID  (e.g. 66)

The script does not recognize strings nor vectors (hence, for example, the ? in PN). In general you cannot select on vectors (e.g. IMom in the example above).

2.1.3 Loading the Geant events (viewing many overlaid)

The reader above allows you to view one event at a time. You may want to see tracks from many events overlaid on the display. To do so, from the More than one reader... dialog box that appeared, select View overlaid events in a Geant4 HeprepXML file. Click on the highlighted Apply button to load the events.

The parameters are the same as above, except for one new one.

Which events to load: Indicates which events you want to overlay. There are several different syntaxes for input.

s:n:t  # example: 5:10:2

Skip s events then load the next n with a stride of t. The example 5:10:2 means to skip the first 5 events, then read every other event from the next 10. The defaults are s=0 (no skip), n=0 (all events), t=1.

f-l   # example: 10-20

Load events where f <= event # <= l. The example says to load events 10, 11, 12, 13, ..., 20.

e1,e2,e3, ...   # example: 5,17,22,80

Load specific events.

The default for the parameter is 0:1 which says to load only the first event.

2.2 Filters from the Plugin

The plugin currently supplies two filters to apply to your pipeline. To select the filters, find them in the menu Filters -> Alphabetical or the Filters -> Search...

2.2.1 Extract Block With Path

This filter allows you to include or exclude blocks in a geometry or event hierarchy (more useful for the former) after the file is loaded. See the explanations for "Regular Expression" and "Invert Regular Expression" from section 2.1.1 above.

2.2.2 Event Particle Table

If you apply this filter to an event source in your pipeline, a spreadsheet viewer will appear with particle information. The table will allow you to see the particle hierarchy. At this time, there is no way to select particles from the table and have them highlighted in the render window.

2.2.3 Normalize a multi-block dataset

The output of the GeantToVTK plugin is a vtkMultiBlockDataSet, which is a hierarchical structure of vtkPolyData objects. ParaView version 5 has a new renderer using OpenGL2 that is extremely fast and is used when a vtkMultiBlockDataSet is homogeneous. A vtkMultiBlockDataSet is homogeneous when all of the constituent vtkPolyData objects within have the same list of attributes. That is if one vtkPolyData object has a Normals vector, then all of the objects should. Or none at all should. All vtkPolyData objects need to have the same list of attributes (e.g. scalar point data).

The vtkMultiBlockDataSet from GeantToVTK is heterogeneous. Some vtkPolyData have Normal vectors, others don't. Some have particular attributes, like color and density; others don't. This situation occurs because the vtkMultiBlockDataSet follows the Geant4 visualization output. Some Geant objects have particular attributes and others don't. The consequence is that a slow generic renderer is used. For a complicated geometry, the generic renderer could be so slow as to make ParaView unusable. Note that this situation only affects ParaView v5. ParaView v4 uses an OpenGL1 renderer. The fast OpenGL2 renderer can be many times faster though, and so it is useful to upgrade to ParaView v5.

The Normalize a multi-block dataset filter makes a heterogeneous vtkMultiBlockDataSet homogeneous by adding missing attributes to the vtkPolyData with appropriate defaults. The resulting vtkMultiBlockDataSet should trigger the fast renderer. This fast renderer is anywhere from 20x - 200x faster than the generic renderer.

Parameters for the filter are the default values to add if an attribute is missing. The values should be obvious. The default color is entered as Red, Green, Blue, Alpha values all between 0.0 and 1.0 and separated by spaces. For example, to make objects that are missing the Color Field Data be blue, use 0 0 1 1. Green would be 0 1 0 1. Transparent would be 0 0 1 0.

3 Tips for using ParaView

We are only scratching the surface here. See the ParaView Guide PDF at for more information.

If you have loaded both geometry and events from the same zip file, you will have the name of the zip file repeated as two sources in your ParaView pipeline. This will cause confusion. You can highlight the name in the pipeline and press ENTER to rename it to something more informative (like geometry).

3.1 Opaque Structures

When you load a geometry into ParaView, you will likely see opaque structures. To be able to see inside, you can do one or some of the following:

  1. Choose the Wireframe representation (typically from the selector that says "Surface" by default).
  2. Only select interesting geometry items with a regular expression as per instructions above.
  3. Choose geometry items with the Multi-block inspector (to bring up, select from the menu View -> Multi-block inspector).
  4. Right click on the opaque structure and hide it or make it transparent.
  5. In the properties box, make sure the little advanced properties gear icon is toggled true [darker grey]" and scroll down to "Backface styling" and choose "Cull Frontface". This will sometimes remove the front face of objects, allowing you to see inside.

3.2 Colors

When you load a geometry and events, the default color (new in ParaView 4.4) is vtkCompositeIndex, which will display each block in a different color, and looks kinda crazy. Geant color attributes for volumes is stored in the HeprepXML file and read by the ParaView reader. To show those colors, click on the color chooser (will probably show vtkCompositeIndex) and choose "Color". These colors are still not correct, as ParaView is interpreting the color information as a tensor (and showing you the magnitude) instead of a tuple specifying red, green, blue, alpha. To show colors as Geant intended, go to the Properties box and be sure the little advanced properties gear icon is toggled true [darker grey]. Then scroll down to "Scalar Coloring" and uncheck "Map Scalars". Now you will see the true Geant colors.

4 Examples

There are several examples included in the distribution. See the example/ directory where you installed GeantToVTK. The examples come from the Geant examples B2b, N02, N04 and N05.

Note: the state files mentioned below work with ParaView 4.4, not earlier versions.

You can load the examples following the instructions above. Note that for N02, N04, and N05 examples, ParaView will show them as with an expansion triangle. Click on the expansion triangle to open the list and choose the individual files.

You can also load a state file corresponding to each example. The state file restores a previous ParaView state including the files that were loaded, the state of the pipeline, etc. They are described below. If you have a visualization loaded and want to try out another one, be sure to reset ParaView. Do this from the menu Edit -> Reset session .

Load a state file from the menu File -> Load State... (not File -> Open). Navigate to the examples directory. From there, load the desired .pvsm file. When you load the file, ParaView will pop up a dialog box allowing you to specify the location of the loaded data files. You will need to alter it so it has your directory path. Making this change for every pvsm file will get tedious. In the example directory is a script called "". Run that script from within the examples directory ( cd /path/to/examples ; ./ ) and it will fix the paths in the pvsm files. Once this is done, you can simply click "OK" for the dialog box when it appears for all of the pvsm files.

Here are the examples:

b2b-trackCuts.pvsm -- Loads the Geant basic B2b example. Note that the names of the readers in the pipeline have been changed (see above). Click on B2b Geometry or B2b Events in the pipeline to populate the Multi-block inspector. The spreadsheet on the right is a particle table. You can control the columns that are shown by choosing the yellow checkerboard icon and selecting or deselecting column headers. You can sort the column by clicking on the header. If you click on B2b Events in the pipeline, note that there is a Test expression to only show tracks over 700 MeV. If you don't do this, then you'll have a monster of an event and ParaView may crash. The colors are the true Geant colors (Map scalars is unchecked).

n02-particleColor.pvsm -- Loads the Geant novice N02 example. This is similar to the one above. Special features are,

  • No cuts on tracks
  • Colors are the particle type. Click on the left most rainbow icon in the middle toolbar and a legend will appear.
  • Click on the 2nd most rainbow icon to bring up the color editor to see how the colors were defined.
  • There are a lot of events in this file. Play with the VCR controls to advance through the events.

n04-clip.pvsm -- Loads the Geant novice N04 example, with the geometry clipped with a clip filter so you can see inside.

n04-slice.pvsm -- Loads the Geant novice N04 with the geometry sliced (made 2D) at z=0 in the x-y plane.

n04-points.pvsm -- Loads the Geant novice N04 with the geometry represented by points and colors by the materials.

n05.pvsm -- Loads the Geant novice N05. Colors are the Geant colors. The Backface styling of "Cull Frontface" is active so that you can see into the boxes.

5 Scripts

There are several scripts in the scripts/ directory where you installed GeantToVTK. These are mainly meant as examples for you to use when converting text output into VTK files. The script is discussed in section 2.1.2 above.

Perhaps the most useful script is, which will take a comma separated values file (CSV) of points and convert it into a VTK PolyData XML file (vtp), using x, y, z columns as the points and other columns as point data (it will automatically convert columns whose names end in x,y,z into vectors). It makes heavy use of numpy and VTK's interface with numpy.

You need to run this script with the pvpython command. For example, on my Mac I run (you machine will likely use a different path)...

/Applications/ ~/ParaView/GeantToVTK-1.4/scripts/ bla.csv