Technical documentation of Geoportal API

  • FR
  • UK

Index / Documentation / Technical documentation

Advanced WMTS use

Introduction

Among the main evolutions of the Geoportal's APIS, there's the replacement of the OsGeO tiled WMS-C by the WMTS standard.

The WMTS standard is close to the WMS. However, instead of generating an image for each request as in the case of WMS, the WMTS returns pre-generated small pictures (tiles) or reuses images previously created for the same request (cache).

This chapter explains how to access the new Geoportal's cache without passing through the APIS (minimum, standard and advanced).

Forging a WMTS request

The Geoportal's cache is a pyramid of images whom resolutions can be found there. Each pyramid's level is made up by tiles of 256 by 256 pixels size.

Example of WMTS request

http://wxs.ign.fr/KEY/geoportail/wmts?LAYER=ORTHOIMAGERY.ORTHOPHOTOS&
        EXCEPTIONS=text/xml&FORMAT=image/jpeg&
        SERVICE=WMTS&VERSION=1.0.0&REQUEST=GetTile&STYLE=normal&
        TILEMATRIXSET=PM&
        TILEMATRIX=18&
        TILEROW=90241&
        TILECOL=132877& 

The parameters of a wmts query

  1. TILEMATRIXSET: The name of the pyramid of images
  1. TILEMATRIX: The name of the matrix containing the tile
  2. TILEROW: the row's number of the tile's upper left corner
  3. TILECOL: the column's number of the tile's upper left corner

How to retrieve the row/column's number of the tile's upper left corner knowing a point expressed in geographical coordinates?

The first step is to transform the geographical coordinates into the targetted SRS: Web Mercator.

One can use the cs2cs software from PROJ.4 or the Geoportal API that is built upon a port of PROJ.4, PROJ4JS. The source code of these libraries gives the needed algorithms for these projections, and, therefore, can be used with any other programming language.

The initial coordinates are, for instance : 2°28'44.1", 48°48'20.3" in sexagecimal degrees, which is 2.478917, 48.805639 in decimal degrees.

Each level point of origin is to be retrieved from the service's capabilities, it is the TopLeftCorner parameter (cf. figure 3). In our case:

X0=-20037508
Y0=20037508

The epsg:3857 coordinates in the grid system are (20313459.78, 13795561.48) :

$ cs2cs -f "%.2f" +init=epsg:4326 +to +init=epsg:3857
2.478917    48.805639
275951.78   6241946.52

X-X0=275951.78+20037508=20313459.78
Y0-Y=20037508-6241946.52=13795561.48
Formula

If installing PROJ.4 is not possible, one can use the following simplified formula for the Web Mercator projection (lon being the longitude expressed in radians, lat being the latitude expressed in radians) :

a: equatorial radius (semi-major axis) of the ellipsoid, is worth 6378137.0 meters

X= a * lon
Y= a * ln(tan(lat/2 + pi/4))

NB: the above formula for computing the ordinate is equivalent to this one:

Y= a/2 * ln((1+sin(lat))/(1-sin(lat))
Computation of the parameters TILEROW / TILECOL :

We are searching for the row/column's number of the tile containing this point at 1/2133 scale (1 pixel is worth 0.597164 m x 0.597164 m), knowing that a tile is 256 x 256 pixels :

  1. 256 x 0.597164 = 152.873984 meters width/height for the tile at the targetted resolution ;
  2. the 20313459.78 abscissa gives us the total number of tiles from the origin of the tiles grid (0):

    20313459.78/152.873984 = 132877.15

  3. the integral part is then : 132877 ;
  4. the 13795561.48 ordinate gives us the total number of tiles from the origin of the tiles grid (0):

    13795561.48/152.873984 = 90241.40

  5. the integral part is then : 90241 ;
  6. the parameters TILEROW/TILECOL : (90241, 132877) ;

What are the available layers for the Geoportal WMTS (LAYERS parameter) ?

They are defined there.

Example of WMTS request for getting tiles covering the (2°28'44.1", 48°48'20.3") location :

  • At Road level, zoom 18 (1 pixel equals 0.597164 m x 0.597164 m) for aerial photographies layer :
    http://wxs.ign.fr/KEY/geoportail/wmts?LAYER=ORTHOIMAGERY.ORTHOPHOTOS&
            EXCEPTIONS=text/xml&FORMAT=image/jpeg&
            SERVICE=WMTS&VERSION=1.0.0&REQUEST=GetTile&STYLE=normal&
            TILEMATRIXSET=PM&
            TILEMATRIX=18&
            TILEROW=90241&
            TILECOL=132877& 
  • Note that parameter TileMatrix corresponds to map's zoom level: