This is the multi-page printable view of this section. .

Return to the regular view of this page.

Reference

Exact routes, parameters, features, defaults, and operational settings.

1: Example HTTP API
2: Cargo features
3: Example server configuration

Use this section when you need exact supported values and defaults.

1 - Example HTTP API

Routes, tile path format, style parameters, and response behavior.

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.

Style parameters

Parameter	Repeat	Default or example	Meaning
`bidx`	yes	`bidx=1&bidx=2&bidx=3`	1-indexed source-band selection.
`expression`	no	`(b5-b4)/(b5+b4)`	Arithmetic expression producing one derived band.
`rescale`	yes	`0,3000`	Explicit per-band `min,max` range; highest stretch priority.
`stretch`	no	`minmax`, `percent`, `stddev`	Automatic stretch mode.
`pc`	no	`2,98`	Percentile cut used by `stretch=percent`.
`sigma`	no	`2.0`	Standard-deviation multiplier.
`nodata`	no	`nan`, `inf`, `-inf`, or float	Override the dataset nodata value.
`colormap_name`	no	`viridis`	Built-in single-band color ramp.
`color_formula`	no	`gamma RGB 1.5`	Supported rio-color operation sequence.
`resampling`	no	`nearest`	Source read or resize kernel.
`reproject`	no	`nearest`	Warp-time resampling kernel.
`tilesize`	no	`256`	One of 64, 128, 256, 512, or 1024.
`format`	no	`png`	Optional format assertion; must agree with the path extension.

Resampling kernels are nearest, bilinear, cubic, cubic_spline, lanczos, and average. Average computes a box mean for downsampling and uses nearest behavior when upsampling.

The mosaic tile route additionally accepts pixel_selection=first, highest, lowest, mean, or median. The default is first.

Responses

200 OK returns encoded image bytes.
204 No Content means the coordinate is valid but fully outside the source dataset or projection domain.
Invalid style values and malformed coordinates return a client error with a structured library error behind it.

The default output size is 256×256, chosen for broad XYZ-client compatibility.

2 - Cargo features

Compile-time capabilities and their dependency effects.

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.

3 - Example server configuration

Environment variables accepted by the included Axum server.

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.

The decode-task and tile-task values tune single-COG work, but are not a single process-wide CPU cap. The command-line default COG uses separate limiters; lazily selected local datasets share one limiter sized to the larger value; mosaics own their own limiter. The example server does not expose environment variables for MosaicConfig fields such as max_assets_per_tile.

Example

ASYNC_GEOTIFF_BIND=0.0.0.0:8080 \
ASYNC_GEOTIFF_BLOCK_CACHE_MB=1024 \
ASYNC_GEOTIFF_MAX_DECODE_TASKS=8 \
ASYNC_GEOTIFF_MAX_TILE_TASKS=8 \
ASYNC_GEOTIFF_PREFETCH_RING=0 \
ASYNC_GEOTIFF_SLOW_TILE_MS=500 \
RUST_LOG=async_geotiff=info \
  cargo run --release --example serve -- https://example.com/cog.tif

Invalid numeric values fail at process startup instead of being silently clamped.