Geo Plugins tutorial

This tutorial is a stub.

Prerequisites

The following prerequisites should be met before starting this tutorial:

• Parts of this tutorial are a continuation of the Template Project Tutorial. If possible, and if you have not already done so, please complete that tutorial first. If you have not yet followed the tutorials related to those subjects please do so first.
• This tutorial can best be started with a Project in the city of The Hague in the Netherlands, due to one of the used data sources being specific to that city. Note that multiple new Projects will be created during this tutorial.
• To work with Project templating functionality fully (specifically, to assign Template status to a Project), either Domain Admin access rights are required, or the assistance of a Domain Admin for your organisation is required. 

Preparations

Take the following steps as preparation for following this tutorial:

• Start the Tygron Platform application, and if necessary log in so you are in the main menu.

Introduction to Geo Plugins

The Tygron Platform allows for the importing of geo data to enrich a Project. This can serve to both amend data which the Tygron Platform already supplies, but also to add types of data which are unique to the use-case at hand. When importing data, almost all of the related operations are to determine precisely how the imported data relates to the potential data types and subtypes available in a Tygron Platform Project.

Geo Plugins offer a way to store such a mapping, so that import operations can be easily repeated. In them, information is stored about which data can be found in the relevant data source, and how that data should be interpreted or modified when it is imported. They can then be used when manually importing data, but can also be called upon when a new Project is created to automatically obtain data relevant for the use-case and models the Template Project entails.

Preparing for the tutorial

Any Project may contain any number of Geo Plugins. However, for the purpose of this tutorial a Project in a specific location is required, due to some of the steps relying on a datasource which has data only in a specific region.

Find an open spot in the Project's 3D world.

In this spot, data can be created which can then be set up to import.

Draw 3 Areas. They can be any shape or orientation. However, ensure they do not overlap.

Give one of the Areas an "OFFICES" Attribute, with value 1.

Give another of the Areas an "RESIDENCES" Attribute, with value 1.

In the editor, go to:

Editor → Current Situation (Ribbon tab) → Areas (Ribbon bar) → Export Geo Data (Dropdown)

Open the window for exporting the Areas' geo data.

Opt to export the created Areas as a GeoJSON to the Geo Share. This will create a small file in your Domain's Geo Share space, which can be used as a source for geo data.

Geo Plugin for Buildings

One of the most important benefits of Geo Plugins is the ability to define a mapping between data in a data source, and the various Functions available in the Tygron Platform. Such a Geo Plugin can then be used while importing data, such as the dataset created earlier, and saved to the Geo Share.

In the editor, go to:

Editor → Tools (Ribbon tab) → Geo Plugins (Ribbon bar)

At the bottom of the left panel, set the type selection to BUILDINGS, and then opt to add a Geo Plugin of that type. It will appear in the list.

In the right panel, set the name of the Geo Plugin to "Geo Plugin for Buildings".

In the right panel, select the GeoLinks tab, and at the bottom of the right panel click on Add to create a Geo Link.

Select the Geo Link. The bottom panel will appear with details for the Geo Link.

A Geo Link is a specific connection which can be applied to any feature. Based on the configuration of the Geo Link, a feature will either be processed and imported, or it will not be processed by this Geo Link. With multiple Geo Links in a Geo Plugin, every feature is checked for whichever Geo Link has the best match (if any) and then that Geo Link will dictate how the feature is imported.

This first Geo Link will be a linkage for data to interpret features in geo data as offices.

Change the name of the Geo Link to "Offices link".

Click on "Select Function", and select any office Function.

Switch to the bottom panel's "Matching Attributes" tab. This allows configuring which attributes (and if desired, which values for those attributes) should be found in a feature for it to be processed by this specific Geo Link.

Add an Attribute.

Double-click to edit it, and change the Attribute to "OFFICES".

This completes the configuration of this Geo Link.

In the right panel, add another Geo Link.

Set the Geo Link's name to "Residences link", and set the Function to any residential Function, such as "Affordable Housing".

Under "Matching Attributes", add an Attribute, and change that Attribute to "RESIDENCES"

Using the Geo Plugin

Now that the Geo Plugin is set up, it can be used while importing geo data.

In the editor, go to:

Editor → Current Situation (Ribbon tab) → Buildings (Ribbon bar) → Import Geo Data (Dropdown)

As data source to import data from, opt to import a GeoJSON.

Select the file which was created earlier and stored on the Geo Share. It should be easily parsed and recognize 3 features.

Continue to the step regarding names, and opt to create names based on your own prefix. Enter a name along the lines of "Geo Plugin Building".

Continue to the step regarding Function Mapping. In that step, opt to use a Geo Plugin, and select the Geo Plugin created earlier.

Continue through the rest of the steps of the import wizard, and finish it. The Buildings will now appear in the 3D world.

Using a Template with a Geo Plugin

One of the most important benefits of Geo Plugins is that they can be configured to automatically include data when a Template Project is used to create a new Project. While the new Project is created and the Tygron Platform establishes connections to external data sources, any active Geo Plugins define additional connections which should be used to obtain more data for the Project automatically.

