Visualization in megamol

Writing ADIOS2 output in MaMiCo

To visualize molecule and/or volume data from MaMiCo in Megamol, the data must be written in the ADIOS2 file format. To do so follow the steps below:

1. Install adios2 as described in the installation manual.

2. If not already done, clone this MaMiCo repository. Checkout the branch kvs_adios

   git checkout kvs_adios

3. create a build directory in the MaMiCo folder and enter it:

   mkdir build && cd build

4. Configure Cmake:

   ccmake ..

   Press c to configure, after that you should see the available Cmake flags. Make sure to enable BUILD_WITH_ADIOS2. Configure with c until no new entries are marked, the hit g to generate.

5. Compile:

   make -j [number of threads]

6. Open the .xml configuration file. Set the file name and writing interval for the MD data.

   Example: <adios2-configuration directory-name="filename.bp" write-every-timestep="x"></adios2-configuration>

   where an output directory with the name [filename].bp is created and the MD data is written every x'th timestep.

The volume data is written independently from the MD data. Currently the volume output is only implemented for the kvs test in kvstest.py (l. 26, l. 286-292, l.342-358) but should be easy to transfer to similar scripts.

To write volume data from the kvs test, open kvstest.ini and set adios2-every-timestep to a number x greater 0. The kvstest will then write volume data to the folder 'kvstest_volume.bp' every x'th timestep.

*Hint: To check if the output was properly written, use the command line tool BPLS.

Megamol

Installation

For the MS Windows installation steps refer to the official installation manual.

• Install the necessary build tools and compilers, as well as CMake and git:

  sudo apt install build-essential cmake cmake-curses-gui git

• As prerequisites, following packages are required:

  $ sudo apt install curl zip unzip tar xorg-dev libgl1-mesa-dev libglu1-mesa-dev libncurses-dev

• Clone the megamol repository from GitHub. For the basic features, the latest version of megamol in the official repository is sufficient. For additional features (visualization of volume data and rendering of animations) use the experimental repo of Dr. Guido Reina (University of Stuttgart).

  $ git clone https://github.com/UniStuttgart-VISUS/megamol.git

  or for experimental features:

  $ git clone https://github.com/reinago/megamol.git

  Change into the main folder

  $ cd megamol

• Using the official version, stick to the master branch. For the experimental features checkout the 'anim-editor' branch in the corresponding repo:

  $ git checkout anim-editor

• Create a build directory

  $ mkdir build && cd build

• Open cmake configuration

  $ ccmake ..

• Enable MMADIOS plugin (Exact name of the cmake flag depends on the version)

• Press c to configure, until no more changes are marked. Press g to generate.

  • Hint: The generation of the build files might take some time during the first installation, as many dependencies will be downloaded and installed by vcpkg (only valid for experimental version).

• Build and install:

  $ make -j [number of threads] && make install

• The executable is located in build/install/bin/

• Test the installation with the 'Test spheres' example:

  $ cd install/bin/

  $ ./megamol ../examples/testspheres.lua

*Hint: By default megamol requires OpenGL 4.6 or later and will crash if the available version is older. To enforce the usage of an older version (possibly necessary e.g. on a virtual machine or on older hardware) call (example: OpenGL 4.0):

$ ./megamol --opengl 4.0 ../examples/testspheres.lua

Using Megamol

This section describes the configuration of megamol to visualize MaMiCo adios2 output. For a more detailed explanation of the configurator read the megamol manual. The navigation the 3D view is explained in the megamol start guide.

1. Open Megamol

2. Create a new project or open an existing one.

3. Press F11 or click Windows>Configurator.

4. Set the configuration up as seen in the screenshot or open the template file. (Hint: Add nodes to the flow graph by double clicking in the empty space and selecting the wanted node. Connect nodes via Drag'n'Drop at the intake/output bullets. The properties of the individual nodes are either found in the properties sub-window or in a temporary panel in the configurator when expanded by clicking on the small triangle in the middle of the node)

