User Guide ========== .. contents:: :local: Overview -------- Welcome to the Simplex4Data Plugin User Guide - your comprehensive resource for leveraging the full potential of this powerful tool. The Simplex4Data plugin is a robust and easy-to-use interface designed to seamlessly integrate the SimplexService geoservice API with your GIS needs in QGIS. It allows you to load your organisation's geographic data into QGIS. Furthermore, it provides you with a comprehensive set of filtering options ranging from simple name and key based filtering of the datasets to advanced spatial filtering. These features allow you to curate your data precisely to suit your needs. This user guide is designed to help you understand and use all these features to enhance your GIS experience by providing a customisable, easy-to-use gateway to your geographic data. In the following sections, we'll take a deep dive into each feature, explaining the user interface and troubleshooting common issues. Interface --------- The Simplex4Data plugin interface consists of two main parts: 1. The :ref:`Authentication ` 2. The :ref:`Layer Loader ` * :ref:`Selection ` * :ref:`Filter Options ` .. image:: images/user_guide/interface/basic-interface.png :alt: Plugin Interface Authentication ++++++++++++++ In the **Authentication** you enter your SimplexService API URL and your username and password. After entering the URL and your credentials (if required), you can press the `Login` button to authenticate to the SimplexService API. .. image:: images/user_guide/interface/authentication.png :alt: Authentication .. _layer-loader: Layer Loader ++++++++++++ The **Layer Loader** is all about loading your data into QGIS. From selecting the **Class** to filtering the data, this is where you can customise your data to suit your needs. It consists of two components: * :ref:`Selection ` to select the **Class**, **Object Type** and **Geometry Attribute** to load * :ref:`Filter Options ` to filter the selected data Selection ^^^^^^^^^ After a successful authentication with the SimplexService API, the **Classes** section of the **Selection** will be populated with all available **Classes**. .. image:: images/user_guide/interface/layer-loader-classes.png :alt: Selection - populated with classes Classes """"""" Each entry in the list represents a **Class** with the following naming scheme: * **Source ID-1-Class ID** - The source and class ID of the **Class** (e.g. ``9-1-100``) * **Class name** - The name of the **Class** (e.g. ``Gemeinde``) After selecting a **Class** from the list, the remaining sections: * **Object Types** and * **Geometry Attributes** will be populated with the data of the selected **Class**. .. image:: images/user_guide/interface/layer-loader-object-geometry.png :alt: Selection - populated with classes, object types and geometry attributes .. _object-types: Object Types """""""""""" The **Object Types** section contains a list of all available **Object Types** for the selected **Class**. Selecting an **Object Type** from the list will filter the data loaded into QGIS to include only objects of the selected **Object Type**. If nothing is manually selected, ``ALL TYPES`` is selected by default. Therefore using the Object Types section is optional. .. _geometry-attributes: Geometry Attributes """"""""""""""""""" The **Geometry Attributes** section contains a list of all available **Geometry Attributes** for the selected **Class**. Selecting a **Geometry Attribute** from the list is necessary to load the data into QGIS, as it determines if any geometry data will be loaded, and if so, what type of geometry data will be loaded. The option ``ONLY ATTRIBUTES`` means that no geometry data will be loaded (only an attribute table). After selecting a **Geometry Attribute** from the list the :ref:`Filter ` button and the :ref:`Filter ` button are enabled. You are not required to use the :ref:`Filter `, but it is recommended to do so, as it allows you to customize the data loaded into QGIS. .. image:: images/user_guide/interface/layer-loader-load.png :alt: Selection - ready to filter and load data .. _layer-loader-filter: Filter Options ^^^^^^^^^^^^^^ The **Filter Options** dialog allows you to filter the selected data that will be loaded into QGIS. It is devided into four sections: 1. :ref:`Name and Key Filter ` 2. :ref:`Bounding Box Filter ` 3. :ref:`Limit Filter ` 4. :ref:`Group Geometry Types ` .. image:: images/user_guide/interface/layer-loader-filter.png :alt: Filter Options When satisfied with your filter settings, you can press the `OK` button to apply the filter and return to the **Layer Loader**. If you want to discard your filter settings, you can close the **Filter Options** dialog to return to the **Layer Loader** without applying the filter. If you want to reset the filter settings to the default values, you can press the `Restore Default` button. .. _name-key-filter: Name and Key Filter """"""""""""""""""" The **Name and Key Filter** section allows you to filter the data by name and key and is an optional filter. Both filters filter the data by the following rules: * **Name** - The name filter is case insensitive and follows the contains rule (i.e. the data is filtered by the name of the object) * If the name filter is ``shop``, all objects with the name ``shop`` or ``Shop`` or ``shopping`` will be loaded into QGIS * **Key** - The key filter is case insensitive and follows the contains rule (i.e. the data is filtered by the key of the object) * If the key filter is ``12``, all objects with the key ``12`` or ``122`` or ``212`` will be loaded into QGIS .. _bbox-filter: Bounding Box Filter """"""""""""""""""" The **Bounding Box Filter** section allows spatial filtering of the data and is an optional filter. If the selected **Geometry Attribute** has a default Bounding Box, it will be used as the default value for the **Bounding Box Filter**. Otherwise, the **Bounding Box Filter** is disabled by default, but can be enabled by checking the box next to `Bounding Box`. .. image:: images/user_guide/interface/layer-loader-filter-bbox-disabled.png :alt: Filter Options - Bounding Box Filter disabled In this case, you must specify a valid bounding box by entering the minimum and maximum coordinates and the EPSG associated with those coordinates. Or you can use the `Get Map Extent` button. The `Get Map Extent` button uses the current map extent of the QGIS canvas as the bounding box. If you want to use a different EPSG than the default EPSG of the **Geometry Attribute**, you can enter the new EPSG in the EPSG code field. You can change the coordinates manually or use the `Convert` button to automatically convert the coordinates to the new EPSG. .. image:: images/user_guide/interface/layer-loader-filter-bbox-enabled.png :alt: Filter Options - Bounding Box Filter enabled You can also change the Layer CRS of the QGIS layer that will be created by the plugin and loaded into QGIS. Just open the drop down menu and select the desired CRS. .. image:: images/user_guide/interface/layer-loader-filter-bbox-layer-crs.png :alt: Filter Options - Bounding Box Filter - Layer CRS selection **Note:** If you selected ``ONLY ATTRIBUTES`` as the **Geometry Attribute**, the `Bounding Box` section will be disabled and cannot be enabled because no geometry data will be loaded. .. _limit-filter: Limit Filter """""""""""" The **Limit Filter** allows you to limit the number of features loaded into QGIS. Minimum and maximum values can be entered in the corresponding `Feature Limit` field. While the minimum value is 1, the maximum value is the total number of features available for the selected **Class**, **Object Type**, **Geometry Attribute** and filter options in the **Filter Options** dialog. If no features are available for the current selection, the `Feature Limit` field is disabled. You can check and update the current number of available features for the current selection next to the `Feature Limit` field. .. image:: images/user_guide/interface/layer-loader-filter-feature-limit.png :alt: Filter Options - Feature limit .. _group-geometry-types: Group Geometry Types """""""""""""""""""" The **Group Geometry Types** section allows you to group the geometry types of the selected **Geometry Attribute**. This means that if you select a **Geometry Attribute** that has several similar geometry types (e.g. ``Point`` and ``MultiPoint`` or ``Polygon`` and ``MultiPolygon``), you can choose to load both in the same layer or in separate layers. .. _layer-loader-load: Load Layer ^^^^^^^^^^ As described in :ref:`Geometry Attributes ` the `Load Layer` button is disabled until a **Geometry Attribute** is selected. But in some cases, the `Load Layer` button is still disabled even if a **Geometry Attribute** is selected. This is because a **Geometry Attribute** may not have any features available for the current selection and/or filter options. When the `Load Layer` button is enabled, you can press it to load the selected data into QGIS. After successfully downloading the data from the SimplexService API, a dialog will appear asking you to select a name for the layer. .. image:: images/user_guide/interface/layer-loader-load-select-name.png :alt: Layer Loader Load - Select name If you enter a name and press the `OK` button, the layer will be loaded into QGIS with the name you entered. If you close the dialog without entering a name, the layer will be loaded into QGIS with the default name. .. _features-and-functionality: Features and Functionality -------------------------- Simplex4Data offers several features designed to enhance your GIS experience. .. _set-default-url: Set a Default URL ++++++++++++++++++ With this feature, you can set a default URL for the SimplexService API. This means that you don't have to enter the URL every time you start QGIS. The default URL is saved in the QGIS settings and will be loaded automatically when you start QGIS. The option to set a default URL is available in the menu bar under `Options > Set Default URL`. .. image:: images/user_guide/features/default-url.png :alt: Set Default URL After selecting this option, a dialog will appear asking you to enter the new default URL. By pressing the `OK` button, the new default URL will be saved in the QGIS settings. If you close the dialog or press the `Cancel` button, the current default URL will be kept. .. image:: images/user_guide/features/default-url-dialog.png :alt: Set Default URL - Enter new default URL .. _url-history: URL History +++++++++++ The URL history is a list of all URLs that have been successfully used to authenticate with different SimplexService APIs. This feature allows you to easily switch between different SimplexService APIs without having to re-enter the URL every time. Like the standard URL, the URL history is saved in the QGIS settings and will be loaded automatically when you start QGIS. The URL history is available in the menu bar under `Options > URL History`. Furthermore, the is also the option to clear the URL history. This option is available in the menu bar under `Options > URL History > Clear URL History`. .. image:: images/user_guide/features/url-history.png :alt: Set Default URL - Enter new default URL .. _class-search: Seach for Classes +++++++++++++++++ The class search allows you to search for classes by name or ID. Searching for classes by name is case insensitive and follows the contains rule (i.e. the data is filtered by the name of the class). .. image:: images/user_guide/features/class-search.png :alt: Class Search .. _class-sort: Sort Classes ++++++++++++ The class list can be sorted by name or ID in ascending or descending order. Default sorting follows no particular order. .. image:: images/user_guide/features/class-sort.png :alt: Class Sort .. _refresh-data: Refresh Data ++++++++++++ After authenticating with the SimplexService API, the data is loaded into the plugin. If something changes in the SimplexService API, the data in the plugin will not be updated automatically. To update the data, you can press the `Refresh` button. .. image:: images/user_guide/features/refresh.png :alt: Refresh Troubleshooting --------------- Occasionally, you might encounter some issues while using the Simplex4Data plugin. .. _locating-issues: Locating Issues +++++++++++++++ You might encounter difficulties locating the Simplex4Data plugin using the methods described in :ref:`Basic Usage `. If so, follow these steps to ensure the plugin is installed and enabled: **Checking the Installation and Activation of Simplex4Data Plugin:** 1. **Access the Plugin Menu:** Navigate to the menu bar and select `Plugins > Manage and Install Plugins`. .. image:: images/getting_started/installation/manage-plugins.png :alt: Open Plugin Manager via Menu Bar 2. **Inspect Installed Plugins:** - Once inside, click on the `Installed` tab. - Search for the Simplex4Data plugin. 3. **If the Plugin is Missing:** - If you cannot find the Simplex4Data plugin in the list, it means it's not installed. In this case, proceed to install it. 4. **If the Plugin is Found:** - If you locate the Simplex4Data plugin, check if it's enabled. You can verify this by ensuring the checkbox next to the plugin name is ticked. .. image:: images/user_guide/troubleshooting/installed-plugins.png :alt: Installed Plugins & Search for Simplex4Data After following these steps, you should be able to locate the Simplex4Data plugin using the methods outlined in :ref:`Basic Usage `. .. _authentication-issues: Authentication Issues +++++++++++++++++++++ If you experience problems during authentication with the SimplexService API, follow the troubleshooting steps below: **SimplexService API Authentication Checklist:** 1. **URL Verification:** - Ensure the URL is correct. - Confirm the URL is accessible. - Verify that the URL points to the SimplexService API. - Check if the URL corresponds to the SimplexService API with authentication. 2. **Username Verification:** - Ensure the username you're using is correct. 3. **Password Verification:** - Confirm the password entered is correct. 4. **Combined Verification:** - Check if the combination of the username and password is correct for the specified URL.