---
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)
```

<!-- AMAPVox logo -->
![](rsc/amapvox-logo.png){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.

<center>![](rsc/tab_config-files.png)</center>

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

<center>![](rsc/tab_output-files.png)</center>

## 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](rsc/menu-new.png){width=24px}
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](rsc/menu-open.png){width=24px}
in the toolbar.
The configuration file is added in the configuration pane but is not edited 
automatically. The Start button ![Start button](rsc/start.png){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 ![Edit button](rsc/menu-edit.png){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 ![Edit button](rsc/help.png){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 ![Save button](rsc/save.png){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 ![Start button](rsc/start.png){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 ![Save button](rsc/save-as.png){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 ![Save button](rsc/menu-close.png){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
![Start button](rsc/start.png){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
![Stop button](rsc/stop.png){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 ![Run button](rsc/run-play.png){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 
![Stop button](rsc/run-stop.png){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...
