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

参考手册

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

1: 示例 HTTP API
2: Cargo features
3: 示例服务配置
4: 版本发布与 crates.io

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

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。

Raster Style Q3

两条瓦片路由只接受完整 Q3：version=3.0&type=...。未知字段、旧格式和未实现能力报错。 dataset、mode、_v 是独立请求上下文，不能重复；资产地址不属于样式。

参数	是否可重复	含义
`version` / `type`	否	`3.0` 与 gray/rgb/pseudocolor/categorized/single_color。
`bidx`	是	从 1 开始的源波段索引，RGB 恰好三个。
`expression`	否	灰度一个表达式；RGB 三个分号分隔的表达式；与 bidx 互斥。
`method` / `rescale`	范围可重复	none、linear、minmax、percentile、stddev、histogram_equalization、curve；参数与共享统计网格见样式指南。
`colormap_name` / `colormap`	否	伪彩色色表；原生色表是精确值或半开区间。
`nodata`	否	有限数值或 nan。
`color_formula`	否	已支持 Gamma 操作，按顺序应用。
`opacity`	否	0–1，默认 1。
`resampling` / `reproject`	否	nearest、bilinear、cubic、cubic_spline、lanczos、average。
`extensions`	否	精确版本 Schema URL 的 JSON 数组，需百分号编码。
`extension_fields`	否	包含 `raster:tile`、`raster:mosaic` 的 JSON 对象，需百分号编码。

raster:tile 支持 tilesize（64、128、256、512、1024）、format（png，或带 lossless: true 的 webp）；格式必须与路径一致。raster:mosaic 必须提供 pixel_selection、stage，highest/lowest 还可提供 rank_channel。在 extensions 声明对应的 Tile 1.0.0 或 Mosaic 1.0.0 Schema URL。旧的瓦片与镶嵌短参数一律拒绝。

原始 Q3 中 + 必须编码为 %2B；不能先解码后直接拼接。样式语义与限制见样式指南。

响应

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

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

2 - Cargo features

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

Feature	默认	作用
`proj`	是	通过系统 `libproj` 启用通用 CRS 转换。
`mosaic`	是	启用 `MosaicTiler`、`MosaicSource`、MosaicJSON 和异步资产扇出。
`webp`	否	通过 `image` 启用无损 WebP 编码。
`jpeg`	否	启用底层 JPEG 编码器；Raster Style 样式请求暂不支持 JPEG。
`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

# 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_MAX_IN_FLIGHT_REQUESTS`	`64`	瓦片请求共享准入上限，必须为正数。
`ASYNC_GEOTIFF_REQUEST_TIMEOUT_MS`	`30000`	含数据集查找/打开的瓦片请求超时，单位毫秒，必须为正数。
`ASYNC_GEOTIFF_PREFETCH_RING`	`1`	默认/本地单 COG reader 的原生块预取圈数；`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 字段提供环境变量。

请求准入与超时配置同时作用于命令行默认 COG、延迟加载的 ?dataset=、MosaicJSON 和 STAC 瓦片。这些路径共享配置后的库准入 limiter；HTTP 请求取消后仍在运行的 CPU 工作也受其约束。调高 HTTP 配置时，库层配置同步生效，不再额外保留固定的 64 请求准入上限或 30 秒总请求时限。传输层连接/读取超时仍独立生效。超额请求返回 503，超时请求返回 504。

这些错误类型也会在 Mosaic 资产打开和 TIFF 错误包装后保留：请求超时、取消和超载分别返回 504、408 和 503；普通 HTTP 资产错误仍使用脱敏后的诊断信息。

预取配置对两种单 COG 入口均生效。Mosaic 资产 reader 保留原有的零预取默认值，服务没有提供 Mosaic 预取配置。

HTTP Mosaic 资产错误的诊断标签不包含 URL 用户名/密码、查询串或 fragment。 Store backend 的对象 key 保持既有语义。源凭据保留在服务端配置中；瓦片调用者无需提供原始资产 URL。

示例

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

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

4 - 版本发布与 crates.io

async-geotiff 的打包范围、验证和发布步骤。

包名是 async-geotiff，Rust 导入名是 async_geotiff。0.13.0 为首次 crates.io 分发做准备；旧 GitHub Release 仍提供源码包。GitHub 仓库公开并不会自动发布 crate， Cargo 会单独上传 .crate 归档。

打包范围

Cargo.toml 明确列出包含内容：核心源码、examples 及 HTML 查看器、tests 和小型可重建 fixture、重采样基准、Cargo 清单、README、变更日志和 MIT 许可全文。测试与 fixture 一起保留，因为单元测试和示例会嵌入 fixture 字节。 website、脚本、Agent 指令、本地影像和生成报告不进入注册表包。

benches/resampler_bench.rs 有六组有效的重采样核对照，因此保留。 scripts/run_load_audit.py 测量本地有界延迟和峰值 RSS，在 Git 中保留，默认结果写入忽略的 target/load-audit/。历史审查与机器实测可在截至 7170204 的 Git 历史中查阅，不再放在当前源代码树中。复现见本地负载测量。

发布前验证

更新 Cargo.toml、Cargo.lock、变更日志和中英文网站。按 AGENTS.md 跑五组 feature 的全目标与文档测试，以及 viewer 和严格 Hugo 构建，然后检查实际注册表包：

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

归档位于 target/package/。提交前本地预览可加 --allow-dirty，正式发布不加。 docs.rs 构建关闭默认 feature，避免要求原生 PROJ，同时生成 mosaic、STAC 和编码器文档；应用使用本库时仍有正常的默认 feature。

发布

验证后提交发布改动，推送与版本号一致的标签：

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

Release workflow 会校验标签、安装原生构建依赖、运行测试、验证归档，并把归档附到 GitHub Release。成功后将同一提交的文档部署到 Cloudflare Pages。单独推送标签不会上传 crates.io。

上传注册表需要已验证邮箱的 crates.io 账号和有权发布该 crate 的 token：

cargo login
cargo +stable publish --locked

也可以设置仓库 secret CARGO_REGISTRY_TOKEN，在 GitHub Actions 的 Release workflow 选择对应的版本标签并勾选 publish_to_crates_io。它会重新验证再上传。不要把 token 放进命令参数、日志或提交文件。

已发布版本不能覆盖，应在上传前核实归档和版本号。详见 Cargo 发布指南。

从 0.12 升级

Raster Style 保持 SDK 0.4.0／协议 3.0/Q3。自定义 STAC 客户端应把已构建客户端的 with_http_client 改成 with_http_client_builder，传入配置好的 reqwest 0.11 ClientBuilder；旧入口返回错误。认证与重定向契约见镶嵌指南。此版本还修正独立 mask 网格、极区覆盖、Alpha 点查询、精确网格 CubicSpline、极端有限值重采样、histogram 计数及示例服务配置传递。