WikiProject Belgium/Building and address import/AIV GRB building import/Instructions for mappers

If you want to start importing GRB and CRAB data, YOU MUST READ THIS WHOLE PAGE very carefully and follow its instructions. If you fail to do so, you might miss important instructions resulting in your access to the tool to be revoked, or worse.

 To do: translate this whole thing to Dutch if the import is approved

Introduction

Welcome to the GRB and CRAB import instructions. Please understand that importing is a complex job that is subject to higher standards than the rest of OSM. You should only consider joining any import effort if you have a decent amount of experience as a mapper in general, and with JOSM in particular.

This import is not rushed. There's no deadline. We're never going to do quantity-based rankings of importers. Please focus on data quality rather than speed. We're not merely copying the GRB in OSM, we're building upon it to create data that is actually better than the GRB.

It's advisable to start in a nearby area so you might be able to go for a survey if need be.

If you have any problem understanding this guide, do not be afraid to ask for help. The Belgian Matrix room #osmbe:matrix.org and IRC channel irc.oftc.net #osmbe are bridged, so you can ask for help on either one. Alternatively you can send a private message to M!dgard (on osm) or Glenn (Glenn Plas on osm).

We're also organizing meetups in real life to get familiar with this import! You are warmly invited to participate in at least one of them. We can give you tips and instant feedback.  To do: how to know when there's a meetup

Requirements

You will need:

• JOSM and experience with it
• the SimplifyArea plug-in for JOSM
• the utilsplugin2 plug-in for JOSM

 To do: method to subscribe to updates about the instructions

Account

 To do: do we need a separate account?

To get started, you have create a dedicated account for the import. A good choice is to take your existing user name and append _GRB to it.

You will need a second e-mail address because the OSM site requires addresses to be unique. On some email providers, like Gmail, you can create aliases by just appending +something to the user name part of your address, e.g. jozefdeveuster+grbimport@gmail.com. You don't need to configure this, it just works.

Set up JOSM

The tool prepares an export of data from the preparation database into JOSM. For user convenience, it's set up so that it can load directly into JOSM, without have to load data files manually in any type of format. However, it is required that you enable 'remote control' within JOSM for this functionality to work.

Where to find the option to enable 'remote control' access

Once that part is set up, there's still the option to get some extra help: using aerial imagery. The use of aerial imagery both gives you a bit of 'feel' for the data you're working with, but having different versions (most recent and slightly older) to detect differences. These are however available through WMS-services.For convenience, note that the links are available within JOSM:

WMS-settings

You can then load these layers as background into JOSM using the 'display' menu:

Overview of the 'display' menu where the WMS background layers can be added to project

At times, there will be differences between aerial imagery and JOSM.

A few cases may occur:

- A building that's there on aerial imagery and not in GRB is most likely a very recent building that has not been adding to GRB.

- A building that's there on GRB but not on the most recent aerial imagery, has probably been torn down. You can use the older version of aerial imagery to confirm this theory.

- A building may appear significantly different between GRB and aerial imagery. In this case (though it should be rare due to both datasets being kept relatively accurate), a building may have been torn down and rebuilt, or had an extension built, ... Also in this particular case, the nature of the change can be verified/validated though comparison with older imagery.

Export data from GRB

• Open JOSM.
• Go to the GRB import tool at http://grbtiles.byteless.net/ and log in using your OpenStreetMap account.
• Zoom in on the area you want to work on.
• Retrieve the GRB buildings that already exist in OSM (currently a button).
• Filter layers to take a cross-section (currently a button, will be automated).
• Open the area in JOSM (button) and load the GRB buildings JOSM (currently yet another button that will disappear in the future).

 To do: talk about desired changeset size (and hence export size)

Conflate data

In the end, you are responsible for the data you add.

 To do: add good/bad screenshots

For each object you are importing

• If the object is already drawn:
  • If you want to use the GRB version, use the Replace Geometry tool.
  • If you want to completely keep the OSM version, just copy the tags from the GRB exported object and delete the latter.
  • If you want to keep some parts of the OSM object and some of GRB's, you can do so like this:  To do: create screenshots and screencast.
• Check the tags. Determine the building type, do not rely on the default:
  • Use street-level imagery if available.
  • Use aerial imagery.
  • Use your common sense: be aware of the environment and any POI that's mapped in or on the building.
