async-geotiff

环境要求

Mon, 01 Jan 0001 00:00:00 +0000

库与示例

Rust 1.88 或更高版本，与 Cargo.toml 保持一致。
默认 feature 集需要系统 libproj 9.x。
从仓库开发时需要 Git。

macOS：

brew install proj

Debian 或 Ubuntu：

什么是 async-geotiff？

Mon, 01 Jan 0001 00:00:00 +0000

async-geotiff 是一个 Rust 库，用于把云优化 GeoTIFF（COG）转换为带样式的 XYZ 地图瓦片。它只读取生成目标瓦片所需的字节范围，解码原生 TIFF 块，按需重投影，应用渲染样式，最后编码输出。

示例 HTTP API

Mon, 01 Jan 0001 00:00:00 +0000

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。

样式与波段计算

Mon, 01 Jan 0001 00:00:00 +0000

Rust API 与示例服务的查询字符串使用同一个 TileStyle 模型。样式会在昂贵的 COG 读取和渲染工作之前完成校验。

常用配方

三波段自然色 RGB：

Cargo features

Mon, 01 Jan 0001 00:00:00 +0000

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`。

示例：

架构

Mon, 01 Jan 0001 00:00:00 +0000

库将异步范围 I/O 与 CPU 密集型的解码、重投影、渲染和编码工作分离。应用只需组合自己需要的公共层。

flowchart LR
 Client[HTTP 客户端或 Rust 调用方] --> Style[TileStyle]
 Client --> Tiler[Tiler]
 Tiler --> Grid[TileMatrixSet]
 Tiler --> Reader[CogReader]
 Reader --> Store[object_store / HTTP 范围读取]
 Reader <--> Cache[共享 BlockCache]
 Reader --> CPU[CpuLimiter + spawn_blocking]
 CPU --> Warp[重投影与重采样]
 Warp --> Render[拉伸 / 色带 / 合成]
 Style --> Render
 Render --> Encode[PNG / WebP / JPEG]
 Encode --> Result[Option&lt;Bytes&gt;]
 Mosaic[MosaicTiler] --> ReaderPool[ReaderPool]
 ReaderPool --> Reader
 Mosaic --> Render

主要组件

组件	职责
`CogReader`	打开 COG，读取元数据和概览层，选择并拼接原生块，以及采样点或窗口。
`BlockCache`	在统一字节预算下跨 reader 共享解码块，并合并并发冷读取。
`Tiler`	规划瓦片、选择概览层、读取源窗口、按需重投影并输出编码字节。
`TileStyle`	在渲染前解析并校验 titiler 风格的查询参数。
`MosaicTiler`	查找资产、通过池打开 reader、重投影各资产、合并重叠像元并统一渲染。
`CpuLimiter`	限制跨 reader 与 tiler 的 CPU 密集型阻塞任务。

瓦片数据流

TileCoord 在受支持的 TileMatrixSet 中定位目标瓦片。
Tiler 计算目标边界并检查其是否与源数据集相交。
根据目标地面分辨率选择合适的概览层。
CogReader 通过范围请求加载缺失的原生块，并复用缓存命中。
同 CRS 使用仿射快速路径；跨 CRS 使用反向重投影。EPSG:4326 与 EPSG:3857 之间有闭式快速路径，其他组合需要 proj feature。
渲染管线依次处理 nodata、scale/offset、波段计算、拉伸、色带或 RGB 合成，最后调用目标编码器。

并发模型

Tokio 负责异步元数据与字节范围 I/O。解码、拼接、重投影、镶嵌归并、渲染和编码通过受信号量限制的 spawn_blocking 运行。应用可以把一个 Arc<BlockCache> 注入单 COG 与 mosaic reader，避免解码缓存预算倍增；也可以在非 mosaic 的 CogReader/Tiler 之间注入同一个 CpuLimiter。当前 MosaicTiler 使用自己的内部 limiter，无法加入该 permit 预算，因此混合流量没有自动的进程级 CPU 上限。

快速上手

Mon, 01 Jan 0001 00:00:00 +0000

克隆并运行

git clone https://github.com/mapseekai/async-geotiff-rs.git
cd async-geotiff-rs
COG_URL='https://raw.githubusercontent.com/cogeotiff/rio-tiler/0b08b7f35a8b639cee2f35a0cb565034f7b55bfd/tests/fixtures/cog.tif'
cargo run --release --example serve -- "$COG_URL"

固定提交版本的 rio-tiler 测试文件约 800 KiB，是一个公开且支持 Range 的 COG，适合首次运行验证。冒烟测试完成后再替换为自己的 COG。服务默认监听 127.0.0.1:8080，并在启动成功后打印查看器与瓦片 URL。

镶嵌与 STAC

Mon, 01 Jan 0001 00:00:00 +0000

默认启用的 mosaic Cargo feature 提供 MosaicTiler 和 MosaicSource trait；不需要镶嵌的应用可以关闭默认 features。由于这也会关闭 proj，仍需通用 CRS 转换时请使用 --no-default-features --features proj。数据源将瓦片坐标映射为资产列表； tiler 打开并重投影这些资产，归并重叠像元，然后统一渲染合成结果。

生产运行

Mon, 01 Jan 0001 00:00:00 +0000

共享一个缓存

解码块缓存的默认预算是 512 MiB。拥有多个 reader 的服务应把同一个 Arc<BlockCache> 注入全部 reader 和 mosaic，并为每个不同 COG 使用稳定的源 ID，避免缓存键冲突。

示例服务配置

Mon, 01 Jan 0001 00:00:00 +0000

以下变量配置 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 变量必须一起提供。

作为库使用

Mon, 01 Jan 0001 00:00:00 +0000

仓库当前设置了 publish = false，因此其他本地项目在开发期需要使用路径依赖。先在仓库旁创建应用；如果目录布局不同，请调整相对路径：

# 从 async-geotiff-rs 检出目录开始：
cd ..
cargo new async-geotiff-demo
cd async-geotiff-demo

[dependencies]
async-geotiff = { path = "../async-geotiff-rs" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

如果要避免系统 libproj，同时保留示例服务使用的 mosaic API，可以在路径依赖上设置 default-features = false, features = ["mosaic"]；此时无法执行通用 CRS 转换。