文档

• 1: 项目概览
  • 1.1: 什么是 async-geotiff？
  • 1.2: 架构
• 2: 快速开始
  • 2.1: 环境要求
  • 2.2: 快速上手
  • 2.3: 作为库使用
• 3: 使用指南
  • 3.1: 样式与波段计算
  • 3.2: 镶嵌与 STAC
  • 3.3: 生产运行
• 4: 参考手册
  • 4.1: 示例 HTTP API
  • 4.2: Cargo features
  • 4.3: 示例服务配置

1 - 项目概览

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

1.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、日志或其他导出方式。

1.2 - 架构

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

主要组件

瓦片数据流

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

并发模型

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

2 - 快速开始

按照最短路径，从全新检出运行到一张可见的地图瓦片。

2.1 - 环境要求

库与示例

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

macOS：

brew install proj

Debian 或 Ubuntu：

sudo apt install libproj-dev libsqlite3-dev libtiff-dev clang

其他平台请通过受支持的包管理器安装 libproj，或关闭默认 features。项目目前没有 提供 Windows 专用安装命令。

如果只需要同 CRS 瓦片或内置的 EPSG:4326 ↔ EPSG:3857 快速路径，可以关闭默认 features：

cargo build --no-default-features

文档站

website/ 下的 OINK 站点需要 Go 1.27 或更高版本，以及 Hugo Extended 0.165.0 或更高版本。Hugo 的版本输出中必须包含 extended：

go version
hugo version

库本身不依赖 Hugo 或 Go。

2.2 - 快速上手

克隆并运行

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。

打开任一内置查看器：

• http://127.0.0.1:8080/maplibre
• http://127.0.0.1:8080/openlayers
• http://127.0.0.1:8080/leaflet

查看器会自动居中到已打开的数据集，是最可靠的可视化冒烟测试。也可以直接请求全球 0 级瓦片：

curl --fail --output tile.png \
  'http://127.0.0.1:8080/tiles/WebMercatorQuad/0/0/0.png'

成功时会生成可用任意图像查看器打开的 PNG 文件。合法但完全位于源数据范围之外的 坐标返回 HTTP 204，而不是合成一张空白图片；遇到这种情况，请使用内置查看器在自动 计算的数据集中心和缩放级别请求范围内瓦片。

浏览本地文件

