Services de tuilage supportés

Author:Thomas Bonfort
Contact:tbonfort at terriscope.fr
Author:Stephen Woodbridge

MapCache has the ability to serve tiles using a variety of different request protocols and tile-naming conventions. This document describes these. The various services must be turned on in the mapcache.xml file for MapCache to respond to these specific requests.

All services are available on the demo interface, from which you are highly encouraged to copy/paste the JavaScript code to get started when creating your own pages accessing the MapCache tiles.

The following notation is used on this page and refers to object names in the mapcache.xml configuration file.

  • <tileset_name> - nom d’un jeu de tuiles configuré

  • <grid_name> - nom de la grille définie explicitement ou implicitement

  • <quadkey> - specific to the Virtual Earth tile service
  • <z> - zoom level in zxy naming scheme
  • <y> - numéro de ligne dans le schéma de nommage zxy

  • <x> - numéro de colonne dans le schéma de nommage zxy

TMS Service

Le service TMS service utilise un schéma de tuilage de type z/x/y où:

  • z est le niveau de zoom

  • x est le numéro de colonne

  • y est le numéro de ligne

Pour activer le service TMS, ajoutez ces lignes au fichier de configuration mapcache.xml:

<service type="tms" enabled="true"/>

Un document de “capabilities” peut être récupéré via:

http://myhost.com/mapcache/tms/1.0.0/

Les tuiles sont demandées en utilisant le schéma:

http://myhost.com/mapcache/tms/1.0.0/<tileset_name>@<grid_name>/<z>/<x>/<y>.png

For EPSG:3857, EPSG:900913, or GoogleMapsCompatible grids, with cell = [z/x/y]:

z0:

[0/0/0]

z1:

[1/0/0][1/1/0]
[1/0/1][1/1/1]

z2:

[2/0/0][2/1/0][2/2/0][2/3/0]
[2/0/1][2/1/1][2/2/1][2/3/1]
[2/0/2]...
[2/0/3]...

etc...

For EPSG:4326 or WGS84 grids:

Note

The OGC WMTS specification rather absurdly requires the GoogleCRS84Quad WellKnownScaleset to have a level 0 whose extent is -180,-180,180,180. The default “WGS84” MapCache grid honors this, which may cause some incompatibilities with software that expects level 0 to be 2x1 tiles with extent -180,-90,180,90

z0:

[0/0/0]

z1:

[1/0/0][1/1/0]

z2:

[2/0/0][2/1/0][2/2/0][2/3/0]
[2/0/1][2/1/1][2/2/1][2/3/1]

etc.

Service KML

The KML service produces Super-Overlays for tilesets that are aligned to the WGS84 / EPSG:4326 grids. A Super-Overlay is a KML file that links to an image URL, and to a set of other KML URLs corresponding to neighboring resolutions. The KML service uses a z/x/y tile naming scheme where:

  • z est le niveau de zoom

  • x est le numéro de colonne

  • y est le numéro de ligne

Note

Pour que le service KML soit opérationnel, le service TMS doit aussi être activé car le KML Super-Overlay fait un lien vers les images en utilisant cette spécification.

Pour activer le service KML, ajoutez ces lignes au fichier de configuration mapcache.xml:

<service type="tms" enabled="true"/>
<service type="kml" enabled="true"/>

Les tuiles sont demandées en utilisant le schéma:

http://myhost.com/mapcache/kml/<tileset_name>@<grid_name>/<z>/<x>/<y>.kml

Service WMTS OGC

Pour activer le service WMTS, ajoutez ces lignes au fichier de configuration mapcache.xml:

<service type="wmts" enabled="true"/>

This service follows the standard OGC WMTS requests and supports both the classical OGC-style key-value-pair encoded and REST-style requests.

http://myhost.com/mapcache/wmts?SERVICE=WMTS&VERSION=1.0.0&...
http://myhost.com/mapcache/wmts/1.0.0/....

Les “capabilities” sont obtenues via:

http://myhost.com/mapcache/wmts?service=wmts&request=getcapabilities&version=1.0.0
http://myhost.com/mapcache/wmts/1.0.0/WMTSCapabilities.xml

Service WMS OGC

MapCache répond aux requêtes WMS version 1.1.1, et a un support limité pour celles en version 1.3.0.

<service type="wms" enabled="true"/>

Note

