What is async-geotiff?

Mon, 01 Jan 0001 00:00:00 +0000

async-geotiff is a Rust library for turning Cloud-Optimized GeoTIFFs (COGs) into styled XYZ map tiles. It reads only the byte ranges needed for a tile, decodes native TIFF blocks, optionally reprojects them, applies a rendering style, and encodes the result.

Core capabilities

Async COG access over HTTPS or any caller-configured object_store backend.
Shared, byte-bounded caching of decoded native TIFF blocks.
WebMercatorQuad (EPSG:3857) and WorldCRS84Quad (EPSG:4326) tile grids.
U8, U16, I16, U32, I32, F32, and F64 source pixels.
Nearest, bilinear, cubic, cubic-spline, Lanczos, and average resampling.
Rescaling, colormaps, RGB composition, color formulas, and arithmetic band math.
PNG output, plus feature-gated WebP and JPEG output.
Multi-asset mosaics backed by MosaicJSON, STAC, or a custom source.

What the library deliberately does not own

No GDAL runtime. TIFF I/O uses async-tiff and object_store. The default proj feature uses the system libproj library only for coordinate transformations that do not have a built-in fast path.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

The library separates asynchronous range I/O from CPU-heavy decode, warp, render, and encode work. Applications compose the public layers they need.

flowchart LR
 Client[HTTP client or Rust caller] --> Style[TileStyle]
 Client --> Tiler[Tiler]
 Tiler --> Grid[TileMatrixSet]
 Tiler --> Reader[CogReader]
 Reader --> Store[object_store / HTTP range reads]
 Reader <--> Cache[Shared BlockCache]
 Reader --> CPU[CpuLimiter + spawn_blocking]
 CPU --> Warp[Warp and resampling]
 Warp --> Render[Rescale / colormap / composite]
 Style --> Render
 Render --> Encode[PNG / WebP / JPEG]
 Encode --> Result[Option&lt;Bytes&gt;]
 Mosaic[MosaicTiler] --> ReaderPool[ReaderPool]
 ReaderPool --> Reader
 Mosaic --> Render

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

TileCoord identifies a tile in a supported TileMatrixSet.
Tiler computes the destination bounds and checks whether they intersect the source dataset.
It selects an overview whose ground resolution is appropriate for the requested tile.
CogReader loads 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 proj feature.
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.