Graphical User Interface

Main frame

AMAPVox GUI fulfills three objectives:

  1. Editing configuration conveniently;
  2. Running simulations (sequentially or concurrently);
  3. Visualizing quickly output files (3D views and vertical profiles)

The main toolbar and the File menu provides the usual functions New/ Open / Edit / Close / Save / Save as etc.

Tabs Configuration files and Output files

The top left pane contains the configuration pane and the output pane.

The configuration pane lists the configurations files that have been opened or created. Double click or right click Edit to edit the configuration file.

The output pane lists the output files grouped by configuration. You may right click on the files to edit a context menu.

Log pane

The bottom left pane contains the logs from the main frame and the processes when there are running. You may clean the log pane, export it as a text file and cap the size of the log in the heap memory.

Vox tools tab pane

The vox tools frame is dedicated to the edition of the configuration files.

New configuration

Menu > File > New or click on the New button New button in the toolbar.

A configuration file is an XML file with following header:

<?xml version="1.0" encoding="UTF-8"?>
<configuration creation-date="Thu Sep 23 16:14:41 CEST 2021" build-version="1.8.0" update-date="Mon Sep 27 09:59:18 CEST 2021">
<process mode="process-name" >

Open configuration

Menu > File > Open or click on the Open button Open button in the toolbar. The configuration file is added in the configuration pane but is not edited automatically. The Start button Start button is disable if the file that has never been edited yet.

Edit configuration

Select one or more files in the configuration pane then Menu > File > Edit or click on the Save button Edit button in the toolbar.

You may also:

  • double click on a file in the configuration pane;
  • right-click on a file in the configuration pane to display the context menu and click on Edit;

Then you may modify the parameters. Use the Help buttons Edit button throughout the configuration editor as much as you can. Many parameters provide on-the-fly validation, for instance some text fields only accept numerical values.

Save configuration

Select a modified files in the configuration pane then Menu > File > Save or click on the Save button Save button in the toolbar.

As soon as a parameter is modified in the configuration editor the name of the configuration will appear in bold with a leading *. It reminds you to save the configuration file. If you were to run a modified configuration file, it would be saved beforehand automatically.

Before saving configuration editors may launch a validity check and provide some feedback. File will not be saved until you address all the issues detected by the validity check. You may notice that in the meantime the Start button is disable.

Save as configuration

Select a file in the configuration pane then Menu > File > Save as or click on the Save as button Save button in the toolbar.

Close configuration

Select one or more files in the configuration pane then Menu > File > Close or click on the Close button Save button in the toolbar.

A dialog box will show up if you attempt to close a modified file, to ask for confirmation. Same when you exit the program.

Closing the configuration tab in the Vox tools tab pane only hides the editor. Unsaved modifications are kept. A configuration file is only closed when it is removed from the configuration pane.

Run configuration

You may run a single configuration by a click on the Start button in the configuration pane. A disable Start button means that the configuration file is either empty (newly created) or that the file did not go through the validity check when saving and need more editing. When the simulation starts, the Start button becomes a Stop button Stop button that you may click to cancel the job.

You may run a bunch of configurations by selecting them in the configuration pane and click on the Run button Run button in the toolbar. You will be asked whether to run the simulation sequentially (one after an other) or concurrently. The maximum number of CPUs dedicated to AMAPVox may be set in Menu > Edit > Preferences. When the simulations start, the Run button becomes a Stop Button Stop button that you may click to cancel all the jobs.

Visualization pane

AMAPVox provides two visualization tools:

  1. A 3D voxel space viewer
  2. A vertical profile viewer

3D viewer

The 3D Viewer relies on OpenGL >= 3.

For Linux users, you may check OpenGL version with:

grep("OpenGL", system2("glxinfo", stdout = TRUE), value = TRUE)

The user is staight-forward. You choose a voxel file, select the variable to plot (that can be changed later on, directly in the viewer) and you can click on the Draw button.

The viewer can optionally draw the digital terrain model, the same one that is used in the voxelization process.

Vertical profile

@TODO…