注意：Robosat 已不再由 Mapbox 维护或积极开发。请参阅此问题。
主要开发者（@daniel-j-h，@bkowshik）已离开 Mapbox。

RoboSat

用于从航空和卫星影像中提取特征的通用生态系统 柏林航空影像、分割掩膜、建筑物轮廓线、简化的 GeoJSON 多边形

目录

1. 概述
2. 安装
3. 使用
   • extract
   • cover
   • download
   • rasterize
   • train
   • export
   • predict
   • mask
   • features
   • merge
   • dedupe
   • serve
   • weights
   • compare
   • subset
4. 扩展
   • 使用自有影像
   • 使用自有掩膜
   • 在预处理中添加对新特征的支持
   • 在后处理中添加对新特征的支持
5. 贡献
6. 许可证

概述

RoboSat 是一个用 Python 3 编写的端到端流程，用于从航空和卫星影像中提取特征。
这些特征可以是影像中任何视觉上可区分的对象，例如建筑物、停车场、道路或汽车。

请查看：

• 这篇 OpenStreetMap 日记文章，我们首次介绍了 RoboSat 并展示了一些结果；
• 这篇 OpenStreetMap 日记文章，我们基于坦桑尼亚的无人机影像提取了建筑物轮廓；
• 这篇 OpenStreetMap 日记文章，我们总结了 v1.1 版本的发布；
• 这篇 OpenStreetMap 日记文章，我们总结了 v1.2 版本的发布；
• 这篇 OpenStreetMap 日记文章，我们使用 RoboSat v1.2 对德国巴伐利亚的航空影像进行了处理；
• 这篇 OpenStreetMap 日记文章，Maning 使用 RoboSat 处理了来自菲律宾的影像。

RoboSat 提供的工具可分为以下几类：

• 数据准备：创建用于训练特征提取模型的数据集；
• 训练与建模：用于图像中特征提取的分割模型；
• 后处理：将分割结果转换为干净且简单的几何图形。

这些工具使用 Slippy Map 的瓦片格式，将地理参考影像抽象为大小相同的瓦片。

数据准备工具帮助您开始创建用于训练特征提取模型的数据集。
此类数据集由航空或卫星影像以及您希望提取的特征对应的掩膜组成。
我们提供了便捷的工具来自动创建这些数据集，即从 Mapbox Maps API 下载航空影像，并从 OpenStreetMap 几何数据中生成掩膜，但并不局限于这些数据源。

建模工具帮助您训练用于分割的全卷积神经网络。
我们建议使用（可能多个）GPU 来运行这些工具：我们已经在 AWS p2/p3 实例和 GTX 1080 TI GPU 上运行 RoboSat。
训练好模型后，您可以保存其检查点，并在 GPU 或 CPU 上进行预测。

后处理工具帮助您清理分割模型的结果。
它们负责去噪、简化几何形状、将 Slippy Map 瓦片中的像素坐标转换为世界坐标（GeoJSON 特征），以及正确处理瓦片边界。

如果您觉得这几乎就是您所需要的，请参阅扩展部分，了解更多关于扩展 RoboSat 的信息。
如果您想参与贡献，请参阅贡献部分，了解如何参与 RoboSat 的开发。

安装

我们在 Docker Hub 的 mapbox/robosat 中提供了适用于 CPU 和 GPU 环境的预构建 Docker 镜像。

使用 CPU 容器显示所有可用子命令：

docker run -it --rm -v $PWD:/data --ipc=host --network=host mapbox/robosat:latest-cpu --help

使用 GPU 容器（需要主机上安装 nvidia-docker）训练模型：

docker run --runtime=nvidia -it --rm -v $PWD:/data --ipc=host mapbox/robosat:latest-gpu train --model /data/model.toml --dataset /data/dataset.toml --workers 4

参数说明：

• --runtime=nvidia 启用 nvidia-docker 运行时，以访问主机上的 GPU；
• --ipc=host 是工作进程之间共享内存通信所必需的；
• --network=host 是下载工具进行网络通信所必需的；
• -v $PWD:/data 将主机上的当前目录挂载到容器内的 /data 路径下。

如需从源代码安装（需先安装依赖项），请参阅 docker/ 目录中的 Dockerfile。

使用

以下介绍构成 RoboSat 流程的各个工具。
所有工具均可通过以下方式调用：

./rs <tool> <args>

您还可以通过以下命令查看各子命令的帮助信息：

./rs --help
./rs <tool> --help

大多数工具都需要一个数据集或模型配置文件。示例可在 configs 目录中找到。
您需要根据自己的数据集调整这些配置文件，例如设置瓦片分辨率（如 256x256 像素）。
此外，您还需要根据具体的部署环境调整这些配置文件，例如使用 CUDA 并设置批处理大小。

