TiTiler

The titiler.core package is organized into several functional modules:

• algorithm/: Contains algorithms for data processing, including base.py (ABC Base Class for custom algorithms), dem.py (elevation data), and index.py (band index algorithms).
• models/: Pydantic models for responses, including mapbox.py (Mapbox TileJSON) and OGC.py (Open GeoSpatial Consortium models like TileMatrixSets).
• resources/: Enumerations (e.g., enums.py) and custom Starlette responses (responses.py).
• templates/: HTML/XML templates for a Leaflet-based map viewer (map.html) and OGC WMTS documents (wmts.xml).
• factory.py: Contains the TilerFactory used to generate dynamic tiler endpoints.
• routing.py: Custom APIRoute class.
• dependencies.py: FastAPI dependencies.
• errors.py: Error handler factory.
• middleware.py: Starlette middlewares.
• telemetry.py: OpenTelemetry tracing functions.
• utils.py: Utility functions.

The response model for the mosaic /point endpoint has been completely restructured in TiTiler 1.0. Instead of a list of tuples, it now returns an assets list containing AssetPoint objects. Each asset object contains name, values, band_names, and an optional band_descriptions field.

# Before (0.26)
response = {
    "coordinates": [-122.5, 37.5],
    "values": [
        ("asset1", [100.0, 200.0], ["B1", "B2"]),
        ("asset2", [150.0, 200.0], ["B1", "B2"])
    ]
}

# Now (1.0)
response = {
    "coordinates": [-122.5, 37.5],
    "assets": [
        {
            "name": "asset1",
            "values": [100.0, 200.0],
            "band_names": ["B1", "B2"],
            "band_descriptions": None
        },
        {
            "name": "asset2",
            "values": [150.0, 200.0],
            "band_names": ["B1", "B2"],
            "band_descriptions": None
        }
    ]
}

Since aiocache.cached does not natively support non-async methods, you can implement a custom cached class that inherits from aiocache.cached. This implementation uses starlette.concurrency.run_in_threadpool to safely execute synchronous functions in a thread pool, ensuring they don't block the event loop.

Key Features of this implementation:

• Async/Sync Support: Detects if the function is a coroutine and handles it accordingly.
• Cache Hit Headers: Automatically adds an X-Cache: HIT header to starlette.responses.Response objects when a cache hit occurs.
• Configurable Write: Supports cache_read, cache_write, and aiocache_wait_for_write (to allow fire-and-forget cache updates).

import asyncio
import aiocache
from starlette.concurrency import run_in_threadpool
from starlette.responses import Response
from fastapi.dependencies.utils import is_coroutine_callable

class cached(aiocache.cached):
    async def get_from_cache(self, key):
        try:
            value = await self.cache.get(key)
            if isinstance(value, Response):
                value.headers["X-Cache"] = "HIT"
            return value
        except Exception:
            aiocache.logger.exception("Couldn't retrieve %s, unexpected error", key)

    async def decorator(self, f, *args, cache_read=True, cache_write=True, aiocache_wait_for_write=True, **kwargs):
        key = self.get_cache_key(f, args, kwargs)

        if cache_read:
            value = await self.get_from_cache(key)
            if value is not None:
                return value

        if is_coroutine_callable(f):
            result = await f(*args, **kwargs)
        else:
            result = await run_in_threadpool(f, *args, **kwargs)

        if cache_write:
            if aiocache_wait_for_write:
                await self.set_in_cache(key, result)
            else:
                asyncio.ensure_future(self.set_in_cache(key, result))

        return result

In titiler Factories, dependencies are used to define the inputs for each endpoint, which also automatically generates the corresponding OpenAPI documentation.

To create a custom dependency, define a dataclass that inherits from titiler.core.dependencies.DefaultDependency. You can use typing.Annotated combined with FastAPI's Query or Path to add descriptions and constraints to your parameters. These parameters will then be injected into your FastAPI endpoint using Depends().

from typing import Annotated
from dataclasses import dataclass
from fastapi import Depends, FastAPI, Query
from titiler.core.dependencies import DefaultDependency
from rio_tiler.io import Reader

@dataclass
class ImageParams(DefaultDependency):
    max_size: Annotated[
        int, Query(description="Maximum image size to read onto.")
    ] = 1024

app = FastAPI()

@app.get("/preview.png")
def preview(
    url: str = Query(..., description="data set URL"),
    params: ImageParams = Depends(),
):
    with Reader(url) as cog:
        # Use .as_dict() to pass parameters to the reader
        img = cog.preview(**params.as_dict())
    ...

TiTiler is designed for Dynamic Tiling, which differs from traditional Static Tiling in how raster data is prepared for web map clients.

Static Tiling

In static tiling, tiles are pre-rendered files stored on a disk or CDN. The process involves:

1. Rescaling non-Uint8 data to an integer range (0-255).
2. Reprojecting data to Web Mercator (or the target projection).
3. Splitting data into fixed tile sizes (e.g., 256x256 or 512x512) across multiple zoom levels.

Pros: Fast loading; simple to serve via web servers or CDNs. Cons: High storage overhead (many tiny files); fixed parameters (projection, rescaling) that cannot be changed without re-rendering; potential for serving tiles that are never actually viewed.

Dynamic Tiling (TiTiler)

Dynamic tiling uses a tile server to access raw data (like Cloud Optimized Geotiffs - COGs) and apply operations on the fly. The process involves:

1. Opening the file and reading internal metadata.
2. Reading only the specific internal parts needed for the requested tile.
3. Applying data rescaling, colormaps, and image encoding (JPEG, PNG, WEBP) dynamically.

Pros: Access to raw data; support for multiple projections; user-defined rescaling and colormaps; band selection and math; dynamic mosaics with multiple datasets. Cons: Higher latency (requires multiple GET requests to fetch data parts); increased server complexity; harder to update (requires re-writing the source COG).