To do this, the Geo Plugin requires a configuration of a related Project Source as well. A new Project Source definition must be created for the dataset which is currently present on the Geo Share, and that Project Source can then be referenced by the Geo Plugin.

In the editor, go to:

Editor → Tools (Ribbon tab) → Geo Plugins (Ribbon bar) → Geo Plugin for Buildings (Left panel)

In the right panel, find the "Source" configuration option, and click on "Select".

This will open the "Select Source" window.

Click on "Add Source". This will open the Source Wizard.

Opt to select a service found in the Geo Share, and continue to the next step.

In the list of available GeoJSONs, select the GeoJSON of the previously created dataset, and continue to the next step.

In the final step, the name and the underlying URL of the Project Source can be reviewed. Nothing needs to be changed.

Continue past the final step. The wizard will close, and the "Select Source" window will close as well. Notice the newly created Project Source is configured in the Geo Plugin.

Save and exit the Project, and restart the Tygron Platform application.

In the main menu, switch to the projects overview and ensure the project created to far is set to "Template".

In the main menu, opt to create a new Project and select the Template Project created so far.

In the location selection screen, place the location selection on approximately the same location as the Template Project is on. Of importance is to have it at least cover the area where the dataset was created earlier.

Open the "Advanced Options" panel

Switch to the "Custom" tab. Take note that the Geo Plugin created is listed here, and can be set to active or inactive. Ensure the Geo Plugin is active.

Start the map creation process.

While the data is being collected from the various data sources, notice an additional entry is present named "Custom Buildings".

After the Project has generated and the 3D world is visible, notice that the Buildings from the created dataset are immediately present in the 3D world.

Geo Plugin for WFS

Geo Plugins are best used as connectors to live data sources with coverage for all potentially relevant areas a Project or Template may apply to. Setting up a Geo Plugin for a WFS is similar to setting one up for GeoJSON data, but with a few more details related to the specific service. Specifically, a WFS is structured in layers and is usually queried in parts, which means some configuration must be provided to properly request the relevant data from it.

Reopen the Template Project in the editor.

In the editor, go to:

Editor → Tools (Ribbon tab) → Geo Plugins (Ribbon bar)

At the bottom of the left panel, set the type selection to AREAS, and then opt to add a Geo Plugin of that type. It will appear in the list.

In the right panel, set the name of the Geo Plugin to "Geo Plugin for districts".

In the right panel, find the "Source" configuration option, and click on "Select".

This will open the "Select Source" screen.

Select the Source "CBS Buurten", and click "OK" This will close the "Select Source" window.

In the right panel, find the "Layer id" configuration option, and click on "Select".

This will open the "Layer selection" prompt.

Select the "wijken" layer (the name may differ slightly), and click "OK". The "Layer selection" prompt will close, and the "Layer id" will be filled out in the right panel.

Additional inputs have appeared in the right panel.

Find the "Name Attribute" configuration option, and click on "Select".

This will open a prompt with which to select the name Attribute. Areas created by this Geo Plugin will have a name based on what the original feature had as a value in this Attribute.

Select the attribute "wijknaam", and click "OK". The prompt will close, and the "Name Attribute" will be filled out with the name of the selected Attribute.

Find the "Unique ID Attribute" configuration option, and click on "Select".

This will open a prompt with which to select a uniquely identifying Attribute of the source data. This is important when data can be queried for large extents, as larger extents will require multiple queries to obtain all the data. To prevent the same feature to be loaded in multiple times, the features are checked to have a uniquely identifying Attribute, and duplicates are discarded.

Select the attribute "wijkcode", and click "OK". The prompt will close, and the "Unique ID Attribute" will be filled out with the name of the selected Attribute.

The configuration of the Geo Plugin is now such that it should refer to the dataset of districts of the dutch CBS, using the "wijknaam" (district name) as the name for the resulting Areas in the Project, and using the "wijkcode" (district code) to uniquely identify the features so as to prevent duplicates.

Testing the WFS Geo Plugin

Save the Project.

Note that you may have to set the editing rights to "WRITE" before you can save the changes. If this is the case, set the editing rights to "WRITE", then save the Project, and then set the editing rights back to "READ".

Exit the Project. As the Project has just been explicitly saved, the Project does not need to be saved on close again.

Restart the Tygron Platform application.

In the main menu, opt to create a new Project and select the Template Project created so far.

In the location selection screen, place the location selection on approximately the same location as the Template Project is on. Of importance is to have it at least cover the area where the dataset was created earlier.

Start the map creation process.

While the data is being collected from the various data sources, notice an additional entry is present named "Custom Areas".

After the Project has generated and the 3D world is visible, go to:

Editor → Current Situation (Ribbon tab) → Areas (Ribbon bar)

Notice a list of Areas has been added to the Project automatically. The list of Areas is similar to the list of Neighborhoods, but is a higher-level urban subdivision.

Tutorial completed

Congratulations. You have now completed this tutorial. In it, you have learned how to create Geo Plugins and use them to automatically map geo data, and use them to automatically retrieve data when using your Project as a Template to create a new Project.