Imagery Offset Database

From OpenStreetMap Wiki
Jump to: navigation, search
Available languages — Imagery Offset Database
· Afrikaans · Alemannisch · aragonés · asturianu · azərbaycanca · Bahasa Indonesia · Bahasa Melayu · Bân-lâm-gú · Basa Jawa · Basa Sunda · Baso Minangkabau · bosanski · brezhoneg · català · čeština · corsu · dansk · Deutsch · eesti · English · español · Esperanto · estremeñu · euskara · français · Frysk · Gaeilge · Gàidhlig · galego · Hausa · hrvatski · Igbo · interlingua · Interlingue · isiXhosa · isiZulu · íslenska · italiano · Kiswahili · Kreyòl ayisyen · kréyòl gwadloupéyen · Kurdî · latviešu · Lëtzebuergesch · lietuvių · magyar · Malagasy · Malti · Nederlands · Nedersaksies · norsk bokmål · norsk nynorsk · occitan · Oromoo · oʻzbekcha/ўзбекча · Plattdüütsch · polski · português · română · shqip · slovenčina · slovenščina · Soomaaliga · suomi · svenska · Tiếng Việt · Türkçe · Vahcuengh · vèneto · Wolof · Yorùbá · Zazaki · српски / srpski · беларуская · български · қазақша · македонски · монгол · русский · тоҷикӣ · українська · Ελληνικά · Հայերեն · ქართული · नेपाली · मराठी · हिन्दी · भोजपुरी · অসমীয়া · বাংলা · ਪੰਜਾਬੀ · ગુજરાતી · ଓଡ଼ିଆ · தமிழ் · తెలుగు · ಕನ್ನಡ · മലയാളം · සිංහල · བོད་ཡིག · ไทย · မြန်မာဘာသာ · ລາວ · ភាសាខ្មែរ · ⵜⴰⵎⴰⵣⵉⵖⵜ · አማርኛ · 한국어 · 日本語 · 中文(简体)‎ · 吴语 · 粵語 · 中文(繁體)‎ · ייִדיש · עברית · اردو · العربية · پښتو · سنڌي · فارسی · ދިވެހިބަސް

This article describes Imagery Offset Database and its usage in JOSM and, possibly, other editors. 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 his 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 hundred 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 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), creation date, 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 in OSM database? 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 his 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 PDDL license: 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 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 traces geometry.

JOSM Plugin

Illustrated step-by-step tutorial

To install the plugin, open configuration dialog (F12), select a tab with a power plug, then find and enable "imagery_offset_db" plugin. Click "OK", then restart the editor.

It's reasonable to add the offset request button to the toolbar at the top: click a right mouse button on it, open configuration window, find in the right panel "Offset/Get offset" and add it to the left panel.

Searching for Offsets

To download an imagery offset, select the corresponding item in the "Offset" menu. In the following dialog window click a button that suits your area the most, judging by a date, distance and description. That's what elements of the window mean:


After choosing an imagery offset, it is applied immediately. A calibration geometry button would add a new layer with a contour. To align an imagery layer, find the corresponding object (it is usually described in the dialog window) and move the layer, so that the calibration geometry is positioned exactly above the object's border. Having done that, you may delete the calibration layer.

Storing an Offset

Make sure that no objects are selected, the correct imagery layer is showing, and its offset is ideal. Choose "Store imagery offset" item from the "Offset" menu. Then enter a description of an area to which this offset is applicable. This is not a description of a place where you've determined the offset, but a way for a person, who would map several kilometres away from the place, to understand if they can safely use your imagery offset. In a town you could name a suburb (for example, "Ülemiste", or "east of the river up to the railway"), in a countryside you could use rivers as a borders, or name villages. If an imagery layer displays different imagery depending on a zoom level, you could include a mention of a desired zoom level (for example, "for the imagery on the highest zoom level").

The only technical requirement for a description is that it should be 3 to 200 characters long.

When you have started to upload all your offset bookmarks to the database, please don't forget to check their relevance (the imagery is updated often) and don't be lazy, write meaningful descriptions. Remember that OSM is a social project, and offset descriptions, as well as changeset ones, help others and rid you of pointless arguments.

Storing a Geometry

First of all, find an object on an imagery layer that has contract borders and low height. A building is a bad candidate, a forest lake or a road intersection are acceptable. The bigger the object is, the better: some imagery is not as detailed as Bing. Try to locate the chosen object on Landsat, for example.

Align the working imagery layer as precisely as possible. Upload the offset if you haven't done this yet. A calibration geometry doesn't have to be an OSM object: in case of a road intersection it's better to draw a 3-noded polyline on it. The object should be easily identifiable, so a user with an imagery offset for hundreds of meters won't be puzzled with a choice.

Select the calibration object, and then the menu item "Store imagery offset". Now you should be presented with a choice between a geometry and an offset (where you are to click the first button). If you aren't, check that only one object is selected, and if it's an OSM object, that all its nodes are inside a downloaded area. In the next window describe the calibration object, and if there could be potential problems with it (e.g. a swamp lake can move), mention them (but better choose a more reliable object). The requirements for the descriptions are the same: 3 to 200 characters.

Advanced Preferences

Key Default Value Description
iodb.server.url Imagery offset server URL.
iodb.radius -1 Offset search area radius in kilometres. -1 means the default server value, 10 km.
iodb.calibration.message false Whether the message on calibration geometries has been shown.
iodb.offset.message false Whether the message on imagery offsets has been shown.
iodb.max.offsets 5 The limit on a number of entries in the offset dialog. true Whether to include calibration geometries in the offset dialog. false Whether to include deprecated entries in the offset dialog.
iodb.offset.radius 15 Imagery offset applicableness radius. A negative value disables the checking.
iodb.modify.toolbar true Whether to add a toolbar button for requesting offsets. Is changed to false after the first successful attempt.
iodb.remember.offsets true Whether to restore imagery offsets after restarting the editor.
iodb.stored.offsets [] Stored offset values for using after editor restart.


As of now, interaction with the database is done through the plugin, but in future this functionality is to be integrated into the editor, as it happened with WMSPlugin. How would it look?

Obviously, all functionality (that is, both buttons) would be put into an imagery offsets menu. User bookmarks would be moved into a submenu, and in the menu itself bookmarks would be updated from the server every time it's opened (or vice-versa). For this the menu item style have to be updated: for selecting a correct offset not only the description is important, but also the date and a distance from the user position.

The offset selection dialog would stay as is, because it allows to find distant offsets and get a detailed information on each of them. So, both actions, "Get" and "Store" would fit right after the "New offset" menu item.

Something like "I'm feeling lucky" button is also possible: if there is an non-deprecated imagery offset in 2-3 km radius with a suitable zoom, it could be applied automatically. But doing all the work without user sanction is undesirable, because a user would feel they're losing control over imagery layers (for example, when there are bad offsets in the database).


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

Web Interface