From b5c1f1f11e57d737ac8880207c6c82cb74158455 Mon Sep 17 00:00:00 2001
From: Pieter Vander Vennet <pietervdvn@posteo.net>
Date: Sun, 12 Feb 2023 22:13:12 +0100
Subject: [PATCH] First documentation on using MapRoulette with MapComplete

---
 Docs/Integrating_Maproulette.md | 129 ++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 Docs/Integrating_Maproulette.md

diff --git a/Docs/Integrating_Maproulette.md b/Docs/Integrating_Maproulette.md
new file mode 100644
index 000000000..cc0e73c96
--- /dev/null
+++ b/Docs/Integrating_Maproulette.md
@@ -0,0 +1,129 @@
+# Integrating MapRoulette
+
+[MapRoulette](https://www.maproulette.org/) is a website which has challenges. A challenge is a collection of _microtasks_, i.e. mapping
+tasks which can be solved in a few minutes.
+
+A perfect example of this is to setup such a challenge to e.g. import new points. [Important: always follow the import guidelines if you want to import data.](https://wiki.openstreetmap.org/wiki/Import/Guidelines)
+(Another approach to set up a guided import is to create a map note for every point with the [import helper](https://mapcomplete.osm.be/import_helper). This however litters the map and will upset mappers if used with to much points.)
+
+## The API
+
+**Most of the heavy lifting is done in layer `maproulette`. Extend this layer with your needs**
+The API is shortly discussed here for future reference only.
+
+There is an API-endpoint at `https://maproulette.org/api/v2/tasks/box/{x_min}/{y_min}/{x_max}/{y_max}` which can be used
+to query _all_ tasks in a bbox and returns this as geojson. Hint:
+use [the maproulette theme in debug mode](https://mapcomplete.osm.be/maproulette?debug=true) to inspect all properties.
+
+To view the overview a single challenge, visit `https://maproulette.org/browse/challenges/<challenge-id>` with your
+browser.
+The API endpoint for a single challenge is `https://maproulette.org/api/v2/challenge/view/<challenge-id>` which returns a
+geojson.
+
+## Displaying MapRoulette data in MapComplete
+
+As you'll probably want to link MapComplete to your challenge, reuse [maproulette_challenge](Docs/Layers/maproulette_challenge.md).
+It has a basic framework already to load the tags.
+
+Of course, interacting with the tasks is the next step.
+
+### Detecting nearby features
+
+You can use [`calculatedTags`](./Docs/CalculatedTags.md) to add a small piece of code to e.g. detect nearby entities.
+
+The following example is to match hotels:
+
+```
+    "calculatedTags": [
+      "_closest_osm_hotel=feat.closest('hotel')?.properties?.id",
+      "_closest_osm_hotel_distance=feat.distanceTo(feat.properties._closest_osm_hotel)",
+      "_has_closeby_feature=Number(feat.properties._closest_osm_hotel_distance) < 50 ? 'yes' : 'no'"
+    ], 
+```
+
+This can be used to decide if tags should be applied on an existing object or a new point should be created.
+
+
+### Creating a new point based on a maproulette challenge (Guided import)
+
+**Requirement**: the MapRoulette task should have `tags` added.
+
+One can add `import`-button in the featureInfoBox ([documentation here](./Docs/SpecialRenderings.md#importbutton)).
+Note that the import button has support for MapRoulette and is able to close the task if the property containing the maproulette-id is given:
+
+```json
+{
+    "id": "import-button",
+    "render": {
+      "special": {
+        "type": "import_button",
+        "targetLayer": "<the layer in which the point should appear afterwards>",
+        "tags": "tags", -- should stay 'tags'
+        "maproulette_id": "mr_taskId",  -- important to get the task closed
+        "text": {
+          "en": "Import this point" -- or a nice message
+        },
+        "icon": "./assets/svg/addSmall.svg", -- optional, feel free to change
+        "location_picker": "photo", -- optional, background layer to pinpoint the hotel
+      }
+    }
+}
+```
+
+
+### Applying tags to already existing features
+
+For this, [the `tag_apply`-button can be used](./Docs/SpecialRenderings.md#tagapply).
+
+The following example uses the calculated tags `_has_closeby_feature` and `_closest_osm_hotel`. These were added by a small extra script using `calculatedTagss`.
+
+```json
+
+ {
+    "id": "tag-apply-button",
+    "condition": "_has_closeby_feature=yes", -- don't show if no feature to add to
+    "render": {
+      "special": {
+        "type": "tag_apply",
+        "tags_to_apply": "$tags", -- note the '$', property containing the tags
+        "id_of_object_to_apply_this_one": "_closest_osm_hotel" -- id of the feature to add those tags to
+        "message": {
+          "en": "Add all the suggested tags"
+        },
+        "image": "./assets/svg/addSmall.svg",
+      }
+    }
+  }
+
+```
+
+## Creating a maproulette challenge
+
+A challenge can be created on https://maproulette.org/admin/projects
+
+This can be done with a geojson-file (or by other means).
+
+To create an import dataset, make a geojson file where every feature has a `tags`-field with ';'-seperated tags to add.
+Furthermore, setting the property `blurb` can be useful.
+
+
+(The following example is not tested and might be wrong.)
+
+```
+{
+    "type": "FeatureCollection",
+    "features": [
+        {
+            "type": "Feature",
+            "geometry": {"type": "Point", "coordinates": [1.234, 5.678]},
+            "properties": {
+                "tags": "foo=bar;name=xyz",
+                "blurb": "Please review this item and add it..."
+            }
+        
+        }
+    
+    ] 
+}
+
+```