refactor and add more templates (#1227)

* refactor and add more templates

* fix for tests

* use colormap image in html preview

* fix tilesets

Author: vincentsarago

CHANGES.md

@@ -16,6 +16,14 @@
 
 * add `description` in `ApiSettings`
 
+### titiler.core
+
+* delete `titiler.core.templating` submodule **breaking change**
+* move `create_html_response` function to `titiler.core.utils` submodule
+* move all HTML templates in `titiler/core/templates` directory  **breaking change**
+* add HTML responses for tilesets, tilematrixsets, algorithms and colormaps endpoints
+* rename response model `ColorMapsList` -> `ColorMapList` and change it's attibutes to `colormaps` **breaking change**
+* add `templates` in the `BaseFactory` class definition
 
 ## 0.23.1 (2025-08-27)
 

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

@@ -5,12 +5,14 @@
 from logging import config as log_config
 from typing import Annotated, Literal, Optional
 
+import jinja2
 import rasterio
 from fastapi import Depends, FastAPI, HTTPException, Query, Security
 from fastapi.security.api_key import APIKeyQuery
 from rio_tiler.io import Reader, STACReader
 from starlette.middleware.cors import CORSMiddleware
 from starlette.requests import Request
+from starlette.templating import Jinja2Templates
 from starlette_cramjam.middleware import CompressionMiddleware
 
 from titiler.application import __version__ as titiler_version
@@ -31,8 +33,7 @@
 )
 from titiler.core.models.OGC import Conformance, Landing
 from titiler.core.resources.enums import MediaType
-from titiler.core.templating import create_html_response
-from titiler.core.utils import accept_media_type, update_openapi
+from titiler.core.utils import accept_media_type, create_html_response, update_openapi
 from titiler.extensions import (
     cogValidateExtension,
     cogViewerExtension,
@@ -48,9 +49,24 @@
 logging.getLogger("rasterio.session").setLevel(logging.ERROR)
 logging.getLogger("rio-tiler").setLevel(logging.ERROR)
 
-
 api_settings = ApiSettings()
 
+# custom template directory
+templates_location = (
+    [jinja2.FileSystemLoader(api_settings.template_directory)]
+    if api_settings.template_directory
+    else []
+)
+# default template directory
+templates_location.append(jinja2.PackageLoader("titiler.core", "templates"))
+
+jinja2_env = jinja2.Environment(
+    autoescape=jinja2.select_autoescape(["html", "xml"]),
+    loader=jinja2.ChoiceLoader(templates_location),
+)
+titiler_templates = Jinja2Templates(env=jinja2_env)
+
+
 app_dependencies = []
 if api_settings.global_access_token:
     ###############################################################################
@@ -111,6 +127,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
             stacExtension(),
         ],
         enable_telemetry=api_settings.telemetry_enabled,
+        templates=titiler_templates,
     )
 
     app.include_router(
@@ -133,6 +150,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
             stacRenderExtension(),
         ],
         enable_telemetry=api_settings.telemetry_enabled,
