refactor wmts (#1282)

* refactor wmts

* fix tests

* more fixes

Author: vincentsarago

CHANGES.md

@@ -6,6 +6,7 @@
 
 * update rio-tiler requirement to `>=8.0,<9.0`
 * return `UINT8` datatype JPEG/PNG when no output format is specified **breaking change**
+* remove `/{tileMatrixSetId}/WMTSCapabilities.xml` endpoints from factories **breaking change**
 
 ### titiler.core
 
@@ -14,6 +15,8 @@
 ### titiler.extensions
 
 * update rio-cogeo requirement to `7.0,<8.0`
+* add `wmtsExtension` which adds `/WMTSCapabilities.xml` to factories
+* `WMTSCapabilities.xml` response now support all TileMatrixSets as separate layers **breaking change**
 
 ### titiler.mosaic
 
@@ -36,9 +39,12 @@
         coordinates: list[float]
         assets: list[AssetPoint]
     ```
+
 * add `/feature`, `/bbox` and `/statistics` optional endpoints 
 * make `cogeo-mosaic` an optional dependency **breaking change**
 * remove default for `MosaicTilerFactory.backend` attribute **breaking change**
+* add `titiler.mosaic.extensions.mosaicjson.MosaicJSONExtension` which adds MosaicJSON specific `/` and `/validate` endpoints
+* add `titiler.mosaic.extension.wmts.wmtsExtension` which adds `/WMTSCapabilities.xml` endpoint
 
 ## 0.26.0 (2025-11-25)
 

docs/src/advanced/Extensions.md

@@ -55,6 +55,10 @@ class FactoryExtension(metaclass=abc.ABCMeta):
 
 - Goal: adds a `/wms` endpoint to support OGC WMS specification (`GetCapabilities` and `GetMap`)
 
+#### titiler.extensions.wmtsExtension
+
+- Goal: adds a `/WMTSCapabilities.xml` endpoint to support OGC WMTS RESTFULL specification (`GetCapabilities` and `GetTile`)
+
 #### titiler.extensions.stacRenderExtenstion
 
 - Goal: adds `/render` and `/render/{render_id}` endpoints which return the contents of [STAC render extension](https://github.com/stac-extensions/render) and links to tileset.json and WMTS service
@@ -63,7 +67,11 @@ class FactoryExtension(metaclass=abc.ABCMeta):
 
 - Goal: adds `/dataset/`, `/dataset/keys` and `/datasets/dict` endpoints which return metadata about a multidimensional Dataset (not a DataArray)
 
-#### titiler.mosaic.extensions.MosaicJSONExtension
+#### titiler.mosaic.extensions.wmts.wmtsExtension
+
+- Goal: adds `/WMTSCapabilities.xml` to support OGC WMTS RESTFULL specification (`GetCapabilities` and `GetTile`)
+
+#### titiler.mosaic.extensions.mosaicjson.MosaicJSONExtension
 
 - Goal: adds `/` and `/validate` endpoints to return MosaicJSON content and validate external mosaics.
 

docs/src/advanced/endpoints_factories.md

@@ -94,7 +94,6 @@ app.include_router(cog.router)
 | `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin                                   | create a web map tile image from a dataset
 | `GET`  | `/{tileMatrixSetId}/map.html`                                   | HTML                                        | return a simple map viewer **Optional**
 | `GET`  | `/{tileMatrixSetId}/tilejson.json`                              | JSON ([TileJSON][tilejson_model])           | return a Mapbox TileJSON document
-| `GET`  | `/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML                                         | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][point_model])                 | return pixel values from a dataset
 | `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                   | create an image from part of a dataset **Optional**
 | `POST` | `/feature[/{width}x{height}][.{format}]`                        | image/bin                                   | create an image from a GeoJSON feature **Optional**
@@ -147,7 +146,6 @@ app.include_router(stac.router)
 | `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin                                        | create a web map tile image from assets
 | `GET`  | `/{tileMatrixSetId}/map.html`                                   | HTML                                             | return a simple map viewer **Optional**
 | `GET`  | `/{tileMatrixSetId}/tilejson.json`                              | JSON ([TileJSON][tilejson_model])                | return a Mapbox TileJSON document
-| `GET`  | `/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML                                              | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][multipoint_model])                 | return pixel values from assets
 | `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                        | create an image from part of assets **Optional**
 | `POST` | `/feature[/{width}x{height}][.{format}]`                        | image/bin                                        | create an image from a geojson feature intersecting assets **Optional**
@@ -203,7 +201,6 @@ app.include_router(landsat.router)
 | `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin                                    | create a web map tile image from a dataset
 | `GET`  | `/{tileMatrixSetId}/map.html`                                   | HTML                                         | return a simple map viewer **Optional**
 | `GET`  | `/{tileMatrixSetId}/tilejson.json`                              | JSON ([TileJSON][tilejson_model])            | return a Mapbox TileJSON document
