Home

Map With AI Self-service Training Document

For Mappers

Accessing RapiD projects in HOT Tasking Manager

RapiD can now be added to any HOT Tasking Manager project. Many projects may have it enabled or try following this link to find those with mapwithai in the description. https://tasks.hotosm.org/explore?text=mapwithai

Find a project marked with RapiD in the name to start mapping.

Once inside the project, either first select a task and then click Map a Task or simply click Map a Task to select a random task:

Select RapiD from the editor dropdown and click Start Editor:

Editing in RapiD

RapiD is Facebook's fork of the iD editor with a set of enhanced features including a more complete set of validation checks to help catch issues on AI or manually generated roads. It takes all the power of Facebook's AI assisted mapping and makes it accessible to all levels of mappers. Upon opening a task area, the mapper will be presented with an additional RapiD Assist layer colored magenta. These magenta ways are road predictions that a mapper can choose to add to the map. When editing from the tasking manager these suggested roads will only load within the bounding box and anything not specifically chosen for inclusion by the mapper will not be uploaded.

To use RapiD, a mapper selects a road then clicks “Use This Feature” or uses the hotkey “A” to bring the predicted way onto the map. Until the feature is brought into the map in this way, it is not editable. From there the feature is like any other newly digitized road and can be altered and tagged. The initial generated data is often in a high quality state but it may need further work to bring it up to a finished quality. If a mapper decides they don't want to use the predicted road they can mark “Remove This Feature” or hotkey “D” to make it disappear. You can also add and remove roads even faster if you hold down “A” or “D” and then click on the magenta road. To aid in tagging these newly created roads correctly, we have added the hotkey “Shift + C” to cycle through the most common road tags. With the hotkey “Shift + R” the RapiD Assist layer can be turned off and “Option + W” will turn off normal OSM data. This will allow a mapper to see the background imagery in order to validate the data.

Additionally, we developed a style toggle to aid in the editing process. When the hotkey “G” is pressed, any modified part of a pre-existing road will turn green. This will also highlight any newly added roads (through either manual editing or the magenta layer) as green.

Editing Esri Data in RapiD/JOSM

RapiD and JOSM now includes Open data sets from Esri's ArcGIS API! right now, only two data types are supported: Buildings and Address Points.

The RapiD UI has been updated to include all these different datasets, which you can 'opt in' to viewing/editing just like any other RapiD feature. Note: These features are not necessarily AI-derived, and could come from a variety of different authoritative sources / methods.

Once added to the map, these features can be used just like other RapiD features. In particular, the address point data can be merged any existing buildings that may be part of the map.

Notice also that there is a lot of tagging data- RapiD has been updated to show tags when hovering over a feature. This makes it easier to scan a dataset- just pass the mouse over the features and watch the sidebar.

For More Information about Esri Data in RapiD/JOSM:

The Esri Announcement and the Facebook Announcement of this collaboration.
The OSM Wiki Entry for these ArcGIS Datasets- if you're curious to find out more about the individual data sets available.

Validation Checks

In addition to the normal validation checks now present in iD, we have added a few additional checks that are particularly useful when working with ML data.

Short road checks

Short road checks look for roads that may need extension or deletion.

Disconnected Roads

We have enhanced the disconnected road check to check when a newly added cluster of roads is disconnected from the already existing road network whereas previously it just looked for single disconnected roads. Sometimes while working in an unmapped area, there will not be pre existing roads and this warning will not be fixable.

Extra nodes near connection

This check looks for nodes near intersections that can possibly be deleted to create a more accurate intersection shape.

Fixes Requiring Human Judgement

RapiD is great at finding and creating roads but it is not perfect. Rather than being complete, the data should be considered as a starting point for human editing. Here are some common mistakes in the AI assisted data to look out for while editing:

Incorrect junction configuration

Forced cross streets

Two T-junctions that are very close together, can sometimes be digitized by the machine as a forced cross street. As you can see, these are better represented by two separate junctions. Y-shaped junctions

Sometimes the machine may add a node or two on either side of a T-junction. These nodes are superfluous, and can create a very slight kink in the way. Often times, they should just be deleted. These will typically be identified by the validation check “Extra nodes near connection” and can be automatically addressed but some may require human identification. Incorrect digitization of roundabouts:

The machine usually roughly digitizes around roundabouts so you could see something like the geometry below when first added. The mapper will need to add the finishing touches using this workflow.

Split and combine the ways to roughly make a circle if needed.
Use the O hotkey to create a perfect circle.
Add the tag junction=roundabout.
Use the V hotkey to set the directionality for the roundabout. You will notice tiny arrows will appear and change on the way, as you hit V multiple times.

False connections

False connections caused by alternative imagery misalignment or poorly digitized pre-existing roads:

We use the “Facebook's Map With AI - Maxar Imagery” an imagery layer to generate our roads. Pre-existing OSM data may be aligned to other imagery, which can cause false connections or data errors. In the below example, the offset preexisting data caused a poor quality ML road to be predicted. In such cases the ML road should just be removed. With Facebook's Map With AI - Maxar Imagery With DigitalGlobe Standard

False connections through physical barriers:

Sometimes the ML may make a connection through an area that is blocked by physical boundaries such as a wall, fence or even building occasionally.

