JOSM/Plugins/Imagery Offset Database/Quick Start

Since the Imagery Offset Database's manual has grown over 20 kilobytes, here is a simple tutorial for JOSM users who don't want to read long texts.

Plugin installation and downloading offsets

Let's start with installing the plugin. Press F12 (or a button with a cog), select the plugins tab, check the box for "imagery_offset_db" and apply the changed settings with "OK".

After that close the editor and start it again. Now it's time to download a map fragment and enable an imagery layer (usually Bing) by choosing it in the "Imagery" menu. But what's that on a toolbar?

A red exclamation mark on a offset downloading button means it's time to update imagery offset. It appears when an imagery layer has been added, or when you edit further than 15 km from the place you've checked the offset.

We'll be lazy and just click the button (see the guide to this window):

Luckily, there's an offset registered only a kilometer from here. Description fits too. Let's click the big button and see:

Buildings are aligned perfectly, and GPS traces (not on this screenshot) too. Time to map!

Imagery offset and how to upload it

For a start, a short introduction to imagery alignment in JOSM.

Download OSM data and traces, then temporarily hide the data layer: traces are almost always the best (and only) basis for imagery alignment.

Click the right mouse button on an imagery layer ("Bing Sat" in our case) and select "New offset".

A window with a couple of numbers would appear. Move it to the side and drag the map with left mouse button. GPS traces must follow roads as precisely as possible.

Now, not closing the window, enable the data layer. WTF?

Yes, someone has mapped the town using a misaligned imagery. Ideally you have to find a golden mean: for a maximum number of objects to align with an imagery, but without traces wandering from roads. Alas, such a trade-off could not be established in this town.

(in newer JOSM versions those items are in the "Imagery" menu)

To upload the determined offset to the server, select the Bing Sat layer and choose the "Store imagery offset" menu item. You'd be asked only the description of an area, to which the offset is applicable. Note that this is not a name of a point where the offset was determined, but an area. The town in this example is small, therefore imagery offset is the same everywhere in it:

"Novorzhev and its surroundings" — in Russian, because this is a russian town.

That's all! The exclamation mark disappeared the moment we moved the imagery layer. If we press the "get offset" button, we would find the expected result:

But wait, we forgot something. Buildings are still misaligned. We have to move them to correct positions, or else someone would "fix" our imagery offset using mapped buildings.

Calibration geometry

If an imagery layer is updated (which can happen with Bing), or new, more detailed imagery appears, it would have to be aligned from scratch. With wobbly GPS traces it is not a pleasant task: aligning is much easier with a sharp-bordered object in a visible place. This is what a calibration object is.

The intersection of two roads or a road and a canal are not the perfect candidates: those are better than a building, but worse than a forest lake with contrast bounds or a pitch. But here we have a winter imagery, and all nearby lakes are swamped.

Let us add a new layer and draw a polyline on centerlines of intersecting objects. Then select it and choose the same menu item: "Store imagery offset". There we would be asked, what are we going to upload, calibration object or an offset:

Click the first button, obviously. Then the description, this time — of an object itself (for identifying it on other imagery). "An intersection of a canal and German Street" it is:

That's it, we're done with this layer:

Now let's use the uploaded geometry. Add an IRS layer, far less detailed. Note the exclamation mark: you already know what it means.

Click the button, and here's the geometry. A dot on the map shows where the geometry is located. It is not important: after downloading the map would be centered on the geometry.

The contour appears in a new layer. It's right-click popup menu allows to change its colour.

Next steps are obvious: move the imagery layer so that geometry aligns perfectly with the corresponding features:

And remove the calibration layer.

Now we should check using GPS traces, how far does this imagery offset apply, and upload it to the server describing the results of this check.

Deprecating an offset

Well... What is this strange offset in my town?

Let's check — indeed, this doesn't look right:

Sometimes someone adds an intentionally wrong offset, or an imagery is updated, or a calibration object suddenly becomes redacted on all imagery sources. This means we have to hide corresponding entries from the database. Open a context menu of an obsolete offset:

And choose "Deprecate offset". After a brief warning enter a reason for deprecation.

"OK" — and done, the offset have disappeared from the list. But once you enable "Deprecated offsets" checkbox, here it is:

If you have encountered mass-vandalism, which is too hard to fix by hand, tell moderators about it with a web interface.