-| `GET`  | `/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML                                          | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][point_model])                  | return pixel value from a dataset
 | `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                    | create an image from part of a dataset **Optional**
 | `POST` | `/feature[/{width}x{height}][.{format}]`                        | image/bin                                    | create an image from a geojson feature **Optional**
@@ -342,7 +339,6 @@ Endpoints factory for mosaics.
 | `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}/assets`                   | JSON                                               | return list of assets intersecting a XYZ tile
 | `GET`  | `/{tileMatrixSetId}/map.html`                                   | HTML                                               | return a simple map viewer **Optional**
 | `GET`  | `/{tileMatrixSetId}/tilejson.json`                              | JSON ([TileJSON][tilejson_model])                  | return a Mapbox TileJSON document
-| `GET`  | `/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML                                                | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][mosaic_point])                       | return pixel value from a MosaicJSON dataset
 | `GET`  | `/point/{lon},{lat}/assets`                                     | JSON                                               | return list of assets intersecting a point
 | `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}/assets`                      | JSON                                               | return list of assets intersecting a bounding box
@@ -430,7 +426,6 @@ app.include_router(md.router)
 | `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin                                   | create a web map tile image from a dataset
 | `GET`  | `/{tileMatrixSetId}/map.html`                                   | HTML                                        | return a simple map viewer **Optional**
 | `GET`  | `/{tileMatrixSetId}/tilejson.json`                              | JSON ([TileJSON][tilejson_model])           | return a Mapbox TileJSON document
-| `GET`  | `/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML                                         | return OGC WMTS Get Capabilities
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][point_model])                 | return pixel values from a dataset
 | `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                   | create an image from part of a dataset **Optional**
 | `POST` | `/feature[/{width}x{height}][.{format}]`                        | image/bin                                   | create an image from a GeoJSON feature **Optional**

docs/src/endpoints/cog.md

@@ -18,7 +18,6 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
 | `GET`  | `/cog/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin | create a web map tile image from a dataset
 | `GET`  | `/cog/{tileMatrixSetId}/map.html`                                   | HTML      | simple map viewer
 | `GET`  | `/cog/{tileMatrixSetId}/tilejson.json`                              | JSON      | return a Mapbox TileJSON document
-| `GET`  | `/cog/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML       | return OGC WMTS Get Capabilities
 | `GET`  | `/cog/point/{lon},{lat}`                                            | JSON      | return pixel values from a dataset
 | `GET`  | `/cog/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of a dataset
 | `POST` | `/cog/feature[/{width}x{height}][.{format}]`                        | image/bin | create an image from a GeoJSON feature
@@ -27,6 +26,7 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
 | `GET`  | `/cog/validate`                                                     | JSON      | validate a COG and return dataset info (from `titiler.extensions.cogValidateExtension`)
 | `GET`  | `/cog/viewer`                                                       | HTML      | demo webpage (from `titiler.extensions.cogViewerExtension`)
 | `GET`  | `/cog/stac`                                                         | GeoJSON   | create STAC Items from a dataset (from `titiler.extensions.stacExtension`)
+| `GET`  | `/cog/WMTSCapabilities.xml`                                         | XML       | return OGC WMTS Get Capabilities (from `titiler.extensions.wmts.wmtsExtension`)
 
 
 ## Description

docs/src/endpoints/mosaic.md

@@ -9,19 +9,20 @@ Read Mosaic Info/Metadata and create Web map Tiles from a multiple COG. The `mos
 
 | Method | URL                                                                        | Output    | Description
 | ------ | -------------------------------------------------------------------------- |---------- |--------------
