Custom imagery#

by Simon Poole, updated 2021-08-30

For Vespucci 10.1 we've added four long requested features: a simple UI to add custom imagery sources, support for WMS servers that support the same projection as conventional OpenStreetMap / google map tiles (EPSG:3857 and EPSG:900913, later Vespucci versions support EPSG:4326 for WMS servers too), support for layers from OAM and support for imagery layers in MBTiles format.

NOTE even though the URLs may look similar to those for a WMS layer, we do not support requesting data from ESRI MapServer with their native protocol.

Adding a custom imagery source#

custom imagery form

To add a custom layer goto the Preferences screen and select Custom imagery, press the + button to add a new layer. In the form you can set

  • a Name this is what is displayed in the Layer control background or overlay selection form. This field is required.
  • an URL the URL for the source with place holders in the same format as the JOSM imagery sources that Vespucci, JOSM and Go Map!! use as source for standard imagery. This field is required.
  • the Overlay flag, indicating that the layer is not a background, but partially transparent images for displaying over a background layer.
  • Coverage left, bottom, right and top coordinates of a coverage bounding box in WGS84 coordinates, if the values are empty it is assumed that the layer covers the whole visible web-mercator area, that is -180°, -85°, 180°, 85°.
  • Zoom Min and Max zoom levels, these indicates the minimum and maximum zoom levels available and are important for the app to determine over- and under-zoom correctly.
  • Tile size side length in pixels for the tiles, default 256. Available from version 16.0 and later

Supported placeholders#

Placeholders are replaced when the application retrieves imagery files from the source and are replaced by calculated values. There are some variants even between applications that in principle use the same system, which are noted for completeness sake below.

The placeholders have the general format of { placeholder name }.

{zoom} the zoom level

{x} the x tile number

{y} the y tile number

{-y} the y tile number for sources using TMS tile numbering. JOSM, iD, Vespucci

{ty} alternative for the y tile number for sources using TMS tile numbering. iD, Vespucci

{switch:a,b,c} rotating server selection (replace a,b,c by the actual sub-domains). JOSM, iD, Vespucci

{quadkey} used for Bing. Vespucci

{proj} projection for WMS servers. JOSM, Vespucci (only in configuration files)

{width} tile width for WMS servers. JOSM, Vespucci

{height} tile height for WMS servers. JOSM, Vespucci

{bbox} bounding box in proj coordinates for WMS servers. JOSM, Vespucci

{subdomain} reserved, used internally by Vespucci

Required placeholders#
  • A valid normal (non-Bing) URL for a tile server must contain at least at least {zoom}, {x} and one of {y}, {-y} or {ty}.
  • A valid WMS entry must be a legal WMS URL for a layer containing at least {width}, {height} and {bbox} placeholders. Note: do not add a {proj} placeholder when adding such a layer in the "Custom imagery" form in Vespucci (it is supported in the configuration files), simply leave the SRS or CRS attribute in the URL as is with the desired projection value.

Examples#

Tile server example:

http://tiles.poole.ch/AGIS/OF2011/{zoom}/{x}/{y}.png

WMS server example:

https://geodienste.sachsen.de/wms_geosn_dop-rgb/guest?FORMAT=image/jpeg&VERSION=1.1.1&SERVICE=WMS&REQUEST=GetMap&LAYERS=sn_dop_020&STYLES=&SRS=EPSG:3857&WIDTH={width}&HEIGHT={height}&BBOX={bbox}

OAM#

You can query the OAM catalog by going to Tools and selecting Add imagery from OAM, this will query the OAM servers for layers in the current view:

oam imagery form

Unluckily it doesn't seem to be customary to give the imagery meaningful names on OAM, but as the use case is likely mostly use of layers that you have created yourself, it is likely bearable. After you've selected an entry you will again be shown the custom imagery dialog. Note: we try to determine the maximum zoom level from the nominal resolution of imagery as stored in OAM, however we've seen a couple of wacky values for this (sub-milimeter) and you should check that the value is roughly correct before saving.

MBTiles#

To add a MBTiles layer, down/upload the MBTiles format file to your device, then go to the Custom imagery form as described above. Tap the SD card icon, navigate to the folder where you saved the file and select it. The form should now be filled out with all necessary values.

Notes:

  • Older MBTiles formats do not contain meta-data for min and max zoom levels, the query that determines the values from the actual file contents may take a long time to run if the file is large.
  • Vespucci currently supports png and jpg contents.
  • You can adjust all values in the form before saving if necessary with exception of the URL field that contains the path to the file.
  • You can create MBTiles files for example with MOBAC and many other tools, some more information can be found on the HOT toolbox site and the separate tutorial about the generation of custom MBTiles files.

MBTiles configuration

Happy mapping!