G4/vis plotting

In Geant4/11.x, the G4/vis system is equipped to be able to do plotting, then to have a representation (a plot) of 1D or 2D histograms within a G4/vis viewer.

The G4 vis primitive G4Plotter had been introduced to capture which histograms to plot, specify a grid of plots (2x2, 2x3, etc...), along some style options to customize the representations (for example to change bins color, title or axis label fonts, etc...). Specifying a grid of plots (or "regions") is a common practice in plotting and is a similar concept as the "zones" found in the good old CERN/PAW.

The known histograms are the one managed in the G4/analysis and is known in G4Plotter by using their integer id.

This said, in charge of each specific vis drivers to implement the representation of a G4Plotter. In G4/11.0, only the ToolsSG drivers come with such representation, but we hope that more vis drivers will come with an implementation in the future.

From the user point of view, commands had been introduced to be able to specify a plot from pure .mac scripting. To start with, the best is to jump on examples/basic/B5 that comes with a commented plotter.mac example. In it you will see how to activate the vis driver (create a "scene handler"), create a viewer, create a scene containing a plotter model object (then a G4Plotter), create a grid of plotting "regions" (here 2x2 regions) and attach the histograms to each region. When done, each "run beamOn" should display at end the content of the histograms.

The skeleton of a plotting script then looks like:

    # viewer:
    /vis/sceneHandler/create TSG scene-handler-plotter
    /vis/viewer/create scene-handler-plotter viewer-plotter 600x600-0+0
    /vis/viewer/set/background 1 1 1
    /vis/viewer/zoomTo 1
    /vis/viewer/set/viewpointVector 0 0 1
    # scene:
    /vis/plotter/create plotter-0
    /vis/scene/create scene-plotter
    /vis/scene/add/plotter plotter-0
    /vis/sceneHandler/attach scene-plotter
    # create plotter regions:
    /vis/plotter/setLayout plotter-0 2 2  # create 2x2 plotting regions.
    # attach histograms to regions (examples/basic/B5 specific):
    /vis/plotter/add/h1 0 plotter-0 0
    /vis/plotter/add/h1 1 plotter-0 1
    /vis/plotter/add/h2 0 plotter-0 2
    /vis/plotter/add/h2 1 plotter-0 3
    # let's go:
    /run/beamOn 100  # it will update the plotters at end of run.

G4/vis plotting style

Being able to customize the representations is an important part of plotting. The concept of named style had been introduced in G4/vis/plotting to handle this. A named style is nothing more than a named list of pairs (key,value) which is managed in the G4/vis system.

A user can create a named style with:

    /vis/plotting/style/select <name>  # create a named style and set it as "current".

and deposit pairs of key/value in the current style with:

    /vis/plotter/style/add <key> <value>
    /vis/plotter/style/add <key> <value>
    ...

A named style can be used on a specific region with:

    /vis/plotter/addRegionStyle <plotter> <region> <style>

For example, in B4/plotter.mac:

    /vis/plotter/addRegionStyle plotter-0 0 style-0

or on a whole grid of plots with:

    /vis/plotter/addStyle <plotter> <style>

Note that someone can add multiple named styles on a plotter or on a region. If so the styles are applied in order with global ones first and then per region ones after.

IMPORTANT: the key/value pairs are specific of a G4Plotter representation implementation. If using the ToolsSG plotting you may have:

    /vis/plotter/style/add bins_style.0.color      blue
    /vis/plotter/style/add bins_style.0.line_width 3
    /vis/plotter/style/add infos_width             0.2   # percent of plotter width.
    /vis/plotter/style/add infos_style.visible     true
    /vis/plotter/style/add infos_style.font        roboto_bold.ttf
    /vis/plotter/style/add infos_style.front_face  cw

but, a priori, the upper key/value pairs are not expected to be known by another plotter implementation. (But it would be great to be so!).

Other usefull style commands are:

    /vis/plotter/style/list           # to list known named styles.
    /vis/plotter/style/print <style>  # to print the list of key/value pairs of a named style.

and:

    /vis/plotter/style/remove <style>  # to remove a name style from G4/vis.

Note that without passing by a style, a plotting region can be customised directly by using the command:

    /vis/plotter/addRegionParameter <plotter> <region> <key> <value>

for example with ToolsSG plotting in B4/plotter.mac:

    /vis/plotter/addRegionParameter plotter-0 0 bins_style.0.color blue
    /vis/plotter/addRegionParameter plotter-0 0 bins_style.0.line_width 3

