Custom imagery#

Supported layer types#

  • google/OSM type tile servers (raster tiles and to a limited extent Mapbox Vector Tiles)
  • imagery layers in MBTiles and PMtiles V3 format on device
  • WMS servers supporting images in EPSG:3857 (including alternative names like EPSG:900913 etc) and EPSG:4326 projections

Besides manually adding layers you can add WMS layers by querying a WMS server for a list of supported layers see layer control, or by querying the Open Aerial Map (OAM) service.

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#

To add a custom layer goto the Preferences screen and select Custom imagery, press the + button to add a new layer, or you can select the same from the layer control, "+" menu. 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. 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

Selecting the Save button will add the source to the configuration, Save and set will additionally add the source to the active layers as the current background for background imagery sources.

Remote PMTiles source#

To add a remote PMTiles source add the URL and then select Save. Vespucci will attempt to retrieve all necessary information for the entry from the remote source if the URL ends with .pmtiles.

Supported place holders#

Place holders 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 place holders have the general format of { place holder name }.

{apikey} api key for sources that require it. JOSM, iD, Vespucci (only in configuration files) see key configuration example for more information.

{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)

{wkid} projection for proprietary ESRI 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#

Note: remote PMTiles sources do not require any 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} place holders. Note: do not add a {proj} place holder 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}

PMTiles example:

https://r2-public.protomaps.com/protomaps-sample-datasets/overture-pois.pmtiles

MBTiles and PMTiles#

To add a MBTiles or PMTIles layer, down/upload the 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, jpg and mvt 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.