-| `GET`  | `/mosaicjson/`                                                             | JSON      | return a MosaicJSON document
 | `GET`  | `/mosaicjson/info`                                                         | JSON      | return mosaic's basic info
 | `GET`  | `/mosaicjson/info.geojson`                                                 | GeoJSON   | return mosaic's basic info as a GeoJSON feature
 | `GET`  | `/mosaicjson/tiles`                                                        | JSON      | List of OGC Tilesets available
 | `GET`  | `/mosaicjson/tiles/{tileMatrixSetId}`                                      | JSON      | OGC Tileset metadata
 | `GET`  | `/mosaicjson/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin | create a web map tile image from mosaic assets
 | `GET`  | `/mosaicjson/{tileMatrixSetId}/map.html`                                   | HTML      | simple map viewer
 | `GET`  | `/mosaicjson/{tileMatrixSetId}/tilejson.json`                              | JSON      | return a Mapbox TileJSON document
-| `GET`  | `/mosaicjson/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML       | return OGC WMTS Get Capabilities
 | `GET`  | `/mosaicjson/point/{lon},{lat}`                                            | JSON      | return pixel value from a mosaic assets
 | `GET`  | `/mosaicjson/tiles/{tileMatrixSetId}/{z}/{x}/{y}/assets`                   | JSON      | return list of assets intersecting a XYZ tile
 | `GET`  | `/mosaicjson/point/{lon},{lat}/assets`                                     | JSON      | return list of assets intersecting a point
 | `GET`  | `/mosaicjson/bbox/{minx},{miny},{maxx},{maxy}/assets`                      | JSON      | return list of assets intersecting a bounding box
+| `GET`  | `/mosaicjson/`                                                             | JSON      | return a MosaicJSON document (from titiler.mosaic.extensions.mosaicjson.MosaicJSONExtension)
+| `GET`  | `/mosaicjson/validate`                                                     | JSON      | validate a MosaicJSON document (from titiler.mosaic.extensions.mosaicjson.MosaicJSONExtension)
+| `GET`  | `/mosaicjson/WMTSCapabilities.xml`                                         | XML       | return OGC WMTS Get Capabilities (from titiler.mosaic.extensions.wmts.wmtsExtension)
 
 ## Description
 

docs/src/endpoints/stac.md

@@ -20,12 +20,12 @@ The `/stac` routes are based on `titiler.core.factory.MultiBaseTilerFactory` but
 | `GET`  | `/stac/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin | create a web map tile image from assets
 | `GET`  | `/stac/{tileMatrixSetId}/map.html`                                   | HTML      | simple map viewer
 | `GET`  | `/stac/{tileMatrixSetId}/tilejson.json`                              | JSON      | return a Mapbox TileJSON document
-| `GET`  | `/stac/{tileMatrixSetId}/WMTSCapabilities.xml`                       | XML       | return OGC WMTS Get Capabilities
 | `GET`  | `/stac/point/{lon},{lat}`                                            | JSON      | return pixel value from assets
 | `GET`  | `/stac/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin | create an image from part of assets
 | `POST` | `/stac/feature[/{width}x{height}][.{format}]`                        | image/bin | create an image from a geojson covering the assets
 | `GET`  | `/stac/preview[/{width}x{height}][.{format}]`                        | image/bin | create a preview image from assets
 | `GET`  | `/stac/viewer`                                                       | HTML      | demo webpage (from `titiler.extensions.stacViewerExtension`)
+| `GET`  | `/stac/WMTSCapabilities.xml`                                         | XML       | return OGC WMTS Get Capabilities (from `titiler.extensions.wmts.wmtsExtension`)
 
 ## Description
 

pyproject.toml

@@ -52,6 +52,7 @@ dev = [
     "pystac[validation]>=1.0.0,<2.0.0",
     "brotlipy",
     "boto3",
+    "owslib",
     "pre-commit",
     "bump-my-version",
 ]

src/titiler/application/tests/routes/test_cog.py

@@ -42,17 +42,14 @@ def test_wmts(rio, app):
     """test wmts endpoints."""
     rio.open = mock_rasterio_open
 
-    response = app.get(
-        "/cog/WebMercatorQuad/WMTSCapabilities.xml?url=https://myurl.com/cog.tif"
-    )
+    response = app.get("/cog/WMTSCapabilities.xml?url=https://myurl.com/cog.tif")
     assert response.status_code == 200
     assert response.headers["content-type"] == "application/xml"
     assert response.headers["Cache-Control"] == "private, max-age=3600"
     assert (
-        "http://testserver/cog/WebMercatorQuad/WMTSCapabilities.xml?url=https"
+        "http://testserver/cog/WMTSCapabilities.xml?url=https"
         in response.content.decode()
     )
