## Setup

Download the source code as a zipped file (or if you'd like you can clone the repository)

![](../media/ToolDownload.PNG)

Unzip the file to a folder of your choosing. This will extract a single folder named `s3ds-main`.

When QGIS add's python files to the processing toolbox, it creates copies of those files in a QGIS 'scripts' directory. The s3ds QGIS tools depend on a few core functions defined in this repository. These core functions are shared by the command line utilities, ArcPro toolbox and QGIS toolbox - so they should be kept in the same directory. However, we need to instruct the QGIS tools in how to find these tools when the scripts get relocated. Specifically, we need to enter the full path to the `src` directory in each of the `*.py` files in the `qgis_toolbox` directory. 

At the top of each of the scripts begenning with `qgis_` is a variable called `PATH_TO_SRC_FOLDER_FOR_YOUR_INSTALL_OF_S3DS`. You need to set this variable equal to the full path to your `src` folder within the s3ds directory:

![](../media/QGIS_updatePathInScripts.png)

One option for capturing this path is to right-click the `src` directory and select `copy as path`:

![](../media/QGIS_copySrcPath.png)

**Note!** You will need to update these paths and re-import the scripts if you ever move your s3ds directory.

Once you have updated all these paths, open QGIS and navigate to the `Processing Toolbox`, often located along the right side of an open project, or accessed view `View > Panels > Processing Toolbox` or opened with `ctr + alt + T`. Within the `Processing Toolbox` select the Python button and then the `Add Script To Toolbox...` option.

![](../media/QGIS_addScriptToToolbox.PNG)

Select the three `.py` files in the `qgis_toolbox` directory of this repository. 

![](../media/QGIS_selectScripts.PNG)

The tools of this toolbox should then appear in a `Scripts > s3ds toolbox` directory at the bottom of the available processing tools. 

![](../media/QGIS_s3dsToolbox.png)

## Usage

This toolbox contains just three simple tools at present, `build database`, `validate database`, and `add tables to existing database`. Future iterations may include other tools, but in general we would like to seperate tools that are used for just building/validating databases (which may be agnostic to the type of data) and tools designed for working with data in a particular standard.

### 1) Build database

This tool calls the s3ds 'builddatabase.py' function to build a database with the requested tables.

![](../media/QGIS_buildDatabase.png)

The arguments of the tool are as follows:

* **Tables** -- Please select the types of data you will include. The code will ensure all required tables are also included.
* **EPSG** --Please specify an EPSG code for the coordinate system you would like to use (e.g., '4326' for WGS84, '32615' for WGS84 UTM Zone 15N, and so on) 
* **Enforce relational integrity?** -- If true, this will make all `<tablename>_id` values auto-incrementing (so that a user doesn't need to populate them) and ensure that records can not be created in the database if they violate relational integrity. For example, you can not create a record that references a 'datasource' that doesn't exist or doesn't reference a datasource at all. 
* **Path to new database** -- The path to the geodatabase of geopackage file.

### 2) Add tables to existing database

This tool assists with creating tables in an existing database, in the event new data types need to be added to a project after editing has begun.   
This tool calls the s3ds 'builddatabase.py' function, which defaults to adding content to existing tables. It is therefore identical to the 'Build database' tool, 
but the database is set as an 'input' in the script tool parameters as opposed to 'output' - ArcPro uses these parameters to control dialog boxes and detect
file conflicts / the need to overwrite data.

![](../media/QGIS_appendDatabase.png)

The arguments of the tool are as follows:

* **Path to existing database** -- The path to the geodatabase of geopackage file.
* **Tables** -- Please select the additional types of data / tables you would like to include. The code will ensure all required tables are also included.
* **EPSG** --Please specify an EPSG code for the coordinate system you would like to use (e.g., '4326' for WGS84, '32615' for WGS84 UTM Zone 15N, and so on) 
* **Enforce relational integrity?** -- If true, this will make all `<tablename>_id` values auto-incrementing (so that a user doesn't need to populate them) and ensure that records can not be created in the database if they violate relational integrity. For example, you can not create a record that references a 'datasource' that doesn't exist or doesn't reference a datasource at all. 

### 3) Validate database

This will validate a supplied database and generate a text file error log, you must open that text file to evaluate for errors.

![](../media/QGIS_validateDatabase.png)

* **Database path** - The path to the geodatabase of geopackage file.
* **Error log (optional)** - This is the path to a .txt file that will be created to log errors in. 

After the tool completes running, view the `log` of the processing tool and/or openthe output file to open and examine it for errors:

![](../media/QGIS_validationResults.png)


### Potential future tools

### 4) Build database metadata

This would be a tool to populate FGDC metadata and USGS data dictionaries for a supplied database

