geo-data-engineering

地理空间数据工程

目的：通过可重复的流水线，将空间数据处理为干净、经过验证且可用于分析的状态——这是现实世界中大多数 GIS 时间花费所在的阶段，也是大多数隐蔽错误产生的阶段。

格式选择

格式	适用场景	不适用的原因
GeoParquet	分析数据交换、大型矢量数据、列式工作流	一些旧版桌面 GIS 尚无法读取
GeoPackage	桌面 GIS 数据交换、多图层项目	大规模处理时比 Parquet 慢；SQLite 锁定
FlatGeobuf	流式处理、HTTP 范围读取	仅支持单图层
COG（Cloud-Optimized GeoTIFF）	所有栅格交付物	—（将每个 GeoTIFF 都制作为 COG）
Zarr/NetCDF	多维数据（时间 × 波段 × y × x）	对单个栅格来说过于复杂
Shapefile	仅在旧版工具有要求时使用	列名限 10 个字符、上限 2 GB、编码混乱、多文件易损
CSV + WKT/lon-lat	简单的点数据交换	没有 CRS 元数据——请明确记录

数据获取指南

• OpenStreetMap：小范围 → osmnx；大型数据提取 → Geofabrik PBF + pyrosm/osmium。注意标签的异质性：筛选前务必检查标签值分布。
• 大规模建筑物/地点数据：Overture Maps（S3/Azure 上的 GeoParquet， 使用 DuckDB spatial 查询——通常是最快的途径）。
• 卫星/栅格数据：通过 pystac-client + odc-stac 使用 STAC API——参见 remote-sensing-analysis；全球档案 → google-earth-engine。
• 边界数据：优先使用权威的国家级来源；全球工作使用 Natural Earth / GADM / geoBoundaries——记录所用来源，因为不同版本存在实质性差异。
• 记录每次数据获取的信息：来源 URL、查询参数、获取日期、 许可证。将其写入数据旁的 DATA_SOURCES.md 文件。

CRS 工程

• 以 EPSG:4326 或源 CRS 存储；使用适合范围的投影 CRS 进行分析：本地 UTM 带（gdf.estimate_utm_crs()）、国家网格，或 用于跨区域面积统计的等面积投影（EPSG:6933/Mollweide）。
• 亚米级精度下，大地基准转换很重要：不同大地基准之间的转换 需要使用正确的转换网格（对精度有要求时，使用 pyproj.network.set_network_enabled(True)）。
• 切勿通过删除或覆盖 CRS 来“修复”图层未对齐的问题——应使用已知地标诊断出错的图层。

清理流水线

运行 scripts/clean_vector.py（或导入其 clean_vector() 函数）作为 标准清理流程：删除空或空值几何，使用 make_valid 修复无效几何， 去重，重新投影，并打印核算报告，从而避免数据悄然丢失。

然后：规范化文本属性（去除首尾空格、合并空白字符、进行符合区域设置的大小写折叠——注意土耳其语 İ/ı、德语 ß），显式转换数据类型，并展示之后会用于筛选的每个分类变量的 value_counts()。

规模处理策略

• 可装入内存：使用 GeoPandas + Shapely 2 的矢量化操作。确保使用空间 索引（sjoin、query_bulk）——手写循环的复杂度为 O(n²)。
• 超出内存容量，单机处理：使用 DuckDB 的 spatial 扩展处理 GeoParquet（谓词下推 + 空间 SQL），或使用 dask-geopandas。
• 服务化/并发/事务处理：使用 PostGIS——参见 postgis-spatial-sql。
• 栅格：使用窗口读取（rasterio.windows）、分块的 xarray + dask； 切勿将 50 GB 的镶嵌数据通过 read() 全部载入内存。

流水线标准

• 步骤应具备幂等性，并明确指定磁盘上的输入/输出；重复运行不会 损坏状态。
• 在开销较大的阶段（下载、大型连接）之后，使用 GeoParquet/GPKG 创建检查点。
• 每个阶段都记录核算信息：输入 → 输出的行数/要素数/像元数。
• 写入前采用确定性的排序（按稳定键排序），使差异具有参考意义。

常见陷阱清单

• 打开 CSV 时未声明经纬度列的 CRS。
• 导出时 Shapefile 列名被静默截断。
• 旧文件出现编码乱码（先尝试 encoding="utf-8"，再尝试 cp1252）。
• 单个图层中包含混合几何类型（Polygon + MultiPolygon 会导致某些工具出错——使用 .explode() 规范化，或提升为 Multi*）。
• 简单重投影后出现跨越日期变更线或极点的几何图形。
• 下载了“最新”数据，却未记录版本或日期——无法复现。

执行约定

• **工作流：**盘点数据源和约定；获取数据并记录来源信息；检查 CRS、模式、几何和比例尺；以确定性方式清理；验证；写出可用于分析的制品。
• **决策规则：**根据数据大小、几何、并发情况和下游访问需求选择格式与引擎；绝不静默推断 CRS 或执行破坏性修复。
• **验证协议：**在每个阶段核对要素或像素数量，断言 CRS 和几何不变量，对输出进行空间抽样，并重新运行以确认幂等性。
• **故障处理：**对含糊不清的 CRS、混合单位、无效编码、有损格式转换或无法解释的行丢失进行隔离，而不是猜测。
• **交付物：**经过验证的数据集、机器可读的模式和 CRS、来源信息清单、核算日志、被拒记录报告，以及可复现的流水线。
• **数据源时效性：**使用版本敏感的格式或 API 前，请查阅权威数据源注册表，并记录查阅日期。