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
4: Releases and crates.io

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 style extensions are png and feature-gated lossless webp.

Raster Style Q3

Both tile routes require complete Q3: version=3.0&type=.... Unknown fields, old parameters, and unimplemented capabilities fail explicitly. dataset, mode, and _v are separate singleton context keys; asset URLs are not styles.

Parameter	Repeat	Meaning
`version` / `type`	no	`3.0` and gray/rgb/pseudocolor/categorized/single_color.
`bidx`	yes	One-based source bands; RGB requires exactly three.
`expression`	no	One expression for gray, three separated by semicolons for RGB; excludes bidx.
`method` / `rescale`	ranges only	none, linear, minmax, percentile, stddev, histogram_equalization, curve; see the styling guide for parameters and the shared statistics grid.
`colormap_name` / `colormap`	no	Pseudocolor maps; native tables use exact values or half-open intervals.
`nodata`	no	Finite number or nan.
`color_formula`	no	Supported Gamma operations, applied in order.
`opacity`	no	0–1; default 1.
`resampling` / `reproject`	no	nearest, bilinear, cubic, cubic_spline, lanczos, average.
`extensions`	no	JSON array of exact versioned Schema URLs; percent-encode the value.
`extension_fields`	no	JSON object containing `raster:tile` and/or `raster:mosaic`; percent-encode the value.

raster:tile supports tilesize (64, 128, 256, 512, 1024), format (png, or webp with lossless: true); the format must match the path. raster:mosaic requires pixel_selection and stage, with optional rank_channel for highest/lowest. Declare the Tile 1.0.0 and/or Mosaic 1.0.0 Schema URLs. The former tile/mosaic short parameters are rejected.

Encode literal + as %2B in raw Q3. Do not decode before concatenating query fragments. See the styling guide for semantics and limits.

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 the low-level JPEG encoder; Raster Style requests currently reject JPEG.
`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

# 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_MAX_IN_FLIGHT_REQUESTS`	`64`	Shared tile request admission limit; must be positive.
`ASYNC_GEOTIFF_REQUEST_TIMEOUT_MS`	`30000`	Tile request timeout, including dataset lookup/opening; must be positive.
`ASYNC_GEOTIFF_PREFETCH_RING`	`1`	Native-block rings prefetched for default/local single-COG readers; `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.

The request admission limit and timeout apply to the command-line default COG, lazy ?dataset= selections, MosaicJSON and STAC tiles. These paths share the configured library admission limiter, including when running CPU work outlives a cancelled HTTP request. Increasing the HTTP settings also increases the effective library settings; no additional fixed 64-request admission cap or 30-second total request deadline is retained. Transport connection/read timeouts remain independent. Excess requests return 503 and expired requests return 504.

Deadline, cancellation and overload classifications are preserved through mosaic asset opening and wrapped TIFF errors: they return 504, 408 and 503 respectively, while ordinary HTTP asset errors still use redacted diagnostics.

Prefetch tuning applies to both single-COG entrypoints. Mosaic asset readers keep their existing prefetch default of zero; the server does not expose a Mosaic prefetch setting.

HTTP mosaic asset errors omit URL userinfo, query strings and fragments from their diagnostic labels. Store-backed object keys retain their existing key semantics. Keep source credentials in server-side configuration; tile callers do not need the original asset URL.

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.

4 - Releases and crates.io

Package contents, verification and publication of async-geotiff.

The package name is async-geotiff; Rust imports use async_geotiff. Version 0.13.0 prepares the first crates.io distribution. Older GitHub releases remain available as source archives. Making the GitHub repository public does not itself publish a crate; Cargo uploads a separate .crate archive.

Package contents

Cargo.toml uses an explicit include list: library sources, examples and their HTML viewers, tests and small reproducible fixtures, the resampler benchmark, manifests, READMEs, changelog and the MIT license text. Tests and fixtures stay together because unit tests and examples embed fixture bytes. website/, scripts, agent instructions, local imagery and generated reports are not in the registry package.

benches/resampler_bench.rs measures six useful kernel cases and is retained. scripts/run_load_audit.py records bounded local latency and peak RSS; it is retained in Git, with output under ignored target/load-audit/. Historical reviews and machine-specific results are available in Git history through 7170204, rather than in the current source tree. See the workload guide for reproducible measurements.

Verify a version

Update Cargo.toml, Cargo.lock, the changelog and both website languages. Run the five feature configurations documented in AGENTS.md, including all-target and documentation tests, plus the viewer and strict Hugo builds. Then inspect and compile the actual registry archive:

cargo +stable package --list --locked
cargo +stable publish --dry-run --locked

The .crate file is generated under target/package/. For local review before committing, add --allow-dirty; omit it for the final publication. The docs.rs build disables default features to avoid requiring native PROJ while documenting mosaics, STAC and image encoders. Applications still get the normal default features.

Publish

After verification, commit the release and push the matching version tag:

git tag v0.13.0
git push origin main v0.13.0

The Release workflow validates the tag against Cargo.toml, installs native build dependencies, runs tests, verifies the archive and attaches it to a GitHub Release. A successful release workflow deploys the exact commit’s documentation to Cloudflare Pages. Pushing a tag does not upload to crates.io.

For the registry upload, use a crates.io account with a verified email and a token allowed to publish this crate:

cargo login
cargo +stable publish --locked

Alternatively, configure the repository secret CARGO_REGISTRY_TOKEN, open the Release workflow in GitHub Actions, select the matching version tag, and enable publish_to_crates_io. The workflow repeats verification before uploading. Do not paste tokens into commands, logs or committed files.

Published versions cannot be overwritten; verify the contents and version before uploading. See the Cargo publishing guide.

Upgrade from 0.12

Raster Style remains SDK 0.4.0 / protocol 3.0/Q3. For custom STAC clients, replace the built-client with_http_client constructor with with_http_client_builder, passing a configured reqwest 0.11 ClientBuilder. The old constructor returns an error. See mosaics for the authentication and redirect contract. The release also fixes independent mask grids, polar coverage, Alpha point queries, exact-grid CubicSpline, extreme finite resampling, histogram counts and server configuration propagation.