Imagery Offset Database

From OpenStreetMap Wiki
Jump to navigation Jump to search

This article describes the Imagery Offset Database and its usage in JOSM and, possibly, other editors for OSM. The server API is described here.


Every armchair mapper should know that all remotely-sensed imagery (e.g. satellite images and aerial photos) and other sources, except GPS traces, are usually poorly aligned with respect to reality. As a result, the mapper should be able to align the imagery in their preferred editor using GPS traces. The process takes 5 to 10 minutes, and because of GPS accuracy, the results vary. It's not too bad if you're the only mapper for hundreds of kilometres in hundreds of years, but for co-operative mapping even a one-metre variance matters.

In JOSM, this problem was partly solved when imagery offsets were matched with exact numbers which could be shared. As a result, several ways of sharing offsets were developed:

  • editor bookmarks: tied to a single computer; one would have to redo all work at another place;
  • offset lists on regional wiki pages: nobody reads a wiki save for its contributors;
  • nodes note=Bing offset: -4;10: effective, but can be missed on downloading;
  • polygons with offset values attached: can be processed automatically, but too hard for mapping (in two years, only 28 were made).

The main disadvantage is that all these techniques don't apply to other editors; JOSM's offset calculation algorithm may be hard to implement in other data models.

Offset database

An analysis of the problem revealed two potential solutions, both equally effective. The offset database and the offset plugin implement both; they don't exclude, but complement each other, allowing the mapper to verify offsets not only with GPS traces, but using an alternative alignment method.

Every object in the OSM database has coordinates (in degrees in the WGS84 projection/EPSG:4326), a creation date, an author, and a description, which help to determine applicability and coverage of an offset.

Calibration geometries

Trace-based alignment is bad, mainly because traces almost never follow the centre of a road. The inherent poor accuracy of GPS receivers leads to major trace drifting, so it is quite hard to determine the correct imagery offset. As a result, different mappers often determine different offset values for the same imagery.

Calibration geometry is a point or line geometry that corresponds to a mappable real-world object of sufficient size and with sufficient edge contrast with the area surrounding it, so that it can be used to calibrate the alignment of the imagery over its general area. Of course, such a mappable object should be easily recognisable on remotely-sensed imagery. The object's geometry should be traced using a pre-aligned image of the highest-resolution possible. The geometry can then be used to align any imagery over the immediate area, even if the imagery was not captured until after the capture date of the image from which the calibration geometry was originally traced.

Imagery offsets

The classic way of storing an offset, allowing to align an imagery with a single button. The database contains coordinates of certain points, both on the map and on the imagery; the difference between which shows the offset value. Because on different zoom levels imagery sources sometimes show different imagery, zoom level brackets are also stored.

In other words, it's a centralized imagery offset bookmark storage, not tied to a single editor.

Deprecating offsets

Imagery is often updated, resulting in outdated offset values. Calibration geometries sometimes turn out to be traced using badly-aligned imagery, or the objects they represent disappear from imagery. Someone may have entered their bookmarked offsets and others proved them wrong. In all of such cases, the corresponding entries are marked obsolete and the reason is also stored. Offsets cannot be updated, one can only deprecate and recreate an offset. The absence of versioning allows for easier recovery of accidentally or maliciously removed offsets, and for checking the correctness of new entries.

Why not OSM data?

Why not store calibration geometries along with OSM data? You could use a special tag, calibration=yes for example, placing it on perfectly aligned objects. This was the way it worked at the beginning, before the author comprehended the size of the code dealing with downloading and uploading such objects, various checks for consistency, related actions and warnings. OpenStreetMap data, which can be modified by anyone at any time, cannot be relied upon. It's rare for nodes, especially in populated places, to remain in their first version. Calibration geometries should be perfectly aligned, but what if some mapper would want to align one "more precisely", moving it according to their imagery layer?

Storing imagery offset information in OSM is even more pointless. As described in the introduction, there was a lot of this before, but every case is tied to a single editor, rarely giving any additional information except an offset value, and easily lost in other data; slowly becoming obsolete.


The offset database and its fragments are published under the PDDL license, which is effectively CC0 for databases. That means, if an imagery provider would wish to correct their layer alignment using our collected offsets, no one could stop them. By submitting an offset or a geometry to the offset database, you agree that it would be distributed under the PDDL license.

To prevent "contaminating" of the database with OpenStreetMap's ODbL, the service distances itself as much as possible from OSM data. Every point of a calibration geometry is verified by a user uploading it, and there is no correlation with GPS traces for imagery offsets; aligning imagery is an artistic process and not a derivative work of trace geometry.

Using with OSM editors


See the plugin manual for JOSM, and the illustrated step-by-step quick start tutorial.


As of version 0.9.4, Vespucci supports reading and setting offsets from the database. Currently geometries are not supported.

Web interface