不传 URL 时，服务会发现 data/*.tif 和 data/*.tiff：

mkdir -p data
cp /path/to/example.tif data/
cargo run --release --example serve

查看器中会出现数据集切换器。

可选输出格式

PNG 始终可用。WebP 与 JPEG 需要显式启用：

cargo run --release --features webp,jpeg --example serve -- \
  https://example.com/cog.tif

/formats 端点只返回当前二进制实际编译的编码器。

2.3 - 作为库使用

仓库当前设置了 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 转换。

渲染一张瓦片

use std::sync::Arc;

use async_geotiff::io::cog::CogReader;
use async_geotiff::style::TileStyle;
use async_geotiff::tiler::Tiler;
use async_geotiff::tms::{TileCoord, TileMatrixSet};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = "https://raw.githubusercontent.com/cogeotiff/rio-tiler/0b08b7f35a8b639cee2f35a0cb565034f7b55bfd/tests/fixtures/cog.tif";
    let reader = Arc::new(
        CogReader::builder()
            .source_id(url)
            .open_http(url)
            .await?,
    );
    let tiler = Tiler::new(reader);
    let style = TileStyle::from_query("colormap_name=viridis&rescale=0,3000")?;
    let coord = TileCoord {
        tms: TileMatrixSet::WebMercatorQuad,
        z: 0,
        x: 0,
        y: 0,
    };

    if let Some(bytes) = tiler.tile(coord, &style).await? {
        std::fs::write("tile.png", bytes)?;
    } else {
        eprintln!("tile is outside the dataset or projection domain");
    }
    Ok(())
}

TileStyle::from_query 接受与示例 HTTP 服务相同的查询字符串，但不包含开头的 ?。 将示例保存为 src/main.rs，然后执行 cargo run。固定 URL 是一个支持 Range 的 小型测试 COG；确认集成成功后再替换为自己的数据。

共享内存与 CPU 预算

处理多个 COG 时，请创建一个块缓存，并为每个 reader 指定稳定且互不相同的源 ID：

use std::sync::Arc;

use async_geotiff::io::block_cache::BlockCache;
use async_geotiff::io::cache::CacheConfig;
use async_geotiff::io::cog::CogReader;

let cache = Arc::new(BlockCache::new(CacheConfig::default()));

let first = CogReader::builder()
    .source_id("scene-a")
    .block_cache(Arc::clone(&cache))
    .open_http("https://example.com/a.tif")
    .await?;

let second = CogReader::builder()
    .source_id("scene-b")
    .block_cache(Arc::clone(&cache))
    .open_http("https://example.com/b.tif")
    .await?;

共享同一缓存的 reader 共用默认 512 MiB 预算。源 ID 是缓存键的一部分，只有相同逻辑 COG 才应复用同一个 ID。

3 - 使用指南

围绕应用最常组合的能力提供任务导向指南。

3.1 - 样式与波段计算

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

常用配方

三波段自然色 RGB：

bidx=1&bidx=2&bidx=3&rescale=0,3000&rescale=0,3000&rescale=0,3000

单波段色带：

bidx=1&colormap_name=viridis&rescale=0,3000

百分位拉伸：

stretch=percent&pc=2,98

下采样使用 average，重投影使用 bilinear：

resampling=average&reproject=bilinear

拉伸行为

对于非 U8 数据，有效值域按以下优先级选择：

1. 显式的 rescale=min,max。
2. 指定的 stretch 模式。
3. 两者都不存在时使用 stretch=stddev&sigma=2.0。

U8 RGB 保留 0–255 快速路径。数据统计优先来自内嵌 STATISTICS_* 标签；如果没有， 则采样最高概览层一次并缓存估算结果。

算术表达式

expression 生成一个派生输出波段，波段编号从 1 开始：

expression=(b5-b4)/(b5+b4)&rescale=-1,1&colormap_name=viridis

这个 NDVI 公式只适用于所选 COG 的第 5 波段为近红外、第 4 波段为红光的情况。库不会 根据波段编号推断光谱含义；使用前必须检查资产元数据并调整引用。预渲染的 STAC visual 资产也不会自动满足此示例。

放入 URL 时请对 / 和 + 进行百分号编码：

curl --output ndvi.png \
  'http://127.0.0.1:8080/tiles/WebMercatorQuad/0/0/0.png?expression=(b5-b4)%2F(b5%2Bb4)&rescale=-1,1&colormap_name=viridis'

语法支持有限十进制数、括号、二元 +、-、*、/ 和一元负号。乘除优先于 加减，不支持科学计数法。

expression 不能与 bidx 或 color_formula 同时使用，并且最多接受一个 rescale。nodata 输入、除零和其他非有限结果会变为透明像元。输入上限为 4096 字节、256 个 token 和 128 层嵌套。

颜色公式

支持的 rio-color 子集按从左到右的顺序应用：

• gamma
• sigmoidal
• saturation

例如：

color_formula=gamma RGB 1.5

放入 URL 查询字符串时需要对空格编码。

3.2 - 镶嵌与 STAC

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

MosaicJSON

运行内嵌示例，或传入一个 MosaicJSON 文件：

cargo run --example mosaic_json
cargo run --example mosaic_json -- /path/to/mosaic.json

解析器支持 MosaicJSON 0.0.3。其 quadkey 索引定义在 WebMercatorQuad 中； 将 MosaicJSON 数据源用于 WorldCRS84Quad 会返回查询错误。

在进程启动时把示例服务连接到文件：

ASYNC_GEOTIFF_MOSAIC=/path/to/mosaic.json \
  cargo run --release --example serve

镶嵌瓦片随后可通过 /mosaic/tiles/... 获取。

像元选择

“第一个输出波段”在内部索引中是 0；面向用户的 bidx 仍然从 1 开始。

MosaicConfig 默认每批并发处理 8 个资产，每个 MosaicTiler 的 reader 池最多保留 256 个已打开 reader，并把每张请求瓦片的资产数硬限制为 64。超过上限时，tiler 会 记录 warning，并按数据源提供的顺序保留前 N 个资产。三个限制都通过 builder 配置：

use std::sync::Arc;

use async_geotiff::io::block_cache::BlockCache;
use async_geotiff::io::cache::CacheConfig;
use async_geotiff::mosaic::{HttpAccessPolicy, MosaicConfig, MosaicTiler};

let cache = Arc::new(BlockCache::new(CacheConfig::default()));
let config = MosaicConfig {
    chunk_size: 4,
    reader_capacity: 64,
    max_assets_per_tile: 32,
};
let mosaic = MosaicTiler::builder(source)
    .config(config)
    .block_cache(Arc::clone(&cache))
    .http_policy(HttpAccessPolicy::strict())
    .build();

对于不可信或低缩放级别的索引，应保留资产上限以避免请求放大。如果截断会影响视觉 正确性，数据源必须提供确定性的资产顺序。

STAC 示例

启用 stac 并提供全部三个启动配置：

ASYNC_GEOTIFF_STAC_URL=https://earth-search.aws.element84.com/v1 \
ASYNC_GEOTIFF_STAC_COLLECTION=sentinel-2-l2a \
ASYNC_GEOTIFF_STAC_ASSET_KEY=visual \
  cargo run --release --example serve --features stac

API、集合与资产 key 在进程启动时固定。HTTP 查询参数无法把示例变成任意 STAC 或 COG 代理。

启动后打开 http://127.0.0.1:8080/maplibre。配置 STAC 时，MapLibre 查看器默认 选择 mosaic 模式，无需猜测瓦片坐标即可验证目标集合。

HTTP 资产策略

默认策略允许公网和私网 HTTP(S) 资产，但阻止 loopback、link-local 和云元数据地址。 对于完全不可信的文档，请使用 HttpAccessPolicy::strict()：它要求 HTTPS，并额外阻止 私有地址范围。permissive() 只应服务于运维方完全控制的资产列表。

示例服务使用默认策略，不提供环境变量覆盖。接受不可信 mosaic 或 STAC 文档的服务应 自行构造 MosaicTiler，并像上例一样通过 builder 传入 strict()。

镶嵌错误和日志会隐藏预签名 URL 的查询字符串。 访问策略是 URL 解析防护，不是完整的出站代理沙箱。应用仍需负责客户端超时、重定向 策略、出站防火墙、文档大小限制，以及自己在库外增加的日志。

3.3 - 生产运行

共享一个缓存

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

这个预算只覆盖缓存中常驻的解码块，不等于进程总 RSS。飞行中的压缩字节、解码和 重投影缓冲区、编码响应、reader 元数据与 mosaic reducer 状态会额外占用内存；其中 Median 会保留全部参与图像直到归并完成。

库不会实施全局请求并发限制，因此不能仅根据缓存容量推导严格 RSS 上限。应在服务或 网关限制并发瓦片请求，保持单瓦片资产扇出有界，并使用包含最大允许源窗口与输出瓦片 尺寸的压力测试来确定容器内存。

通过 BlockCache::stats() 可观察：

• hits 与 misses
• decoded 与 fetched
• entries
• resident_bytes

可进一步计算命中率、fetch/decode 放大比，以及常驻字节占配置预算的比例。

限制 CPU 工作

解码、拼接、重投影、镶嵌归并、渲染与编码都是 CPU 密集型工作。它们通过受 CpuLimiter 限制的 spawn_blocking 运行。非 mosaic CogReader 与 Tiler 接受 调用方提供的 limiter；MosaicTiler 在资产与最终渲染之间共享一个内部 limiter， 但不能接入非 mosaic limiter。默认值取主机可用并行度，并把 0 修正为至少一个 permit。

Tiler::new 会复用其 reader 携带的 limiter：

use std::sync::Arc;

use async_geotiff::CpuLimiter;
use async_geotiff::io::cog::CogReader;
use async_geotiff::tiler::Tiler;

let cpu = CpuLimiter::new(8);
let reader = Arc::new(
    CogReader::builder()
        .source_id("scene-a")
        .cpu_limiter(cpu.clone())
        .open_http("https://example.com/a.tif")
        .await?,
);
let tiler = Tiler::new(reader);

示例服务的 CPU 计数方式取决于数据路径。命令行默认 COG 使用相互独立的 reader 解码 与 tiler 渲染 limiter，两阶段可以重叠；延迟选择的本地数据集复用一个 AppState limiter，其大小取两项配置中的较大值；MosaicTiler 还拥有自己的共享 limiter。因此 两个环境变量是组件调优项，不是通用的进程级 CPU 上限。需要单一上限时，应在库级别把 同一个 CpuLimiter 注入所有支持注入的非 mosaic reader 与 tiler。

当前 MosaicTiler 拥有内部共享 limiter，但 builder 不支持注入非 mosaic 路径的 limiter。因此，目前不支持对混合 mosaic 与单 COG 流量设置严格的数值型 CPU-job 上限。库外请求并发限制只能提供粗粒度背压，并不等同于共享 permit 预算。

不要在没有测量时主动降低瓦片并发。过小的限制会给每次瓦片请求增加排队时间；应先 观察 P95 延迟与 CPU 竞争。

调整访问模式

• 多数据集服务或大范围平移/缩放场景可增加缓存容量。
• 读取延迟敏感时优先使用 ZSTD 压缩 COG，而不是 DEFLATE。
• 示例服务默认预取一圈原生块；不希望产生额外对象存储 GET 时，设置 ASYNC_GEOTIFF_PREFETCH_RING=0。
• 对不可信索引保持 MosaicConfig::max_assets_per_tile 有界。

导出 trace 与指标

Tiler::tile 和 CogReader::read_window 会发出 tracing span。需要 OTLP trace 时， 在应用中连接 tracing-opentelemetry layer；库本身有意不依赖 OpenTelemetry。

在 HTTP 或应用边界记录请求量、延迟、错误量以及 Ok(None) 比例；另行轮询缓存统计， 观察内存与远程读取行为。

保护远程访问

当 mosaic 或 STAC 文档不可信时使用严格的 HttpAccessPolicy。凭据应配置在 object_store 实例上，而不是嵌入资产标识。应用边界也应避免记录原始预签名 URL。

4 - 参考手册

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

4.1 - 示例 HTTP API

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

路由

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

样式参数

重采样核包括 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 客户端。

4.2 - Cargo features

示例：

# 默认：投影 + 镶嵌 + 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 始终可用。

4.3 - 示例服务配置

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

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

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