Web Map Layer GeoPackage
A web map layer GeoPackage carries web map layers (links to public tile services, with their credits and optional cut shapes) from one room to another, or from ArcGIS Pro into a room. It holds no imagery, so it stays small: the converted example below is about 100 KB.
It is an ordinary GeoPackage whose only extra table is comap_service_layers. Room exports include the
same table next to the room’s other data. A file that holds only this table is a complete import:
Import into Room adds its web map layers, with their cut shapes, and nothing else (see
Add a Layer).
The table
Section titled “The table”CREATE TABLE comap_service_layers ( layer_id TEXT PRIMARY KEY, name TEXT, kind TEXT, -- 'wmts' or 'xyz' template TEXT, attribution TEXT, definition TEXT NOT NULL -- the layer as JSON; the only column an import reads);The other columns are there for people browsing the file in a GeoPackage tool.
The definition
Section titled “The definition”definition holds the layer as the room stores it:
{ "id": "svc-6f1b2a3c-…", "name": "SWISSIMAGE_LEAF_ON", "kind": "wmts", "template": "https://wayback.maptiles.arcgis.com/arcgis/rest/services/World_Imagery/WMTS/1.0.0/GoogleMapsCompatible/MapServer/tile/13968/{z}/{y}/{x}", "tileSize": 256, "minZoom": 0, "maxZoom": 18, "bounds": [5.950367, 45.88915, 8.403069, 47.165493], "attribution": "Esri, Maxar, Earthstar Geographics, and the GIS User Community", "opacity": 1, "visible": true, "eventDate": 1711584000000, "createdAt": 1791871458688, "description": "Converted from DeadwoodPackage.ppkx (SHA-256 99651860…), project p30/WMS_Test.aprx, map Map, …", "provenance": { "capabilitiesUrl": "https://wayback.maptiles.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/WMTS/1.0.0/WMTSCapabilities.xml", "layer": "WB_2024_R03", "style": "default", "matrixSet": "GoogleMapsCompatible", "format": "image/jpeg", "title": "World Imagery (Wayback 2024-03-28)" }, "clip": { "rings": [[[7.0, 46.0], [7.0, 47.0], [8.0, 47.0], [8.0, 46.0], [7.0, 46.0]]] }}| Field | Meaning |
|---|---|
id |
The layer’s id, svc- followed by a UUID. Kept on import unless the room already has a layer with that id; then the layer gets a new one. |
name, description |
Plain text shown in the Layers tab. |
kind |
wmts (resolved from a capabilities document) or xyz. |
template |
The tile URL: https on a public host name, with exactly one {z}, one {x} and one {y} (or {-y} for rows counted from the south). At most 2,048 characters. |
tileSize, minZoom, maxZoom |
Tile size in pixels (256 or 512) and the zoom levels the service offers. |
bounds |
Optional [west, south, east, north] in degrees; no tiles are requested outside it. |
attribution |
The credit, plain text, required. It is shown on the map whenever the layer is visible. |
opacity, visible |
Display settings, 0–1 and true or false. |
eventDate |
Optional imagery date, in milliseconds since 1970. |
createdAt |
When the definition was written, in milliseconds since 1970. |
provenance |
Where a WMTS template came from: the capabilities URL, layer, style, tile grid, format and title. For reference only. |
clip |
Optional cut shape (below). |
The cut shape
Section titled “The cut shape”clip cuts the imagery to a shape as each tile is fetched:
ringsare closed rings (the first point repeated last) of[longitude, latitude]in degrees, within the Web Mercator latitudes (about ±85°).- They are filled with the even-odd rule: a point is inside when an odd number of rings surround it. A hole is simply another ring, in any order or orientation.
- At most 1,000 rings and 10,000 points in all.
- A shape that breaks these rules makes the import skip the whole layer, rather than show it uncut.
When bounds is missing, the shape’s own box is used.
Checks on import
Section titled “Checks on import”A GeoPackage is untrusted input, so every definition is checked with the same rules as the Add layer dialog. A definition that fails is skipped; unknown fields are dropped. At most 500 definitions are read, each up to 512 KiB and 8 MiB in all. Importing never requests a tile or the capabilities document.
Make one from an ArcGIS Pro package
Section titled “Make one from an ArcGIS Pro package”The converter python-geo-service/tools/web_map_package.py (in the app’s source code) reads an ArcGIS
Pro project package (.ppkx, or a bare .aprx) and writes a web map layer GeoPackage. It takes the
map’s WMTS layer and, when the map is clipped to a custom shape (Clip layers → to a shape in
ArcGIS Pro), that shape as the cut shape.
-
Make sure you have Python 3.10 or later and
bsdtar(libarchive; it reads the package’s 7-Zip container). Nothing else is needed. -
Run the converter with the package and a new output file:
Terminal window python3 python-geo-service/tools/web_map_package.py DeadwoodPackage.ppkx swissimage-leaf-on.gpkg \--name SWISSIMAGE_LEAF_ON \--attribution "Esri, Maxar, Earthstar Geographics, and the GIS User Community" -
Import the new file into the room from the Export / Import tab.
What it does:
- It reads the capabilities document once to resolve the tile URL, with the rules of the dialog’s
Web map tab: a Web Mercator tile grid (
GoogleMapsCompatiblewhen the service offers it), its zoom range, and the imagery date from the layer’s title. - The shape must be a polygon in a Web Mercator or WGS 84 map. Curves must be densified in ArcGIS Pro first. Coordinates are rounded to 6 decimals (about 10 cm).
- The description records the package’s SHA-256, the project, the map and the layer.
- It never overwrites a file, and only fetches public https capabilities URLs.
| Option | Use |
|---|---|
--name |
The layer’s name in the room (default: the ArcGIS layer’s name). |
--attribution |
The credit (default: the provider and the layer’s title). Check the provider’s terms. |
--matrix-set |
The tile grid, when you need another one than GoogleMapsCompatible. |
--map, --layer |
Which map and which WMTS layer, when the project has several. |
--capabilities FILE |
Read a saved capabilities document instead of the URL. |