rs extract

从 OpenStreetMap 中提取 GeoJSON 特征，以构建训练数据集。

rs extract 的结果是一个包含提取特征几何的 GeoJSON 文件。

rs extract 工具会遍历 OpenStreetMap .osm.pbf 基础地图文件（例如来自 Geofabrik），并收集特征几何。
这些特征包括停车场、建筑物或道路等多边形。

rs cover

生成覆盖 GeoJSON 特征的瓦片列表，用于构建训练集。

rs cover 的输出是一个文件，其中包含以 (x, y, z) Slippy Map 瓦片格式表示的、覆盖 GeoJSON 特征的瓦片。

rs cover 工具会读取由 rs extract 生成的 GeoJSON 特征，并生成一个覆盖这些特征几何体的瓦片列表。

rs download

根据瓦片列表从 Slippy Map 端点（例如 Mapbox Maps API）下载航空或卫星影像。

rs download 的输出是一个包含航空或卫星图像的 Slippy Map 目录——这是模型训练所需的训练集图像。

rs download 工具会下载由 rs cover 生成的、以 (x, y, z) Slippy Map 瓦片格式表示的瓦片列表对应的图像。

rs download 工具需要一个 Slippy Map 端点，该端点中的 {x}、{y} 和 {z} 占位符应使用每个瓦片的 ID 进行格式化。 例如，对于 Mapbox Maps API：https://api.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}@2x.webp?access_token=TOKEN。

rs rasterize

根据瓦片列表将 GeoJSON 特征栅格化为掩码图像。

rs rasterize 的输出是一个包含掩码的 Slippy Map 目录——这是模型训练所需的训练集掩码。

rs rasterize 工具会读取 GeoJSON 特征，并将其栅格化为单通道掩码，同时附带调色板以便快速目视检查。

rs train

在由 (image, mask) 对组成的训练集上训练模型。

rs train 的输出是一个包含已训练模型权重的检查点。

rs train 工具会在由 rs download 和 rs rasterize 生成的 (image, mask) 数据集上训练一个用于语义分割的全卷积神经网络。 我们建议使用 GPU 进行训练：我们正在使用 AWS p2 实例和 GTX 1080 TI 显卡。

在开始训练之前，您需要准备以下内容。

• 您需要一个数据集，将其分为三部分：用于 rs train 训练和计算验证指标的训练集和验证集，以及用于最终模型评估的保留数据集。数据集目录应如下所示：

  dataset
  ├── training
  │   ├── images
  │   └── labels
  └── validation
      ├── images
      └── labels
  

• 您需要使用 rs weights 在训练集的标签上计算类别权重。

• 您需要将数据集目录路径以及计算出的类别权重和统计信息添加到数据集配置中。

rs export

将训练好的模型导出为 ONNX 格式，以便在不同后端（如 Caffe2、TensorFlow）上进行预测。

rs export 的输出是一个 ONNX GraphProto .pb 文件，可用于 ONNX 生态系统。

注意：rs predict 工具使用 .pth 检查点。与这些 .pth 检查点不同，ONNX 模型不依赖 PyTorch 或模型类的 Python 代码，因此可以在资源受限的环境（如 AWS Lambda）中使用。

rs predict

对 Slippy Map 目录结构中的每个图像瓦片预测类别概率。

rs predict 的输出是一个 Slippy Map 目录，其中每个瓦片都包含一个编码了类别概率的 .png 文件。

rs predict 工具会加载由 rs train 生成的检查点权重，并对由图像瓦片组成的 Slippy Map 数据集进行语义分割类别概率预测。

rs masks

为 Slippy Map 目录结构中的每个包含类别概率的 .png 文件生成分割掩码。

rs masks 的输出是一个 Slippy Map 目录，其中每个瓦片都有一张带有调色板的单通道图像，便于快速目视检查。

rs masks 工具会加载由 rs predict 生成的 .png 瓦片分割类别概率，并将其转换为分割掩码。 如果您希望使用多个模型的集成，可以使用此工具将包含类别概率的多个 Slippy Map 目录合并为一个掩码。

rs features

提取 Slippy Map 目录结构中用于分割掩码的简化 GeoJSON 特征。

rs features 的输出是一个包含提取的简化特征的 GeoJSON 文件。

rs features 工具会加载由 rs masks 生成的分割掩码，并将其转换为简化的 GeoJSON 特征。

rs merge

将彼此靠近的相邻 GeoJSON 特征合并为单个特征。

rs merge 的输出是一个包含合并后特征的 GeoJSON 文件。

rs merge 工具会加载 GeoJSON 特征，并根据阈值将相邻的几何体合并在一起。

rs dedupe

将预测的特征与现有的 OpenStreetMap 特征去重。

