Docs for version 3.5

docs/3.5/01_import_calc_results.md

@@ -0,0 +1,37 @@
+* [Index](index.md)
+* [Import Calculator Results](01_import_calc_results.md)
+* [Export Calculator Results](02_export_calc_results.md)
+* [Extract GML from AERIUS PDF](03_extract_gml_from_pdf.md)
+* [Generate Calculator Input](04_generate_calc_input.md)
+* [Relate Calculator results](05_relate_calc_results.md)
+* [Add Open data Layer](06_open_data_layers.md)
+* [Connect - Receptor Sets](07_connect_receptor_sets.md)
+* [Connect - Jobs](08_connect_jobs.md)
+* [Configuration](09_configuration.md)
+
+<img src="img/icons/icon_import_calc_result.svg" alt="button" width="96"/>
+
+# Import AERIUS Calculator results
+
+Import AERIUS Calculator result files and add them as QGIS vector layers.
+
+## Howto
+
+Click the import button in the IMAER toolbar and browse to the downloaded IMAER GML file from Aerius Calculator. (Make sure you downloaded the "GML with calculation results".)
+
+![dialog](img/import_result_file_dlg.png)
+
+The data will be converted into a GeoPackage (.gpkg) file at the same location your GML file is placed. Make sure you have write access to that directory.
+
+After conversion, the calculation result hexagons will be opened as a normal polygon vector layer in QGIS. The attribute table contains the deposition values in fileds starting with `dep_`.
+
+![deposition map and attribute table](img/import_result_map_and_table.png)
+
+You can use all standard QGIS functionality for viewing, analysing and editing the data.
+
+## Remarks
+
+* This functionality can only import calculation results on **receptor points** that
+contain hexagon information. Results on **calculation points** are skipped during the
+import.
+* Should work on IMAER versions 2, 3, 4 and 5 data.

docs/3.5/02_export_calc_results.md

@@ -0,0 +1,23 @@
+* [Index](index.md)
+* [Import Calculator Results](01_import_calc_results.md)
+* [Export Calculator Results](02_export_calc_results.md)
+* [Extract GML from AERIUS PDF](03_extract_gml_from_pdf.md)
+* [Generate Calculator Input](04_generate_calc_input.md)
+* [Relate Calculator results](05_relate_calc_results.md)
+* [Add Open data Layer](06_open_data_layers.md)
+* [Connect - Receptor Sets](07_connect_receptor_sets.md)
+* [Connect - Jobs](08_connect_jobs.md)
+* [Configuration](09_configuration.md)
+
+<img src="img/icons/icon_export_calc_result.svg" alt="button" width="96"/>
+
+# Export edited AERIUS Calculator results
+
+After editing the imported AERIUS Calculator results, the plugin can export the data back to IMAER GML format.
+
+## Howto
+
+Select the layer with the (edited) Calculator results to enable the export button in the IMAER toolbar. Clicking the button will save a new GML file in the same directory as the source GML file used for the import. The filename will be `<old_file_name>_modified.gml`.
+
+Currently there is no support for changing the file name. A second export operation will
+overwrite the existing file.

docs/3.5/03_extract_gml_from_pdf.md

@@ -0,0 +1,33 @@
+* [Index](index.md)
+* [Import Calculator Results](01_import_calc_results.md)
+* [Export Calculator Results](02_export_calc_results.md)
+* [Extract GML from AERIUS PDF](03_extract_gml_from_pdf.md)
+* [Generate Calculator Input](04_generate_calc_input.md)
+* [Relate Calculator results](05_relate_calc_results.md)
+* [Add Open data Layer](06_open_data_layers.md)
+* [Connect - Receptor Sets](07_connect_receptor_sets.md)
+* [Connect - Jobs](08_connect_jobs.md)
+* [Configuration](09_configuration.md)
+
+<img src="img/icons/icon_extract_gml_from_pdf.svg" alt="button" width="96"/>
+
+# Extract GML from AERIUS PDF
+
+## Introduction
+
+AERIUS Calculator provides downloading a PDF file which contains emission sources
+in a data block. This function helps you extracting that data from the PDF and save
+it to one or more GML files.
+
+## Howto
+
+1. Click the PDF/GML button to open the dialog.
+2. Choose the PDF file containing your input data.
+
+![dialog](img/extract_gml_from_pdf_dlg.png)
+
+After pressing `open`, the plugin will save the extracted data to a GML file with the
+same file name with a `_0` postfix and `.gml` as extension. In case there are multiple
+GML files present in the PDF, the postfix will be `_1`, `_2` and so on.
+A link to the file(s) will be displayed in the message bar on top of your map. If
+anything goes wrong, an error will be displayed there.

