async-geotiff

Example HTTP API

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

The HTTP API belongs to examples/serve.rs; it is not part of the library’s dependency surface.

Routes

Method and path	Purpose
`GET /tiles/{tms}/{z}/{x}/{y}.{ext}`	Render a tile from the selected single COG.
`GET /mosaic/tiles/{tms}/{z}/{x}/{y}.{ext}`	Render a tile from the configured mosaic or STAC source.
`GET /datasets`	List local TIFF files discovered under `data/`.
`GET /cache/stats`	Return decoded-block cache statistics.
`GET /formats`	Return output formats compiled into the server.
`GET /bounds`	Return bounds used by the example viewers.
`GET`, `HEAD /data/{name}`	Serve a discovered local TIFF with range support.

Supported TMS names are WebMercatorQuad and WorldCRS84Quad. Supported extensions are png, feature-gated webp, and feature-gated jpg/jpeg.

Requirements

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

Library and examples

Rust 1.88 or newer, matching Cargo.toml.
The default feature set requires system libproj 9.x.
Git is required when working from the repository.

On macOS:

brew install proj

On Debian or Ubuntu:

sudo apt install libproj-dev libsqlite3-dev libtiff-dev clang

On other platforms, install libproj with the platform’s supported package manager or build without the default features. The project does not currently provide platform-specific Windows installation commands.

Styling and band math

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

The same TileStyle model serves the Rust API and the example server’s query string. Styles are validated before expensive COG reads and rendering work.

Common recipes

Natural-color RGB from three bands:

bidx=1&bidx=2&bidx=3&rescale=0,3000&rescale=0,3000&rescale=0,3000

Single-band color ramp:

bidx=1&colormap_name=viridis&rescale=0,3000

Percentile stretch:

stretch=percent&pc=2,98

Average downsampling and bilinear reprojection:

resampling=average&reproject=bilinear

Stretch behavior

For non-U8 data, the effective value range is selected in this order:

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.

Cargo features

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

Feature	Default	Effect
`proj`	yes	Enables general CRS transformation through system `libproj`.
`mosaic`	yes	Enables `MosaicTiler`, `MosaicSource`, MosaicJSON, and async asset fan-out.
`webp`	no	Enables lossless WebP encoding through `image`.
`jpeg`	no	Enables JPEG encoding; alpha is flattened because JPEG has no alpha channel.
`stac`	no	Adds the STAC client and implies `mosaic`.
`perf-tracing`	no	Emits detailed internal timing events.
`tokio-console`	no	Enables Tokio Console integration and implies `perf-tracing`.

Examples:

# Default: projection + mosaics + PNG
cargo build --release

# Minimal library without general PROJ or mosaics
cargo build --release --no-default-features

# Example server with all image formats
cargo run --release --example serve --features webp,jpeg

# STAC-backed mosaic demo
cargo run --release --example serve --features stac

# Full verification surface
cargo test --all-features --locked

The serve, mosaic_source, and mosaic_json examples require the mosaic feature. PNG support is always compiled.

Mosaics and STAC

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

The default-enabled mosaic Cargo feature adds MosaicTiler and the MosaicSource trait; applications that do not need mosaics can disable default features. Because that also disables proj, use --no-default-features --features proj when general CRS transformation is still required. The source maps a tile coordinate to assets; the tiler opens and warps those assets, reduces overlapping pixels, and renders the composite once.

MosaicJSON

Run the embedded example or pass a MosaicJSON file:

Quick start

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

Clone and run

git clone https://github.com/mapseekai/async-geotiff-rs.git
cd async-geotiff-rs
COG_URL='https://raw.githubusercontent.com/cogeotiff/rio-tiler/0b08b7f35a8b639cee2f35a0cb565034f7b55bfd/tests/fixtures/cog.tif'
cargo run --release --example serve -- "$COG_URL"

The pinned 800 KiB rio-tiler fixture is a public, range-capable COG intended for tests and first-run verification. Replace it with your own COG after the smoke test. The server listens on 127.0.0.1:8080 by default and prints the available viewer and tile URLs when startup completes.

Example server configuration

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

These variables configure cargo run --example serve. They are example-server contracts, not global library configuration.

Variable	Default	Meaning
`ASYNC_GEOTIFF_BIND`	`127.0.0.1:8080`	Socket address for the HTTP server.
`ASYNC_GEOTIFF_BLOCK_CACHE_MB`	`512`	Shared decoded-block cache capacity in MiB; must be positive.
`ASYNC_GEOTIFF_MAX_DECODE_TASKS`	available parallelism	Maximum concurrent decode/stitch CPU jobs; must be positive.
`ASYNC_GEOTIFF_MAX_TILE_TASKS`	available parallelism	Maximum concurrent tile warp/render CPU jobs; must be positive.
`ASYNC_GEOTIFF_PREFETCH_RING`	`1`	Number of native-block rings prefetched around a read; `0` disables it.
`ASYNC_GEOTIFF_SLOW_TILE_MS`	unset	Emit a slow-tile warning above this positive millisecond threshold.
`ASYNC_GEOTIFF_MOSAIC`	unset	Path to a MosaicJSON file loaded at startup.
`ASYNC_GEOTIFF_STAC_URL`	unset	Fixed STAC API URL; requires the `stac` feature and the next two variables.
`ASYNC_GEOTIFF_STAC_COLLECTION`	unset	Fixed STAC collection ID.
`ASYNC_GEOTIFF_STAC_ASSET_KEY`	unset	Fixed STAC COG asset key.
`ASYNC_GEOTIFF_TOKIO_CONSOLE`	off	Enable Tokio Console with `1`, `true`, `yes`, or `on` when compiled with `tokio-console`.
`RUST_LOG`	`async_geotiff=debug,warn`	Standard tracing filter for the example server.

ASYNC_GEOTIFF_MOSAIC and the STAC configuration are mutually exclusive. All three STAC variables must be supplied together.

Library usage

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

The repository currently sets publish = false, so another local project uses a path dependency while developing. Create the application next to the clone, then replace the relative path if your directories differ:

# Starting inside the async-geotiff-rs checkout:
cd ..
cargo new async-geotiff-demo
cd async-geotiff-demo

[dependencies]
async-geotiff = { path = "../async-geotiff-rs" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

To avoid the system libproj dependency while retaining the mosaic APIs used by the example server, set default-features = false, features = ["mosaic"] on the path dependency. General CRS transformations will then be unavailable.

Production operation

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

Share one cache

The default decoded-block cache budget is 512 MiB. A server with many readers should inject the same Arc<BlockCache> into every reader and mosaic. Give each distinct COG a stable source ID so cache entries cannot collide.

This budget covers resident decoded blocks in the cache, not total process RSS. In-flight compressed bytes, decode and warp buffers, encoded responses, reader metadata, and mosaic reducer state are additional memory. In particular, Median retains every contributing image until reduction completes.