geopandas

GeoPandas

使用 GeoPandas 处理以类似 pandas 的 GeoSeries 和 GeoDataFrame 对象表示的平面矢量数据。本技能面向稳定版 GeoPandas 1.1.4（于 2026-06-26 发布），而非尚未发布的 1.2 版文档。

可复现环境

GeoPandas 1.1.4 要求 Python 3.10+；其标记版本的源代码要求 NumPy >=1.24、pandas >=2.0、Shapely >=2.0、pyproj >=3.5、pyogrio >=0.7.2 和 packaging。此 Python 3.12 精确快照已于 2026-07-23 通过冒烟测试：

uv venv --python 3.12
uv pip install \
  "geopandas==1.1.4" \
  "numpy==2.5.1" \
  "pandas==3.0.5" \
  "shapely==2.1.2" \
  "pyproj==3.7.2" \
  "pyogrio==0.13.0" \
  "pyarrow==25.0.0" \
  "packaging==26.2"

还应在项目锁定文件中固定可选绘图和 PostGIS 软件包的版本。不要混用来自不兼容软件包渠道的二进制地理空间软件包。

安全与隐私约定

• 将精确坐标、地址、地块边界、轨迹和小区域连接视为敏感信息。报告默认仅提供计数、类别、粗略范围和已脱敏标识符。发布前进行泛化处理。
• 切勿自动加载 URL、云 URI、GDAL /vsi* 路径、归档文件，也不要自动对地址进行地理编码。先取得明确批准，验证来源信息和哈希值，再将解压后的本地文件暂存到隔离工作区。
• GDAL/OGR 驱动、GEOS、PROJ、pyogrio、Shapely、pyproj 及其 wheel 属于原生代码信任边界。优先使用官方 wheel/conda-forge，记录原生组件版本，限制驱动，并在沙箱中处理不可信数据。
• 不要通过宽松的 GDAL 驱动打开启用宏的办公文件或嵌套归档。捆绑的 CLI 使用扩展名允许列表并拒绝归档文件。
• 只读取名称明确的数据库密钥，例如 GEOPANDAS_POSTGIS_PASSWORD；使用密钥管理器或作用域受限的环境变量。切勿将密码嵌入 URL 或源代码、打印 engine/URL，或转储环境变量。
• 每个派生产物都需要记录源哈希值/版本、CRS、操作参数、谓词、连接基数、精度/修复选项以及行数检查结果。

正确性检查关卡

在信任结果前，应用以下检查：

1. 身份与来源 — 确认源图层、稳定要素键、重复 ID、行数、几何列、解析器/驱动和内容哈希值。
2. 几何状态 — 分别统计空值、空几何、无效几何、混合几何、Z/M 和退化几何。None 表示缺失；空的 Shapely 几何是真实几何。
3. CRS 语义 — 必须有 CRS 元数据。set_crs() 用于指定元数据；to_crs() 用于转换坐标。切勿根据坐标范围猜测 CRS。
4. 单位与操作 — GeoPandas 使用平面计算。地理坐标的单位是角度；不要直接将其用于缓冲区、距离、面积、最近邻连接、精度网格或容差计算。选择适用的局部/等面积 CRS，或使用大地测量方法。
5. 转换质量 — 检查轴顺序、适用范围、大地基准转换管线、预期精度、近似转换状态和缺失网格。除非用户明确批准获取网格，否则保持 PROJ 网络禁用。
6. 拓扑与精度 — 在修复/叠加前后进行验证。根据源数据精度和 CRS 单位选择精度网格；任意吸附可能使要素退化或造成偏差。
7. 基数 — 在使用 merge、sjoin 或 sjoin_nearest 前，说明预期的一对一、一对多或多对多行为；之后审核未匹配和行数倍增的情况。
8. 输出约定 — 使用新的输出路径，保留稳定的要素 ID，记录架构/CRS/编码，重新打开产物，并比较计数/类型。

CRS 和反子午线规则

