项目地址: https://github.com/OSGeo/gdal
API 总览文档: https://gdal.org/en/stable/api/index.html
C/C++ API 参考: https://gdal.org/en/stable/api/index.html#c-api
Python API 参考: https://gdal.org/en/stable/api/python/index.html
Java API 参考: https://gdal.org/en/stable/api/java/index.html
C# API 参考: https://gdal.org/en/stable/api/csharp/index.html
最新版本: 3.13.3(截至 2026-10,下载页);Java 绑定(Maven Central)3.13.0
许可证: MIT
概述
GDAL 是地理空间数据处理的事实标准库,由 OSGeo 基金会维护。它提供:
- 200+ 栅格驱动:GeoTIFF、NetCDF、HDF5、COG、JPEG2000 等
- 100+ 矢量驱动:Shapefile、GeoJSON、GeoPackage、PostGIS、FlatGeobuf 等
- 坐标参考系统:基于 PROJ 的坐标变换与投影转换
- 栅格分析:重采样、镶嵌、裁剪、波段运算、DEM 分析等
- 矢量操作:空间过滤、属性查询、要素创建与编辑等
GDAL 核心以 C++ 实现,同时通过 SWIG 提供 Python、Java、C# 三种语言绑定,各语言 API 与 C++ 保持一致的类与方法命名。
环境准备
C++ 环境
# Linux (Debian/Ubuntu)
apt-get install libgdal-dev
# macOS (Homebrew)
brew install gdal
# CMake 项目中链接 GDAL
# CMakeLists.txt
find_package(GDAL REQUIRED)
target_link_libraries(myapp PRIVATE GDAL::GDAL)
Python 环境
# pip 安装(需系统已安装 GDAL 库)
pip install GDAL
# Conda 安装(推荐,自动处理 C 库依赖)
conda install -c conda-forge gdal
# 验证
python -c "from osgeo import gdal; print(gdal.VersionInfo())"
Java 环境
<!-- Maven 依赖(Java 绑定版本随 GDAL 次版本发布,Maven Central 当前最新 3.13.0) -->
<dependency>
<groupId>org.gdal</groupId>
<artifactId>gdal</artifactId>
<version>3.13.0</version><!-- 最新版查看 https://central.sonatype.com/artifact/org.gdal/gdal -->
</dependency>
// Gradle
implementation 'org.gdal:gdal:3.13.0'
注意: Java 绑定需要在系统 PATH(Windows)或 LD_LIBRARY_PATH(Linux)中找到 gdalalljni 本地库。
C# 环境
# .NET Core / .NET 5+ 项目
dotnet add package MaxRev.Gdal.Core
dotnet add package MaxRev.Gdal.LinuxRuntime.Minimal # Linux
dotnet add package MaxRev.Gdal.WindowsRuntime.Minimal # Windows
注意: 官方 SWIG 绑定命名空间为 OSGeo.GDAL、OSGeo.OGR、OSGeo.OSR。NuGet 包 MaxRev.Gdal.Core 是社区维护的跨平台封装,2026-10 的最新版为 3.13.3.583(对应 GDAL 3.13.3),运行时包需与 MaxRev.Gdal.Core 主版本一致。
核心 API 一览
GDAL API 在四种语言中保持一致的类结构,下表列出核心类及其作用:
栅格 API 核心类
| 类 | C++ 头文件 / 模块 | 用途 |
|---|---|---|
GDALDriver |
gdal_priv.h / osgeo.gdal |
栅格驱动——注册格式、创建数据集 |
GDALDataset |
gdal_priv.h / osgeo.gdal |
(推荐)栅格数据集——打开、读写、获取元数据 |
GDALRasterBand |
gdal_priv.h / osgeo.gdal |
栅格波段——读写像素、获取统计信息 |
GDALColorTable |
gdal_priv.h / osgeo.gdal |
颜色表——索引颜色映射 |
GDALRasterAttributeTable |
gdal_priv.h / osgeo.gdal |
栅格属性表 |
矢量 API 核心类(OGR)
| 类 | C++ 头文件 / 模块 | 用途 |
|---|---|---|
OGRSFDriver / GDALDriver |
ogrsf_frmts.h / osgeo.ogr |
矢量驱动 |
GDALDataset / OGRDataSource |
ogrsf_frmts.h / osgeo.ogr |
(推荐)矢量数据源——管理图层集合 |
OGRLayer |
ogrsf_frmts.h / osgeo.ogr |
(推荐)矢量图层——读写要素、空间过滤 |
OGRFeature |
ogr_feature.h / osgeo.ogr |
矢量要素——属性 + 几何 |
OGRFeatureDefn |
ogr_feature.h / osgeo.ogr |
要素定义——字段结构 |
OGRFieldDefn |
ogr_feature.h / osgeo.ogr |
字段定义——名称、类型 |
OGRGeometry |
ogr_geometry.h / osgeo.ogr |
几何基类(Point、LineString、Polygon 等) |
空间参考类(OSR)
| 类 | C++ 头文件 / 模块 | 用途 |
|---|---|---|
OGRSpatialReference |
ogr_spatialref.h / osgeo.osr |
(推荐)空间参考系统——定义 CRS |
OGRCoordinateTransformation |
ogr_spatialref.h / osgeo.osr |
(推荐)坐标变换——在不同 CRS 间转换坐标 |
各语言模块 / 命名空间对照
| 功能域 | C++ | Python | Java | C# |
|---|---|---|---|---|
| 栅格 | #include "gdal_priv.h" |
from osgeo import gdal |
import org.gdal.gdal.* |
using OSGeo.GDAL; |
| 矢量 | #include "ogrsf_frmts.h" |
from osgeo import ogr |
import org.gdal.ogr.* |
using OSGeo.OGR; |
| 空间参考 | #include "ogr_spatialref.h" |
from osgeo import osr |
import org.gdal.osr.* |
using OSGeo.OSR; |
栅格数据读取与创建写入的完整 API 与代码示例见 reference/raster-api.md 矢量数据读取与创建写入的完整 API 与代码示例见 reference/vector-api.md
坐标参考系统与坐标变换
C++
#include "ogr_spatialref.h"
// 定义坐标系
OGRSpatialReference srcSRS, dstSRS;
srcSRS.SetWellKnownGeogCS("WGS84"); // EPSG:4326
dstSRS.importFromEPSG(3857); // Web Mercator
// 创建坐标变换
OGRCoordinateTransformation *transform =
OGRCreateCoordinateTransformation(&srcSRS, &dstSRS);
// 变换坐标
double x = 116.4, y = 39.9;
if (transform->Transform(1, &x, &y)) {
// x, y 已变换为 EPSG:3857 坐标
}
// C++ 用 DestroyCT 归还;OCTDestroyCoordinateTransformation 是 C API(接收 OGRCoordinateTransformationH)
OGRCoordinateTransformation::DestroyCT(transform);
Python
from osgeo import osr
# 定义坐标系
src_srs = osr.SpatialReference()
src_srs.SetWellKnownGeogCS("WGS84") # EPSG:4326
dst_srs = osr.SpatialReference()
dst_srs.ImportFromEPSG(3857) # Web Mercator
# 创建坐标变换
transform = osr.CoordinateTransformation(src_srs, dst_srs)
# 变换坐标
x, y, z = transform.TransformPoint(116.4, 39.9)
Java
import org.gdal.osr.SpatialReference;
import org.gdal.osr.CoordinateTransformation;
import org.gdal.osr.osr;
// 定义坐标系
SpatialReference srcSRS = new SpatialReference();
srcSRS.SetWellKnownGeogCS("WGS84"); // EPSG:4326
SpatialReference dstSRS = new SpatialReference();
dstSRS.ImportFromEPSG(3857); // Web Mercator
// 创建坐标变换
CoordinateTransformation transform =
osr.CreateCoordinateTransformation(srcSRS, dstSRS);
// 变换坐标
double[] point = new double[]{116.4, 39.9, 0};
transform.TransformPoint(point);
// point[0], point[1] 已变换为 EPSG:3857 坐标
C#
using OSGeo.OSR;
// 定义坐标系
SpatialReference srcSRS = new SpatialReference("");
srcSRS.SetWellKnownGeogCS("WGS84"); // EPSG:4326
SpatialReference dstSRS = new SpatialReference("");
dstSRS.ImportFromEPSG(3857); // Web Mercator
// 创建坐标变换
CoordinateTransformation transform =
new CoordinateTransformation(srcSRS, dstSRS);
// 变换坐标
double[] point = new double[3] { 116.4, 39.9, 0 };
transform.TransformPoint(point);
// point[0], point[1] 已变换为 EPSG:3857 坐标
栅格格式转换与重投影的完整示例见 reference/raster-api.md 矢量格式转换、空间过滤、几何操作与 GeoPackage 读写的完整示例见 reference/vector-api.md 常用栅格数据格式与创建选项详见 reference/raster-api.md 常用矢量数据格式详见 reference/vector-api.md
典型工作流:矢量筛选与坐标变换
端到端示例(Python):读取 Shapefile → 空间 + 属性过滤 → 写出 GeoJSON:
from osgeo import gdal, ogr, osr
gdal.UseExceptions() # 启用异常模式,便于排错
src_ds = ogr.Open("cities.shp")
layer = src_ds.GetLayer(0)
layer.SetSpatialFilterRect(116.0, 39.5, 117.0, 40.5) # 空间粗筛(走空间索引)
layer.SetAttributeFilter("POPULATION > 1000000") # 属性过滤
dst_srs = osr.SpatialReference()
dst_srs.ImportFromEPSG(4326)
gdal.VectorTranslate(
"cities_filtered.geojson", src_ds,
format="GeoJSON", dstSRS=dst_srs,
layers=[layer.GetName()]
)
src_ds = None # 释放数据源
栅格端到端(读取 → 重投影 → 压缩写出)等价流程见 reference/raster-api.md。
典型应用场景
| 场景 | C++ | Python | Java | C# |
|---|---|---|---|---|
| 读取栅格元数据 | GDALOpen + GetGeoTransform |
gdal.Open + GetGeoTransform |
gdal.Open + GetGeoTransform |
Gdal.Open + GetGeoTransform |
| 栅格格式转换 | CreateCopy |
gdal.Translate |
gdal.Translate |
Gdal.wrapper_GDALTranslate |
| 栅格重投影 | GDALAutoCreateWarpedVRT |
gdal.Warp |
gdal.Warp |
Gdal.Warp |
| 读取矢量要素 | GDALOpenEx + GetNextFeature |
ogr.Open + 迭代 |
ogr.Open + GetNextFeature |
Ogr.Open + GetNextFeature |
| 矢量格式转换 | CopyLayer / CreateFeature |
gdal.VectorTranslate |
ogr.CopyLayer |
Ogr.CopyLayer |
| 坐标变换 | OGRCreateCoordinateTransformation |
osr.CoordinateTransformation |
osr.CreateCoordinateTransformation |
new CoordinateTransformation |
| 创建缓冲区 | OGRGeometry::Buffer |
geom.Buffer |
geom.Buffer |
geom.Buffer |
| 空间查询 | SetSpatialFilterRect |
SetSpatialFilterRect |
SetSpatialFilterRect |
SetSpatialFilterRect |
| SQL 查询 | ExecuteSQL |
ExecuteSQL |
ExecuteSQL |
ExecuteSQL |
| 波段运算 | RasterIO 手动计算 |
gdal_calc.py / NumPy |
RasterIO 手动计算 |
RasterIO 手动计算 |
常见问题
| 类别 | 问题 | 解决 |
|---|---|---|
| 通用 | 功能调用报「驱动未注册」 | 先注册:C++/Python GDALAllRegister();Java gdal.AllRegister();C# Gdal.AllRegister();矢量另需 OGRRegisterAll() / ogr.RegisterAll() |
| 通用 | 文件损坏 / 写入未生效 | 及时释放资源:C++ GDALClose()、OGRFeature::DestroyFeature();Python 赋值 None;Java .delete();C# .Dispose() |
| 通用 | 经纬度顺序颠倒 | GDAL 3.0+ 默认纬度在前;用 OGRSpatialReference::SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER) 强制经度在前 |
| 通用 | 多线程下崩溃 | GDAL 全局状态非线程安全:每个线程使用独立 GDALDataset,避免并发写同一数据集 |
| 通用 | 大栅格内存溢出 | 用 RasterIO 指定窗口分块读写,避免一次性读入整个影像 |
| 通用 | 报错信息不明确 | C++ 用 CPLGetLastErrorMsg(),Python 用 gdal.GetLastErrorMsg() 获取详细错误 |
| C++ | WKT 等 C 字符串泄漏 | 用 CPLFree() 释放(如 exportToWkt 返回值);几何用 OGRGeometryFactory::destroyGeometry() |
| C++ | 坐标变换释放方式混用 | C++ 用 OGRCoordinateTransformation::DestroyCT();OCTDestroyCoordinateTransformation() 只接收 C API 的 OGRCoordinateTransformationH |
| C++ | 编译 / 链接失败 | 用 gdal-config --cflags --libs 或 CMake find_package(GDAL) 配置编译参数 |
| Python | 出错却不抛异常 | 脚本开头调用 gdal.UseExceptions() 启用异常模式 |
| Python | 如何高效读写像素 | band.ReadAsArray() / band.WriteArray(array) 直接与 NumPy 数组互转 |
| Java | UnsatisfiedLinkError |
确保 gdalalljni(Linux libgdalalljni.so、Windows gdalalljni.dll)在 java.library.path 中 |
| Java | 选项参数如何传递 | 许多方法使用 java.util.Vector<String> 传递选项参数 |
| C# | 本地库加载失败 | 按目标平台引入对应 NuGet 运行时包(Linux / Windows / macOS) |
| C# | 中文路径乱码 | 字符串参数默认 UTF-8,注意编码一致性 |
AI 使用建议
- 本技能的组织:主文件给高频用法,完整参数表与高级示例在
reference/raster-api.md、reference/vector-api.md,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。 - 执行环境:编译与运行在终端 / shell 中执行(Windows 用 PowerShell)。C++ 用
gdal-config --cflags --libs或 CMakefind_package(GDAL REQUIRED);Python 用装好绑定的解释器;Java 的gdalalljni、.NET 的 MaxRev 运行时包必须与平台、架构匹配。 - 先探测版本:
ogrinfo --version、python -c "from osgeo import gdal; print(gdal.VersionInfo())"(返回3130300这类数字)、mvn -v、dotnet --version;本技能按 GDAL 3.13.3、Java 绑定 3.13.0 编写,低版本缺少新驱动与部分 SWIG 方法,回答里要说明差异。 - 验证产物:写完后重新打开核对——
python -c "from osgeo import gdal; ds=gdal.Open('out.tif'); print(ds.GetDriver().ShortName, ds.RasterCount, ds.GetSpatialRef().GetAuthorityCode(None))";矢量用ogrinfo -al -so out.gpkg看要素数与字段;Python 一律先gdal.UseExceptions(),否则错误被静默吞掉。 - 语言选择:数据处理脚本优先 Python(
ReadAsArray()直通 NumPy);生产服务与嵌入式优先 C++;Java 注意用java.util.Vector<String>传选项;.NET 用OSGeo.GDAL/OSGeo.OGR命名空间,或 MaxRev 封装 + 对应平台运行时包。 - 资源与轴序:Python 置
ds = None、C++GDALClose()、Java.delete()、C#.Dispose()之后才算落盘;GDAL 3+ 默认纬度在前,需要经度在前时用SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER),轴序改错是坐标错位最常见的原因。 - 安全与权限:以更新模式(
gdal.GA_Update、GDALOpen(..., GA_Update))打开会直接改原文件;覆盖已有输出前先确认;安装libgdal-dev、dotnet add package、写系统目录前先征得用户同意。
相关技能
- gdal — GDAL 命令行工具:../gdal/SKILL.md
- jts — Java 几何引擎(比 OGR 几何更丰富):../jts/SKILL.md
- pyqgis — QGIS Python 开发(内部使用 GDAL):../pyqgis/SKILL.md
- postgis — PostgreSQL 空间数据库(与 GDAL 配合导入导出):../postgis/SKILL.md
- opengis-all — 一站式 GIS 全流程:../opengis-all/SKILL.md
参考资源
- GitHub 仓库: https://github.com/OSGeo/gdal
- API 总览: https://gdal.org/en/stable/api/index.html
- C/C++ API 文档: https://gdal.org/en/stable/api/index.html#c-api
- Python API 文档: https://gdal.org/en/stable/api/python/index.html
- Python 绑定说明: https://gdal.org/en/stable/api/python/python_bindings.html
- Java API 文档: https://gdal.org/en/stable/api/java/index.html
- C# API 文档: https://gdal.org/en/stable/api/csharp/index.html
- SWIG 绑定源码: https://github.com/OSGeo/gdal/tree/master/swig
- 官方文档首页: https://gdal.org/en/stable/
- GDAL 教程: https://gdal.org/en/stable/tutorials/index.html
- 驱动格式列表: https://gdal.org/en/stable/drivers/vector/index.html
- 问题追踪: https://github.com/OSGeo/gdal/issues