这是本节的多页打印视图。 .

参考手册

准确记录路由、参数、features、默认值和运行配置。

1: 示例 HTTP API
2: Cargo features
3: 示例服务配置

需要查询确切支持值和默认行为时，请使用本节。

1 - 示例 HTTP API

路由、瓦片路径、样式参数与响应行为。

HTTP API 属于 examples/serve.rs，不会进入库本身的依赖表面。

路由

方法与路径	用途
`GET /tiles/{tms}/{z}/{x}/{y}.{ext}`	从选中的单个 COG 渲染瓦片。
`GET /mosaic/tiles/{tms}/{z}/{x}/{y}.{ext}`	从配置的 mosaic 或 STAC 数据源渲染瓦片。
`GET /datasets`	列出 `data/` 下发现的 TIFF 文件。
`GET /cache/stats`	返回解码块缓存统计。
`GET /formats`	返回当前服务编译支持的输出格式。
`GET /bounds`	返回示例查看器使用的边界。
`GET`、`HEAD /data/{name}`	通过范围请求提供本地 TIFF。

支持的 TMS 名称是 WebMercatorQuad 和 WorldCRS84Quad。扩展名支持 png，以及 feature 控制的 webp、jpg、jpeg。

样式参数

参数	可重复	默认值或示例	含义
`bidx`	是	`bidx=1&bidx=2&bidx=3`	从 1 开始的源波段选择。
`expression`	否	`(b5-b4)/(b5+b4)`	生成一个派生波段的算术表达式。
`rescale`	是	`0,3000`	显式逐波段 `min,max`，拉伸优先级最高。
`stretch`	否	`minmax`、`percent`、`stddev`	自动拉伸模式。
`pc`	否	`2,98`	`stretch=percent` 使用的百分位裁剪。
`sigma`	否	`2.0`	标准差倍数。
`nodata`	否	`nan`、`inf`、`-inf` 或浮点数	覆盖数据集 nodata。
`colormap_name`	否	`viridis`	内置单波段色带。
`color_formula`	否	`gamma RGB 1.5`	支持的 rio-color 操作序列。
`resampling`	否	`nearest`	源读取或缩放重采样核。
`reproject`	否	`nearest`	重投影阶段的重采样核。
`tilesize`	否	`256`	64、128、256、512 或 1024。
`format`	否	`png`	可选格式断言，必须与路径扩展名一致。

重采样核包括 nearest、bilinear、cubic、cubic_spline、lanczos 和 average。average 下采样时计算盒式均值，上采样时使用 nearest 行为。

镶嵌瓦片路由还接受 pixel_selection=first、highest、lowest、mean 或 median，默认值为 first。

响应

200 OK 返回编码后的图像字节。
204 No Content 表示坐标有效，但完全位于数据集或投影有效范围之外。
无效样式值与格式错误的坐标会返回客户端错误，底层保留结构化库错误。

默认输出尺寸为 256×256，以兼容更多 XYZ 客户端。

2 - Cargo features

编译期能力及其依赖影响。

Feature	默认	作用
`proj`	是	通过系统 `libproj` 启用通用 CRS 转换。
`mosaic`	是	启用 `MosaicTiler`、`MosaicSource`、MosaicJSON 和异步资产扇出。
`webp`	否	通过 `image` 启用无损 WebP 编码。
`jpeg`	否	启用 JPEG；由于 JPEG 没有 alpha，透明度会被压平。
`stac`	否	添加 STAC 客户端，并隐含启用 `mosaic`。
`perf-tracing`	否	发出更详细的内部耗时事件。
`tokio-console`	否	启用 Tokio Console，并隐含启用 `perf-tracing`。

示例：

# 默认：投影 + 镶嵌 + PNG
cargo build --release

# 不包含通用 PROJ 与镶嵌的最小库
cargo build --release --no-default-features

# 包含全部图像格式的示例服务
cargo run --release --example serve --features webp,jpeg

# STAC 镶嵌示例
cargo run --release --example serve --features stac

# 完整验证面
cargo test --all-features --locked

serve、mosaic_source 和 mosaic_json 示例要求启用 mosaic。PNG 始终可用。

3 - 示例服务配置

内置 Axum 服务接受的环境变量。

以下变量配置 cargo run --example serve。它们是示例服务约定，不是库的全局配置。

变量	默认值	含义
`ASYNC_GEOTIFF_BIND`	`127.0.0.1:8080`	HTTP 服务监听地址。
`ASYNC_GEOTIFF_BLOCK_CACHE_MB`	`512`	共享解码块缓存容量（MiB），必须为正数。
`ASYNC_GEOTIFF_MAX_DECODE_TASKS`	可用并行度	最大并发解码/拼接 CPU 任务数，必须为正数。
`ASYNC_GEOTIFF_MAX_TILE_TASKS`	可用并行度	最大并发重投影/渲染 CPU 任务数，必须为正数。
`ASYNC_GEOTIFF_PREFETCH_RING`	`1`	围绕读取范围预取的原生块圈数；`0` 为关闭。
`ASYNC_GEOTIFF_SLOW_TILE_MS`	未设置	超过此正整数毫秒阈值时发出慢瓦片警告。
`ASYNC_GEOTIFF_MOSAIC`	未设置	启动时加载的 MosaicJSON 文件路径。
`ASYNC_GEOTIFF_STAC_URL`	未设置	固定 STAC API URL；需要 `stac` 及后两个变量。
`ASYNC_GEOTIFF_STAC_COLLECTION`	未设置	固定 STAC collection ID。
`ASYNC_GEOTIFF_STAC_ASSET_KEY`	未设置	固定 STAC COG 资产 key。
`ASYNC_GEOTIFF_TOKIO_CONSOLE`	关闭	使用 `tokio-console` 编译时，以 `1`、`true`、`yes` 或 `on` 启用 Tokio Console。
`RUST_LOG`	`async_geotiff=debug,warn`	示例服务的标准 tracing 过滤器。

ASYNC_GEOTIFF_MOSAIC 与 STAC 配置互斥；三个 STAC 变量必须一起提供。

解码与瓦片任务变量用于调优单 COG 工作，但不构成一个进程级 CPU 上限：命令行默认 COG 使用独立 limiter；延迟选择的本地数据集共享一个取两者较大值的 limiter；mosaic 拥有自己的 limiter。示例服务没有为 max_assets_per_tile 等 MosaicConfig 字段提供环境变量。

示例

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

无效数值会使进程在启动时失败，而不会被静默修正。