Reference on 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.

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.

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.