docs/3.5/04_generate_calc_input.md

@@ -0,0 +1,99 @@
+* [Index](index.md)
+* [Import Calculator Results](01_import_calc_results.md)
+* [Export Calculator Results](02_export_calc_results.md)
+* [Extract GML from AERIUS PDF](03_extract_gml_from_pdf.md)
+* [Generate Calculator Input](04_generate_calc_input.md)
+* [Relate Calculator results](05_relate_calc_results.md)
+* [Add Open data Layer](06_open_data_layers.md)
+* [Connect - Receptor Sets](07_connect_receptor_sets.md)
+* [Connect - Jobs](08_connect_jobs.md)
+* [Configuration](09_configuration.md)
+
+<img src="img/icons/icon_generate_calc_input.svg" alt="button" width="96"/>
+
+# Generate Calculator Input
+
+Convert your own data into IMAER GML data for use in AERIUS Calculator. This feature can turn data from any type of QGIS vector layer into emission sources, buildings and/or calculation points.
+
+The the available fields in the interface are depending on your country setting.
+
+The plugin simply attempts to generate the GML code based on your input data and plugin settings. There is no check for data validity! The easiest way to check validity is using the website.
+In general, leaving a field blank or having NULL values in your data will result in NULL values in the output. For optional parameters, this will simply not output anything. But in case of mandatory data it might result in errors.
+
+## Emission Sources
+
+Open your emission data as a regular vector layer in QGIS. The geometries can be points,
+lines or polygons. (And not multi-points, -lines or -polygons.)
+
+![dialog](img/generate_aerius_calculator_input_dlg_2.png)
+
+1. Make sure your Country and CRS are set to the right values. If not, change them in the plugin configuration dialog.
+2. Click the Generate IMAER Calculator input GML button to open the dialog for generating Calculator input GML.
+3. Choose the emission source type for your data. Currently only 2 sectors are available, `Roads` and `Generic` (for generic emission sources).
+4. In both the Metadata and Emission Source tabs, choose the fields from your layer for every variable you want to store in the GML file.
+5. Choose a file name for your GML file. The dialog will suggest a name including the current date and time (like `calcinput_20230623_130244.gml`)
+
+![dialog](img/generate_aerius_calculator_input_dlg_es.png)
+
+After pressing Save, the GML file will be generated. A link to the file will be displayed in the message bar on top of your map. If anything goes wrong, an error will be displayed there.
+
+## Other Content
+
+You can also generate other information into GML, such as buildings and calculation points.
+
+### Buildings
+
+![dialog](img/generate_aerius_calculator_input_dlg_bld.png)
+
+Buildings can either be created from a (single) polygon layer or a point layer containing
+a diameter value (for circular buildings).
+
+The id field should contain the same integer value as used in the emission source pointing to it. The generated GML will automatically contain the right localId values referring to the buildings.
+
+### Calculation Points
+
+![dialog](img/generate_aerius_calculator_input_dlg_cp.png)
+
+Those are typically stand alone GML files to upload to AERIUS Connect for calulating depositions at your peronally picked locations. The input must be a point layer.
+
+### Diurnal Variation
+
+![dialog](img/generate_aerius_calculator_input_dlg_dv.png)
+
+Diurnal variation profiles are not created from a layer (as there is no geometry needed) but by hand
+from a semicolon separated value table.
+
+The three values per hour of the day are for mon-fri ; saturday ; sunday. In total there should b 72 values (24h x 7d).
+
+The id field should contain the same integer value as used in the emission source pointing to it.
+
+## Saving and loading settings
+
+Because picking all the fields is a lot of work, there's a way to store the current
+field settings in a file. This is done with the `Save settings` and `Load settings` buttons
+at the bottom of the dialog.
+Loading the settings will set the field names.
+* In case the current input layer does not contain that field name, the entry will be cleared.
+* Empty values are stored as well.
+* The settings are stored in the work directory in a file called `generate_gml_config.json`
+which will be overwritten on every save operation.
+
+![roads tab](img/generate_aerius_calculator_input_dlg_3.png)
+
+## Using the exported GML file
+
+There are several ways of using the generated GML.
+
+1. Use the **plugin's Connect** functionality. This can validate the GML content, start a calculation and retreive the results.
+2. The generated GML file can be imported using the interface at [Aerius Calculator (NL)](https://calculator.aerius.nl/) for starting the calculation. It is possible
+to import multiple files before starting the calculation, which you can use when having
+multiple maplayers with emission data (and different geometry types).
+3. Use the **AERIUS Connect API** using the [Swagger](https://connect.aerius.nl/) interface or
+create your own software to connect to it.
+
+## Remarks
+
+* The current version of the generated GML file is `IMAER 5.1`
+* IMAER does not support multi geometry types (like MultiLineString) and will try to
+convert your data in case it has a multi type, because single geometry data is often stored as multi geometry type in GIS.
+* Your attribute data must contain the exact values that should end up in the GML file. The plugin does not attempt to convert values in some smart way.

docs/3.5/05_relate_calc_results.md

@@ -0,0 +1,52 @@
+* [Index](index.md)
+* [Import Calculator Results](01_import_calc_results.md)
+* [Export Calculator Results](02_export_calc_results.md)
+* [Extract GML from AERIUS PDF](03_extract_gml_from_pdf.md)
+* [Generate Calculator Input](04_generate_calc_input.md)
+* [Relate Calculator results](05_relate_calc_results.md)
+* [Add Open data Layer](06_open_data_layers.md)
+* [Connect - Receptor Sets](07_connect_receptor_sets.md)
+* [Connect - Jobs](08_connect_jobs.md)
+* [Configuration](09_configuration.md)
+
+<img src="img/icons/icon_relate_calc_results.svg" alt="button" width="96"/>
+
+# Relate Calculator results
+
+Relate IMAER layers to one another by calculating the difference, sum or maximum values
+of the receptor's deposition values.
+
+## Howto
+
+You will need at least 2 IMAER layers, loaded with the Import IMAER GML tool.
+
+1. Click the Relate calculation results button to open the dialog.
+2. Choose the `calculation type` (difference, sum or maximum).
+3. By default, the name for the new layer will be the name of the calculation type.
+You can choose a more specific name in the `layer name` input widget.
+4. Choose the layers to perform the calculation on. (In case of calculating the difference, is will be layer1 minus layer2)
+
+![dialog](img/relate_calc_results_dlg.png)
+
+A new memory layer will be created, holding all receptors from the input layers. In case a receptor only exists in one of the layers, the calculation will use the value 0 for the missing receptor.
+
+![dialog](img/relate_calc_results_map.png)
+
+The generated memory layer will have a predefined, 2 color style showing positive or negative values. This style can of course be changed with standard QGIS functionality.
+
+![dialog](img/relate_calc_results_legend.png)
+
+Output layers will have the same deposition fields as the IMAER layers so they can be used with this relate function as well. For example for summarizing more than 2 layers.
+
+## Processing
+
+The relate functions are also available as algorithms in the processing toolbox. These can be used
+in a more generic way, for example combined with other algorithms in a model. And it's possible to
+call them from a Python script.
+
+![dialog](img/relate_calc_results_processing.png)
+
+## Remarks
+
+* The `difference` operation works on 2 layers, but the `sum` and `maximum` can work
+on up to 5 layers.

docs/3.5/06_open_data_layers.md

@@ -0,0 +1,20 @@
+* [Index](index.md)
+* [Import Calculator Results](01_import_calc_results.md)
+* [Export Calculator Results](02_export_calc_results.md)
+* [Extract GML from AERIUS PDF](03_extract_gml_from_pdf.md)
+* [Generate Calculator Input](04_generate_calc_input.md)
+* [Relate Calculator results](05_relate_calc_results.md)
+* [Add Open data Layer](06_open_data_layers.md)
+* [Connect - Receptor Sets](07_connect_receptor_sets.md)
+* [Connect - Jobs](08_connect_jobs.md)
+* [Configuration](09_configuration.md)
+
+<img src="img/icons/icon_add_open_data_layer.svg" alt="button" width="96"/>
+
+# Open Data Layers
+
+Easily add an AERIUS Connect Open Data layer to your QGIS project.
+
+## Remarks
+
+* This function is currently disabled and waiting for a new implementation.

docs/3.5/07_connect_receptor_sets.md

@@ -0,0 +1,70 @@
+* [Index](index.md)
+* [Import Calculator Results](01_import_calc_results.md)
+* [Export Calculator Results](02_export_calc_results.md)
+* [Extract GML from AERIUS PDF](03_extract_gml_from_pdf.md)
+* [Generate Calculator Input](04_generate_calc_input.md)
+* [Relate Calculator results](05_relate_calc_results.md)
+* [Add Open data Layer](06_open_data_layers.md)
+* [Connect - Receptor Sets](07_connect_receptor_sets.md)
+* [Connect - Jobs](08_connect_jobs.md)
+* [Configuration](09_configuration.md)
+
+<img src="img/icons/icon_connect_receptorsets.svg" alt="button" width="96"/>
+
+# Connect - Receptor Sets
+
+In this dialog you can manage your own Receptor Sets in Connect. The dialog displays a
+list of uploaded data sets.
+
+## Howto
+
+You can add a Receptor Set by uploading a GML file with CalculationPoints and a name to identify them. The GML should contain featureMembers like this:
+
+`    <imaer:featureMember>
+        <imaer:CalculationPoint gml:id="CP.1">
+            <imaer:identifier>
+                <imaer:NEN3610ID>
+                    <imaer:namespace>NL.IMAER</imaer:namespace>
+                    <imaer:localId>CP.1</imaer:localId>
+                </imaer:NEN3610ID>
+            </imaer:identifier>
+            <imaer:GM_Point>
+                <gml:Point srsName="urn:ogc:def:crs:EPSG::28992" gml:id="CP.1.POINT">
+                    <gml:pos>123456.0 456789.0</gml:pos>
+                </gml:Point>
+            </imaer:GM_Point>
+            <imaer:label>Bossen &amp; Duinen</imaer:label>
+        </imaer:CalculationPoint>
+    </imaer:featureMember>`
+
+Unfortunately, the plugin can not (yet) create these kind of files.
+
+### Adding a set
+
+1. Create a GML containing CalculationPoint(s) like this:
+2. Choose the GML file.
+3. Choose a name and optional description.
+4. Click Add to start uploading.
+
+![dialog](img/connect_receptorsets_dlg_1.png)
+
+![dialog](img/connect_receptorsets_dlg_2.png)
+
+### Removing a set
+
+1. Select the set you want to remove by clicking the line in the table.
+2. Click `Delete`.
+
+![dialog](img/connect_receptorsets_dlg_3.png)
+
+### Refresh
+
+1. Click the `Refresh` button. :)
+
+After adding and removing Receptor Sets, a refresh should happen automatically. But in
+some occasions, like changes on the server or after network problems, you might want
+to refresh manually to make sure you are looking at the current data status.
+
+## Remarks
+
+* Make sure to keep a local copy of your GML files, as they get deleted during a server update.