rs dedupe 的输出是一个包含不在 OpenStreetMap 中的预测特征的 GeoJSON 文件。

rs dedupe 会将预测的特征与 OpenStreetMap 进行去重。 注：使用 rs extract 可以生成包含 OpenStreetMap 特征的 GeoJSON 文件。

rs serve

通过提供按需分割瓦片服务器来服务瓦片掩码。

rs serve 工具实现了一个 Slippy Map 栅格瓦片服务器，该服务器请求卫星瓦片并实时应用分割模型。

注：这对于实时目视检查原始分割掩码很有用；对于实际应用场景，请使用 rs predict 等工具。

rs weights

计算包含掩码的 Slippy Map 目录的类别权重。

rs weights 的输出是一个类别权重列表，可用于 rs train 根据掩码中的类别分布调整损失函数。

rs compare

准备图像、标签和预测掩码，以便并排进行目视比较。

rs compare 的输出是一个 Slippy Map 目录，其中左侧是原始图像，中间是标签，右侧是预测结果。

rs subset

根据瓦片 ID 列表筛选 Slippy Map 目录。

rs subset 的输出是一个按瓦片 ID 筛选后的 Slippy Map 目录。

该工具的主要用途是硬负样本挖掘，即从一次预测运行中筛选出假阳性样本。

扩展

有多种方式可以针对您的特定用例扩展 RoboSat。 默认情况下，我们使用来自 Maps API 的 Mapbox 航空影像，以及基于 OpenStreetMap 几何体生成的特征掩码。 如果您想引入自己的影像、掩码或要提取的特征，以下内容将帮助您入门。

引入您自己的影像

RoboSat 的主要抽象是 Slippy Map 瓦片格式。 只要您的影像具有地理参考，并且可以将其转换为 Slippy Map 目录结构以供命令行指向，您就可以开始使用。 请确保影像和掩码正确对齐。

请自备口罩

RoboSat 的主要抽象是 Slippy Map 平铺格式。 只要能将你的掩码转换为 Slippy Map 目录结构，并让命令行指向该结构，就可以开始使用了。 掩码必须是单通道 .png 文件，类索引从零开始。 请确保影像和掩码正确对齐。

在预处理中添加对新要素的支持

预处理（rs extract）负责将 OpenStreetMap 的几何和标签转换为多边形要素掩码。 如果你想基于 OpenStreetMap 中的几何添加一个新要素，你需要：

• 实现一个 osmium 处理器，将 OpenStreetMap 的几何转换为多边形；现有处理器可参见 robosat/osm/。
• 将你的处理器导入并注册到 robosat/tools/extract.py 中。

仅此而已！此后整个流水线都是通用的。

在后处理中添加对新要素的支持

后处理（rs features）负责将分割掩码转换为简化的 GeoJSON 要素。 如果你想为分割掩码添加自定义后处理，你需要：

• 实现一个要素化处理器，将掩码转换为 GeoJSON 要素；现有处理器可参见 robosat/features/。
• 将你的处理器导入并注册到 robosat/tools/features.py 中。

仅此而已！此后整个流水线都是通用的。

贡献说明

我们非常感谢大家的贡献，并乐于提供帮助；不过也需要注意以下几点限制：

• 对于非 trivial 的更改，你应该先创建一个 issue 来概述和讨论你的想法及实现草图。如果你直接提交包含数千行代码的 pull request，我们很可能不会接受你的更改集。
• 我们遵循 80/20 法则，即 80% 的效果来自 20% 的原因：我们更注重简洁性和可维护性，而非追求像素级的完美结果。如果你能将模型准确率提高两个百分点，但需要增加数千行代码，我们很可能不会接受你的更改集。
• 我们会对合并到 master 分支的更改集承担责任：一旦你的更改集被批准，后续的维护和调试工作就由我们负责。如果你的更改集无法被测试，或未来难以由核心开发者维护，我们很可能不会接受你的更改集。

许可证

版权所有 © 2018 Mapbox

根据 MIT 许可证（MIT）发布。

RoboSat 快速上手指南

重要提示：RoboSat 目前已不再由 Mapbox 维护或积极开发（主要开发者已离职）。本项目适用于学习卫星/航拍图像特征提取原理或作为历史参考。生产环境请谨慎评估。

RoboSat 是一个基于 Python 3 的端到端流水线工具，用于从航拍和卫星图像中提取地理特征（如建筑物、道路、停车场等）。它利用深度学习进行语义分割，并将结果转换为 GeoJSON 格式。

1. 环境准备

系统要求

• 操作系统：Linux (推荐 Ubuntu 18.04+) 或 macOS
• 硬件：
  • 训练阶段：强烈建议使用 NVIDIA GPU (如 GTX 1080 Ti 或更高)，需安装 CUDA 驱动。
  • 推理阶段：CPU 即可运行，但速度较慢。
