WikiProject Belgium/Building and address import/Instructions

These instructions will get you started with the Geometry Import & Merge Tool in no time and and are meant to be as short as possible. There are separate, more detailed instructions including peculiar stuff specific to the regions in the subprojects pages.

• Flanders: GRB buildings (including addresses) and pure CRAB addresses
• Brussels: TODO
• Wallonia: TODO

Reminder: OpenStreetMap Belgium DOES NOT want the buildings to be imported as quick as possible but as good as possible.

We require that you let the community review your initial work and that you stick to the quality level that we ask. You must join the dedicated building import channel first ( #osmbe-buildingimport:matrix.org / irc.oftc.net #osmbe-grb), or if you don't want to join Matrix/IRC, please contact us in other ways. Failing to do this will get you blocked.

Before you start

• Good mapping starts with good surveying / source data. This applies to both source data from the tool as actual fieldwork.
• Go in small chunks. Don't get too carried away. Prefer quality over speed.
• Report a changeset link of your first changesets in the dedicated channel #osmbe-buildingimport:matrix.org.

Setting up JOSM

• This tool is specifically tailored to work with JOSM. No compatibility for other editors.
• You need to allow acces by 'remote control', so the tool can feed data into JOSM:
  • In English: Edit > Preferences… (F12) > Remote Control ('TV remote' icon) > Check the 'Enable remote control' checkbox.
  • In Dutch: Voorkeuzen / Voorkeuzen voor voorkeuzen / Icon with a 'TV remote' (above WMS) / toggle the checkbox 'afstandsbediening inschakelen'.
• Frequent users will want to uncheck the last checkbox ('Confirm all Remote Control actions manually').
• It's easier to work with utilsplugin2 installed.

Connecting to the tool

URL: https://buildings.osm.be/

• Sign up / Log in to be able to export data to JOSM.
• Test remote control: With JOSM open, hit the "Check JOSM" button. Info about the check will be displayed below the map.
• If you don't get a successful connection, join the Matrix room and ask for help.

Getting data from the tool into JOSM

• Zoom almost at maximum details (around zoom level 18) into the area you want to map (just a little wider, in fact) and hit Open area in JOSM. This creates a layer in JOSM with the corresponding OSM data.
• Now, use the buttons on the left or the icon buttons on the top of the map in the import tool:
  • Load OSM data to look for already imported data. Wait for a message below the map that the data has been parsed.
  • Filter Export layer to throw out the buildings that have already been imported and have not changed in the source data.
  • Export Data to JOSM to create a layer in JOSM with just the buildings that could be imported.

Note: If you get an error message in this step refering to a 'malformed url', it means there's more data than the maximum string length that certain browsers allow to pass to JOSM. Zoom in closer and retry.

Copying buildings to the OSM layer

You should now have a layer with a random name in JOSM. It's where you'll be working in. And also a layer called "source layer" or "filtered-sourcelayer" containing the buildings from the source data.

Important: Never download OSM data to the source layer, because you will NOT be able to upload changes to OSM from here.

To move (some of) the buildings from the 'filtered-sourcelayer' to the 'working layer':

• Select the data to copy by doing one of the following:
  • Either you delete the parts you don't want from the 'filtered sourcelayer', then select all and then copy.
  • Or you select only what you want and copy.
    

Note: Only the first method will correctly copy the multipolygons (if any) from the source layer. But copying everything at once makes it harder to keep an overview of the buildings to review.

• Activate (click) the 'working layer' (the one with green checkmark).
• Paste by using Ctrl+Alt+V (with the 'Alt'-key in the combination, you paste at the exact source geo-coordinates).

Before you can Upload the data, you first have to make sure it's worth importing!

Make the data worth importing

Don't just dump buildings into OpenStreetMap, but let's make the best map of the world together.

Verifying the building type

The import tool tries to assign a decent building type. But this remains a guess. So, check the building types and improve it to map garage, garages, carport, shed, house, appartments etc.

Tip! - Use the 'paint styles' in JOSM to visualize different building types:

• Go to Settings > Map drawing styles (kaarttekenstijlen) and find the '+' icon on the top right.
• Choose a name and add https://raw.githubusercontent.com/gplv2/grb-mapcss/master/grb_buildings.css and/or https://framagit.org/Midgard/osm/raw/master/josm_style_grb.mapcss.

• Activate the map style under View > map drawing style.

With this style, the first letters of the building type are displayed over each building, making it easier to see what's what without manually selecting the building to read the tags. And the new buildings are colored distinctively, so you can see which buildings are enterily new or merged already (see below).

Cleaning up duplicate buildings — Merge

Where buildings were already mapped, merge the imported building into the existing one (this avoids deleting useful data, keeps the history intact, and respects previous mappers' work):

• Make sure you have the utilsplugin2 installed.
• Select the 'old' and 'new' geometry you want to merge (using Shift).
  

Tip! - You can select the corner nodes of overlapping buildings and hit Shift+E to select the two.

• Use shortcut 'Ctrl+Shift+G' to merge the tags. You'll get a message box in case of conflicts in which you need to select which conflicting tag values to preserve.

With this, you assigned the imported NEW geometry to the existing OLD building and preserved all existing tags.

Cleaning up special buildings — Fixme tags

For some objects, the import tool cannot determine the building type should be or it might be known upfront that a manual check is important. These situations are identified with a fixme=* tag. You need to handle these. The most convenient way to find the notes is to hit Ctrl+F and find 'fixme=*'.
Be careful for small objects that might escape your attention. Don't assume none are found, unless you explicitly get a message saying so. Some people find it convenient to copy these to a separate layer to spot them.
Tip! - If 'expert mode' is enabled in JOSM, a checkbox is available on the left to add a toolbar button for that search (for future edits).

Resolving 'fixme' related to 'levels' ('verdieping', in Dutch)

The fixme tags related to 'verdieping' usually concern building parts that are a raised part of the building, i.e. something where you can stand under. In contradiction with a 'roof', which can be considered separately from a building (e.g. house), 'verdieping' mostly concerns an integral part of the building.

Proceed as follows:

• Copy the building (gbg) and the building annex (gba) of type 'Verdieping' to the OSM edit layer.
• Select the two objects and use Alt+Shift+W to create a new object combining the two objects into one (install the JOSM plugin shrinkwrap).
• Change the building tag of both original objects into building:part=yes.
• Add the number of levels to both original objects with building:levels=*.
• Add the number of skipped levels to the building annex object building:min_level=*.
• Remove the fixme tag.
• Remove the address tags in the original building object and add them to the new combined object.
• Add a building=* tag.

Validating

To help you validate, please install the Building import issues rules:

• Go to Edit → Preferences... (F12) → ✓ Data validator → second tab "Tag checker rules" → '+' sign to add a ruleset → URL: https://framagit.org/Midgard/osm/raw/master/josm_validation_grb.validator.mapcss
• Trigger a validation by hitting the upload button but don't upload just yet! It'll validate just the data you touched.

You can expect the following issues to resolve:

• Warnings for duplicate housenumbers. Based on survey, keep the correct house numbers.
• Warnings for building overlaps. Very often this is about buildings with holes, where you need to rebuild the 'inner' and 'outer' relations, and set the tags to the building.
• Warnings about duplicate nodes. If you pasted a building adjacent to an existing one, sometimes you'll have duplicate nodes. Select the duplicate nodes and merge them with 'M'.
• Untagged single nodes. Often relics of incomplete building removal when cleaning up the 'filtered sourcelayers'.

Fix the errors and repeat the validation until resolved.

Now select nothing and hit "Validate" to validate all other data in the area you downloaded. This detects overlaps with existing buildings, crossings with landuse, or other errors you should also resolve.

Resolving common address issues

Keep an eye out for addressing errors. The official data is not perfect, and things can go wrong in the data transformation.

• Addresses might be missing because a building has addresses from two streets. Add these addresses as nodes.
• The address might not be properly linked. Often this will result in one house having two numbers, and the one next to it none. Perhaps you can see an address on the background map, but it's not linked to the building. Usually you can add those to the map as well.
• The government simply forgot to label the building with an address in their database.
• Another typical error is a whole row of houses sharing the same range of addresses. Usually, all these buildings should have just one housenumber.
• Look out for difference between the name=* of the highway=* and the addr:street=* of the building. The map paint style "Coloured Streets" helps visualise this. When there are differences, the imported data is usually correct, but seek advice nonetheless. Errors in the official data exist. Sometimes both names are worth keeping, for example when the street name on the sign (this should go in name=*) is different from the official name (this can be kept in official_name=*.

Understanding addresses and reporting errors

• In Flanders, have a look at CRAB data via Lara to fully understand the addresses. You can also load the CRAB data to JOSM with http://crab-import.osm.be/.
• In Wallonia, you can download raw ICAR data.

Please report errors back to the government. The next mapper might not spot the error in the official data and change your work! If you're not sure, discuss the case in the chat group.

In Flanders, you can report errors in addresses through Lara (free account needed, but better issue tracking) or with Geopunt (click on the ? on the map, then choose "Meld een probleem met de kaart").

In Wallonia, ICAR has agreed to recieve our issues at icar@spw.wallonie.be. However, please discuss any issues you see in the chat group. That way, we can make sure to only report true ICAR issues.

For missing or wrong buildings, see the Dealing with errors in the source data section below.

Uploading & reviewing

Alright! You've gotten this far... Make sure you have the 'working layer' active and upload that changeset!

Please do:

• Mention GRB/PICC/URBIS as source in the changeset comments. We chose not to add it to the object tags, but it should definitely be on the changeset.
• Copy a link to your first changesets and share it in the dedicated Matrix-channel for peer-review. Just so both YOU and the rest of the community have confidence we're doing this the RIGHT way.
• Ignore trying to upload the data from your 'filtered sourcelayers' you used in the process of editing when you close the application. You've used what you needed and uploaded that.

Dealing with errors in the source data

There are occasional errors in the source data. We like to be able to communicate them to the data source in a structured way. To help doing that, we recommend this tagging:

• when the official source has a building that does not exist anymore, import it with razed:building=* instead of building=*. Make sure source:geometry:ref=* and source:geometry:date=* are still on the object. That way, we can easily extract all the buildings we believe do not exist anymore. This also avoids people accidentaly adding the building later. In complicated cases (huge old geometry, confusing overlaps with current geometry etc), convert the building to a singe node (at the centroid) and put the tags there.
• when you can clearly see a new building that is not in the source yet (do check old imagery to confirm it's new and not razed!), add source:geometry:ref=missing to the building you draw by hand.
• if a building has a significantly different shape (totally rebuilt, wrong digitalization in the source) than what you can see on imagery, use source:geometry=outdated to indicate the source error. Do copy the source:geometry:ref=* and source:geometry:date=* to the OSM building, to prevent the tool from trying to replace the correct OSM building.

Note that the data in the import tool is not updated daily. So check the relevant official background map (available within JOSM!) to check if the building is truly wrong in the source data.

For missing or wrong addresses, see the Resolving common address issues section above.