GeoPandas 将 CRS 存储为 pyproj.CRS。坐标数组使用传统 GIS (x, y) 顺序，而权威定义可能会将轴指定为纬度优先。对于显式的坐标数组处理流程，请使用 Transformer(..., always_xy=True)，并记录这一选择。

to_crs() 会转换顶点，并假定每条线段在源 CRS 中都是直线；它不会转换大地线弧。跨越 ±180° 或投影边界的几何可能会严重错位。请在有文档记录的地理表示中检测跨界、拆分／解缠并加密，再转换各部分，最后进行验证。不要将 Web Mercator 用作通用测量 CRS。

crs = gdf.crs  # a pyproj.CRS when present
if crs is None or crs.is_geographic:
    raise ValueError("Choose a justified projected CRS before planar measurement")

unit_names = [axis.unit_name for axis in crs.axis_info]
areas = gdf.geometry.area  # square CRS units, not automatically square metres

请参阅 CRS 管理。

核心 API 决策

数据结构

• GeoDataFrame 可以包含多个几何列，每列都有 CRS 元数据，但只有 active_geometry_name 会驱动框架级空间操作。
• 二元 GeoSeries 方法按行处理，并默认按索引对齐。只有在明确需要按位置配对且已验证长度和顺序时，才使用 align=False。
• 重复的列名和重复的要素 ID 容易引起歧义；在联接和导出前应拒绝或解决这些问题。

请参阅 数据结构。

几何有效性、精度和并集

在使用 make_valid(method="linework"|"structure", keep_collapsed=...) 前，请使用 is_valid 和已脱敏的 is_valid_reason() 类别。修复可能会更改几何类型或维度；请保留原始数据，并比较数量、面积、类型、空几何和退化部分。

set_precision(grid_size, mode=...) 使用 CRS 单位，且可能移除重复顶点或使要素退化。union_all(method="unary", grid_size=...) 是稳健的默认选项。仅在 is_valid_coverage() 确认不存在重叠且边界匹配后才使用 coverage；当其分区假设适用时，可在 Shapely >=2.1 中使用 disjoint_subset。

请参阅 几何操作。

联接、叠加、裁剪和融合

• sjoin 谓词具有方向性：left.within(right) 不等同于 left.contains(right)。intersects 包含边界接触；contains 不包含仅接触边界的点，而 covers 包含边界点。
• predicate="dwithin" 需要 distance；标量距离或逐左侧行指定的距离均以 CRS 单位表示。sjoin_nearest 会返回所有距离相同的最近匹配项，并不实现 k= 参数。
• overlay(..., make_valid=True) 会修复无效输入，但可能更改类型；keep_geom_type=None 会在发出警告的同时丢弃其他类型。精度不匹配可能会产生狭长碎片；请量化这些碎片，而不是默默删除它们。
• clip 会融合掩膜。矩形裁剪速度快，但结果可能不精确，也可能遗漏退化为点的线；请验证输出。
• dissolve 将 groupby.agg 与 union_all 结合使用；请明确选择属性聚合方式，并审查空值分组键。

请参阅 空间分析。

I/O、Arrow 和 PostGIS

GeoPandas 1.x 默认使用 pyogrio。驱动程序的可用性和语义取决于已安装的 GDAL，而不只取决于 GeoPandas。通用数据交换优先使用本地 GeoPackage，列式互操作优先使用 WKB GeoParquet。

GeoParquet 默认使用稳定的架构 1.0.0。原生 GeoArrow 编码和 bbox 覆盖需要架构 1.1.0，且互操作性仍较低。缺少 GeoParquet 的 crs 键表示 OGC:CRS84；显式设置 crs: null 则表示未知——不要将两者混为一谈。每次导出后都应重新打开并验证。

对 PostGIS 使用参数化 SQL 和 SQLAlchemy Engine／Connection。if_exists="replace" 会造成破坏；默认使用 "fail"，并使用事务。

请参阅 数据 I/O。

迁移检查清单

对于从 GeoPandas 0.14 或更早版本迁移的代码：