These are often observed around commercial complexes, temples, schools, hospitals, parks, factories, etc.. Such boundaries can be very hard to see on satellite imageries and the machine sometimes connects these roads by mistake. In the example below the ML mistakes a roof shadow for a narrow road.

False positives

False positives can be caused when the machine mistakingly identifies a feature like a waterway or building as a road. In this example, a canal was incorrectly picked up as a road so the predicted road should just be removed.

Submitting Data

Once the data is ready to be uploaded to OSM, take a last look at the validation panel for any lingering issues. Then zoom out and check the task for completeness and tagging accuracy. When you are ready to proceed press the Save button.

Then leave a changeset comment describing what sort of roads you have added.

Hot Keys

Function	hot key
Hide/Show ML Roads	shift + R
Cycle road types	shift + C
Add ML feature	A
Remove ML feature	D
Highlight edited ways	G

Known Data Issues

We are constantly improving our generated roads but there are some current limitations listed below. If you find different bugs or data issues not listed please feel free to report them.

Y shaped intersections

Tile edge connections

AI roads are created from tiled imagery and then stitched together in post processing. At these tile borders, drawn in blue for illustration purposes but not visible normally, you may find rows of segments that are connected but not merged or the two segments may not properly connect at all sometimes.

Straight road kinks

Occasionally, a straight road might generate with some extra nodes that require straightening.

Wide road issues

Wide roads may cause data errors such as circles or false connections between parallel lanes.

Suggested Road type Tagging

Automated road type tagging is still a work in progress. We are actively working to improve our predictions for it, but always be sure to evaluate and change road types as needed.

Other special features on RapiD

Source=maxar

We automatically add source=maxar to all of the RapiD assisted roads. Older versions of the data used source=digitalglobe.

JOSM MapWithAI Plugin

Installation

Mandatory

Start JOSM
Open JOSM Preferences
Go to Plugins

Search for mapwithai (rapid also works)
Install the MapWithAI Plugin
Press OK

Paintstyle (Plugin should automatically add and enable it)

Start JOSM
Open JOSM Preferences
Go to Map Settings (the globe with a grid over it)
Go to Map Paint Styles
Add MapWithAI from the Available style list
Press OK

Usage

Basic Usage

Please note that the screen shots were taken with Expert Mode checked in JOSM preferences. You may not see all the actions available without that check, the missing actions may be buggy or for a niche audience.

Download an area of interest (either through a tasking manager or through the standard download window)
Download data from MapWithAI by going to Data -> MapWithAI -> MapWithAI: Download Data (default keyboard shortcut is ctrl + r / cmd + r, will conflict with a LiveGPSPlugin shortcut).

Switch to the MapWithAI layer if it is not already selected
Select an object or objects to add
Add the object by going to Data -> MapWithAI -> MapWithAI: Add selected data (default keyboard shortcut is shift + a)

Advanced Usage

Preferences

MapWithAI Preferences are currently under JOSM Preferences -> MapWithAI Preferences.

Servers: contains available datasets for mapping using the plugin. When a datasets is selected, a bounding box will show the extent on a map.

Select a dataset and click activate to make it available when mapping.

Settings

Preference	Explanation	Expert Mode
Automatically switch layers	if checked, when adding data switch layers automatically (default `yes`)	no
Maximum features (add)	The maximum number of features that can be added from the MapWithAI Layer in one action (default `5`)	no
Merge address nodes and buildings	Merges buildings added from the MapWithAI layer with building nodes (default `yes`)	no
Show Preview DataSets	Allows for viewing upcoming ArcGIS Online datasets	no
Table of replacement tags	Table of keys to replace (default is empty)	yes

The table of replacement tags tags key and value entries in the format of key=TAG=VALUE and value=TAG=VALUE, for example:

Remote control

For current features, if JOSM is running with remote control enabled and the MapWithAI plugin is installed, you can go to http://localhost:8111/features?q=mapwithai .

Remote control only affects the current MapWithAI layer.

Downloading data for current layers http://localhost:8111/mapwithai
Setting a bbox to download data http://localhost:8111/mapwithai?bbox=longitude1,latitude1,longitude2,latitude2
Setting an arbitrary URL http://localhost:8111/mapwithai?url=STRING
Setting max objects to add in each action http://localhost:8111/mapwithai?max_obj=INT
Setting autoswitch layer http://localhost:8111/switch_layer=BOOLEAN
Setting a crop bbox http://localhost:8111/crop_bbox=longitude1,latitude1,longitude2,latitude2

For Project Managers

Add RapiD to a Tasking Manager project

Note: You must have expert mode enabled in your user profile

After you create a project, you can add RapiD as a Custom Editor:

Click the Custom Editor menu on the left pane:

Fill out the fields for the Custom Editor:

Name - the name that will appear in the editor dropdown list
Description - the description will appear below the editor drop down when a user selects the editor (note: you can use markdown to style the description)
URL - the URL of the editor (https://mapwith.ai/rapid)
Enabled - toggle to enable/disable the custom editor as an option in the permitted editor lists

Bonus: You can also supply the remote control URL for the JOSM MapWithAI Plugin (http://localhost:8111/mapwithai). For more info on the plugin see JOSM MapWithAI Plugin.

In the Settings menu you can add RapiD for the mapping stage and the validation stage independently: RapiD will now appear as an option in the editor drop down list and the description will appear below: