GDAL Python 接口怎么用
GDAL 的 Python 接口通过 from osgeo import gdal、ogr、osr 等模块调用，用来读写栅格和矢量地理空间数据。安装优先选 conda-forge，保证 libgdal 与绑定版本一致；写代码时先执行 gdal.UseExceptions()，再用 gdal.Open、ReadAsArray 或 OGR 图层接口完成读写。绑定由 SWIG 生成，与 C++ API 高度对应。截至 2026 年 11 月，最新稳定版为 GDAL 3.13.3（2026-08-18 发布），要求 Python ≥3.8。
怎么安装 GDAL Python 绑定
先解决“环境里有没有匹配的 libgdal”，再装 Python 包。Windows 和 macOS 上混用系统 Python 与预编译二进制最容易踩坑，跨平台推荐 Conda。
- Conda（推荐）：conda install -c conda-forge gdal。需要完整驱动可再装 libgdal meta-package；Parquet/Arrow、netCDF 等按需装对应 libgdal-* 插件包。Conda 一般会处理好 GDAL_DATA、PROJ_LIB。
- pip：系统已有匹配版本的 libgdal 及开发头文件时，可用 pip install gdal。若要 NumPy 支持，先装 numpy、wheel、setuptools，再按 gdal-config –version 对齐版本安装；验证可用 python -c “from osgeo import gdal_array”。缓存异常时加 –no-cache –force-reinstall。
- 系统包 + pip：Debian/Ubuntu 可先 apt install gdal-bin libgdal-dev，再 pip；macOS 可用 Homebrew 装 gdal 后 pip；Windows 更稳妥的是 Conda、OSGeo4W 或匹配的预编译 wheel，避免 DLL 与编译器版本冲突。
官方以源码与 Docker 为主分发，二进制多由第三方提供。版本与构建依赖以官网下载页为准；自 GDAL 3.9 起 Python 要求 ≥3.8，构建侧常见需求包括 C++17、CMake ≥3.16、PROJ ≥6.3.1 等。安装后用下面命令确认模块可导入：
- from osgeo import gdal, ogr, osr
- print(gdal.__version__)，核对是否与期望的 libgdal 一致
| 安装方式 | 适用场景 | 注意点 |
|---|---|---|
| conda-forge | 跨平台日常开发 | 插件按需装 libgdal-*；环境变量通常已配好 |
| pip + 系统 libgdal | Linux 已装开发包 | 版本必须匹配；NumPy 需单独启用 |
| OSGeo4W / 预编译 wheel | Windows 快速上手 | 勿混用多套 Python；检查 PATH、PROJ_LIB、GDAL_DATA |
栅格数据读写怎么做
栅格入口是 gdal 模块。打开数据集、读波段、转 NumPy 数组是最常用路径；写文件时指定驱动与创建选项。
- 开启异常：gdal.UseExceptions()（强烈建议；未显式调用时可能有 FutureWarning，GDAL 4.0 计划默认开启）。
- 打开：ds = gdal.Open(path, gdal.GA_ReadOnly)。失败时若未开异常会返回 None。
- 读元数据与波段：ds.RasterXSize、ds.GetGeoTransform()、ds.GetProjection()；band = ds.GetRasterBand(1)，再 band.ReadAsArray() 或整幅 ds.ReadAsArray()（需 gdal_array/NumPy）。
- 写出：用 gdal.GetDriverByName(“GTiff”).Create(…) 或 CreateCopy，写完后对 Dataset 调用 FlushCache/Close，或使用上下文管理器（GDAL 3.8+ 支持 Close）。
验收标准：能打印行列数与地理变换；数组形状与波段一致；写出的 GeoTIFF 能被 QGIS 或其他 GDAL 工具正确打开且投影未丢。更完整的 Raster API 说明见 GDAL Python API 文档。
矢量与空间参考怎么用
矢量走 ogr，空间参考走 osr。典型流程是打开数据源 → 取图层 → 遍历要素 → 读几何与字段。
- 打开：ds = ogr.Open(path) 或 gdal.OpenEx（可同时处理栅格/矢量）。
- 图层：layer = ds.GetLayer(0)；可设空间过滤或属性过滤（注意属性过滤主要影响 GetNextFeature 一类迭代）。
- 要素：循环 feat = layer.GetNextFeature()，取几何 feat.GetGeometryRef()，取字段按索引或名称。
- 投影：用 osr.SpatialReference 导入 WKT/EPSG，再对几何做 Transform；也可从图层 GetSpatialRef 读取。
创建矢量时先建驱动、建数据源、建图层并定义字段，再创建 Feature 写入。写完后务必关闭数据源，避免文件锁或未刷盘。几何操作依赖 GEOS 等可选依赖，环境缺库时相关方法会失败，需对照安装的驱动与插件。
使用时要注意哪些坑
Python 绑定和常见“纯 Python 库”习惯不一致，官方 Gotchas 页列得很清楚，动手前先记住这几条。
- 默认不抛异常：错误常返回 None 并往 stdout 打信息。一上来就 gdal.UseExceptions()；需要安静模式再用 DontUseExceptions()。
- 对象生命周期：Dataset 被销毁后，其上的 Band、图层、要素引用可能崩溃。保持父对象存活，避免一行链式临时对象；优先 with 或显式 Close。
- 勿滥用 Destroy：更推荐 Close / 上下文管理；随意 Destroy 容易留下悬空引用。
- NumPy ABI：升级或降级 NumPy 后若绑定未重建，可能崩溃；conda 环境里尽量整体升级，pip 则按版本对齐重装。
- 驱动/插件缺失：报错常提示缺某个格式。Conda 下安装对应 libgdal-*；检查 GDAL_DRIVER_PATH。
- 环境变量：自建或混装环境时确认 GDAL_DATA、PROJ_LIB、PATH；Conda 一般已设好。
细节与更多边界行为见 Python 绑定常见陷阱说明。验收时故意关掉异常、提前 del Dataset 再读 Band，能快速验证自己是否踩中生命周期问题。
常见问题
pip 安装失败或导入报 DLL/找不到模块怎么办？
多数是 libgdal 版本与 wheel 不匹配，或 Windows 下 PATH/编译器不一致。优先改用 conda-forge；若必须 pip，先装好同版本开发头与 gdal-config，再强制重装，并检查 PROJ_LIB、GDAL_DATA。不要混用 OSGeo4W Python 与系统 Python。
ReadAsArray 不可用或一用就崩？
通常是构建时未带 NumPy，或运行时 NumPy 主版本与绑定 ABI 不一致。验证 from osgeo import gdal_array；在 conda 中重装 gdal/numpy，或按官方说明带 numpy extra 重装绑定。
打开文件返回 None，却没有异常？
未调用 gdal.UseExceptions() 时的默认行为。先开启异常，再根据报错查路径、驱动是否注册、文件是否损坏或权限问题。
矢量图层设了属性过滤却好像没生效？
属性过滤主要作用于 GetNextFeature 等迭代接口；若用了其他取要素方式或过滤后未重置读取位置，会表现为“没过滤”。按官方 Gotchas 用正确的遍历方式，并在改过滤条件后重置阅读。
用 GDAL Python 接口时，先保证 libgdal 与绑定同版本并开启异常，再按栅格 Open/ReadAsArray、矢量图层遍历的固定套路写代码，同时盯住 Dataset 生命周期与驱动插件。建议：新环境一律用 conda-forge 安装并对齐插件包；每个脚本开头固定 gdal.UseExceptions()，读写后用 Close 或 with 收尾，避免隐蔽崩溃。