New Orleans, Louisiana/Building Outlines Import/Contributor Guide

From OpenStreetMap Wiki
Jump to navigation Jump to search

So you want to help out with the New Orleans building import? Great! We could use the help. Here's how.


This is a work in progress, feel free to add to it or give feedback!

Thank you for your interest in helping with the New Orleans building import! Here is a guide for how to contribute.

The How to start section contains steps that only need to be completed one time at the beginning. This data import process requires a bit more software setup than nomal OSM editing, but we'll try to make it fast and painless. Here are the steps.

 Youtube-24x24.png The NYC buildings folks made nice video demonstrations and their process is very similar to ours. These will be good supplementary reference materials.

 Throughout this guide, links to the corresponding videos will be given in these boxes (or by clicking the red play button). The whole series of short videos is available from this youtube playlist.

How to start

First there are a few things we need to do one time, before starting to import data.

Create import username

 Youtube-24x24.png You can watch/listen to a demo of this step from the NYC buildings folks: click here for youtube video.

According to OSM's Import guidelines, bulk data imports like this should be done from special usernames. This is important so that the OSM community can easily identify what data is coming from imports and what is created by normal users.

  1. Go to the sign up page:
  2. Please create a new username for the data import, not your normal account. We're using the format <username>_nolaimport where username is your normal OSM username.
  3. The password does not need to be super secure. You probably should not use one that you also use for important things.
  4. A confirmation email will be sent, and you'll need to click on the link it sends to confirm the new account.

(If you don't have a normal OSM username, that's fine, but go ahead and create a user that ends in _nolaimport for the building import)

Note: if you already have an OSM account registered with one email address, it will not allow you to register a second account on the same email address. If you have another email account, you could use that. Or, many email services (including gmail) allow you to append any text to your username after a plus sign (+) and it will still go to your account. For example, you could use for a second account.

Install JOSM

  • Go to the JOSM website at
  • Windows users: you will want the Windows installer (look for the first of three grey boxes)
  • Mac users: you will want the Mac OS package (link is found right below the windows installer)
  • Linux users: download josm-testing.jar and run from the terminal with: java -Xmx1024m -jar josm-testing.jar
  • You may be able to install the josm package from the Debian or Ubuntu package manager, but it will likely be an out of date version. JOSM maintains an up-to-date repository though, see notes on the download page.

Java dependency

Java runtime version 7 is required to run JOSM. If you are able to run JOSM after downloading, then you're fine and can ignore this section. If not, see notes below.

Mac OS shipped with Java 6 through version 10.6 (Snow Leopard). That will not work for JOSM unfortunately. You will need to download Java 7 manually.

Java 7 requires an Intel-based Mac running Mac OS X version 10.7.3 or above. See Oracle's Mac java installation instructions.

If you're really stuck on Java 6 (for example, if you have an older Mac), you can run an older version of josm. See details on the System Requirements page.

Add import username credentials to JOSM

  1. Edit -> Preferences JosmPreferences1.png
  2. click the globe for connection settings: JOSM settings connection.png
  3. Add the OSM username/password you just created.
  4. Click OK at the bottom of the preferences window.

Set up JOSM remote control

 Youtube-24x24.png You can watch/listen to a demo of this step from the NYC buildings folks: click here for youtube video.

(Note on the video: the utils2 plugin isn't strictly needed for us, but it won't hurt either. The notes plugin may also be useful.)

  1. From the top menubar choose Edit -> Preferences
  2. click remote control icon on left which looks like this: JOSM Remote Control Button.png
  3. check Enable remote control
  4. check Download objects to a new layer
  5. click OK

Now JOSM is set up properly (when you click on links in the task manager, the data will automatically open in JOSM). You will need to restart JOSM for this to take effect.

How to import a precinct

Now that those preparations are complete, we're ready to start working with the building and address data.

The OSM Tasking Manager is our central tool for coordinating this buildings import project.

Take a task

In order to make sure two people don't work on the same precinct at the same time, when you "take" a task the task tracker will mark it as "currently worked on" and not give it to anybody else. Here's how:

 Youtube-24x24.png You can watch/listen to a demo of this step from the NYC buildings folks: click here for youtube video.

City divided into precincts in OSM task manager
  1. Start with the task manager here: (Note: you should log in with your username_nolaimport account)
  2. Now you should be able to browse the map of the city and see what areas are complete and what areas need work. You "take" a task by clicking on a precinct on the map.
    • Grey areas are still available to be imported. Click on one of these grey areas to start importing for that precinct.
    • Green areas have been uploaded *and* verified (checked by a second set of eyes)
    • Red areas have been uploaded but not yet verified
    • If you don't care what precinct you will work on, you can click on "Task" and then "Take a task" -- this will randomly choose one for you.

Now you have taken a task. If you don't actually want to do it right now, you can click "Unlock it!" at the bottom of the page. The lock on that task will automatically expire in 2 hours.

Where should I start?

For folks just starting out, please don't take one of the more complicated areas as your very first attempt. This means places with a lot of existing stuff on the map: like the French Quarter, Magazine Street, Oak Street, various University campuses and hospitals -- these will all require a bit more work to merge existing data with the imported data.

Easier tasks suitable for less experienced mappers would be less-dense residential areas where there is little to merge. For example, many parts of the Westbank, Lakeview, Gentilly, NO East that aren't in busy sections would be good candidates.

