---
title: "Graphical User Interface"
output: rmarkdown::html_vignette
#output: rmarkdown::pdf_document
vignette: >
%\VignetteIndexEntry{amapvox-gui}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
options(rmarkdown.html_vignette.check_title = FALSE)
```
{width=256px}
```{r setup}
library(AMAPVox)
```
## 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 {width=24px}
in the toolbar.
A configuration file is an XML file with following header:
```
```
### Open configuration
Menu > File > Open or click on the Open button {width=24px}
in the toolbar.
The configuration file is added in the configuration pane but is not edited
automatically. The Start button {width=24px} 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 {width=24px}
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 {width=24px} 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 {width=24px}
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 {width=24px} is disable.
### Save as configuration
Select a file in the configuration pane then Menu > File > Save as or click on
the Save as button {width=24px}
in the toolbar.
### Close configuration
Select one or more files in the configuration pane then
Menu > File > Close or click on the Close button {width=24px}
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
{width=24px} 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
{width=24px} 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 {width=24px}
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
{width=24px} 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:
```{r eval=FALSE}
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...