JOSM/Plugins/Imagery Offset Database

From OpenStreetMap Wiki
< JOSM‎ | Plugins
Jump to navigation Jump to search

To install the Imagery Offset Database plugin for JOSM, 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.

See also our illustrated step-by-step quick start tutorial.

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).