Contents

Recording known offsets

Where trusted information has been gathered reliably, it can be determined that an adjustment is required. This adjustment can be expressed in terms of degrees of offset in the northern and eastern directions. That is, a positive eastern offset indicates that the background imagery without adjustment would appear too far to the east. (Note JOSM displays offset numbers following the opposite rule. Positive eastern offset indicates the imagery without adjustment would appear too far to the west)

As there are many sources of background imagery, we must be able to state to which imagery source any given known offset applies. In addition, it frequently happens that different imagery (and therefore different offset requirements) applies to different zoom levels as displayed in the editor. It is proposed that the first implementation of the process should record known offsets in the OSM database itself as ways outlining areas of imagery deemed to have the same offset requirements. It is expected that imagery from a single batch will often require the same offset. These outline ways will be tagged in accordance with the scheme proposed below to record the details of the required offset.

It should be noted that the practice of using the OSM database to store outlines for imagery coverage has been criticised by many mappers. It may prove appropriate to find another home. However, as a proof of concept, recording the data in JOSM allows all mappers to use familiar tools and an available infrastructure to prove the approach. The process as proposed does not require OSM to remain the home for these data.

Tagging scheme

Key

Value

Element

Value

calibration

Area

This is the tag that identifies the purpose of this enclosing area and allows us to find it via XAPI. "point" or "node" may be used in the future if we wish to support control points.

data_provider

bing / yahoo / landsat / …

An identifier under which editors will identify the imagery family for which it seeks offset information.

area_name

Text

A free text, human-readable description of the area covered by this batch of imagery. Tagging this as "name" could lead to the name rendering, so we don't do that.

zoom_min

Integer number

The minimum zoom level (in OSM terminology) for which this offset is deemed valid. Often different imagery is used at low zoom levels and it may or may not be worth attempting to record its offset

zoom_max

Integer number

The maximum zoom level (in OSM terminology) for which this offset is deemed valid. Optional, and very possibly not useful in real life.

offset_north

Real number

Distance in degrees by which the unadjusted imagery must be corrected by moving it to the north. Negative if the imagery must be shifted to the south. Optional: if omitted, it will be assumed that the imagery is accurately positioned in this dimension. This has the same meaning as the Offset Northing in the JOSM Imagery module.

offset_east

Real number

Distance in degrees by which the unadjusted imagery must be corrected by moving it to the east. Negative if the imagery must be shifted to the west. Optional: if omitted, it will be assumed that the imagery is accurately positioned in this dimension. This has the same meaning as the Offset Easting in the JOSM Imagery module.

Examples

Web service

The implementation details of the web service will likely vary over time, but the expectation is that it would maintain a local PostGIS database of all defined offset areas. The web service will be essentially RESTful and will be called chiefly by editing software, which will issue a request similar to the following:

It is recommended that any tool supporting the service support configuration of the calling URL to a sufficient extent to support both the proposed and the current testing URL schemes.

The meaning of the data_provider is as above. The zoom level is the zoom level of the data provider image tiles the editor is preparing to display. Lat and long are the co-ordinates of the centre point of the current editor window. Imagery will be aligned with respect to this centre point. The version number is used to future-proof the interface. When version 1.0 is requested, data is returned as defined below. If incompatible changes to the web service interface are deemed necessary in the future, requests with a higher version number will be defined.

The web service response will look for a matching offset polygon and send a response in XML or possibly JSON format (details to be finalised) containing the following:

Case

Data returned

No matching offset data found

This means that we have no outline defined within which the requested centre point is located, or if we do, not one valid at the requested zoom level. In this case we return a mostly empty message indicating that no offset data can be found. A bounding box will also be received indicating an area within which it has been determined that no further offset information will be found. The requesting application should apply no offset, trusting the default position. The bounding box data should be cached for at least a day to avoid unnecessary lookups inside the indicated area.

One set of offset data found

This means that we have exactly one outline defined within which the requested centre point is located that is valid at the requested zoom level. In this case we return a response indicating the required north and east offsets (if present - missing values should be assumed accurate). A bounding box will also be returned, indicating the largest possible "horizontal" bounding box within which the returned offset remains valid. Zoom levels within which this offset can be trusted will also be returned. The requesting application should apply that offset, and should cache the data received for at least one day to avoid unnecessary lookups inside the area indicated in the bounding box received.

Several sets of offset data found

This is undesirable, as it can cause the cacheing described above to work unreliably. As such, it is preferable if offset areas not overlap in both area and zoom ranges. However, even where mappers take care, thin areas of overlap are likely to arise. Of the data sets found, that having the smallest bounding area should be selected and its offset data returned.

Challenges

Behaviour is poorly defined at interfaces between areas requiring different offsets (a challenge for editors)

Each editor will need to support this process in order to derive maximum benefit

Editor authors and mappers storing known offsets will need to use standardised values for data_provider

"Enclaves" of imagery inside other areas of imagery may require different offsets. Based on current thinking, the outer areas will need to be split, as no support for "holes" is currently proposed and overlapping areas will break the cacheing strategy.

Mappers who mapped their world with a 5m error may be surprised when imagery suddenly fails to match their data.

Need to decide whether the areas bounding imagery batches should be drawn where the imagery wishes to be placed or around the corrected positions. (not that big a deal, but we should recognise that this is not yet defined)

Need to consider how much load this will apply to the web service if, as hoped, editors all start to use the service.

Do we need cache-dirtying logic to let users see the fruits of their fresh calibration?

Unfortunately it's a fool's errand chasing a moving target. We have no control or real knowledge of the underlying data. It simply can't be done in a practical sense. See the Talk side of this page for why.