SamGeo

一个用于使用 Segment Anything Model (SAM) 对地理空间数据进行分割的 Python 包

简介

SamGeo 包的灵感来源于由 Aliaksandr Hancharenka 编写的 segment-anything-eo 仓库。SamGeo 的主要目标是简化用户利用 SAM 进行地理空间数据分析的过程，使用户只需少量代码即可实现这一目标。SamGeo 的源代码改编自 segment-anything-eo 仓库，其原始版本的功劳归于 Aliaksandr Hancharenka。

• 自由软件：MIT 许可证
• 文档：https://samgeo.gishub.org

引用

• Wu, Q., & Osco, L. (2023). samgeo: A Python package for segmenting geospatial data with the Segment Anything Model (SAM). Journal of Open Source Software, 8(89), 5663. https://doi.org/10.21105/joss.05663
• Osco, L. P., Wu, Q., de Lemos, E. L., Gonçalves, W. N., Ramos, A. P. M., Li, J., & Junior, J. M. (2023). The Segment Anything Model (SAM) for remote sensing applications: From zero to one shot. International Journal of Applied Earth Observation and Geoinformation, 124, 103540. https://doi.org/10.1016/j.jag.2023.103540

特性

• 从 Tile Map Service (TMS) 服务器下载地图瓦片并创建 GeoTIFF 文件
• 使用 Segment Anything Model (SAM) 和 HQ-SAM 对 GeoTIFF 文件进行分割
• 使用文本提示对遥感影像进行分割
• 交互式地创建前景和背景标记
• 从矢量数据集中加载现有标记
• 将分割结果保存为常见的矢量格式（GeoPackage、Shapefile、GeoJSON）
• 将输入提示保存为 GeoJSON 文件
• 在交互式地图上可视化分割结果
• 对时序遥感影像中的对象进行分割
• 提供 REST API，通过 HTTP 提供分割服务（参见 API 文档）

QGIS 插件

SamGeo 也作为 QGIS 插件 提供。请观看这段 简短的视频演示 和 完整的视频教程，了解如何使用该插件。

安装

使用 pixi 安装（推荐）

为了获得最可靠的安装体验，尤其是在 Windows 系统上或处理 PyTorch/CUDA 和 SAM 3 等复杂依赖时，我们建议使用 pixi。Pixi 比 conda/mamba 提供更快、更可靠的依赖解析，并避免常见的 numpy 版本冲突。有关详细说明，请参阅 完整的 pixi 安装指南。

使用 pixi 的快速入门：

# 在 Linux/macOS 上安装 pixi
curl -fsSL https://pixi.sh/install.sh | sh

# 或在 Windows 上（PowerShell）
powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

# 创建一个新的 pixi 项目
pixi init geo
cd geo

# 根据您的配置编辑 pixi.toml（参见 GPU/CPU 示例文档）
# 然后安装
pixi install

# 启动 Jupyter Lab
pixi run jupyter lab

从 PyPI 安装

segment-geospatial 已在 PyPI 上发布，可以通过多种方式安装，以便更精细地控制其依赖项。这有助于减小 CI 环境中的包大小，因为并非每次都会使用所有模型。

根据您需要使用的工具，您可以选择：

• segment-geospatial 或 segment-geospatial[samgeo]：仅安装运行 SAMGeo 所需的最低依赖项
• segment-geospatial[samgeo2]：安装运行 SAMGeo 2 的依赖项
• segment-geospatial[samgeo3]：安装运行 SAMGeo 3 的依赖项
• segment-geospatial[fast]：安装运行 Fast SAM 的依赖项
• segment-geospatial[hq]：安装运行 HQ-SAM 的依赖项
• segment-geospatial[text]：安装 Grounding DINO，以便将 SAMGeo 1 和 2 与文本提示结合使用
• segment-geospatial[fer]：安装运行特征边缘重建算法所需的依赖项
• segment-geospatial[api]：安装 FastAPI 和 Uvicorn，以将分割作为 REST API 提供

此外，还定义了以下两个可选导入：