As for styles, the key/value pairs are specific of a vis driver plotting implementation. Note that the pairs given with the addRegionParameter on a region are applied after all styles on this region.

G4/vis ToolsSG plotting

The ToolsSG/G4Plotter representation is done by using the high level tools::sg::plots and tools::sg::plotter nodes (found in externals/g4tools/include/tools/sg). The tools::sg::plotter node uses a lot of nodes as tools::sg::axis, tools::sg::vertices, etc.. to build representations. (tools::sg::plots permits to implement a grid of plots). A tools::sg::node manages "smart fields", for example the tools::sg::sf<float> (simple float smart field) "width" in tools::sg::plotter. (Smart field is a similar concept as the SoField in OpenInventor). It is these fields that are customizable as key/value pairs from styles or region parameters. (A smart field is smart in the sense that if "touched", for example by setting a new value, it may induce an automatic update of the node at next rendering traversal of a scene graph).

The list of what is customizable on a tools::sg::plotter, is given with the ToolsSG specific command:

    /vis/tsg/plotter/printParameters

For styles, specific to ToolsSG plotting, are the named styles "default", "ROOT_default", "hippodraw" that are "embedded" styles (defined as C++ functions in: tools/sg/plotter_some_styles). In particular the ROOT_default styles permits to mimic the default style plotting found in CERN/ROOT. Then someone can do:

    /vis/plotter/addStyle <plotter> ROOT_default

to have the ROOT style for all regions. (Note that ROOT_default needs freetype).

In the second part of B5 plotter.mac, is shown various ways to customize the regions, for example changing the bins color, the axis labels fonts, etc... This could be done by using default embedded styles, defining styles with commands, or setting up directly parameters of the various parts of a plot by using the dedicated addRegionParameter command.

For texts (title, tick labels, etc...), the fonts used by default are the Hershey vectorial ones (the ones of the good old CERN/PAW) that do not need an extra package, but you can use some freetype fonts if building with the cmake flag -DGEANT4_USE_FREETYPE=ON. For example the ROOT_default embedded style uses freetype fonts. Two embedded ttf fonts comes with the ToolsSG plotting: roboto_bold (some open source kind of the Microsoft arialbd) and lato_regular (close to an helvetica). You can use also your own .ttf files by using the TOOLS_FONT_PATH environment variable to specify the directory where they could be found.

G4/vis ToolsSG plotting keys

A style or parameter key as the form:

    <direct field> of sg::plotter, as width, height, left_margin, right_margin, etc...

or is a field of a sub node representing a component of the scene of the plot, as [x,y,z] axis, infos box, title box, grid, bins, errors, etc... The key may refer a direct field of the component as x_axis.title, or the style of a component handled by a tools::sg::style or sg::text_style node. A component key may contain two or three words separated by a dot.

Two words keys are for:

    [x_axis,y_axis,z_axis].<field>

For example:

    x_axis.modeling   # string field with value hplot, hippodraw.
    x_axis.divisions  # in case of hplot modeling, an int specifiying primary/secondary ticks encoded as in hplot (for exa 510).

or for the style components:

    background_style, title_style, infos_style, title_box_style,
    inner_frame_style, grid_style, wall_style

For example:

    infos_style.visible
    infos_style.font
    infos_style.front_face

Three words keys are also for the style of the components of the tools::sg::axis as:

    line_style, ticks_style, labels_style, mag_style, title_style

for example:

    x_axis.labels_style.color

Three words keys are used also to specified style fields of the bins, errors, function, points, legend data representations components. For example, in one sg::plotter, you can specify to plot multiple histograms, ie multiple "bins". In this case, you can customize the style of the i-th "bins" (i-th histogram) with a key of the form:

    bins_style.<i-th>.<field>

for example:

    bins_style.0.color  # to change color of the "front" histogram.

For the moment, the G4/vis plotting knows only histograms, but the tools::sg::plotter can handle cloud of points, errors, functions, legends, and in some future, a G4 user may have to use the errors_style, func_style, points_style, legend_style in the same way to customize a "i-th" cloud of points, a i-th function, a i-th legend, etc...

We do not give here the full list of available parameters since it may evolve in time. The best is to use the command:

    /vis/tsg/plotter/printParameters

that dumps, by querying directly the nodes, the available styles and smart fields for the sg::plotter itself or for one of its component. Moreover it dumps also the type of a field (float, integer, boolean, string, etc...).

Put all together, the combinatory of available keys is rather rich and permits a strong customization of good parts of a sg::plotter.