+        templates=titiler_templates,
     )
 
     app.include_router(
@@ -149,6 +167,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
     mosaic = MosaicTilerFactory(
         router_prefix="/mosaicjson",
         enable_telemetry=api_settings.telemetry_enabled,
+        templates=titiler_templates,
     )
     app.include_router(
         mosaic.router,
@@ -160,7 +179,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
 
 ###############################################################################
 # TileMatrixSets endpoints
-tms = TMSFactory()
+tms = TMSFactory(templates=titiler_templates)
 app.include_router(
     tms.router,
     tags=["Tiling Schemes"],
@@ -169,7 +188,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
 
 ###############################################################################
 # Algorithms endpoints
-algorithms = AlgorithmFactory()
+algorithms = AlgorithmFactory(templates=titiler_templates)
 app.include_router(
     algorithms.router,
     tags=["Algorithms"],
@@ -178,7 +197,7 @@ def validate_access_token(access_token: str = Security(api_key_query)):
 
 ###############################################################################
 # Colormaps endpoints
-cmaps = ColorMapFactory()
+cmaps = ColorMapFactory(templates=titiler_templates)
 app.include_router(
     cmaps.router,
     tags=["ColorMaps"],
@@ -365,6 +384,18 @@ def landing(
                 "type": "application/json",
                 "rel": "http://www.opengis.net/def/rel/ogc/1.0/tiling-schemes",
             },
+            {
+                "title": "List of Available Algorithms",
+                "href": str(request.url_for("available_algorithms")),
+                "type": "application/json",
+                "rel": "data",
+            },
+            {
+                "title": "List of Available ColorMaps",
+                "href": str(request.url_for("available_colormaps")),
+                "type": "application/json",
+                "rel": "data",
+            },
             {
                 "title": "TiTiler Documentation (external link)",
                 "href": "https://developmentseed.org/titiler/",
@@ -380,13 +411,13 @@ def landing(
         ],
     }
 
-    output_type: Optional[MediaType]
     if f:
         output_type = MediaType[f]
     else:
         accepted_media = [MediaType.html, MediaType.json]
-        output_type = accept_media_type(
-            request.headers.get("accept", ""), accepted_media
+        output_type = (
+            accept_media_type(request.headers.get("accept", ""), accepted_media)
+            or MediaType.json
         )
 
     if output_type == MediaType.html:
@@ -395,6 +426,7 @@ def landing(
             data,
             title="TiTiler",
             template_name="landing",
+            templates=titiler_templates,
         )
 
     return data
@@ -433,13 +465,13 @@ def conformance(
     """
     data = {"conformsTo": sorted(TITILER_CONFORMS_TO)}
 
-    output_type: Optional[MediaType]
     if f:
         output_type = MediaType[f]
     else:
         accepted_media = [MediaType.html, MediaType.json]
-        output_type = accept_media_type(
-            request.headers.get("accept", ""), accepted_media
+        output_type = (
+            accept_media_type(request.headers.get("accept", ""), accepted_media)
+            or MediaType.json
         )
 
     if output_type == MediaType.html:
@@ -448,6 +480,7 @@ def conformance(
             data,
             title="Conformance",
             template_name="conformance",
+            templates=titiler_templates,
         )
 
     return data

src/titiler/application/titiler/application/settings.py

@@ -27,6 +27,8 @@ class ApiSettings(BaseSettings):
     root_path: str = ""
     debug: bool = False
 
+    template_directory: Optional[str] = None
+
     disable_cog: bool = False
     disable_stac: bool = False
     disable_mosaic: bool = False

src/titiler/core/tests/test_factories.py

@@ -1706,11 +1706,28 @@ def test_algorithm():
 
     response = client.get("/algorithms")
     assert response.status_code == 200
-    assert "hillshade" in response.json()
+    algo_ids = [algo["id"] for algo in response.json()["algorithms"]]
+    assert "hillshade" in algo_ids
+
+    response = client.get("/algorithms", params={"f": "html"})
+    assert response.status_code == 200
+    assert "text/html" in response.headers["content-type"]
+
+    response = client.get("/algorithms", headers={"Accept": "text/html"})
+    assert response.status_code == 200
+    assert "text/html" in response.headers["content-type"]
 
     response = client.get("/algorithms/hillshade")
     assert response.status_code == 200
 
+    response = client.get("/algorithms/hillshade", params={"f": "html"})
+    assert response.status_code == 200
+    assert "text/html" in response.headers["content-type"]
+
+    response = client.get("/algorithms/hillshade", headers={"Accept": "text/html"})
+    assert response.status_code == 200
+    assert "text/html" in response.headers["content-type"]
+
 
 def test_path_param_in_prefix():
     """Test path params in prefix."""
@@ -1954,14 +1971,23 @@ def test_colormap_factory():
 
     response = client.get("/colorMaps")
     assert response.status_code == 200
-    assert "cust" in response.json()["colorMaps"]
-    assert "negative" in response.json()["colorMaps"]
-    assert "seq" in response.json()["colorMaps"]
-    assert "viridis" in response.json()["colorMaps"]
+    cmap_ids = [cm["id"] for cm in response.json()["colormaps"]]
+    assert "cust" in cmap_ids
+    assert "negative" in cmap_ids
+    assert "seq" in cmap_ids
+    assert "viridis" in cmap_ids
+
+    response = client.get("/colorMaps", headers={"Accept": "text/html"})
+    assert response.status_code == 200
+    assert "text/html" in response.headers["content-type"]
 
     response = client.get("/colorMaps/viridis")
     assert response.status_code == 200
 
+    response = client.get("/colorMaps/viridis", headers={"Accept": "text/html"})
+    assert response.status_code == 200
+    assert "text/html" in response.headers["content-type"]
+
     response = client.get("/colorMaps/cust")
     assert response.status_code == 200
 
@@ -1974,7 +2000,7 @@ def test_colormap_factory():
     response = client.get("/colorMaps/yo")
     assert response.status_code == 422
 
-    response = client.get("/colorMaps/viridis", params={"format": "png"})
+    response = client.get("/colorMaps/viridis", params={"f": "png"})
     assert response.status_code == 200
     meta = parse_img(response.content)
     assert meta["dtype"] == "uint8"
@@ -1983,7 +2009,7 @@ def test_colormap_factory():
     assert meta["height"] == 20
 
     response = client.get(
-        "/colorMaps/viridis", params={"format": "png", "orientation": "vertical"}
+        "/colorMaps/viridis", params={"f": "png", "orientation": "vertical"}
     )
     assert response.status_code == 200
     meta = parse_img(response.content)
@@ -1993,7 +2019,7 @@ def test_colormap_factory():
     assert meta["height"] == 256
 
     response = client.get(
-        "/colorMaps/viridis", params={"format": "png", "width": 1000, "height": 100}
+        "/colorMaps/viridis", params={"f": "png", "width": 1000, "height": 100}
     )
     assert response.status_code == 200
     meta = parse_img(response.content)
@@ -2002,7 +2028,7 @@ def test_colormap_factory():
     assert meta["width"] == 1000
     assert meta["height"] == 100
 
-    response = client.get("/colorMaps/cust", params={"format": "png"})
+    response = client.get("/colorMaps/cust", params={"f": "png"})
     assert response.status_code == 200
     meta = parse_img(response.content)
     assert meta["dtype"] == "uint8"
@@ -2011,7 +2037,7 @@ def test_colormap_factory():
     assert meta["height"] == 20
 
     response = client.get(
-        "/colorMaps/cust", params={"format": "png", "orientation": "vertical"}
+        "/colorMaps/cust", params={"f": "png", "orientation": "vertical"}
     )
     assert response.status_code == 200
     meta = parse_img(response.content)
@@ -2020,7 +2046,7 @@ def test_colormap_factory():
     assert meta["width"] == 20
     assert meta["height"] == 256
 
-    response = client.get("/colorMaps/negative", params={"format": "png"})
+    response = client.get("/colorMaps/negative", params={"f": "png"})
     assert response.status_code == 200
     meta = parse_img(response.content)
     assert meta["dtype"] == "uint8"
@@ -2029,7 +2055,7 @@ def test_colormap_factory():
     assert meta["height"] == 20
 
     response = client.get(
-        "/colorMaps/negative", params={"format": "png", "orientation": "vertical"}
+        "/colorMaps/negative", params={"f": "png", "orientation": "vertical"}
     )
     assert response.status_code == 200
     meta = parse_img(response.content)
@@ -2038,7 +2064,7 @@ def test_colormap_factory():
     assert meta["width"] == 20
     assert meta["height"] == 256
 
-    response = client.get("/colorMaps/seq", params={"format": "png"})
+    response = client.get("/colorMaps/seq", params={"f": "png"})
     assert response.status_code == 200
     meta = parse_img(response.content)
     assert meta["dtype"] == "uint8"
@@ -2047,7 +2073,7 @@ def test_colormap_factory():
     assert meta["height"] == 20
 
     response = client.get(
-        "/colorMaps/seq", params={"format": "png", "orientation": "vertical"}
+        "/colorMaps/seq", params={"f": "png", "orientation": "vertical"}
     )
     assert response.status_code == 200
     meta = parse_img(response.content)

src/titiler/core/titiler/core/algorithm/__init__.py

@@ -9,8 +9,11 @@
 from pydantic import ValidationError
 from typing_extensions import Annotated
 
-from titiler.core.algorithm.base import AlgorithmMetadata  # noqa
-from titiler.core.algorithm.base import BaseAlgorithm
+from titiler.core.algorithm.base import (  # noqa
+    AlgorithmMetadata,
+    AlgorithmtList,
+    BaseAlgorithm,
+)
 from titiler.core.algorithm.dem import Contours, HillShade, Slope, TerrainRGB, Terrarium
 from titiler.core.algorithm.index import NormalizedIndex
 from titiler.core.algorithm.math import _Max, _Mean, _Median, _Min, _Std, _Sum, _Var

src/titiler/core/titiler/core/algorithm/base.py

@@ -1,11 +1,13 @@
 """Algorithm base class."""
 
 import abc
-from typing import Dict, Optional, Sequence
+from typing import Dict, List, Optional, Sequence
 
 from pydantic import BaseModel
 from rio_tiler.models import ImageData
 
+from titiler.core.models.common import Link
+
 
 class BaseAlgorithm(BaseModel, metaclass=abc.ABCMeta):
     """Algorithm baseclass.
@@ -38,3 +40,17 @@ class AlgorithmMetadata(BaseModel):
     inputs: Dict
     outputs: Dict
     parameters: Dict
+
+
+class AlgorithmRef(BaseModel):
+    """AlgorithmRef model."""
+
+    id: str
+    title: Optional[str] = None
+    links: List[Link]
+
+
+class AlgorithmtList(BaseModel):
+    """AlgorithmList model."""
+
+    algorithms: List[AlgorithmRef]