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

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


Tile server example:{zoom}/{x}/{y}.png

WMS server example:{width}&HEIGHT={height}&BBOX={bbox}


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.


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.


MBTiles configuration

Happy mapping!