跳转到主要内容

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

返回本页常规视图.

快速开始

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

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

1 - 环境要求

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

库与示例

  • Rust 1.92 或更高版本，与 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 需要显式启用：

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

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

3 - 作为库使用

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

在应用中添加 crates.io 依赖：

cargo new async-geotiff-demo
cd async-geotiff-demo
[dependencies]
async-geotiff = "0.13.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

如果要避免系统 libproj，同时保留示例服务使用的 mosaic API，可以在依赖上设置 default-features = false, features = ["mosaic"]；此时无法执行通用 CRS 转换。 本地开发时可用 path = "../async-geotiff-rs" 替换版本号，并按检出位置调整路径。

渲染一张瓦片

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_raster_query("version=3.0&type=pseudocolor&bidx=1&colormap_name=viridis&method=linear&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_raster_query 接受与示例 HTTP 服务相同的查询字符串，但不包含开头的 ?。 将示例保存为 src/main.rs，然后执行 cargo run。固定 URL 是一个支持 Range 的 小型测试 COG；确认集成成功后再替换为自己的数据。

点查询与地理范围

CogReader::point(x, y, &coord_crs, bidx) 返回最近像素的值，不执行渲染。坐标使用 coord_crs；影像外的点返回 None。波段从 1 开始编号，对应 read_window 输出的 波段；空选择按现有顺序返回全部输出波段。

没有独立 TIFF mask 时，首个 Alpha 样本会转为有效性 mask 并从输出波段中移除， 因此普通 RGBA 的点查询返回 RGB。有独立 mask 时，reader 保留原生波段并使用该 mask。无效像素返回 Some(PointValue { valid: false, .. })，不会被误判为波段 选择错误。Raster Style 渲染对 Alpha 源的独立限制仍然适用。

wgs84_bounds() 返回用于数据集统计的地理包络。投影足迹包含极点时，包络包括该 极点，经度范围为 [-180, 180]。包络可能包含影像之外的区域；实际覆盖仍应通过 像素查询或有效性 mask 判断。

低层 io::stats::Histogram::quantile 接受公开的 u64 分桶计数，在累计时避免 u64 溢出，也适用于直接构造的 histogram。100% 分位返回最后一个非空桶的上边界， 即使前面的计数非常大，也不会丢掉末尾的小计数桶；尾部空桶不参与该端点。 Raster Style 统计不使用这些嵌入式直方图。

共享内存与 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。