• Make sure the object is properly connected to existing objects where applicable, in particular other buildings.  To do: what to do with landuse if building is adjacent to it? Merge to building or keep separate?
• Use the Simplify Area operation (Ctrl+⇧ Shift+Y) if the building appears to have too many nodes.
•  To do: add instructions for building=verdieping, the tool will probably export this tag as-is and it requires manual fixes: in some cases it is best to merge it with the main building and drawing a road with tunnel=building_passage underneath, in other cases one should use building:min_level=*, but it might not be always building:min_level=1 so a survey should be done, street-level imagery should be consulted, or a fixme=* should be added
•  To do: add other instructions?
• If you encounter strange tags, like for example building=gebouw omlijnd met virtuele gevels or building=tuinhuis, contact us. These should not be there.

 To do: let the tool analyze building types to check for anomalies?

Watch out

• Conflating means merging with existing data. You might be tempted to just remove existing objects and drop the GRB ones in OSM, but don't ever do that! Delete as little existing OSM objects as possible.
• You might be tempted to remove buildings that aren't in the GRB. Only do this when you are sure the building really does not exist. It may be not included in the GRB because it's a new building, or a small shed for which no building permit was needed. Use different sources to determine what to do: old aerial imagery of different years is very useful to see the history of the place. Of course doing a survey would be perfect. If you're not sure, leave the building in OSM and add a note.
• The GRB is not perfect. Moreover, the ground truth always prevails.
  • Some buildings in the GRB have separate addresses but are just one GRB building. In OSM those may be mapped separately if the addresses are clear. Both buildings should get the same GRB source tags.
  • The inverse is also possible: some buildings and bridges are mapped separately in the GRB but may make more sense in OSM as one building. Merge those using ⇧ Shift+J. For the GRB source values, you can merge the values of both objects (select "all" in the tag merge conflict dialog).  To do: screenshot
  • Only parts of buildings that are visible from the public roads are measured by surveyors in the GRB, the rest is drawn from aerial imagery. If building parts that are not adjacent to the road look more correct in OSM than in the GRB, keep the OSM version for that part of the building (tutorial linked above).
• Keep the source:geometry:*=* tags that the tool exports. They let the tool detect that the building was imported and also allow for updating the building in the future. If you didn't use GRB's geometry, you can remove the source=GRB tag.  To do: is the tool going to continue adding this tag?

Workflow tips

 To do: make sure to explain every action's effect on history

Checking if an object already exists in OSM

To preserve as much history as possible, it is useful to be able to find out whether an object already exists in OSM or it is new. To do this, you can press Ctrl+I and look at the number on the first line. If it's a positive number the object already exists, and you shouldn't just delete it without good reason. If it's negative (having a minus sign) it only already exists in your editor and it's no problem to delete it.

Alternatively, you can request an object's history with Ctrl+H. If the object exists, you will see an overview of its history. If it doesn't, you will get a popup saying you should select an already uploaded object to view history. If the object exists, loading the history might take a while, that's why we recommend the Ctrl+I approach, but you might find the Ctrl+H method a bit clearer. Both methods always produce the same answer, so you can choose.

When you upload your changes, all objects with a negative ID will be added to OSM, and thus get a positive ID.

Tagged nodes on an existing building

Replace Geometry will not work if there are tagged nodes on the building. Fixing this while at the same time retaining the history of all objects is desirable and not difficult. Simply snap the nodes onto the new building, and Replace Geometry will work.  To do: screenshots+screencast

Merging and splitting buildings

You can split areas by drawing a split way and pressing Alt+X. The larger one of the parts inherits the history.  To do: screenshots+screencast

You can merge two connected areas with ⇧ Shift+J. If there are conflicting tags, you will get a popup to consolidate the tags. For the source:geometry:*=* tags, you can choose 'all'. Merging areas is equivalent to consolidating the tags, and then adjusting the geometry of one area and deleting the other. So if both objects already exist in OSM, you are effectively deleting one.  To do: screenshots+screencast

After you're done with the objects

• Run JOSM's validator on the data and resolve issues with your data.
• Upload the data.

Complete addresses with CRAB

Address data in the GRB is copied semi-manually from the CRAB, so it's not always correct or up-to-date. Therefore, check the imported buildings with the CRAB. If you're not sure, go survey or leave a note.

• After uploading the GRB buildings, wait a minute or two. (This is to make sure the Overpass data is updated and contains your new buildings.)
• Go to the CRAB import tool at http://crab-import.osm.be/.
•  To do: write instructions on how to check addresses with CRAB data

You can now start working on a new area.