deprecate default tilematrixset (#802)

* deprecate default tilematrixset * move deprecation of default_tms in BaseTilerFactory * update changelog
developmentseed · Mar 22, 2024 · b24b6b5 · b24b6b5
1 parent 9df1731
commit b24b6b5
Show file tree

Hide file tree

Showing 25 changed files with 434 additions and 2,959 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -5,6 +5,47 @@
 ### titiler.core
 
 * Add `ColorMapFactory` to create colorMap metadata endpoints (https://github.com/developmentseed/titiler/pull/796)
+* **Deprecation** remove default `WebMercatorQuad` tile matrix set in `/tiles`, `/tilesjson.json`, `/map` and `/WMTSCapabilities.xml` endpoints (https://github.com/developmentseed/titiler/pull/802)
+
+    ```
+    # Before
+    /tiles/{z}/{x}/{y}
+    /tilejson.json
+    /map
+    /WMTSCapabilities.xml
+
+    # Now
+    /tiles/WebMercatorQuad/{z}/{x}/{y}
+    /WebMercatorQuad/tilejson.json
+    /WebMercatorQuad/map
+    /WebMercatorQuad/WMTSCapabilities.xml
+    ```
+
+* **Deprecation** `default_tms` attribute in `BaseTilerFactory` (because `tileMatrixSetId` is now required in endpoints).
+
+### titiler.mosaic
+
+* **Deprecation** remove default `WebMercatorQuad` tile matrix set in `/tiles`, `/tilesjson.json`, `/map` and `/WMTSCapabilities.xml` endpoints (https://github.com/developmentseed/titiler/pull/802)
+
+    ```
+    # Before
+    /tiles/{z}/{x}/{y}
+    /tilejson.json
+    /map
+    /WMTSCapabilities.xml
+
+    # Now
+    /tiles/WebMercatorQuad/{z}/{x}/{y}
+    /WebMercatorQuad/tilejson.json
+    /WebMercatorQuad/map
+    /WebMercatorQuad/WMTSCapabilities.xml
+    ```
+
+* **Deprecation** `default_tms` attribute in `MosaicTilerFactory` (because `tileMatrixSetId` is now required in endpoints).
+
+### Misc
+
+* add `request` as first argument in `TemplateResponse` to adapt with latest starlette version
 
 ## 0.17.3 (2024-03-21)
 

diff --git a/docs/src/advanced/endpoints_factories.md b/docs/src/advanced/endpoints_factories.md
@@ -89,14 +89,14 @@ app.include_router(cog.router)
 | `GET`  | `/info.geojson`                                                 | GeoJSON ([InfoGeoJSON][info_geojson_model]) | return dataset's basic info as a GeoJSON feature
 | `GET`  | `/statistics`                                                   | JSON ([Statistics][stats_model])            | return dataset's statistics
 | `POST` | `/statistics`                                                   | GeoJSON ([Statistics][stats_geojson_model]) | return dataset's statistics for a GeoJSON
-| `GET`  | `/tiles[/{tileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                   | create a web map tile image from a dataset
-| `GET`  | `[/{tileMatrixSetId}]/tilejson.json`                            | JSON ([TileJSON][tilejson_model])           | return a Mapbox TileJSON document
-| `GET`  | `[/{tileMatrixSetId}]/WMTSCapabilities.xml`                     | XML                                         | return OGC WMTS Get Capabilities
+| `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                   | create a web map tile image from a dataset
+| `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`  | `/preview[.{format}]`                                           | image/bin                                   | create a preview image from a dataset **Optional**
 | `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**
-| `GET`  | `[/{tileMatrixSetId}]/map`                                      | HTML                                        | return a simple map viewer **Optional**
+| `GET`  | `/{tileMatrixSetId}/map`                                      | HTML                                        | return a simple map viewer **Optional**
 
 
 ## MultiBaseTilerFactory
@@ -134,14 +134,14 @@ app.include_router(stac.router)
 | `GET`  | `/asset_statistics`                                             | JSON ([Statistics][multistats_model])            | return per asset statistics
 | `GET`  | `/statistics`                                                   | JSON ([Statistics][stats_model])                 | return assets statistics (merged)
 | `POST` | `/statistics`                                                   | GeoJSON ([Statistics][multistats_geojson_model]) | return assets statistics for a GeoJSON (merged)
-| `GET`  | `/tiles[/{tileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                        | create a web map tile image from assets
-| `GET`  | `/[{tileMatrixSetId}]/tilejson.json`                            | JSON ([TileJSON][tilejson_model])                | return a Mapbox TileJSON document
+| `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                        | create a web map tile image from assets
+| `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`  | `/preview[.{format}]`                                           | image/bin                                        | create a preview image from assets **Optional**
 | `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**
-| `GET`  | `[/{tileMatrixSetId}]/map`                                      | HTML                                             | return a simple map viewer **Optional**
+| `GET`  | `/{tileMatrixSetId}/map`                                      | HTML                                             | return a simple map viewer **Optional**
 
 
 ## MultiBandTilerFactory
@@ -189,14 +189,14 @@ app.include_router(landsat.router)
 | `GET`  | `/info.geojson`                                                 | GeoJSON ([InfoGeoJSON][info_geojson_model])  | return basic info for a dataset as a GeoJSON feature
 | `GET`  | `/statistics`                                                   | JSON ([Statistics][stats_model])             | return info and statistics for a dataset
 | `POST` | `/statistics`                                                   | GeoJSON ([Statistics][stats_geojson_model])  | return info and statistics for a dataset
-| `GET`  | `/tiles[/{tileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                    | create a web map tile image from a dataset
-| `GET`  | `/[{tileMatrixSetId}]/tilejson.json`                            | JSON ([TileJSON][tilejson_model])            | return a Mapbox TileJSON document
+| `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                    | create a web map tile image from a dataset
+| `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`  | `/preview[.{format}]`                                           | image/bin                                    | create a preview image from a dataset **Optional**
 | `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**
-| `GET`  | `[/{tileMatrixSetId}]/map`                                      | HTML                                         | return a simple map viewer **Optional**
+| `GET`  | `/{tileMatrixSetId}/map`                                      | HTML                                         | return a simple map viewer **Optional**
 
 
 ## MosaicTilerFactory
@@ -213,7 +213,7 @@ Endpoints factory for mosaics, built on top of [MosaicJSON](https://github.com/d
 - **pixel_selection_dependency**: Dependency to select the `pixel_selection` method. Defaults to `titiler.mosaic.factory.PixelSelectionParams`.
 - **tile_dependency**: Dependency to defile `buffer` and `padding` to apply at tile creation. Defaults to `titiler.core.dependencies.TileParams`.
 - **supported_tms**: List of available TileMatrixSets. Defaults to `morecantile.tms`.
-- **default_tms**: Default `TileMatrixSet` identifier to use. Defaults to `WebMercatorQuad`.
+- **default_tms**: **DEPRECATED**, Default `TileMatrixSet` identifier to use. Defaults to `WebMercatorQuad`.
 - **add_viewer**: . Add `/map` endpoints to the router. Defaults to `True`.
 
 #### Endpoints
@@ -224,14 +224,14 @@ Endpoints factory for mosaics, built on top of [MosaicJSON](https://github.com/d
 | `GET`  | `/bounds`                                                       | JSON ([Bounds][bounds_model])                      | return mosaic's bounds
 | `GET`  | `/info`                                                         | JSON ([Info][mosaic_info_model])                   | return mosaic's basic info
 | `GET`  | `/info.geojson`                                                 | GeoJSON ([InfoGeoJSON][mosaic_geojson_info_model]) | return mosaic's basic info  as a GeoJSON feature
-| `GET`  | `/tiles[/{tileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                          | create a web map tile image from a MosaicJSON
-| `GET`  | `[/{tileMatrixSetId}]/tilejson.json`                            | JSON ([TileJSON][tilejson_model])                  | return a Mapbox TileJSON document
-| `GET`  | `[/{tileMatrixSetId}]/WMTSCapabilities.xml`                     | XML                                                | return OGC WMTS Get Capabilities
+| `GET`  | `/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                          | create a web map tile image from a MosaicJSON
+| `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`  | `/{z}/{x}/{y}/assets`                                           | JSON                                               | return list of assets intersecting a XYZ tile
 | `GET`  | `/{lon},{lat}/assets`                                           | JSON                                               | return list of assets intersecting a point
 | `GET`  | `/{minx},{miny},{maxx},{maxy}/assets`                           | JSON                                               | return list of assets intersecting a bounding box
-| `GET`  | `[/{tileMatrixSetId}]/map`                                      | HTML                                               | return a simple map viewer **Optional**
+| `GET`  | `/{tileMatrixSetId}/map`                                      | HTML                                               | return a simple map viewer **Optional**
 
 
 ## TMSFactory

diff --git a/docs/src/endpoints/cog.md b/docs/src/endpoints/cog.md
@@ -14,14 +14,14 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
 | `GET`  | `/cog/info.geojson`                                                 | GeoJSON   | return dataset's basic info as a GeoJSON feature
 | `GET`  | `/cog/statistics`                                                   | JSON      | return dataset's statistics
 | `POST` | `/cog/statistics`                                                   | GeoJSON   | return dataset's statistics for a GeoJSON
-| `GET`  | `/cog/tiles[/{tileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin | create a web map tile image from a dataset
-| `GET`  | `/cog[/{tileMatrixSetId}]/tilejson.json`                            | JSON      | return a Mapbox TileJSON document
-| `GET`  | `/cog[/{tileMatrixSetId}]/WMTSCapabilities.xml`                     | XML       | return OGC WMTS Get Capabilities
+| `GET`  | `/cog/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`    | image/bin | create a web map tile image from a dataset
+| `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/preview[.{format}]`                                           | image/bin | create a preview image 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
-| `GET`  | `/cog[/{tileMatrixSetId}]/map`                                      | HTML      | simple map viewer
+| `POST` | `/cog/feature[/{width}x{height}][].{format}]`                       | image/bin | create an image from a GeoJSON feature
+| `GET`  | `/cog/{tileMatrixSetId}/map`                                        | HTML      | simple map viewer
 | `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`)
@@ -30,10 +30,10 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
 
 ### Tiles
 
-`:endpoint:/cog/tiles[/{tileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{format}]`
+`:endpoint:/cog/tiles/{tileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]`
 
 - PathParams:
-    - **tileMatrixSetId** (str): TileMatrixSet name, default is `WebMercatorQuad`. **Optional**
+    - **tileMatrixSetId** (str): TileMatrixSet name (e.g `WebMercatorQuad`)
     - **z** (int): TMS tile's zoom level.
     - **x** (int): TMS tile's column.
     - **y** (int): TMS tile's row.
@@ -60,8 +60,8 @@ The `/cog` routes are based on `titiler.core.factory.TilerFactory` but with `cog
 
 Example:
 
-- `https://myendpoint/cog/tiles/1/2/3?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/cog/tiles/1/2/3.jpg?url=https://somewhere.com/mycog.tif&bidx=3&bidx=1&bidx2`
+- `https://myendpoint/cog/tiles/WebMercatorQuad/1/2/3?url=https://somewhere.com/mycog.tif`
+- `https://myendpoint/cog/tiles/WebMercatorQuad/1/2/3.jpg?url=https://somewhere.com/mycog.tif&bidx=3&bidx=1&bidx2`
 - `https://myendpoint/cog/tiles/WorldCRS84Quad/1/2/[email protected]?url=https://somewhere.com/mycog.tif`
 - `https://myendpoint/cog/tiles/WorldCRS84Quad/1/2/3?url=https://somewhere.com/mycog.tif&bidx=1&rescale=0,1000&colormap_name=cfastie`
 
@@ -204,10 +204,10 @@ Example:
 
 ### TilesJSON
 
-`:endpoint:/cog[/{tileMatrixSetId}]/tilejson.json` tileJSON document
+`:endpoint:/cog/{tileMatrixSetId}/tilejson.json` tileJSON document
 
 - PathParams:
-    - **tileMatrixSetId**: TileMatrixSet name, default is `WebMercatorQuad`. **Optional**
+    - **tileMatrixSetId** (str): TileMatrixSet name (e.g `WebMercatorQuad`)
 
 - QueryParams:
     - **url** (str): Cloud Optimized GeoTIFF URL. **Required**
@@ -233,17 +233,17 @@ Example:
 
 Example:
 
-- `https://myendpoint/cog/tilejson.json?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/cog/tilejson.json?url=https://somewhere.com/mycog.tif&tile_format=png`
+- `https://myendpoint/cog/WebMercatorQuad/tilejson.json?url=https://somewhere.com/mycog.tif`
+- `https://myendpoint/cog/WebMercatorQuad/tilejson.json?url=https://somewhere.com/mycog.tif&tile_format=png`
 - `https://myendpoint/cog/WorldCRS84Quad/tilejson.json?url=https://somewhere.com/mycog.tif&tile_scale=2&bidx=1,2,3`
 
 
 ### Map
 
-`:endpoint:/cog[/{tileMatrixSetId}]/map` Simple viewer
+`:endpoint:/cog/{tileMatrixSetId}/map` Simple viewer
 
 - PathParams:
-    - **tileMatrixSetId**: TileMatrixSet name, default is `WebMercatorQuad`. **Optional**
+    - **tileMatrixSetId** (str): TileMatrixSet name (e.g `WebMercatorQuad`)
 
 - QueryParams:
     - **url** (str): Cloud Optimized GeoTIFF URL. **Required**
@@ -269,9 +269,9 @@ Example:
 
 Example:
 
-- `https://myendpoint/cog/map?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/cog/map?url=https://somewhere.com/mycog.tif&tile_format=png`
-- `https://myendpoint/cog/WebMercatorQuad/map?url=https://somewhere.com/mycog.tif&tile_scale=2&bidx=1,2,3`
+- `https://myendpoint/cog/WebMercatorQuad/map?url=https://somewhere.com/mycog.tif`
+- `https://myendpoint/cog/WebMercatorQuad/map?url=https://somewhere.com/mycog.tif&tile_format=png`
+- `https://myendpoint/cog/WorldCRS84Quad/map?url=https://somewhere.com/mycog.tif&tile_scale=2&bidx=1,2,3`
 
 
 ### Bounds