-    assert "<ows:Identifier>default</ows:Identifier>" in response.content.decode()
     assert (
         "http://testserver/cog/tiles/WebMercatorQuad/{TileMatrix}/{TileCol}/{TileRow}@1x.png?url=https"
         in response.content.decode()
@@ -63,7 +60,7 @@ def test_wmts(rio, app):
     )
 
     response = app.get(
-        "/cog/WebMercatorQuad/WMTSCapabilities.xml?url=https://myurl.com/cog.tif&tile_scale=2&tile_format=jpg"
+        "/cog/WMTSCapabilities.xml?url=https://myurl.com/cog.tif&tile_scale=2&tile_format=jpg"
     )
     assert response.status_code == 200
     assert response.headers["content-type"] == "application/xml"
@@ -73,7 +70,7 @@ def test_wmts(rio, app):
     )
 
     response = app.get(
-        "/cog/WebMercatorQuad/WMTSCapabilities.xml?url=https://myurl.com/cog.tif&use_epsg=true"
+        "/cog/WMTSCapabilities.xml?url=https://myurl.com/cog.tif&use_epsg=true"
     )
     assert response.status_code == 200
     assert response.headers["content-type"] == "application/xml"

src/titiler/application/tests/routes/test_mosaic.py

@@ -180,7 +180,7 @@ def test_wmts(app):
     """test GET /mosaicjson/WebMercatorQuad/WMTSCapabilities.xml endpoint"""
     with patch.object(FileBackend, "_read", mosaic_read_factory(MOSAICJSON_FILE)):
         response = app.get(
-            "/mosaicjson/WebMercatorQuad/WMTSCapabilities.xml",
+            "/mosaicjson/WMTSCapabilities.xml",
             params={"url": MOSAICJSON_FILE},
         )
         assert response.status_code == 200
@@ -191,7 +191,7 @@ def test_wmts(app):
         )
 
         response = app.get(
-            "/mosaicjson/WebMercatorQuad/WMTSCapabilities.xml",
+            "/mosaicjson/WMTSCapabilities.xml",
             params={"url": MOSAICJSON_FILE, "tile_scale": 2},
         )
         assert response.status_code == 200

src/titiler/application/titiler/application/main.py

@@ -43,9 +43,11 @@
     stacExtension,
     stacRenderExtension,
     stacViewerExtension,
+    wmtsExtension,
 )
 from titiler.mosaic.errors import MOSAIC_STATUS_CODES
-from titiler.mosaic.extensions import MosaicJSONExtension
+from titiler.mosaic.extensions.mosaicjson import MosaicJSONExtension
+from titiler.mosaic.extensions.wmts import wmtsExtension as mosaic_wmtsExtension
 from titiler.mosaic.factory import MosaicTilerFactory
 
 logging.getLogger("botocore.credentials").disabled = True
@@ -70,7 +72,7 @@
 )
 
 jinja2_env = jinja2.Environment(
-    autoescape=jinja2.select_autoescape(["html", "xml"]),
+    autoescape=jinja2.select_autoescape(["html"]),
     loader=jinja2.ChoiceLoader(templates_location),
 )
 titiler_templates = Jinja2Templates(env=jinja2_env)
@@ -133,6 +135,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
             cogValidateExtension(),
             cogViewerExtension(),
             stacExtension(),
+            wmtsExtension(),
         ],
         enable_telemetry=api_settings.telemetry_enabled,
         templates=titiler_templates,
@@ -153,10 +156,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
         reader=STACReader,
         router_prefix="/stac",
         add_ogc_maps=True,
-        extensions=[
-            stacViewerExtension(),
-            stacRenderExtension(),
-        ],
+        extensions=[stacViewerExtension(), stacRenderExtension(), wmtsExtension()],
         enable_telemetry=api_settings.telemetry_enabled,
         templates=titiler_templates,
     )
@@ -177,6 +177,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
         router_prefix="/mosaicjson",
         extensions=[
             MosaicJSONExtension(),
+            mosaic_wmtsExtension(),
         ],
         enable_telemetry=api_settings.telemetry_enabled,
         templates=titiler_templates,