True Offset Process
The True Offset process is intended to solve the following problems:
- Not all background imagery used for tracing is accurately aligned
- Many (most?) users are unaware that editors allow alignment of misaligned background imagery
- Users wishing to correctly align background imagery often lack sufficiently dependable information to use for realignment
- Because many different mappers trace using a mix of unadjusted and differently-adjusted background imagery, map quality suffers
- Even the same user will find it difficult to use a consistent alignment as it needs to be recreated manually by shifting the imagery layer into place at the start of each editing session
True Offset is intended to automate the human process of adjusting background imagery so that it is correctly positioned based on best available information. The process defines:
- How to record a known alignment error for an affected area of the map
- How editing software can query the True Offset web service in order to discover:
- whether an offset should be applied to displayed imagery at all? (is it wrong in the first place?)
- what degree of offset is appropriate?
- in addition to the zoom level currently being displayed, what zoom range may safely use the discovered offset?
- over what map area may the discovered offset safely be applied?
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
- Naas/Enfield/Kilcock, Ireland
86370040 Badly misaligned
- Dublin area, Ireland 86370151 Only slightly misaligned
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:
http://offset.openstreetmap.org/1.0/offset/bing/17/53.1234/-6.1234
http://offset.openstreetmap.org/<version>/offset/<data_provider>/<zoom>/<lat>/<long>
As currently deployed on the dev server, the service can be called as follows:
http://mackerski.dev.openstreetmap.org/offset/1.0/offset/bing/20/53.26/-6.67
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.
