Merge pull request #57 from heremaps/readme

Update readme

.github/workflows/main.yml

@@ -26,11 +26,8 @@ jobs:
     - name: Setup conda
       uses: conda-incubator/setup-miniconda@v2
       with:
-        mamba-version: "*"
         channels: conda-forge
-
-    - name: Mamba install dependencies
-      run: mamba install python=${{ matrix.python-version }} pip
+        python-version: ${{ matrix.python-version }}
 
     - name: Install dependencies
       run: |

README.md

@@ -1,7 +1,7 @@
 # HERE Maps for QGIS Plugin
 
 
-HERE Maps for QGIS is a [QGIS](https://www.qgis.org) plugin which can be used to visualize, edit and analyze data from [HERE Data Hub](https://www.here.xyz/) spaces and from Interactive Map Layer inside the [HERE Platform](https://platform.here.com/).
+HERE Maps for QGIS is a [QGIS](https://www.qgis.org) plugin which can be used to visualize, edit and analyze data from [Interactive Map Layers](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/layers.html#interactive-map-layers) (IML) on [HERE Platform](https://platform.here.com/) and from [xyz-hub](https://github.com/heremaps/xyz-hub) spaces directly on a map.
 
 ![new connection](res/new-connection.png)
 
@@ -25,76 +25,70 @@ HERE Maps for QGIS is a [QGIS](https://www.qgis.org) plugin which can be used to
 
 ## Usage
 
-Once you have installed and enabled the plugin HERE Maps for QGIS, it can be accessed via the toolbar, or the menu **Web**. The main dialog contains 5 tabs:
+Once user have installed and enabled the plugin HERE Maps for QGIS, it can be accessed via the toolbar, or the menu **Web**. To use the plugin, user first need to create an account in [HERE Platform](https://platform.here.com/). Once done, user can try to login in the plugin either with the same HERE Platform user credential or with the app credential (in case the first option does not work).
 
-+ `Load` : load data from an XYZ space into QGIS, given a valid token and server (PRD/CIT). To learn more about how to generate a token, refer to https://www.here.xyz/api/getting-token/ and https://xyz.api.here.com/token-ui/. 
+### Login
 
-    + `Mode`: there are 3 modes of loading
-        + `Live loading`: interactively refresh features in tiles within the current canvas. Useful for visualization of dynamic dataset with full editing capabilities
-        + `Incremental loading`: interactively refresh and cached features in tiles within the current canvas (no features delete). Useful for visualization and exploration of large dataset
-        + `Static loading`: load and cache all features in space in background. Useful for importing and analysis of static dataset
-    + `Chunk size` indicates the number of features per tile or iteration
-    + `Layering` controls the organization of data in XYZ space into different QGIS layers based on fields similarity, with 3 levels:
-        + `single`: merge data into 1 layer per geometry type
-        + `maximal`: do not merge data, as many layers per geometry type
-        + `balanced`: merge only similar data into 1 layer, balanced number of layers per geometry type
-
-+ `Upload` : upload current Vector Layer to a new XYZ Hub space. For this to work, make sure that your token also has write-level permissions.
+#### Add User Credential
 
-+ `Manage` : create new space, edit or delete existing space.
+1. Ensure that `HERE Platform` is selected in the Server drop down.
+2. If the User credential `HERE Platform User Login` exist in the Credential drop down, proceed directly to step 7
+3. Click on `Add` to add your credential.
+4. Tick the box `User login`
+5. Enter "HERE Platform User Login" in the `Name`, user email in the `User email` and the realm from the Account confirmation email.
+6. Click on OK to save the credential
+7. Select the User credential and click `Connect` to login for the first time. The Platform login webpage will pop up.
+8. Follow the steps in the Platform login webpage. Once login succesfully, the popup windows will be closed automatically and the list of available IML layers in your Platform account shall show up.
 
-+ `Map Tile` : create HERE Map Tile layer given valid `app_id` and `app_code`. Alternatively, `api_key` can also be used.
+#### Add App Credential (optional)
 
-+ `Settings` :
+1. Ensure that `HERE Platform` is selected in the Server drop down.
+2. Click on `Add` to add your credential.
+3. Enter "My App credential" as the name.
+4. Select a `credentials.properties` containing your HERE Platform app credential (typically location in `{$HOME}/.here/credentials.properties`)
+5. If user don't already have an app or a `credentials.properties` file then user can create one, following [the instructions here](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html).
+6. Grant access on the data to the HERE platform app so that it can access your project, following [the instructions here](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/manage-projects.html).
+7. Click on OK to save the credential, and close the connection window.
+8. Click `Connect` to show the list of available IML layers.
 
-    + `Clear cache` : empty the temporary cache folder. Active layers will be invalid after clearing cache.
+#### Connect and list catalogs and layers
 
-When the user make some edits to the loaded layer, the changes can be pushed to XYZ Hub via the button `Push changes` in the toolbar.
+1. Select either the User credential or the App credential and click `Connect` 
+2. The list of available IML layers in your Platform account shall show up in the tabular form
+3. User use the search bar to find the catalogs and layers of interest
 
-### Configure Server connection
+### Features
 
-Official Data Hub server is predefined under name "HERE Server" and thus is not required to be created. The following steps are only required for self-hosted Data Hub server and HERE Platform server.
+The main dialog contains 5 tabs:
 
-1. From the "Web" menu in QGIS, select "HERE Maps for QGIS" > "Add HERE Layer".
-2. Press the "Setup" button and then "Setup Server" to add a new server. 
-3. Click "Add" to add a new server.
-4. Select server type
++ `Load` : load data from a HERE Platform IML into QGIS, given a valid credential.
 
-    a. Server Type: DATAHUB, enter "HERE self-hosted Data Hub" as the name and your Data Hub URL as the server.
+    + `Mode`: there are 3 modes of loading
+        + `Live loading`: interactively refresh features in tiles within the current canvas. Useful for visualization of dynamic dataset with full editing capabilities
+        + `Incremental loading`: interactively refresh and cached features in tiles within the current canvas (no features delete). Useful for visualization and exploration of large dataset
+        + `Static loading`: load and cache all features in space in background. Useful for importing and analysis of static dataset
 
-    b. Server Type: PLATFORM, enter "HERE platform" as the name and PLATFORM_PRD as the server.
+    + `Chunk size` indicates the number of features per tile or iteration. Default: 100. For large layer of point, lines features, value of 10000 is recommended. For large layer of polygon features, value of 1000 is recommended.
 
-5. Click on OK to save the new server and OK again to return to the setup screen.
+    + `Layering` controls the organization of data in one layer into different QGIS layers based on fields similarity, with 3 levels:
+        + `single`: merge data into 1 layer per geometry type
+        + `maximal`: do not merge data, as many layers per geometry type
+        + `balanced`: merge only similar data into 1 layer, balanced number of layers per geometry type
 
-### Add HERE Data Hub Token
++ `Upload` : upload local QGIS Vector Layer to the server. For this to work, make sure that your token also has write-level permissions.
 
-1. From the "Web" menu in QGIS, select "HERE Maps for QGIS" > "Add HERE Layer".
-2. Press the "Setup", ensure that "HERE Server" is selected in the Server drop down.
-3. Click on "Add" to add your token.
-4. Enter a name and corresponding Data Hub token created previously according to the guide https://www.here.xyz/api/getting-token/
-5. Click on OK to save the token, and close the connection window
++ `Manage` : create new space, edit or delete existing space.
 
-### Add HERE Platform Credentials
++ `Map Tile` : create HERE Map Tile layer given valid `app_id` and `app_code`. Alternatively, `api_key` can also be used.
 
-1. From the "Web" menu in QGIS, select "HERE Maps for QGIS" > "Add HERE Layer".
-2. Press the "Setup", ensure that "HERE Platform" is selected in the Server drop down.
-3. Click on "Add" to add your credentials.
-4. Enter "My credentials" as the name.
-5. Select a credentials.properties containing your HERE Platform app credentials (typically location in `{USER_HOME}/.here/credentials.properties`
-6. If you don't already have an app or a credentials.properties file then you can follow "platform credentials" section of this guide to create one: https://developer.here.com/documentation/java-scala-dev/dev_guide/topics/get-credentials.html
-7. Grant access on the data to the HERE platform app so that it can access your project.  Do so by following this guide: https://developer.here.com/documentation/identity-access-management/dev_guide/topics/manage-projects.html
-8. Click on OK to save the credentials, and close the connection window
++ `Settings` :
 
-### Load Your Data from HERE Platform
+    + `Clear cache` : empty the temporary cache folder. Active layers will be invalid after clearing cache.
+    + `Clear cookies` : clear the login cookies. This could be helpful when login or loading show Authorization error
 
-1. Create a new project (Project → New), save the project
-2. From the "Web" menu in QGIS, select "HERE Maps for QGIS" > "Add HERE Layer"
-3. From the Connection drop down, select the "HERE Platform" connection and the "My Credentials" credentials that you created previously
-4. Click "Connect"
-5. Select one or more Interactive Map Layer entries
-6. Click on "Load" to load the data
+When the user make some edits to the loaded layer, the changes can be pushed to the server via the button `Push changes` in the toolbar.
 
-**Note:** You can also add background map tiles via the "Map Tile" tab. You will need to use your credentials from https://developer.here.com/.
+**Note:** User can also add background map tiles via the "Map Tile" tab. User will need to use your API key following [the instructions here](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-using-apikeys.html).
 
 ## Testing
 
@@ -116,8 +110,9 @@ e.g. `sh makeBuild.sh 1.5.5`.
 
 ## Changelog
 [CHANGELOG](CHANGELOG.md)
+
 ## License
 
-Copyright (C) 2019-2021 HERE Europe B.V.
+Copyright (C) 2019-2024 HERE Europe B.V.
 
 This project is licensed under the MIT license - see the [LICENSE](./LICENSE) file in the root of this project for license details.