Notez que le service WMS est un petit peu différent des autres services MapCache, car il écoute à la racine de l’instance configurée plutôt que sur un emplacement dédié (en fait le service répond sur http://server/mapcache/? et non sur http://server/mapcache/wms?). Ce comportement est rendu nécessaire pour permettre la proxyfication des requêtes non prises en charge tout en offrant un point d’entrée unique à tous les services OGC.

Note

MapCache primarily supports version 1.1.1 WMS requests, but has limited support for the newer version 1.3.0 ones. For 1.3.0 requests, MapCache will determine which grid to use by using the CRS= parameter instead of the SRS= one, and will correctly honor axis ordering for the EPSG reference systems that switch the usual x/y ordering of the BBOX parameter.

WMS requests follow the classical key-value-pair encoded style:

http://myhost.com/mapcache?SERVICE=WMS&VERSION=1.1.1&REQUEST=....

Le document de “capabilities” est retourné par:

http://myhost.com/mapcache?service=wms&request=getcapabilities

Optional WMS Configuration Options

Untiled GetMap Support

Support for untiled (non WMS-C) GetMap requests can be enabled or disabled:

<service type="wms" enabled="true">
   <!-- full_wms
        Configure response to WMS requests that are not aligned to a tileset's grids.
        Responding to requests that are not in the SRS of a configured grid is not supported, but
        this should never happen as only the supported SRSs are publicized in the capabilities
        document.

        Allowed values are:
          - error: return a 404 error (default)
          - assemble: build the full image by assembling the tiles from the cache
          - forward: forward the request to the configured source.
   -->
   <full_wms>assemble</full_wms>
</service>

GetMap Image Format

You may explicitly set which image format should be returned to the client for an untiled WMS request (i.e. whenever the tile data cannot be served directly from the caches but needs to go through a decompression/recompression phase).

<service type="wms" enabled="true">
  <format allow_client_override="true/false">myjpegformat</format>
</service>

If the allow_client_override attribute is set to true, then MapCache will honor the FORMAT=... parameter sent by the client. By default MapCache ignores this parameter and uses its configured image format.

Image Resampling Quality

<service type="wms" enabled="true">
   <!-- resample mode
   Filter applied when resampling tiles for full WMS requests.
   Can be either:
   - nearest : fastest, poor quality
   - bilinear: slower, higher qulity
   -->
   <resample_mode>bilinear</resample_mode>
</service>

Service XYZ GoogleMaps

<service type="gmaps" enabled="true"/>

Prerequisites: Your WMS should be capable of producing images in the EPSG:900913 or EPSG:3857 SRS, i.e. it should reference the “g” or “GoogleMapsCompatible” grid.

This is the minimal HTML page that should get you going. The important bits are in the urlTemplate (for V2) and getTileURL (for V3) variables:

  • /mapcache is the Apache path where MapCache handles requests.
  • test@g is the tileset and grid name to use, joined by a ‘@’ - the {Z}/{X}/{Y} should be left alone.
  • The final extension should be changed to “jpg” if you are using a JPEG format with your tileset.

API V2

<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google/MapServer Tile Example</title>
<script src="http://maps.google.com/maps?file=api&v=2&key=ABQIAAAAnfs7bKE82qgb3Zc2YyS-oBT2yXp_ZAY8_ufC3CFXhHIE1NvwkxSySz_REpPq-4WZA27OwgbtyR3VcA"
        type="text/javascript"></script>
<script type="text/javascript">

function load() {
  if (GBrowserIsCompatible()) {
    var urlTemplate = '/mapcache/gmaps/test@g/{Z}/{X}/{Y}.png';
    var myLayer = new GTileLayer(null,0,18,{
                                 tileUrlTemplate:urlTemplate,
                                 isPng:true,
                                 opacity:0.8 });
    var map = new GMap2(document.getElementById("map"));
    map.addControl(new GLargeMapControl());
    map.addControl(new GMapTypeControl());
    map.setCenter(new GLatLng(0, 0), 1);
    map.addOverlay(new GTileLayerOverlay(myLayer));
  }
}

</script>
</head>
<body onload="load()" onunload="GUnload()">
  <div id="map" style="width: 500px; height: 500px"></div>
</body>
</html>

API V3

The previous JavaScript for the V2 example should be slightly changed to:

var map = new google.maps.Map("<element-id>", { /*options*/ });
var layerOptions = {
  getTileUrl: function(coord, zoom) {
    return "/mapcache/gmaps/test@g/" + zoom + "/" + coord.x + "/" + coord.y + ".png";
  },
  tileSize: new google.maps.Size(256,256) // or whatever
};
map.overlayMapTypes.insertAt(0, new google.maps.ImageMapType(layerOptions));

Virtual Earth tile service

Tiles are organized in one of two different layouts depending on whether they are using a Spherical Mercator projection, like EPSG:3857 or EPSG:900913, or if they are using a geographical projection, like EPSG:4326.

Les tuiles sont demandées en utilisant le schéma:

http://myhost.com/mapcache/ve?LAYER=<tileset_name>@<grid_name>&tile=<quadkey>

For EPSG:3857, EPSG:900913, or GoogleMapsCompatible grids, <quadkey> are arranged:

z0:

[0]

http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=0

z1:

[00][01]
[02][03]

http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=00
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=01
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=02
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=03
etc.

For EPSG:4326 or WGS84 grids, <quadkey> are arranged:

z1:

[0][1]

http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=0
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=1

z2:

[00][01][10][11]
[02][03][12][13]

http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=00
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=01
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=02
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=03
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=10
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=11
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=12
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=13
etc.