Translation of slippy map tile names to TMS tile names

Question

I am using mapproxy to serve slippy map tiles. I noticed that there are several URLs which return the same tile.

---

Example I

Below is slovakia.yaml (based on this thread). Local service can be launched via mapproxy-util serve-develop slovakia.yaml.

services:
  tms:
    use_grid_names: true
    origin: 'nw'

layers:
  - name: slovakia
    title: Slovakia example
    sources: [slovakia_cache]

caches:
  slovakia_cache:
    grids: [webmercator]
    sources: [slovakia_wms]

sources:
  slovakia_wms:
    type: wms
    req:
      url: https://zbgisws.skgeodesy.sk/zbgis_ortofoto_wms/service.svc/get?
      layers: 1

grids:
    webmercator:
        base: GLOBAL_WEBMERCATOR

globals:

After the service is running, both

http://localhost:8080/tiles/slovakia/webmercator/8/140/88.png

and

http://localhost:8080/tms/1.0.0/slovakia/webmercator/7/140/167.png

return the same tile:

---

Example II

Below is italy.yaml (based on this thread). Local service can be launched via mapproxy-util serve-develop italy.yaml.

services:
  tms:
    use_grid_names: true
    origin: 'nw'
    
layers:
  - name: italyparcels
    title: italyparcels
    sources: [ItalyCache]
    
caches:
  ItalyCache:
    grids: [webmercator]
    sources: [ItalyWMS]
    cache:
      type: file
      directory: cached_tms
      directory_layout: tms

sources:
  ItalyWMS:
    type: wms
    req:
      url: https://wms.cartografia.agenziaentrate.gov.it/inspire/wms/ows01.php?language=ita&
      layers: CP.CadastralParcel,strade,vestizioni,province,codice_plla,fabbricati,CP.CadastralZoning,acque,simbolo_graffa,copyright
    supported_srs: ['EPSG:25832']

grids:
  webmercator:
    base: GLOBAL_WEBMERCATOR

globals:

Both

http://localhost:8080/tiles/italyparcels/webmercator/6/34/23.png

and

http://localhost:8080/tms/1.0.0/italyparcels/webmercator/5/34/40.png

return the same tile:

---

I can observe that the y coordinates of the 2 URLs in the Slovak example add up to 255 (88+167=255). 2^8=256, and 8 is the zoom level in the first Slovak URL.

I can observe that the y coordinates of the 2 URLs in the Italian example add up to 63 (23+40=63). 2^6=64, and 6 is the zoom level in the first Italian URL.

I am aware that the y axis of TMS points northwards, unlike standard XYZ layers (source).

Based on the above, it seems that given a mapproxy-served URL:

http://localhost:8080/tiles/some-layer/webmercator/{z}/{x}/{y}.png

we can construct another URL which returns the same tile:

http://localhost:8080/tms/1.0.0/some-layer/webmercator/{z-1}/{x}/{2**z-1-y}.png

---

I am looking for an explanation on why exactly the above pairs of URLs return the same tile. The more the explanation is supported by documentation, and not mere observation, the better (as reading those docs might also help getting closer to a solution to this and this question).

Why is tiles/.../{z}/{x}/{y} equivalent to tms/1.0.0/.../{z-1}/{x}/{2**z-1-y}?

Answer 1

Which tiles are the z=0 tiles?

In the OpenLayers section, of the MapProxy documentation, it is said:

TMS begins with two or four tiles by default, depending on the SRS. [...] MapProxy will start with a single-tile level if you request /tiles instead of /tms.

Based on this, it seems that if /tms is used, MapProxy won't start with a single-tile level. Requesting 4 tiles to cover the extent of Global Webmercator projection while calling these tiles the zoom level 0 tiles coincides with the observation above: the z values in the /tms tilenames are off by 1.

I am not sure how conventional nowadays this practice is. The quoted sentences were written in 2010. The TMS Service section here makes it seems like that the z=1 level is the one which has two or four tiles depending on the SRS (4 for EPSG:3857, 2 for EPSG:4326 grids). This article provides a figure showing the difference in the Y axes, but it does not mention difference in zoom level counting (their figure uses Google to indicate the tiling system referred to as XYZ or slippy map tiles in this thread).

Why does Y_tms+Y_tiles equal to 2ᶻ-1?

Because at every zoom level, there are 2ᶻ rows and columns (where z refers to standard slippy map / XYZ tiling zoom levels, not the TMS one). Both /tms and /tiles tiling starts counting from 0. The Y axis is pointing in the opposite direction (source), so counting starts at the opposite ends of the extent.

Visualise these concepts easily!

One can use this XYZ layer to easily visualize tilenames of different conventions in QGIS: https://tilevis.fly.dev/XYZ/{z}/{x}/{y}. (Source code here, I'm the author.) After adding the XYZ layer to QGIS: we can see that the XYZ tile 8/140/88 is indeed the same as TMS tile 7/140/167, and within this square, the outline of Slovakia has the same shape as it had on the orthophoto returned by MapProxy (see below).