WikiProject Belgium/Building and address import/AIV GRB building import/Instructions
If you want to start importing GRB and CRAB data, you should read this page carefully.
This is a work in progress, please don't translate this unless you can commit to keep the translation up to date.
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). Or contact community@osm.be if you prefer e-mail.
We require that you join the dedicated GRB channel ( #osmbe-grb:matrix.org / irc.oftc.net #osmbe-grb) and announce your first changesets there. We will provide you with a PDF presentation with summary instructions.
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. Ask about a meetup near you on Riot, talk-be or our meetup page
Technical 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
We do not recommend to do "pure GRB importing". If you are still planning to do that, you have to 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.
Note that we vastly prefer you to combine GRB work with real surveying and more data cleaning/conflation. If you do that, we do not think that you need a dedicated import account.
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.
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:
You can then load these layers as background into JOSM using the 'display' menu:
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 https://buildings.osm.be/#/ 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 (Ctrl+⇧ Shift+G).
- 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.
- After one day or two, have a look at the osmose validator (http://osmose.openstreetmap.fr/en/map/). Some errors, such as "split building" errors, may appear where you worked
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.
Other info
Some more documentation lives inside the tool. It is partly outdated and partly overlaps with what is on this page.