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

快速开始

安装依赖、运行示例服务，并通过库渲染一张瓦片。

1: 环境要求
2: 快速上手
3: 作为库使用

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

1 - 环境要求

Rust、系统库和可选的文档工具链要求。

库与示例

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 - 快速上手

运行示例服务并请求第一张渲染瓦片。

克隆并运行

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。

打开任一内置查看器：

查看器会自动居中到已打开的数据集，是最可靠的可视化冒烟测试。也可以直接请求全球 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 端点只返回当前二进制实际编译的编码器。

3 - 作为库使用

直接从 Rust 打开 COG 并渲染瓦片。

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