• GeoPandas 1.0 仅支持 Shapely >=2；PyGEOS、Shapely <2 和 rtree 空间索引后端均已移除。
• pyogrio 已取代 Fiona，成为已安装/默认的 I/O 引擎。请显式设置 engine=，并测试 schema、空值、日期时间、编码和追加行为。
• 将 sjoin(op=...) 替换为 predicate=，将 sindex.query_bulk() 替换为 sindex.query()，将 unary_union 替换为 union_all()，并将 GeometryArray.data 替换为 to_numpy()/np.asarray。
• 将 read_file(include_fields=...|ignore_fields=...) 替换为 columns=。使用 schema_version=，不要使用已移除的 GeoParquet version= 兼容选项。
• 不要使用已移除的 geopandas.datasets、内部 geopandas.io.* 入口点、绘图 axes/colormap 或集合运算符。
• explode() 现在默认 index_parts=False；传入 set_geometry() 的命名 Series 会提供新的活动列名称；命名的右侧索引可以在 sjoin 输出中取代 index_right。
• 不要通过赋值 .crs 覆盖元数据，也不要依赖已弃用的 set_geometry(drop=...)；请显式使用 set_crs()，并执行重命名/删除步骤。
• GeoPandas 1.1 要求 Python >=3.10、pandas >=2.0、NumPy >=1.24 和 pyproj >=3.5。版本 1.1.2 修复了通过 PostGIS 几何列名称进行的 SQL 注入；固定使用的 1.1.4 已包含此修复。

绘图与探索

地图是分析结果：请标注单位、分类方法、缺失数据、标准化分母和日期。explore() 可能会在工具提示/弹出窗口中暴露所有属性，并联系地图瓦片/CDN 服务器；请先进行泛化，并在本地草稿中使用 tiles=None、tooltip=False 和 popup=False。

参见可视化。

捆绑的本地 CLI

所有辅助工具均为确定性工具，会拒绝网络/归档路径、限制输入字节数和要素数量、延迟导入以确保 --help 无需依赖即可运行，并输出不含坐标或记录标识符的 JSON。

CLI	用途
scripts/vector_inventory.py	脱敏的本地矢量/GeoParquet 技术清单
scripts/crs_reprojection_plan.py	CRS 单位、坐标轴、候选变换和跨日期变更线方案
scripts/geometry_validity_report.py	有效性审计试运行；可选修复并写入新的 GeoPackage
scripts/spatial_join_audit.py	谓词语义、重复 ID 和连接基数
scripts/export_plan.py	不执行的矢量/GeoParquet 导出规范
scripts/sensitive_coordinates_checklist.py	隐私/泛化发布门禁

python skills/geopandas/scripts/vector_inventory.py --help
python skills/geopandas/scripts/crs_reprojection_plan.py \
  --source-crs EPSG:4326 --target-crs EPSG:32631
python skills/geopandas/scripts/geometry_validity_report.py data.gpkg
python skills/geopandas/scripts/spatial_join_audit.py points.gpkg zones.gpkg \
  --predicate within --left-id point_id --right-id zone_id
python skills/geopandas/scripts/export_plan.py data.gpkg result.parquet \
  --format geoparquet --schema-version 1.0.0 \
  --stable-id-column feature_id --id-unique-verified
python skills/geopandas/scripts/sensitive_coordinates_checklist.py \
  --public-output --precise-points --contains-addresses

参考索引

• 数据结构
• CRS 管理
• 几何运算
• 空间分析
• 数据 I/O
• 可视化

来源（已于 2026-07-23 核实）

• PyPI 上的 GeoPandas 1.1.4 — 发布于 2026-06-26。
• GeoPandas 1.1.4 发布说明 — 错误修复版本。
• GeoPandas 1.1.4 标签对应的依赖项。
• GeoPandas 稳定版文档。
• GeoPandas 1.0 迁移版本。

相关技能

• geomaster：使用 GeoPandas、Rasterio、GDAL、Xarray、Shapely、Laspy、PDAL、Google Earth Engine 等提供地理空间和地球观测工作流。