This toolbox serves as a simple proof of concept to demonstrate the compatibility of the Sen2Cube EO Data Cube with ArcGIS Pro such that registered users can access the application directly from within their ArcGIS Pro desktop software.
This toolbox is a prototype. It includes three standalone script tools that represent three different versions of the Proof of Concept Script Tool. Once is a more static, light-weight tool. The second is a more dynamic tool, designed to validate parameter inputs on the fly. The third one is a batch version, which can be used in model builder for batching different AOIs and soon also different dates.
The idea behind this project is for a registered user to be able to access the Sen2Cube EO Data Cube directly from a desktop GIS (in this case through an ArcGIS Pro toolbox). The goal is to let the user access the application, set necessary parameters, run the query to the data cube and retrieve the information outputs directly in the GIS. This project thereby focuses on creating a first working Proof of Concept, but possible further development ideas are listed in a following section.
A detailed description on how the semantic EO data cube and the Sen2Cube work in detail can be found in the Manual.
Simply download the content of the folder "Sen2Cube_Toolbox") and then add it to your ArcGIS Project as shown below. This toolbox was created for ArcGIS Pro 2.9.
When opening the toolbox, you will see the three standalone script tools. Each can be executed independently.
Code file available here
In this initial scipt tool the objective was to create a connection to Sen2Cube and load an inference result into the ArcGIS Pro map. The tool is structured in such a manner that all parameters are first defined by the user and when the uesr then clicks "Run" a pop up window prompts the user to login to Sen2Cube. For the login a tkinter pop-up window was created, where the user enters their credentials. This toolbox comes with a pre-defined (hard-coded) set of factbases and knowledgebases from which the user can choose. All user inputs are then converted into the required formats for the Sen2Cube inference request. Once the inference is sent, every 10 seconds the script tool checks the status of the inferece. Once the status is "Succeeded" the result is downloaded and saved in the user's specified folder and automatically loaded into the map.
A large amount of time was spent understanding the OAuth login and session handling process to correctly generate a user token and refresh it after a certain amount of time. In addition, the formatting and conversion of the data to match the Sen2Cube requirements took some trial & error. During the testing phase it was seen that the pop-up window (implemented with tkinter) appears to work differently on different devices. Since no on-the-fly parameter validation is implemented here the user must be familiar with the valid geographic and temporal ranges.
Parameters
Upon opening the tool, the user is promted to set a total of 8 optional and required parameters in the toolbox user interface. While the first seven will be used for creating the inference, the last one lets the user specify an output directory for the model outputs.
Complete list of toolbox parameters:
| Nr. | Parameter | Format |
|---|---|---|
| 1 | Area of interest* | Extent |
| 2 | Factbase* | String (Dropdown List) |
| 3 | Knowledgebase* | String (Dropdown List) |
| 4 | Start Date* | Date |
| 5 | End Date* | Date |
| 6 | Comment | String |
| 7 | Save as Favourite in Sen2Cube Account | Boolean |
| 8 | Output Directory* | Folder |
After clicking "Run" these further parameters are required from the user in a pop-up window:
| Nr. | Parameter | Format |
|---|---|---|
| 9 | Username* | String |
| 10 | Password* | Hidden String |
* Required Parameters
Login and Session Handling
Only registered users are able to use the toolbox. Therefore, when the tool is run, a pop-up login window asks the user for credentials to request the initial session token. This token is needed to create POST and GET requests to the JSON web API that interacts with the Sen2Cube backend. The initial token is only valid for 5 minutes, thus a refreshment is performed in the backbround to keep the session alive.
Major parts of logic and code for login and session handling are based on the Sen2Cli repository.
Requests
In the background, a POST request is used to post the created inference datamodel to the inference API endpoint which will then create an inference entity which is executed by the backend. When the inference is posted, the inferece status is recurrently requested using a GET request until the inference failed or was successful. In the former case the process is exited, in the latter case the outputs are accessed.
Output
Inference outputs can be either one or more Geotiff rasters, CSV tables or a mix of both. The outputs are read from the response object as soon as the inference status is switched to "SUCCESSFUL" by the system. The results are then downloaded into the user-specified target folder and additionally added to the active map in ArcGIS Pro. In case only CSV and no spatial information is produced, the additional AOI polygon indicates which are was investigated.
A visual step-by-step display of how the tool works.
Code Files available here
The second version of the script tool implements a more dynamic functionality. It is based on the first tool and implements many of the same functions. It also uses the same parameters. In contrast to the first version, which only establishes a connection with Sen2Cube when the user has already set the parameters and clicks "run", this version creates the connection to Sen2Cube at the beginning and then validates the user's parameter inputs on the fly.
- Only factbases with the status "OK" are loaded into the drop down box for Factbases
- Once a Factbase is selected, it is shown in the map to make the Area of Interest selection more intuitive
- Once a Factbase is selected, the Factbase's valid time ranges are used to validate the user's selected dates
- If the entered start date is either before or after the selected factbase's valid time range an Error Message is returned to the user immediately asking them to adjust this input
- If the entered end date is either before or after the selected factbase's valid time range an Error Message is returned to the user immediately asking them to adjust this input
- If the entered end date is before the entered start date an Error Message is returned to the user immediately asking them to adjust this input
- Once the user selects an Area of Interest (extent), the outline is shown in the map as well
- If the Area of Interest (extent) does not intersect with the Factbase's footprint, an Error Message is returned to the user asking them to adjust the AOI. The error is re-evaluated if the user changes the AOI or the Factbase.
An example of these error messages is shown here:
This second version of the script tool is likely the more user-friendly Sen2Cube prototype toolbox since it actively responds to the user's input, helping the user create a successful inference request. The visual components (the AOI and the factbase footprints) also enhance the user experience. By seeing the valid factbase footprint on the map it is easier for the user to understand where to place the AOI. Though this toolbox works, there are some further issues that need to be dealt with - these are outlined in the "Challenges and Future To-Do's" below.
A visual step-by-step display of how the tool works.
(1) Projections (relevant to the AOI and map outputs): The default map projection in ArcGIS Pro is the Web Mercator (EPSG: 3857). This means that any given spatial extent for the AOI is, by default, passed to the script tool in the unit "meters" rather than decimal degrees or degrees-minutes-seconds. The Sen2Cube backend expects to receive the AOI in the WGS84 (EPSG: 4326) projection in decimal degrees. To resolve this the following functions were implemented:
- In script tool 1: The tool reads the input extent and the map's current CRS. It then converts the given extent into ARcGIS point objects and reprojects them from the given CRS into the WGS84 CRS. This way the map displayed in the project can stay in the CRS chosen by the user.
- In script tool 2: This tool loads several intermediate objects into the map (the footprint of the factbases and the selected AOI) as well as the final results. Since the factbase footprints are in WGS84 and reprojecting them into the Web Mercator format proved difficult, this tool changes the map's CRS to WGS84 when the tool is opened. Upon completion the CRS of the map can, of course, be changed back into any other CRS and will still contain all of the tools output products.
(2) Scripting the Tool Validation: The tool validator reacts according to the user's live parameter input. As such, no "logging" or "print messages" are available to the programmer designing the validation functions. This proved to be a tedious task. A work-around was to user a "dummy" parameter or to add Error Messages to parameters whose values contain certain messages that reveal some insight into any errors in the code. In particular, working with geographical queries or objects was complex since the input for a "dummy parameter" or for Error messages can only be a string, and converting geographical objects into useful strings was not easy (this was the case for validating if the AOI intersects the Factbase). An unresolved issue is the user input for the AOI "union of inputs" and "intersection of inputs". In both cases, no information was found about what data is sent to the script tool and in whcih format. Due to the uncertain format it was (so far) not possible to create a "dummy parameter" or an Error Message with this information. This must be handled in the future.
- Allowing a more diverse input for the AOI. Currently the tool only accepts an extent. In the future, this should be expanded for more complex shapes.
- The default option of the AOI needs to be handled.
- Implement an area check on the entered AOI, i.e. with a maximum allowed size to avoid a user time-out after 600 seconds.
- Handing the user more descriptive error messages from the backend.
- Transferring the logic of the entire toolbox into a QGIS Plugin using the respective plugin creator for a free software solution.
- Handle "Union of Inputs" and "Intersection of Inputs" for the AOI options. It's unclear what data and which format is passed to the script tool.
- Add metadata! Not possible while creating the toolbox:
Niklas Jaggy - Login and Session Handling, POST requests to Sen2Cube, GET requests to Sen2Cube, filling inference request based on user input, displaying AOI in map, JSON data formatting, extracting information from inference result, documentation, general toolbox development, AOI area size validation (in progress)
Christina Zorenboehmer - Login and Session Handling, token refresh, Pop-Up login box, AOI CRS reprojection, filling inference request based on user input, JSON data formatting, handling multiple inference outputs and loading into map, validation functions for dynamic script tool (loading factbases and knowledgebases into parameters after login, validating time ranges and AOI on the fly, loading factbase AOIs into map on the fly, validation class login handling), general toolbox development, documentation
Kabul River, Afghanistan: Count Water Presence Inference.
This demo shows an example of how to use the toolbox and then work with the results in ArcGIS.
