Documentation of VIMoD

Calculations of sophisticated impact scenarios (especially three-dimensional ones) are leading to a huge amount of data. Thus, visualization is not only a useful working step for presenting results. It has now become to a central topic in impact research.

We developed VIMoD (=Visualization of Impact MOdelling Data), a powerful software which enables a three-dimensional visualization and analysation of modelling data derived from both iSALE and iSALE-3D. VIMoD is completely written in C++. It comes with a Qt-based, user friendly GUI and uses OpenGL to generate the graphics output. The rendered data can be easily rotated or moved. Thus, arbitrary views of the data are possible. VIMoD contains a broad variety of visualization methods (isosurfaces, cutfaces, vectors, tracer and trajectory representations, ...). It enables high-resolution snapshot generation as well as encoding of videos in different formats and qualities. It comes with a plugin-interface which allows to write your own add-ons and thus eases the post-processing of the data.

First time configuration

Configuration dialog

When using VIMoD for the very first time, a configuration dialog opens and asks for several information, such as
  • Your full name and email-address (used to display copyright information in your visualization).
  • The location where movies shall be stored.

Configuration file

While installing vimod on your machine, a configuration file is created:


In this file some default visualization settings, appearance and behavior of VIMoD is stored. You can change these settings according to your own wishes.
NOTE: It is highly recommended to create a backup of your configuration file before performing any changes - in particular, if you are not familiar with VIMoD.

Using VIMoD

Using VIMoD is quite intuitive. Thus, a complete explanation of all the contained features is not given here. Instead, we focus on the handling of vimod and the most important features only.

Starting VIMoD

VIMoD is usually started from command line via

vimod filename.dat

where 'filename.dat' is the name of the iSALE-datafile you want to visualize. Additionally, following flags (=command line options) are available1:
Scaling options:
  -a <VAL>         define impact angle as VAL
  -A <VAL>         define impact angle2 as VAL
  -R <VAL>         set density ratio (RHO_TARGET/RHO_PROJECTILE). Default: 1.00
  -U <VAL>         scale velocity between -VAL...VAL. Default: no scaling

Rendering options:
  -c               disable cylindrical projection (2D-data)
  -e <VAL>         set cutoff threshold for empty cells (EPS_MIN) to VAL. Default: 1.00e-04
  -D <VAL>         set density_threshold (for cutoff) to VAL. Default: 1325.0
  -q <NUM>         set absolute rendering quality to NUM (0 is best). Default: 0
  -I <NUM>         set number of iso simp to NUM (NUM=2...180; 180 must be multiple of NUM). Default: 2

Main options:
  -v <NUM>         set verbose mode to NUM (0: nearly no output ... 3: plenty of output). Default: 2
  -s               use system defaults instead of those from ${HOME}/.vimod3/default.conf
  -n <NUM>         immediately jump to timestep <NUM>, if possible. Default: 0
  -h, --help         display this help and exit
  -V, --version      output version information and exit

Rotating, zooming, translating

You can use the mouse to rotate, zoom or move your current visualization.

Action Mouse action Hotkeys
Rotate Move the mouse while holding left mouse button Use keys up/down/left/right
Zoom Move mouse while holding right mouse button Use keys PageUp/PageDown
Translate Move mouse while holding middle mouse button Use CTRL+(keys up/down/left/right)

How to select visualization techniques

Explaining all the different visualization techniques, their functionality, different options and the theory behind is currently beyond the scope of this wiki. Most of the primary visualization techniques (arranged in a tab in the control panel of vimod) are activated as follows:

  1. select the desired visualization method by clicking the appropriate tab in the control panel (left side of the vimod window).
  2. select the field which you like to visualize from the field list (located above the tab folder)
  3. adjust your visualization according to your own needs, if required

How to visualize different timesteps

Use the widgets in the bottom part of the control panel to change the current timestep:

button meaning
<\\ jump to the first timestep
<< moving through all timesteps backward (beginning from the current)
<\ move one timestep back
STP stop moving
/> move one timestep forward
>> move through all timesteps forward (beginning from the current)
step skip some timesteps

You can also move the slider to jump directly to a certain timestep. Hold the left mouse button while moving the slider. Release it to visualize the selected timestep.

Creating snapshots

Press the key 'F2' (or select 'Media' --> 'snapshot' from the menu) to create a snapshot of the current visualization. The output is stored in the current working directory as an image file (usually JPEG, you can change the output format by choosing 'Options'->'Preferences'->'Media options').

Creating videos

To allow vimod create videos of your visualizations the 'mencoder' package must be installed on your computer and 'mencoder' must be found in your PATH-environmental settings2. To render a video perform the following steps

  1. adjust the visualization according to your own wishes.
  2. jump to the timestep with which the video should start with.
  3. select the appropriate timestep skip value (note that a video usually requires 25 timesteps per second).
  4. press 'CTRL+m' (or select 'Media'->'encode movie') once to start encoding your video.
  5. wait until the animation has reached the end of the file (or press 'STP' if you want to stop or pause your animation manually).
  6. press 'CTRL+m' (or select 'Media'->'encode movie') again to finish encoding your video.

The video is found in the location you specified in the configuration dialog (see above) or adjusted in your local configuration file in a subfolder called newmovie/newmovieXXX (where XXX is a three-digit consecutive number). The video usually is called msmpeg4.avi. All the frames of the movie are additionally stored in the subfolder 'img'.

1 Note that the existence, meaning and behavior of the flags might change from time to time. Call 'vimod --help' for an up-to-date list of all available flags.

2 Just type in 'mencoder' from the command line if you are not sure whether all your requirements are satisfied - if you get no error, everything is fine.