• segment-geospatial[all]：安装运行所有 SAMGeo 模型所需的依赖项
• segment-geospatial[extra]：安装运行所有 SAMGeo 模型以及其他实用程序所需的依赖项，例如 Jupyter 笔记本支持、leafmap 等。

只需运行以下命令即可为每个用例安装相应的依赖项：

pip install "segment-geospatial[samgeo3]" # 或上述其他任何选项

要详细了解每种选择包含哪些软件包，请参阅 pyproject.toml。

从 conda-forge 安装

segment-geospatial 也在 conda-forge 上提供。如果你的计算机上已经安装了 Anaconda 或 Miniconda，你可以使用以下命令来安装 segment-geospatial。建议为 segment-geospatial 创建一个新的 conda 环境。以下命令将创建一个名为 geo 的新 conda 环境，并安装 segment-geospatial 及其依赖项：

conda create -n geo python
conda activate geo
conda install -c conda-forge segment-geospatial

如果你的系统配备了 GPU，但上述命令并未安装 GPU 版本的 PyTorch，你可以通过以下命令强制安装 GPU 版本的 PyTorch：

conda install -c conda-forge segment-geospatial "pytorch=*=cuda*"

segment-geospatial 有一些可选依赖项，默认的 conda 环境中并不包含这些依赖。要安装这些依赖，请运行以下命令：

conda install -c conda-forge groundingdino-py segment-anything-fast

在 Windows 上安装 SAM 3

在 Windows 上安装 SAM 3 会稍微复杂一些。请在 Windows 上运行以下命令来安装 SamGeo：

conda create -n geo python=3.12
conda activate geo
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia
pip install "segment-geospatial[samgeo3]"
pip install triton-windows ipykernel jupyterlab

示例

• 分割遥感影像
• 自动生成对象掩码
• 使用输入提示分割遥感影像
• 使用框提示分割遥感影像
• 使用文本提示分割遥感影像
• 使用文本提示进行批量分割
• 将 segment-geospatial 与 ArcGIS Pro 结合使用
• 使用文本提示分割游泳池
• 分割来自 Maxar 开放数据计划的卫星影像

演示

• 自动掩码生成器

• 使用输入提示的交互式分割

• 使用现有文件中的提示

• 使用文本提示的交互式分割

教程

我的 YouTube 频道 上提供了视频教程。

• 自动掩码生成

• 在 ArcGIS Pro 中使用 SAM

• 使用文本提示的交互式分割

将 SAM 与桌面 GIS 结合使用

• QGIS：请查看 SamGeo QGIS 插件。
• ArcGIS：请查看 适用于 ArcGIS 的 Segment Anything Model (SAM) 工具箱以及 利用 ArcGIS 解锁深度学习应用强大功能的资源。

计算资源

Segment Anything Model 对计算资源的需求较高，处理大型数据集时建议使用性能强大的 GPU。推荐使用至少配备 8 GB 显存的 GPU。你也可以利用 Google Colab 提供的免费 GPU 资源。此外，你还可以申请 AWS 研究云积分，该计划为学术研究提供云积分支持。如果你位于大中华地区，可以在此处申请 AWS 研究云积分：AWS 教育云研究积分。

法律声明

本仓库及其内容仅用于教育目的。用户在使用所提供的信息和代码时，即表示已知悉并同意自行承担使用相关 API 和模型的风险，并遵守所有适用的法律法规。建议有意从任何底图下载大量图像瓦片的用户，在操作前先联系底图提供商以获得许可。未经授权使用底图或其任何组成部分，可能构成对版权法或其他适用法律法规的违反。

贡献

有关更多信息，请参阅 贡献指南。

致谢

本项目部分得到了美国国家航空航天局（NASA）的支持，资助编号为 80NSSC22K1742，该资助通过 2020 年开源工具、框架和库计划 提供。本项目还得到了亚马逊网络服务（AWS）的支持。此外，本软件包的实现也离不开以下开源项目，特此向这些项目的开发者致谢。

• segment-anything
• SAM 3
• segment-anything-eo
• tms2geotiff
• GroundingDINO
• lang-segment-anything

Segment-Geospatial (SamGeo) 快速上手指南