Open in JOSM

With JOSM's remote control enabled, you can simply click on the buttons in the task tracker to load the data into JOSM for review and upload.

Before proceeding farther, make sure JOSM is running (with remote control enabled, as described above)

  1. Now you should see a box with two blue buttons. Click JOSM. This will load the pre-existing data from OSM into JOSM.
  2. Then click the second button labelled .osm. This loads the new to-be-imported data into JOSM (as another layer).

Now you should see the buildings for your precinct task, as well as the streets and other OSM data that it'll be merged into.

Review data

A side note: JOSM can be a bit daunting to use at first. This is OSM's advanced offline editor, which is quite powerful and allows us to integrate nicely with the task manager and import data. So it is the best fit for this import process. But for many other situations we'd likely prefer OSM's more friendly online editors like iD.

Now we will use JOSM to review and make any changes or merges to the data before uploading to OSM's database. Until the upload step, no changes are made to the public map, so you can still bail out if you have problems.

If you haven't used JOSM before, there is a nice guide on this wiki that may be helpful. For our purposes JOSM/Basic_editing will contain most of what's needed to get up to speed. And there's another guide here from the folks at (Of couse you can also just learn by trying, we're here to help)

 Youtube-24x24.png You can watch/listen to a demo of this step from the NYC buildings folks: click here for youtube video.

Note: the NYC buildings import tends to have different issues since they have many adjoining high-density buildings.

Address nodes may be slightly offset from building footprints, but should be ordered properly. Small adjustments like these can be made by local importers during our workflow.

Review steps: (as we get more experience in this process, we should add more tips/suggestions to this list)

  • General sanity check: does the data look reasonable compared to aerial photos? (Mapbox at zoom levels 12–17 appears to be the most up-to-date.)
  • For the region, compare with the current data in OSM:
    • Are there existing building outlines? If so, we must decide if we want to replace the existing one with the import or keep the existing building. Usually comparing geometries shows that one or the other is of superior quality, when compared with aerial photography.
      • If we keep the existing building, we can transfer the addr:housenumber and addr:street tags from the import building (if they exist) and then remove the duplicate entry from the import data. (to transfer tags, use: Edit->Copy, Edit->Paste tags)
      • If there are addresses in the import data in point form, they should stay in the data for upload as long as they're adding useful information to the map.
      • If we replace the existing building, check it for any useful tags (either addressing, name, or other indication of function) which can be transferred to the new building outline. (Might also use Paste tags in this case, if needed.)
    • Are there POIs (points of interest) that should be merged with our building outlines?
      • If a small building contains, for example, a restaurant and nothing else, then it could be appropriate to transfer the restaurant POI tags to the building.
      • However a larger building with multiple tenants should keep POIs as separate nodes which indicate which part of the building they occupy.
  • Is the addressing correct?
    • Make sure an address is attached to the "main" building and not a shed or outbuilding.
    • If there are two (or more) address points within a building (duplex/multiplex), are they placed in a reasonable location within the building footprint? (see 2910/2908 St Ann Street in the example to the right)

Validator JOSM tool

JOSM has something called a Validator that attempts to automatically find common errors and alert us to fixes before we finish.

  • Run JOSM validator and review any errors/warnings it presents. (Typically these only come up in very dense areas like the French Quarter)
    • May find these warnings: Crossing buildings; Self-intersecting ways; Building inside building
  • If you have serious doubts about the data's accuracy or suspect a technical glitch, contact the rest of the import team for assistance or a second opinion.
  • For additional quality assurance, the FixAddresses plugin may come in handy.

Upload data

 Youtube-24x24.png You can watch/listen to a demo of this step from the NYC buildings folks: click here for youtube video.

Click the upload button which looks like this: JOSM-Icon Daten upload.jpg. It should be the fourth from the left on the top button toolbar.

You'll be faced with a dialog listing the modified objects (likely a lot, in the case of our import). It will also ask you for a brief comment and source. We're going to follow a consistent format for these two fields throughout the import, which is important as it allows us to track our work within this rather large chunk of data. It also clearly documents our work so that others in the OSM community to understand how this data got here. See below:

Changeset settings:

  • Comment: should follow the form New Orleans building import, Ward X Precinct Y ( where X is the ward and Y is the precinct.
    • How do you know what ward/precinct this is? Here are a few ways:
      • You should be able to see these numbers in the Layers pane, upper right corner of JOSM.
      • You can also find it in the tasking manager by putting your pointer over the .osm button, and look on the bottom of your browser for the link.
    • In either of the above cases, the name should be of the form: buildings-addresses-X-Y.osm
      • (note that in some cases, the precinct may contain both letters and numbers. Wards will always be between 1 and 17.)
  • Source:

Mark complete in task manager

Back in your web browser, there is a third box with a field for comment. This is a good place to put qualitative thoughts on how the data seemed to you, which parts you are more or less confident of, or any other notes you think the next person looking over this section should see first.

Then click Mark task as done. Now the area will show as done on the task tracker (colored in red). Congratulations!

How to validate completed precincts

After precincts are marked as done on the task manager, a second mapper will check it over to see if everything looks right. The task manager calls this the validation step.

This step will come later in our process, so this documentation is incomplete for now. Updates are welcome.

View on OSM

View in JOSM

Using geofabrik QA tool

Mark as validated in task manager

How to get help

More info