• 软件依赖：
  • Docker 及 Docker Compose (推荐方式)
  • 或 Python 3.6+ (若从源码安装)

前置知识

• 了解 Slippy Map 瓦片格式 (x, y, z)。
• 拥有地图数据源访问权限（如 Mapbox Token 或本地 OSM .osm.pbf 文件）。

2. 安装步骤

推荐使用官方提供的 Docker 镜像，以避免复杂的环境依赖配置。

方案 A：使用 Docker (推荐)

Mapbox 提供了预构建的 CPU 和 GPU 镜像。

1. 拉取镜像

# CPU 版本
docker pull mapbox/robosat:latest-cpu

# GPU 版本 (需主机安装 nvidia-docker)
docker pull mapbox/robosat:latest-gpu

2. 验证安装 运行以下命令查看可用子命令：

docker run -it --rm -v $PWD:/data --ipc=host --network=host mapbox/robosat:latest-cpu --help

方案 B：从源码安装 (仅限高级用户)

若需修改代码，可参考仓库中 docker/ 目录下的 Dockerfile 手动安装依赖（PyTorch, GDAL, Shapely 等）。

3. 基本使用流程

RoboSat 的核心工作流分为：数据准备 -> 模型训练 -> 预测与后处理。所有命令通过 ./rs <tool> <args> 调用（在 Docker 中则为 docker run ... mapbox/robosat <tool> <args>）。

以下是一个简化的典型工作流示例：

第一步：数据准备 (Data Preparation)

你需要生成训练数据集，包含“图像”和对应的“标签掩膜”。

1. 提取特征 (rs extract) 从 OpenStreetMap (.osm.pbf) 文件中提取目标特征（如建筑物）的 GeoJSON。

   ./rs extract --config=configs/osm-extract.toml --output=features.geojson input.osm.pbf
   

2. 生成瓦片覆盖列表 (rs cover) 计算覆盖上述 GeoJSON 特征所需的地图瓦片列表。

   ./rs cover --config=configs/cover.toml --input=features.geojson --output=tiles.txt
   

3. 下载影像 (rs download) 根据瓦片列表下载卫星图（需配置 Mapbox API URL 和 Token）。

   ./rs download --config=configs/download.toml --tiles=tiles.txt --output=dataset/images
   

4. 生成掩膜 (rs rasterize) 将 GeoJSON 特征渲染为与下载图像对应的单通道掩膜图片。

   ./rs rasterize --config=configs/rasterize.toml --input=features.geojson --tiles=tiles.txt --output=dataset/labels
   

注：请将数据集划分为 training 和 validation 目录结构。

第二步：模型训练 (Training)

使用准备好的 (image, mask) 对训练分割模型。

1. 计算类别权重 (rs weights) 分析训练集标签，计算类别权重以平衡样本。

   ./rs weights --config=configs/dataset.toml --dataset=dataset/training/labels
   

2. 开始训练 (rs train) 启动训练过程（建议使用 GPU 容器）。

   docker run --runtime=nvidia -it --rm -v $PWD:/data --ipc=host mapbox/robosat:latest-gpu \
     train --model /data/model.toml --dataset /data/dataset.toml --workers 4
   

   输出：生成包含模型权重的 checkpoint 文件。

第三步：预测与导出 (Prediction & Post-processing)

使用训练好的模型对新区域进行预测并生成最终的 GeoJSON。

1. 预测概率 (rs predict) 对新的影像瓦片目录进行推理，输出每个像素的类别概率图。

   ./rs predict --model=model_checkpoint.pth --dataset=predict_images_dir --output=predict_probs
   

2. 生成掩膜 (rs masks) 将概率图转换为二值化或单通道分割掩膜。

   ./rs masks --probs=predict_probs --output=predict_masks
   

3. 提取矢量特征 (rs features) 从掩膜中提取简化的 GeoJSON 多边形。

   ./rs features --masks=predict_masks --output=result_raw.geojson
   

4. 后处理优化

   • 合并相邻要素：./rs merge --input=result_raw.geojson --output=result_merged.geojson
   • 去重（对比现有 OSM 数据）：./rs dedupe --input=result_merged.geojson --reference=osm_features.geojson --output=final_new_features.geojson

配置说明

所有工具均依赖 .toml 配置文件。在使用前，请复制 configs/ 目录下的示例文件，并根据实际情况修改：

• 瓦片分辨率 (如 256x256)
• API 地址与 Token (下载影像用)
• 超参数 (批次大小、学习率、GPU 设置等)

详细参数请参考各子命令的 --help 输出或 configs 目录中的示例。