SamGeo 是一个基于 Facebook Segment Anything Model (SAM) 的 Python 包，专为地理空间数据分割设计。它支持卫星影像分割、文本提示分割、交互式标记以及多种矢量格式输出，旨在让开发者以最小的代码量完成复杂的遥感图像分析任务。

1. 环境准备

系统要求

• 操作系统: Linux, macOS, Windows
• Python 版本: 推荐 Python 3.9 - 3.12
• 硬件建议:
  • 处理大型数据集时，强烈建议使用配备至少 8GB 显存 的 NVIDIA GPU。
  • 若无 GPU，可在 CPU 模式下运行（速度较慢），或使用 Google Colab / AWS 云端资源。

前置依赖

• 包管理器：推荐使用 pixi（最稳定），也可使用 pip 或 conda。
• 若需使用文本提示功能（Text Prompts），需额外安装 Grounding DINO。
• 若需使用 Fast SAM 或 HQ-SAM 等变体，需安装对应可选依赖。

注意：国内用户若遇到 PyPI 或 Conda 下载缓慢，可配置清华源或中科大源加速（见安装步骤）。

---

2. 安装步骤

方案 A：使用 Pixi（推荐，尤其适用于 Windows 和复杂依赖）

Pixi 能更好地解决 PyTorch/CUDA 版本冲突问题。

# Linux/macOS 安装 pixi
curl -fsSL https://pixi.sh/install.sh | sh

# Windows (PowerShell) 安装 pixi
powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

# 创建项目并安装
pixi init geo
cd geo
# 编辑 pixi.toml 配置 GPU/CPU 环境（参考官方文档）
pixi install

# 启动 Jupyter Lab
pixi run jupyter lab

方案 B：使用 Pip（灵活选择组件）

根据需求安装不同组件，避免冗余依赖。

基础安装（仅核心功能）：

pip install "segment-geospatial[samgeo3]" -i https://pypi.tuna.tsinghua.edu.cn/simple

其他可选组件：

• 文本提示支持：pip install "segment-geospatial[text]"
• 全功能安装：pip install "segment-geospatial[all]"
• 包含示例工具（Jupyter, leafmap 等）：pip install "segment-geospatial[extra]"

Windows 安装 SAM 3 特别说明：

conda create -n geo python=3.12
conda activate geo
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia
pip install "segment-geospatial[samgeo3]" -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install triton-windows ipykernel jupyterlab

方案 C：使用 Conda

# 创建新环境
conda create -n geo python
conda activate geo

# 安装主包（使用清华源加速）
conda install -c conda-forge segment-geospatial --override-channels -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

# 若有 GPU 但未自动安装 CUDA 版 PyTorch，强制安装：
conda install -c conda-forge "pytorch=*=cuda*"

# 安装可选依赖（如文本提示）
conda install -c conda-forge groundingdino-py segment-anything-fast

---

3. 基本使用

以下示例展示如何加载卫星影像并自动生成对象掩膜（Mask）。

示例：自动生成分割掩膜

from samgeo import SamGeo

# 初始化模型（自动下载预训练权重）
m = SamGeo(
    model_type="vit_h", # 可选：vit_h, vit_l, vit_b
    automatic=True      # 启用自动掩膜生成器
)

# 输入遥感影像路径（GeoTIFF 或本地图片）
image_path = "satellite_image.tif"

# 执行分割
m.generate(image_path, output="masks.tif")

# 将结果保存为矢量文件（GeoJSON）
m.save_vectors(output="objects.geojson")

示例：使用文本提示分割（需安装 [text] 依赖）

from samgeo import SamGeo

m = SamGeo(model_type="vit_h")

# 使用文本提示分割特定地物（如“游泳池”）
m.generate(
    image="satellite_image.tif",
    text_prompt="swimming pool",
    output="pools_mask.tif"
)

m.save_vectors(output="pools.geojson")

可视化结果

SamGeo 内置交互式地图查看功能（需在 Jupyter 环境中）：

m.show_map()

---

更多示例：请访问 官方文档示例页 获取卫星影像下载、批量处理、ArcGIS/QGIS 集成等进阶教程。