Architecture
Follow a tile from an HTTP request or library call to encoded bytes.
The library separates asynchronous range I/O from CPU-heavy decode, warp, render, and encode work. Applications compose the public layers they need.
Main components
| Component | Responsibility |
|---|---|
CogReader | Open a COG, read metadata and overviews, select and stitch native blocks, and sample points or windows. |
BlockCache | Share decoded native blocks across readers under one byte budget; coalesce concurrent cold fetches. |
Tiler | Plan a tile, choose an overview, read the source window, warp when required, and render encoded bytes. |
TileStyle | Parse and validate titiler-style query parameters before rendering. |
MosaicTiler | Find assets, open readers through a pool, warp each asset, reduce overlapping pixels, and render once. |
CpuLimiter | Bound CPU-heavy blocking work across readers and tilers. |
Tile data flow
TileCoordidentifies a tile in a supported TileMatrixSet.Tilercomputes the destination bounds and checks whether they intersect the source dataset.- It selects an overview whose ground resolution is appropriate for the requested tile.
CogReaderloads missing native blocks through range requests and reuses cached blocks where possible.- Same-CRS tiles use an affine fast path. Cross-CRS tiles use an inverse warp;
EPSG:4326 ↔ EPSG:3857 has a closed-form fast path, while other pairs require
the
projfeature. - The render pipeline applies nodata, scaling, optional band math, rescaling, colormaps or RGB composition, and the requested output encoder.
Concurrency model
Tokio drives asynchronous metadata and byte-range I/O. Decode, stitch, warp,
reduction, render, and encode jobs run through spawn_blocking behind a
semaphore. Applications can inject one Arc<BlockCache> across single-COG and
mosaic readers to avoid multiplying decoded-cache budgets. They can also inject
one CpuLimiter across non-mosaic CogReader/Tiler instances. Current
MosaicTiler uses its own internal limiter and cannot join that permit budget,
so mixed traffic has no automatic process-wide CPU cap.