c2g-dev/city2graph
GitHub: c2g-dev/city2graph
一个将地理空间数据转化为图表示的 Python 库，为图神经网络和空间网络分析提供从数据预处理到张量输出的集成接口。
Stars: 939 | Forks: 91
# City2Graph：基于图神经网络（GNN）与空间网络分析的 GeoAI
[](http://city2graph.net/latest/assets/logos/social_preview_city2graph.png)
**City2Graph** 是一个 Python 库，用于将地理空间数据集转换为图表示，为跨多个领域（如街道、交通、OD矩阵、POI邻近度等）的 [GeoPandas](https://geopandas.org/)、[NetworkX](https://networkx.org/) 和 [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/) 提供了一个集成接口。它使研究人员和从业者能够无缝地开发高级 GeoAI 和地理数据科学应用。欲了解更多信息，请访问[文档](https://city2graph.net)。
[](https://badge.fury.io/py/city2graph/) [](https://anaconda.org/conda-forge/city2graph/) [](https://pepy.tech/projects/city2graph) [](https://doi.org/10.5281/zenodo.15858845) [](https://github.com/c2g-dev/city2graph/blob/main/LICENSE)
[](https://anaconda.org/conda-forge/city2graph) [](https://codecov.io/gh/c2g-dev/city2graph) [](https://github.com/astral-sh/ruff)
## 功能特性
[](http://city2graph.net/latest/assets/figures/scope.png)
- **面向 GeoAI 的图构建：** 从各种城市数据集（包括建筑物、街道和土地利用）构建图，为 GeoAI 和 GNN 应用提供支持。
- **交通网络建模：** 通过 DuckDB 查询 GTFS 数据，并构建详细的交通图，用于可达性和服务分析。
- **邻近度和连续性分析：** 基于空间邻近度和邻接关系创建图，包括多中心距离过滤和分层等时线。
- **出行流分析：** 对来自共享单车、人口迁移和行人流等多种数据源的城市出行模式进行建模和分析。
- **PyTorch Geometric 集成：** 将地理空间数据无缝转换为用于 GNN 的 PyTorch 张量。
## 安装
### 使用 pip
#### 基础安装
安装 City2Graph 最简单的方法是通过 pip：
```
pip install city2graph
```
这会安装核心功能，但不包含 PyTorch 和 PyTorch Geometric。
#### 包含 PyTorch（CPU）
如果您需要图神经网络功能，请使用 `cpu` 选项进行安装：
```
pip install "city2graph[cpu]"
```
这将安装带有 CPU 支持的 PyTorch 和 PyTorch Geometric，适用于开发和小规模处理。
#### 包含 PyTorch + CUDA (GPU)
要进行 GPU 加速，您可以安装带有特定 CUDA 版本的 City2Graph。例如，对于 CUDA 13.0：
```
pip install "city2graph[cu130]"
```
支持的 CUDA 版本为 `cu126`、`cu128` 和 `cu130`。
### 使用 conda
#### 基础安装
您也可以通过 conda-forge 使用 conda 安装 City2Graph：
```
conda install -c conda-forge city2graph
```
这会安装核心功能，但不包含 PyTorch 和 PyTorch Geometric。
#### 包含 PyTorch（CPU）
要将 PyTorch 和 PyTorch Geometric 与从 conda-forge 安装的 City2Graph 结合使用，您需要手动将这些库添加到您的环境中：
```
# 安装 city2graph
conda install -c conda-forge city2graph
# 然后安装 PyTorch 和 PyTorch Geometric
conda install -c conda-forge pytorch pytorch_geometric
```
#### 包含 PyTorch + CUDA (GPU)
要获得 GPU 支持，您应通过指定版本和 CUDA 构建字符串来选择合适的 PyTorch 变体。例如，要安装支持 CUDA 12.8 的 PyTorch 2.9.0：
```
# 安装 city2graph
conda install -c conda-forge city2graph
# 然后安装支持 CUDA 的 PyTorch
conda install -c conda-forge pytorch=2.9.0=*cuda128*
conda install -c conda-forge pytorch_geometric
```
您可以在 [conda-forge PyTorch 文件页面](https://anaconda.org/conda-forge/pytorch/files)浏览支持 CUDA 的可用版本，并在安装命令中替换为您所需的版本和 CUDA 变体。请确保您安装的 PyTorch 和 PyTorch Geometric 版本彼此兼容，且与您的系统兼容。
**⚠️ 重要提示：** conda 已不再被 PyTorch 和 PyTorch Geometric 官方支持，目前仅提供 conda-forge 发行版。如果您需要 PyTorch 功能，我们建议使用 pip 或 uv 以获得最流畅的安装体验。
## 开发指南
如果您想为 City2Graph 做贡献，可以使用 `uv` 设置开发环境。
```
# 如果尚未安装 uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆仓库
git clone https://github.com/c2g-dev/city2graph.git
cd city2graph
# 安装带有 PyTorch 变体（例如 cpu 或 cu128）的开发依赖
uv sync --extra cpu --group dev
```
然后您可以在托管环境中运行命令：
```
# 为交互式开发添加 IPython kernel
uv run ipython kernel install --name "your-env-name" --user
# 或者启动 Jupyter Notebook
uv run jupyter notebook
```
### 开发环境
开发依赖包括：
- `ipython`：增强的交互式 Python shell，支持 Jupyter 内核
- `jupyter` 和 `notebook`：用于运行带有项目特定内核的 Jupyter notebook
- `isort`：代码格式化工具
- `pytest` 和 `pytest-cov`：测试工具
Jupyter 内核的安装确保了当您启动 Jupyter notebook 时，您可以选择“city2graph”内核，该内核可以在正确的虚拟环境中访问您所有的项目依赖。
### 使用 Docker Compose
在使用 Docker Compose 之前，请确保您的系统上已安装 Docker 和 Docker Compose：
```
# 检查 Docker 安装
docker --version
# 检查 Docker Compose 安装
docker compose version
```
如果这些命令不起作用，您需要先安装 Docker：
- 对于 macOS：安装 [Docker Desktop](https://www.docker.com/products/docker-desktop)
- 对于 Linux：按照针对您特定发行版的[安装说明](https://docs.docker.com/engine/install/)进行操作
- 对于 Windows：安装 [Docker Desktop](https://www.docker.com/products/docker-desktop)
安装 Docker 后，克隆仓库并启动容器：
```
# 克隆仓库
git clone https://github.com/yu-ta-sato/city2graph.git
cd city2graph
# 以 detached 模式构建并运行
docker compose up -d
# 通过 http://localhost:8888 访问 Jupyter notebook
# 完成后停止容器
docker compose down
```
您可以根据需要在 `docker-compose.yml` 文件中自定义服务。
## 引用
如果您在研究中使用 City2Graph，请按如下方式引用：
```
@software{sato2025city2graph,
title = {City2Graph: Transform geospatial relations into graphs for spatial network analysis and Graph Neural Networks},
author = {Sato, Yuta},
year = {2025},
url = {https://github.com/c2g-dev/city2graph},
doi = {10.5281/zenodo.15858845},
}
```
您也可以使用 DOI 来引用特定版本：[](https://doi.org/10.5281/zenodo.15858845)
或者，您可以在本仓库的 [CITATION.cff](CITATION.cff) 文件中找到引用信息，该文件遵循 Citation File Format 标准。
## 贡献
我们欢迎对 City2Graph 项目的贡献！要做出贡献，请：
1. **派生并克隆仓库：**
git clone https://github.com//city2graph.git
cd city2graph
git remote add upstream https://github.com/c2g-dev/city2graph.git
2. **设置开发环境：**
uv sync --group dev --extra cpu
source .venv/bin/activate # 在 Windows 上使用：.venv\Scripts\activate
3. **创建特性分支：**
git checkout -b your-feature-name
4. **进行更改并测试：**
# 运行 pre-commit 检查
uv run pre-commit run --all-files
# 运行测试
uv run pytest -q
5. **提交拉取请求**，并附上对您更改的清晰描述。
有关详细的贡献指南、代码风格要求和文档标准，请参阅我们的[贡献指南](docs/contributing.md)。
## 代码质量
我们使用以下工具维持严格的代码质量标准：
- **Ruff**：用于代码检查和格式化
- **mypy**：用于静态类型检查
- **numpydoc**：用于 docstring 风格验证
所有贡献在合并前必须通过 pre-commit 检查。
## 文档
City2Graph 使用 **MkDocs** 作为当前版本的文档（v0.2.0+），并为旧版（v0.1.0–v0.1.7）保留 **Sphinx**。
- **旧版标签**（`v0.1.*`）：Read the Docs 通过 Sphinx 构建 `docs/source`。
- **其他所有内容**（分支 / 较新标签）：Read the Docs 通过 MkDocs（`mkdocs.yml`）进行构建。
这是通过在 `.readthedocs.yaml` 中使用 `READTHEDOCS_VERSION_TYPE` 和 `READTHEDOCS_VERSION_NAME` 进行控制的。
[](https://www.liverpool.ac.uk/geographic-data-science/)
标签：GeoAI, GeoPandas, GIS, GNN, NetworkX, OD矩阵, POI, Python, PyTorch Geometric, Vectored Exception Handling, 交通网络, 人工智能, 兴趣点, 图构建, 图神经网络, 图表示学习, 地理信息系统, 地理空间数据, 城市计算, 开源库, 搜索引擎爬虫, 数据转换, 数据预处理, 无后门, 智慧城市, 深度学习, 特权检测, 用户模式Hook绕过, 空间关系, 空间数据科学, 空间网络分析, 突变策略, 系统分析, 网络分析, 请求拦截, 起讫点矩阵, 逆向工具