Skip to content
EN

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

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.

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

clip cuts the imagery to a shape as each tile is fetched:

  • rings are 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.

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.

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.

  1. Make sure you have Python 3.10 or later and bsdtar (libarchive; it reads the package’s 7-Zip container). Nothing else is needed.

  2. 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"
  3. 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 (GoogleMapsCompatible when 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.