Merge pull request #17 from developmentseed/feature/add-wmts-service

add wmts service

.env.example

@@ -0,0 +1,2 @@
+TITILER_STACAPI_API_DEBUG="TRUE"
+TITILER_STACAPI_STAC_API_URL="https://stac.eoapi.dev"

README.md

@@ -57,7 +57,11 @@ $ cd titiler-stacapi
 $ docker-compose up --build api
 ```
 
-It runs `titiler.stacapi` using Gunicorn web server. 
+It runs `titiler.stacapi` using Gunicorn web server.
+
+### How it works
+
+![](https://github.com/developmentseed/titiler-stacapi/assets/10407788/2e53bfe3-402a-4c57-bf61-c055e32f1362)
 
 ## Contribution & Development
 

docs/mkdocs.yml

@@ -18,9 +18,12 @@ nav:
   - Home: index.md
   - Endpoints:
     - endpoints/index.md
+    - OGC WMTS: endpoints/ogc_wmts_endpoints.md
     - Collections: endpoints/collections_endpoints.md
     - Items: endpoints/items_endpoints.md
     - TileMatrixSet: endpoints/tms_endpoints.md
+  - Customization:
+    - Authentication: custom/application_with_auth.md
   - Technical Considerations: technical-considerations.md
   - Development - Contributing: contributing.md
   - Release notes: release-notes.md

docs/src/custom/application_with_auth.md

@@ -0,0 +1,88 @@
+
+
+Goal: add `Authentication` forwarding to the `/wmts` endpoints
+
+requirements: titiler.stacapi
+
+
+```python
+"""TiTiler+stacapi FastAPI application."""
+
+
+from fastapi import Depends, FastAPI
+from fastapi.security import APIKeyHeader
+from starlette.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+from typing_extensions import Annotated
+
+import morecantile
+from titiler.core.errors import DEFAULT_STATUS_CODES, add_exception_handlers
+from titiler.core.middleware import CacheControlMiddleware
+from titiler.mosaic.errors import MOSAIC_STATUS_CODES
+from titiler.stacapi import __version__ as titiler_stacapi_version
+from titiler.stacapi.dependencies import APIParams
+from titiler.stacapi.factory import OGCWMTSFactory
+from titiler.stacapi.settings import ApiSettings, STACAPISettings
+
+settings = ApiSettings()
+stacapi_config = STACAPISettings()
+
+
+header_scheme = APIKeyHeader(name="Authorization", description="STAC API Authorization")
+
+
+def STACApiParamsAuth(
+    request: Request,
+    token: Annotated[str, Depends(header_scheme)],
+) -> APIParams:
+    """Return STAC API Parameters."""
+    return APIParams(
+        api_url=request.app.state.stac_url,
+        headers={"Authorization": token},
+    )
+
+
+app = FastAPI(
+    title=settings.name,
+    openapi_url="/api",
+    docs_url="/api.html",
+    description="""Connect titiler to STAC APIs.""",
+    version=titiler_stacapi_version,
+    root_path=settings.root_path,
+)
+
+# We store the STAC API url in the application state
+app.state.stac_url = stacapi_config.stac_api_url
+
+add_exception_handlers(app, DEFAULT_STATUS_CODES)
+add_exception_handlers(app, MOSAIC_STATUS_CODES)
+
+# Set all CORS enabled origins
+if settings.cors_origins:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_credentials=True,
+        allow_methods=["GET"],
+        allow_headers=["*"],
+    )
+
+app.add_middleware(CacheControlMiddleware, cachecontrol=settings.cachecontrol)
+
+webmerc = morecantile.tms.get("WebMercatorQuad")
+webmerc.id = "EPSG:3857"
+supported_tms = morecantile.TileMatrixSets({"EPSG:3857": webmerc})
+
+###############################################################################
+# OGC WMTS Endpoints
+wmts = OGCWMTSFactory(
+    path_dependency=STACApiParamsAuth,
+    supported_tms=supported_tms,
+)
+
+app.include_router(
+    wmts.router,
+    tags=["Web Map Tile Service"],
+)
+
+```

docs/src/endpoints/ogc_wmts_endpoints.md

@@ -0,0 +1,62 @@
+
+### OGC WMTS endpoints
+
+
+| Method | URL                                                                                 | Output                       | Description
+| ------ | ------------------------------------------------------------------------------------|------------------------------|--------------
+| `GET`  | `/wmts`                                                                             | XML or image/bin or GeoJSON  | OGC Web map tile service (KVP encoding)
+| `GET`  | `/{LAYER}/{STYLE}/{TIME}/{TileMatrixSet}/{TileMatrix}/{TileCol}/{TileRow}.{FORMAT}` | image/bin                    | return a web map tile image
+
+### WMTS (GetCapabilities / GetTile / GetFeatureInfo) - KVP Encoding
+
+`:endpoint:/wmts`
+
+- QueryParams:
+
+    - `GetCapabilities`:
+
+        - **Request** ([`GetCapabilities`, `GetTile`, `GetFeatureInfo`]): Operation name
+        - **Service** ([`wmts`]): Service type identifier
+        - **Version** ([`1.0.0`], optional): Standard and schema version
+
+    - `GetTile`:
+
+        - **Layer** (str): Layer identifier
+        - **Format** (str): Output image format
+        - **Style** (str): Style identifier
+        - **TileMatrixSet** (str): TileMatrixSet identifier
+        - **TileMatrix** (int): TileMatrix identifier
+        - **TileRow** (int): Row index of tile matrix
+        - **TileCol** (int): Column index of tile matrix
+        - **Time** (str, Optional): TIME Dimension
+
+    - `GetFeatureInfo`:
+
+        - **I** (int): Column index of a pixel in the tile
+        - **J** (int): Row index of a pixel in the tile
+        - **InfoFormat** ([`application/geo+json`]): Output format of the retrieved information
+
+Example:
+
+- `https://myendpoint/wmts?Request=GetCapabilities&Services=wmts&Version=1.0.0`
+- `https://myendpoint/wmts?Request=GetTiles&Services=wmts&Version=1.0.0&Style=default&Layer=MyLayer&TileMatrixSet=WebMercatorQuad&TileMatrix=0&TileRow=0&TileCol=0&Time=2023-01-01&Format=image/png`
+- `https://myendpoint/wmts?Request=GetTiles&Services=wmts&Version=1.0.0&Style=default&Layer=MyLayer&TileMatrixSet=WebMercatorQuad&TileMatrix=0&TileRow=0&TileCol=0&Time=2023-01-01&Format=image/png&I=100&J=100&InfoFormat="application/geo+json`
+
+
+### GetTile - REST
+
+`:endpoint:/{LAYER}/{STYLE}/{TIME}/{TileMatrixSet}/{TileMatrix}/{TileCol}/{TileRow}.{FORMAT}`
+
+- PathParams:
+    - **Layer** (str): Layer identifier
+    - **Style** (str): Style identifier
+    - **Time** (str): TIME Dimension
+    - **TileMatrixSet** (str): TileMatrixSet identifier
+    - **TileMatrix** (int): TileMatrix identifier
+    - **TileRow** (int): Row index of tile matrix
+    - **TileCol** (int): Column index of tile matrix
+    - **Format** (str): Output image format
+
+Example:
+
+- `https://myendpoint/MyLayer/default/2023-01-01/WebMercatorQuad/0/0/0.png