Using Custom Raster Layers

Prerequisites:
Basic knowledge of how to use the Soarvo web portal.
Basic knowledge of how to use the Soarvo mobile application.
An understanding of JSON.
An understanding of mapping tile sources (WMS, ZXY, TMS).

NOTE: At the time of writing (18/Jun/2025) this functionality is only available in the dev version of the Soarvo web portal and in Soarvo Mobile V2 0.0.47+ (which is only available in the open beta channel for the Play Store / TestFlight for iOS).

Currently, only web mercator (EPSG 3857) projections have been tested and are supported for custom background raster layers.

Preparing the .mapjson/.wms File Content

The Soarvo web portal allows you to use custom WMS and ZXY raster tile sources via uploading a file with the extension ‘.mapjson’ or ‘.wms’. These custom raster layers are then available for every location in a project. These custom raster layers are then available in the far left layers list under the ‘Maps’ folder once processed for a given Soarvo location.

The file itself can either end in .mapjson or .wms, it doesn’t use the extension to determine what tile source it is but rather the files contents.

The contents of the file must be valid JSON and follow the schema that is described in the table below. You can also view the examples below the table for what the file content should look like.

The format of the ‘url_template’ follows the format for the url in the UrlTemplateImageryProvider component provided by Cesium. You can read more about the format in the Cesium documentation.

ZXY Template

{
  "service_type": "ZXY_TEMPLATE",
  "url_template": "https://api.os.uk/maps/raster/v1/zxy/Road_3857/{z}/{x}/{y}.png?apikey=here"
}

ZXY Template (TMS)

{
  "service_type": "ZXY_TEMPLATE",
  "url_template": "https://api.os.uk/maps/raster/v1/zxy/Road_3857/{z}/{x}/{reverseY}.png?apikey=here"
}

ZXY Template with All Optional Attributes

{
  "service_type": "ZXY_TEMPLATE",
  "url_template": "https://example.com/{z}/{x}/{y}.png",
  "tile_width": 256,
  "tile_height": 256,
  "bounds": {
    "west": -180,
    "south": -90,
    "east": 180,
    "north": 90
  }
}

WMS Template

{
  "service_type": "WMS_TEMPLATE",
  "url_template": "https://services.ga.gov.au/gis/services/NM_Hydrology_and_Marine_Points/MapServer/WMSServer?tiled=true&transparent=true&format=image%2Fpng&exceptions=application%2Fvnd.ogc.se_xml&styles=&service=WMS&version=1.3.0&request=GetMap&layers=Bores&crs=EPSG%3A3857&bbox={westProjected}%2C{southProjected}%2C{eastProjected}%2C{northProjected}&width=256&height=256"
}

WMS Template with All Optional Attributes

{
  "service_type": "WMS_TEMPLATE",
  "url_template": "https://services.ga.gov.au/gis/services/NM_Hydrology_and_Marine_Points/MapServer/WMSServer?tiled=true&transparent=true&format=image%2Fpng&exceptions=application%2Fvnd.ogc.se_xml&styles=&service=WMS&version=1.3.0&request=GetMap&layers=Bores&crs=EPSG%3A3857&bbox={westProjected}%2C{southProjected}%2C{eastProjected}%2C{northProjected}&width=256&height=256",
  "tile_width": 256,
  "tile_height": 256,
  "bounds": {
    "west": -180,
    "south": -90,
    "east": 180,
    "north": 90
  }
}

Tips for Generating the .wms/.mapjson File Contents

for the ZXY custom raster layers the URL template is quite easy to create, and is usually provided by the provider of the tiles. The only thing to note is if the ZXY tile service is serving the tiles in OSGeo’s Tile Map Service (TMS) format you might need to change the template to use {reverseY} rather than just {y}. As typically ZXY layers take the Y origin as north, where as for TMS it is south.

For the WMS custom raster layers you can use a LLM (ChatGPT/Claude/Gemini) to construct the required JSON for you. If you give it the contents from ‘WMS Template’ in this article and a new WMS link, with the provided layers and styles, it does a good job of creating the JSON required.

It is also vital you check the JSON is valid using something like jsonformatter.

Uploading and Using the Layer on the Soarvo Portal

With the file prepared, you can then upload it in your opened location via the ‘Upload Files’ button. Wait a couple of minutes and then refresh the page. The new custom layer (if processed successfully) will be at the bottom of the ‘layers’ list in the ‘Maps’ folder.

Using the Layer on the Soarvo Mobile App

Once the layer has been uploaded via the portal – you can then also use it on the mobile app too. For the given location, if you ‘pull to refresh’ in the map manager the layers should appear in the list and be viewable on the map. The below video provides a walkthrough: