The Problem
Geospatial data is stored as points, lines, and polygons, but most GeoAI and Graph Neural Network (GNN) workflows need graph structures. Converting between these representations manually is error-prone and time-consuming. City2Graph provides a standardized Python interface for turning geospatial datasets into graphs across multiple urban domains.
What This Does
City2Graph is a Python library that bridges GeoPandas, NetworkX, and PyTorch Geometric. The core modules in city2graph/ handle distinct graph construction tasks: proximity.py builds graphs from spatial distance and contiguity, transportation.py models transit networks from GTFS feeds, mobility.py handles flow data like bike-sharing and migration, and morphology.py constructs graphs from building and street geometry. metapath.py adds typed multi-relational edges for heterogeneous graph learning.
The library is distributed on PyPI and conda-forge, with optional extras for PyTorch CPU or CUDA support. The pyproject.toml defines these extras, and the docs/examples/ folder contains Jupyter notebooks showing real workflows.
How To Use It
Setup: Install via pip or conda. For basic graph construction without deep learning dependencies:
pip install city2graph
For GNN support with GPU acceleration, use a CUDA-specific extra:
pip install "city2graph[cu130]"
Configuration: No environment variables or config files are required. The library functions accept GeoPandas GeoDataFrame objects directly.
Running it: The library is used as an imported Python package. Entry points are the module functions, e.g., from city2graph.proximity import generateproximitygraph. A Dockerfile and docker-compose.yml exist for containerized development, but the primary usage is as a library.
Real-World Use
A typical workflow: load building footprints from OpenStreetMap or Overture Maps, construct a proximity graph, then feed it to a GNN for urban function classification.
import geopandas as gpd from city2graph.proximity import generateproximitygraph
buildings = gpd.readfile("buildings.geojson") graph = generateproximitygraph(buildings, distancethreshold=100) graph is a NetworkX object; convert for PyTorch Geometric as needed
Code Health & Issues
Low - Missing lockfile for pip reproducibility - pyproject.toml declares dependencies but the uv.lock file is present, which mitigates this. The lockfile is for uv, not pip, so pip users get floating versions. Low - Large documentation asset files - The docs/assets/ folder contains PSD files and MP4 videos. These bloat the repository but do not affect runtime. Good - Tests exist in tests/ covering all core modules, CI is configured via GitHub Actions (.github/workflows/), and the project has a LICENSE, SECURITY.md, and CITATION.cff. The codebase appears well-maintained with pre-commit hooks and Ruff linting configured.
The Bottom Line
City2Graph is a focused, well-structured library for a specific niche: converting urban geospatial data into graph formats for GNN research. The domain coverage is solid, documentation is thorough, and the test suite is reasonable. It is best suited for researchers and data scientists working on GeoAI problems who want to avoid writing custom conversion code. The lack of a pip lockfile is a minor concern for reproducibility, but the uv.lock mitigates this for users on that toolchain.