5. Select your Input data by clicking on the triangle on the adiosDataSource node. In the expanded menu click on the left icon to browse your files. The volume renderer needs the input folder containing the volume data and the node feeding the sphere renderer must contain the folder with the data of the MD domain.

6. Hit F11 again or close the configurator with the small x to return to the 3D view. Scroll the mouse wheel (zoom) and click and hold mouse wheel (pan) to move in 3D space to locate your visualized data. Rotate around it holding STRG + left mouse button (or ALT instead of STRG to rotate freely, but I highly recommend not to do this).

7. The simulation time can be chosen in the parameter window under view::anim::time. There you can also toggle playback. However this might severly lag for large scenarios.

The transfer function (or 'how to make things look fancy')

The renderer nodes take a transfer function as input. This node represents a function, that maps a floating point value to a color value (RGBA). For the visualisation of particles it takes the adios2 variable specified under 'intensity' in the adios_flex_convert node as input value. The function can be edited externally and imported as json string or with the internal editor, by adding points in the graph and moving them around or draw a free hand graph (good luck ;). Make sure to apply the changes or check the auto-apply option and see how it influences the look, to get a feeling for it.

Taking high-resolution screenshots

The screenshot resolution is usually limited by the screen size resolution. However there is an (unofficial) workaround to capture screenshots with higher resolution

1. Enforce a higher 3D-view resolution: Press F9 or click Windows > Log Console to open the console. In the field "Input" insert the command:

   mmSetViewFramebufferSize("::View3DGL_1", [X-resolution], [Y-resolution])

   Note that this may significantly decrease the performance or even crash the application or lead to buggy rendering.

2. Write a frame directly from the 3D-View to a file:

   mmScreenshotEntryPoint("::View3DGL_1", "[path to file]/[filename].png")

Animation rendering

Megamol offers some functionality for video rendering, but it comes with some limitations. The old 'cinematic' plugin had some important advantages with respect to the final video quality but comes with some, for most purposes, unacceptable limitations and is not recommended to animate MaMiCo data. Instead a new version of megamol is used with a rather experimental (and yes, sometimes unstable) built-in animator. It comes with some limitations and bugs as well but unlike the cinematic plugin it might be enhanced in the future.

*Hint: In the new animation rendering system, there is no explicit option to set the video resolution. To achieve the desired resolution, set the resolution of the 3D-view as described in step 1 in the section "Taking high-resolution screenshots" above.

To create an animation open an existing project in the experimental version of megamol from the branch 'anim-editor' of the alternative repo as described in the installation manual above.

In megamol press F5 or click Windows > Animation Editor. On the left hand side you can set a start and end frame and a playback framerate for the renderer. Drag and drop the current frame slider or the yellow marker in the timeline window to select the point of time you want to edit.

In the new animation system, any setting can be edited (even the ones for which it makes no sense). The easiest way to start an animation is to tick the auto-capture checkbox and manipulate a parameter. The editor will automatically add a key in the animation window with the set value at the current frame position. You can also add any keys manually with the button on the top of the animator windows. There you also find also a button for deleting keys again. The button frame view is super useful whenever you mess up the view in the animation window....

In the animation timeline view you can see the inserted keys and select them with the left mouse button to edit the value and the interpolation type on the right hand side. The interpolation tangent can be edited in the view directly.

Experiment a little bit with the animation editor to get a feeling for how to use it. Unfortunately there is no documention available yet.

*Hint: It is recommended to use the 'Hermite'-interpolation instead of the 'Cubic Bezier' as the latter one is very unperformant.

To preview an animation hit SHIFT + SPACE, to render it hit SHIFT + R. The "renderer" only manipulates the animated parameters and makes screenshots. This means that you should close all unnecessary windows in megamol and that the video resolution will depend on your screen resolution / window size. This might be fixed in the future. The recorded screenshots are gathered in one folder at the location from where you started megamol.

These frames can be merged together to one video with online tools or software like blender (Video tutorial on how to do it with blender).