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

项目概览

了解 async-geotiff 的职责边界以及数据如何在系统中流动。

1: 什么是 async-geotiff？
2: 架构

从这里开始了解项目定位、架构与有意保留的边界。

1 - 什么是 async-geotiff？

项目目标、支持的数据类型以及有意保留的边界。

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

核心能力

通过 HTTPS 或调用方配置的 object_store 后端异步访问 COG。
在一个按字节限制的共享缓存中保存解码后的原生 TIFF 块。
支持 WebMercatorQuad（EPSG:3857）和 WorldCRS84Quad（EPSG:4326）。
支持 U8、U16、I16、U32、I32、F32 和 F64 源像元。
支持 nearest、bilinear、cubic、cubic-spline、Lanczos 和 average 重采样。
支持拉伸、色带、RGB 合成、颜色公式和算术波段计算。
默认输出 PNG，并可通过 feature 启用 WebP 和 JPEG。
使用 MosaicJSON、STAC 或自定义数据源组合多资产镶嵌。

有意保留的边界

不依赖 GDAL 运行时。 TIFF I/O 使用 async-tiff 和 object_store。默认的 proj feature 仅在非内置快速路径的坐标转换中使用系统 libproj。

库中不包含 Web 框架。 Axum HTTP 层以及 MapLibre、OpenLayers、Leaflet 查看器位于 examples/。应用可以直接使用 CogReader、Tiler 或 MosaicTiler，无需引入 Axum。

不管理凭据。 使用 S3、GCS、MinIO 或其他对象存储时，由应用完成认证配置，再把可用的 store 传给库。

不绑定可观测性后端。 crate 发出 tracing span 并公开缓存统计；应用自行选择 OpenTelemetry、Prometheus、日志或其他导出方式。

说明

完全位于数据集或投影有效范围之外的瓦片返回 Ok(None)；示例 HTTP 服务将其映射为 204 No Content。

2 - 架构

跟踪一次瓦片请求如何从 HTTP 或库调用变为编码后的字节。

库将异步范围 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 上限。