简介这是一份面向 QTMinGW 版C 开发者的 Windows 预编译 GDAL 1.11.5 开发包采用 MSYS2 MinGW64 工具链编译可让使用者跳过源码编译阶段直接获得可链接的库文件与命令行工具。压缩包约 70.71MB共 149 个文件其中 63 个头文件用于 C API 调用28 个 CSV 文件提供投影坐标系、基准面转换参数及要素目录数据22 个 exe 覆盖常见 GDAL 命令工具同时附带静态库、动态库以及 GFS、WKT、DXF、DGN 等格式支持文件为不同数据源接入提供便利。资源已吸引 1520 人学习下载特别适合在 QT/Mingw 工程中完成 GDAL 的快速集成省去自行编译配置的兼容性烦恼。作者还针对解压使用后可能出现的程序异常结束问题给出配套排查指引能够帮助开发者在 GIS 二次开发、空间数据解析与投影转换等任务中更顺畅地上手这对于需要快速搭建 GIS 原型或验证算法的开发者尤为实用。1. 老版本 GDAL 1.11.5为什么还在用它解决了什么做 C 桌面端 GIS 工具的人多半在某个下午被 GDAL 折腾得想摔鼠标我当时也是这样。本来在 MSVC 下编好的 GDAL 库换到 Qt MinGW 环境后就各种装不上找不到符号、头文件路径不对、Debug/Release 混了……直到有人甩给我一个用 mingw64 编译好的 GDAL 1.11.5至少省掉了我两天的编译时间。别小看这个版本它发布于 2015 年却依然是老项目里最稳的选择尤其对还在维护 Qt 5 / Qt 4 时代代码的人来说。GDAL 是地理数据格式转换和处理的事实标准1.11.5 属于 1.x 系列晚期补丁版功能上够用——支持几十种栅格格式读写矢量库 OGR 也在里边不需要再单独装一套。装上它你可以直接在自己的 C 工程里打开 Shapefile、GeoTIFF、ENVI 等格式做坐标转换、裁剪、重采样甚至借助它封一层 Qt 界面做图层管理。我这里拿到的是别人编译好的二进制不是源码编译流程所以讲的是“怎么用”不是“怎么从零编”。适合谁呢不是所有做 GIS 的都适合它。如果你打算写生产级工具给客户和其他开发者使用这方案性价比非常高但你要是追新格式、需要最新算法比如深度传感器数据或者云端 Airflow 管道那就该考虑更新版本。下面主要讲参数怎么配、坑在哪、怎么把它激活到自己的工程里。2. GDAL 1.11.5 核心功能拆解数据驱动、坐标系与两种 API 的取舍2.1 驱动模型为什么它几乎什么格式都能读GDAL 的底层架构就是“驱动模型”每个驱动单独处理一种或一类格式。你打开一个文件时GDAL 遍历所有已注册驱动自带文件头信息做识别匹配到了就交给那个驱动去读。这很像浏览器对网页做的 MIME 嗅探只不过嗅探对象变成了栅格或矢量的真实文件。1.11.5 的栅格驱动里GeoTIFF 是主打的因为它自带地理配准信息和 ArcGIS/QGIS 兼容性最好。它的读写稳定性比较高你拿来做瓦片临时落盘或数据交换问题不大。另一个常用的是 HFA即须 .img 格式虽然是某老牌商业软件留下的但 GDAL 依然良好支持。还有 ENVI 的 .hdr 格式很多遥感原始影像都是它。矢量方面ESRI Shapefile 当然排在前面但它的属性字段有 DBF 限制字段名最多 10 字节字段数也受限GeoJSON 驱动适合现在 Web 地图生态中流转数据KML 则是 Google 系的格式很多地方用得到。以“驱动注册”为例你写代码时要先调用GDALAllRegister()否则你只调用了GDALOpen一定会报driver not found。这正是源码包与编译好的二进制不同的地方头文件和.dll或.a都在链接方式由你控制。#include gdal_priv.h #include ogrsf_frmts.h int main() { GDALAllRegister(); // 注册所有内置驱动不调用这步后面什么都打不开 GDALDataset* poDS static_castGDALDataset*( GDALOpen(D:/Work/mosaic/area51.tif, GA_ReadOnly) ); if (poDS nullptr) { printf(Open failed. Check driver registration or file existence.\n); return 1; } printf(Driver: %s\n, poDS-GetDriver()-GetDescription()); printf(Raster size: %dx%d\n, poDS-GetRasterXSize(), poDS-GetRasterYSize()); GDALClose(poDS); return 0; }这段代码里GDALOpen的第二个参数GA_ReadOnly表示只读打开如果你需要写文件再存盘就传GA_Update。一般地图渲染只读就够了乱开GA_Update容易把原始文件搞脏到时候后悔药都没得吃。GetRasterXSize和GetRasterYSize返回的是像素宽高如果你要给界面分配内存读像素先拿这两个值做计算。项目中我用过它打开约十余种格式没见过大的翻车但要注意1.11.5发布较早较新的云优化GeoTIFFCOG虽然也能读性能却不如新版本。因此业务上如果特别依赖 COG建议别在这里折腾直接换更高版本。2.2 栅格与矢量不要把它们放到同一个“概念盒子”里初学 GDAL 的常见误区是把栅格与矢量混在一起理解。其实在 GDAL 1.11.5 里栅格部分叫 GDAL矢量部分叫 OGR两个体系在代码里也有差异但最终都通过GDALDataset统一表达只是它的子接口不同。栅格数据处理你一般要做四件事读栅格块、重采样、写新文件、算统计。1.11.5 的RasterIO是核心函数能把你需要的窗口和波段一次读入内存也能做降采样即通过nBufXSize和nBufYSize控制输出缓冲区尺寸。比如你有原始 20000×20000 的影像只要预览时缩小到 1000×1000 的窗口GDAL 内部会帮你做抽取或平均这比你自己写循环去读像素再缩放要快得多。矢量处理的核心则是 OGR 的图层、要素、字段三层结构。你要遍历一个 Shapefile 里的所有多边形先拿GetLayerCount看层数再拿GetLayer(0)取第一层接着用GetNextFeature()循环取要素取完用GetFieldInt等函数拿属性。凡是涉及空间关系查询如“点在哪个面内”1.11.5 也带了相应接口只是性能远不如空间索引体系完整的新版本。所以你要先判断自己的应用属于哪一类再决定接口方向。我见过有人拿GDALRasterIO去处理属性表越用越别扭那实际上是在拿栅格 API 处理矢量数据属于典型黑匣子用法。正确的做法是栅格归栅格矢量归矢量两者需要交互时再通过转换函数比如GDALRasterizeLayers把矢量转成栅格掩膜或者用GDALVectorTranslate反向操作。2.3 从按文件访问到按目录访问GDAL 的路径与配置参数GDAL 1.11.5 对路径的处理比较朴素它对中文路径、含空格路径虽然大多能正常打开但有时会有编码障碍。1.x 时代GDAL 推荐用 UTF-8 路径如果你在 Windows 下用的是系统默认 GBK 编码字符串某些驱动会直接失败。我看到很多老项目里都预设了GDAL_FILENAME_IS_UTF8这个配置为YES如果你手头代码是自己写的记得保持一致。配置项不止这一个另一个是GDAL_DATA它指向gdal-data目录里面有pcs.csv、gcs.csv等坐标系统定义文件。你装完编译好的二进制后如果用相对路径运行找不到gdal-data就会出大问题——比如坐标转换时提示Unable to find PROJ.4 database。设置环境变量可以用系统级设置也可以在代码里指定#include cstdlib setenv(GDAL_DATA, D:/tools/gdal1115/share/gdal, 1); setenv(GDAL_FILENAME_IS_UTF8, YES, 1);setenv在 Windows 下的 MinGW 环境中也可用只是严格来说它是 POSIX 风格Windows 下最好用_putenv_s两者行为略有差异。我用_putenv_s多一些因为在 MSVC 下它更标准化。注意必须在GDALAllRegister()之前设置否则某些驱动初始化时就会读取错误配置。3. 在 Windows 上用 MinGW 落地把库装进 C/Qt 工程的每一步3.1 为什么这个包选 MinGW 而不是 MSVC主流的 Windows C 开发一般分 MSVC 和 MinGW 两大阵营。GDAL 官方提供的 Windows 二进制大多是 MSVC 编译的而 Qt 从 5.15 开始虽然官方支持 MSVC但很多长期维护的老项目却在用 MinGW——比如基于某个或某开源工具定制的 Qt 套件。GDAL 用 MinGW 编译主要是符合同一套工具链的 ABI 需求。C 没有稳定的 ABIMSVC 的.lib与 MinGW 的.a不能混用。如果你把 MSVC 的 GDAL 库丢给 MinGW 的 Qt 程序去链接最常见的结果是链接失败、符号找不到甚至是运行时崩溃。反过来自己拿 MinGW 源码编译 GDAL 也是一个办法但你要处理依赖库、构建配置等问题比较费神。因此直接用 mingw64 编译好的 GDAL 1.11.5可以少趟很多坑尤其是它连依赖库都一并編好你只需要在工程里指一下路径。工程配置上IDE 里要区分 include 目录和 lib 目录。以 Qt Creator 为例你的.pro文件里应该写明INCLUDEPATH D:/tools/gdal1115/include LIBS -LD:/tools/gdal1115/lib -lgdal-l后面的gdal会自动链上libgdal.dll.a或libgdal.a具体取决于包内提供的是静态库还是导入库。一般 mingw64 编译的 GDAL 是动态库也就是说你会看到gdal.dll与libgdal.dll.a同时存在.dll.a是导入库链接时用运行时需要把gdal.dll放到可执行文件旁边或加进 PATH。3.2 整理依赖你需要把哪些 DLL 带到部署目录很多人在这里会踩坑。编译过了程序也起来了但部署到另一台电脑上就报“找不到 gdal.dll”或“找不到 libgcc_s_seh-1.dll”。前者好理解后者是 MinGW 运行时库需要一并带上。我一般会把用到的 DLL 收拾到同一个目录里包括gdal.dll、libgcc_s_seh-1.dll、libstdc-6.dll、libwinpthread-1.dll这些然后写个deploy.bat将它们拷到一个bin文件夹。Qt 自身的 DLL 就交给windeployqt去处理。打包发布时目标机器不装开发环境这些运行时库不带上就会出现很神秘的状态代码明明没问题应用却打不开。另外一个细节是 PATH。开发机上编译能运行可能是因为你环境变量里已经加了 GDAL 的bin目录而当你要把应用交给别人环境变量没了就容易出问题。比较稳的做法是在主程序main()最开始把 GDAL 的 bin 目录用SetDllDirectory或者QCoreApplication::addLibraryPath加上去如果你用的是 QtQCoreApplication的路径机制和 Windows DLL 搜索路径不完全一致需要小心。实际中我通常选择静态链接 MinGW 运行时库只把gdal.dll作为外部依赖这样发布时文件少很多。想通过静态链接方式需要在编译 GDAL 时就使用-static-libgcc -static-libstdc。不过此前提到这是别人编好的二进制静态与否取决于包内.a文件的具体情况。如果你看到包中只有单个libgdal.dll.a那依然是动态依赖gdal.dll静态编译的说法就不成立。3.3 “开箱即用”之前的环境变量四件套拿到编译好的包不要急着打开 IDE 写代码。我先看目录结构确认里面包含include、bin、lib和share有的包把gdal-data放在share/gdal下。位置不同环境变量指向就不同。然后按顺序设置四个环境变量确认没放错环境变量作用我常用的示例GDAL_DATA指向坐标系定义等数据文件D:/tools/gdal1115/share/gdalGDAL_DRIVER_PATH驱动动态库所在路径如需要D:/tools/gdal1115/lib/gdalpluginsPATH加入 GDAL 的 bin 目录D:/tools/gdal1115/binPROJ_LIB若是新版含 PROJ 才需要1.11.5 一般不要求设置完后先用命令行试一下gdalinfo --version能正常输出版本号就说明库可以被找到。如果提示缺少 DLL回到 3.2 节补运行时库。3.4 编译和链接写一个最简单的栅格打开例子从代码验证到配置再到编译整个过程是一步步来的。以下用命令行方式演示因为很多 IDE 新手容易在图形界面上找错按钮用命令行可以把逻辑展示得更清楚。假设目录结构是D:/work/read_tif/ main.cpp你的main.cpp可以写成#include gdal_priv.h #include cstdio int main() { GDALAllRegister(); const char* path D:/work/read_tif/input.tif; GDALDataset* poDS static_castGDALDataset*(GDALOpen(path, GA_ReadOnly)); if (poDS nullptr) { printf(Failed to open dataset: %s\n, path); return 1; } int width poDS-GetRasterXSize(); int height poDS-GetRasterYSize(); int bands poDS-GetRasterCount(); printf(Size: %d x %d, Bands: %d\n, width, height, bands); double geo[6]; if (poDS-GetGeoTransform(geo) CE_None) { printf(Origin: (%.6f, %.6f)\n, geo[0], geo[3]); } else { printf(No geo transform available.\n); } GDALClose(poDS); return 0; }GetGeoTransform是栅格数据最常调用的函数它返回一个六元素数组存放像元大小和旋转参数用于把行列坐标换算成地理坐标。geo[0]是左上角 x 坐标geo[3]是左上角 y 坐标geo[1]和geo[5]一般是像元宽高。如果返回不是CE_None说明这个文件没有空间参考信息那你只能拿到行列值无法直接做投影转换。命令行编译g -o read_tif main.cpp \ -ID:/tools/gdal1115/include \ -LD:/tools/gdal1115/lib \ -lgdal-I是头文件查找路径-L是库查找路径-l指定库名。MinGW 将gdal解析为libgdal.dll.a或libgdal.a。链接成功后运行之前确认gdal.dll在 PATH 或当前目录下否则会出现“程序无法启动找不到 dll”的情况。这几个命令写在一个build.bat里以后每次改工程都能反复用。4. 常见问题与避坑记录五个最容易翻车的地方4.1 现象undefined reference链接失败我在用 mingw64 版本对接 Qt 工程时最常见的就是链接期报出成串的undefined reference to GDALOpen...。如果你查库文件会发现libgdal.dll.a在目录里摆着-lgdal也写了但就是链接不过。原因一般是库路径没配对或在同一个命令行里把.a文件直接当源文件放在main.cpp前导致链接器处理顺序不对。GNU 链接器对库的依赖顺序相当敏感被依赖的库要放在右边。我当时把-lgdal放到了main.cpp前面结果一堆符号解析不了。解决方式是把-lgdal放到源文件之后再不行就加上-Wl,--start-group -lgdal -Wl,--end-group强制循环解析。这个参数会让链接器多次扫描库能缓解库之间的相互依赖但一般没必要。调整顺序后我这边问题消失。这是最常见也最容易解决的坑。4.2 现象运行时提示“无法定位程序输入点”场景是机器上已经装有另一个 GDAL 版本或者系统 PATH 中存在旧版gdal.dll。程序启动时优先加载了那个不兼容的版本就会出现“无法定位程序输入点”或各种函数地址错误。原因是 Windows DLL 搜索顺序把旧版 GDAL 排在了前面。解决方式是让程序所在目录优先放上正确版本的 DLLWindows 首先搜索应用程序所在目录这比 PATH 优先级高。我一般会在发布目录里放一份和编译时相同的gdal.dll让程序绝对不要“借用”系统里的新版——曾经图省事没放结果换到客户机器就黑匣子一样打不开后来强制自己每次部署前先检查目录里 DLL 的版本。4.3 现象中文路径打开文件总是失败写代码时用D:/数据/影像.tif这种路径在 Windows 下GDALOpen返回nullptr。英文路径则一切正常。原因有两点一是 GDAL 1.11.5 很多内部接口默认按 UTF-8 解释路径如果你用std::string存的是 GBK 编码就会解析不出来二是某个驱动会调 C 标准库函数对非 ASCII 字符支持不够好。解决方式是把所有路径转成 UTF-8 编码再传给 GDAL。Qt 下可以用QString::toUtf8()非 Qt 环境则可以在 Windows 上自己写一个小函数调MultiByteToWideChar转到宽字符再用WideCharToMultiByte转成 UTF-8。这件事我踩过后就在代码里加了一层路径转换封装再也不用玄学去猜为什么打不开。4.4 现象PROJ相关的坐标转换失败使用OGRCoordinateTransformation做投影转换时突然报failed to load PROJ.4或者坐标系解析不出来。原因在于GDAL_DATA没有正确指向gdal-data目录或者 1.11.5 的pcs.csv缺失。有的精简版包会把gdal-data去掉以减小体积但代价是你做不了重投影。解决方式是重新下载完整包确认share/gdal下存在pcs.csv、gcs.csv和gdal_datum.csv等文件。用代码设好GDAL_DATA后可以在应用启动时打印当前环境变量并检查关键文件是否存在避免部署环境差异引起问题。我把这步写进了一个诊断函数客户环境出错时直接看日志就能判断是不是gdal-data缺失。4.5 现象Debug 与 Release 混用后行为怪异在 Qt Creator 里把编译模式切到 Debug结果链接到的是一个 Release 版的gdal.dll表面上能运行但某些内存相关操作崩溃或输出乱码。原因是 GDAL 1.11.5 的动态库本身如果带调试符号就不是同一个 DLL而你链接的导入库对应的是 Release 运行时。这是 C 开发的通用问题——跨配置、跨编译器混用二进制库都会带来 ABI 不兼容。解决方式是不要试图混用明确自己用的是 MinGW 编译的版本就不要去链 MSVC 的导入库反之亦然。另外一个容易被忽略的点是运行时库也要配好MinGW 的libstdc-6.dll和 MSVC 的运行时文件不能乱放。我在一个模拟项目里试过混搭结果调试了两天才发现 Debug 与 Release 目录下两个 DLL 被同时放到了 PATH 里清理后问题解决。5. 拿去就能用的验证方法用 gdalinfo 与自写脚本确认库没问题拿到编译好的 GDAL 1.11.5别急着塞进工程先用它自带的命令行工具做一次“体检”确认这个二进制在你目标机器上是否正常。因为命令行工具依赖的 DLL 和开发时用的库是同一套命令行能跑通C 工程里大概率也能跑通。第一步打开 cmd 或 PowerShell运行gdalinfo --version正常情况下会输出类似GDAL 1.11.5, released 2015/...的版本信息。如果提示“不是内部或外部命令”说明 PATH 没生效或gdalinfo.exe不在bin目录里回到之前的环境变量配置去查。我手上的包通常把gdalinfo.exe放在 GDAL 的bin目录如果你在目录下找到gdalinfo.exe但运行时提示缺 DLL就用Dependencies.exe或lddMinGW 环境自带看它依赖哪些 DLL。第二步拿一个你实际要处理的 GeoTIFF 文件试运行gdalinfo D:/work/read_tif/input.tif观察输出里的Driver、Size、Coordinate System和Corner Coordinates。如果源文件带投影但这里没有显示说明GDAL_DATA配置有问题或者该文件的元数据本来就不完整。比如你会发现Coordinate System is下面空白这时候先检查文件本身有没有.tfw、.prj之类的辅助文件。原始 TIFF 不带prj文件是很正常的因为坐标信息被放在 TIFF 的 GeoTag 里不依赖外置文件。gdalinfo跑通了再用命令行做一次小转换验证写路径也没问题gdal_translate -of GTiff -outsize 50% 50% D:/work/read_tif/input.tif D:/work/read_tif/output_half.tif-outsize 50% 50%表示把宽和高各缩小一半。加了-of GTiff指定输出格式为 GeoTIFF。如果这条命令能成功跑完说明 GDAL 不只是能读写文件也正常。若输出文件生成的尺寸和坐标信息都正确库的读写链路就基本过关。这一步我每次拿到“新”GDAL 包都会做相当于一个两分钟冒烟测试。如果你有多个驱动要验证把文件后缀换成.shp再用ogrinfo测试一下矢量部分。接下来的问题是确认这个 GDAL 1.11.5 是否能和你的 Qt 版本共存。先在空的 Qt 工程里调用GDALVersionInfo(RELEASE_NAME)返回字符串能打印出来再继续写其他代码。我一般会在窗口标题上显示 GDAL 版本号这样运行期一看就知道加载的库到底是不是编译时指定的那个。这个方法很简单但相当实用——它确保你不会被系统里其他 GDAL 干扰。实际开发时我还习惯把gdalinfo的散列值和库文件的修改时间写进一个构建信息文件里。当现场出现怪异问题先比对客户机上这份文件与本地是否一致不一致就直接替换不用浪费时间查代码。因为很多看起来像“代码 bug”的问题最后都会回归到 DLL 版本不一致上。从那以后我每次拿到新的 GDAL 包都会强制走一遍命令行冒烟测试再在程序里显示版本号最后把文件散列值记录到构建日志里。希望这套流程也能帮你少绕几个弯。本文还有配套的精品资源点击获取 
长河君 · 2026/10/18 22:37:35 · 阅读 1.2k MinGW+Qt下GDAL 1.11.5环境配置与避坑指南
简介这是一份面向 QTMinGW 版C 开发者的 Windows 预编译 GDAL 1.11.5 开发包采用 MSYS2 MinGW64 工具链编译可让使用者跳过源码编译阶段直接获得可链接的库文件与命令行工具。压缩包约 70.71MB共 149 个文件其中 63 个头文件用于 C API 调用28 个 CSV 文件提供投影坐标系、基准面转换参数及要素目录数据22 个 exe 覆盖常见 GDAL 命令工具同时附带静态库、动态库以及 GFS、WKT、DXF、DGN 等格式支持文件为不同数据源接入提供便利。资源已吸引 1520 人学习下载特别适合在 QT/Mingw 工程中完成 GDAL 的快速集成省去自行编译配置的兼容性烦恼。作者还针对解压使用后可能出现的程序异常结束问题给出配套排查指引能够帮助开发者在 GIS 二次开发、空间数据解析与投影转换等任务中更顺畅地上手这对于需要快速搭建 GIS 原型或验证算法的开发者尤为实用。1. 老版本 GDAL 1.11.5为什么还在用它解决了什么做 C 桌面端 GIS 工具的人多半在某个下午被 GDAL 折腾得想摔鼠标我当时也是这样。本来在 MSVC 下编好的 GDAL 库换到 Qt MinGW 环境后就各种装不上找不到符号、头文件路径不对、Debug/Release 混了……直到有人甩给我一个用 mingw64 编译好的 GDAL 1.11.5至少省掉了我两天的编译时间。别小看这个版本它发布于 2015 年却依然是老项目里最稳的选择尤其对还在维护 Qt 5 / Qt 4 时代代码的人来说。GDAL 是地理数据格式转换和处理的事实标准1.11.5 属于 1.x 系列晚期补丁版功能上够用——支持几十种栅格格式读写矢量库 OGR 也在里边不需要再单独装一套。装上它你可以直接在自己的 C 工程里打开 Shapefile、GeoTIFF、ENVI 等格式做坐标转换、裁剪、重采样甚至借助它封一层 Qt 界面做图层管理。我这里拿到的是别人编译好的二进制不是源码编译流程所以讲的是“怎么用”不是“怎么从零编”。适合谁呢不是所有做 GIS 的都适合它。如果你打算写生产级工具给客户和其他开发者使用这方案性价比非常高但你要是追新格式、需要最新算法比如深度传感器数据或者云端 Airflow 管道那就该考虑更新版本。下面主要讲参数怎么配、坑在哪、怎么把它激活到自己的工程里。2. GDAL 1.11.5 核心功能拆解数据驱动、坐标系与两种 API 的取舍2.1 驱动模型为什么它几乎什么格式都能读GDAL 的底层架构就是“驱动模型”每个驱动单独处理一种或一类格式。你打开一个文件时GDAL 遍历所有已注册驱动自带文件头信息做识别匹配到了就交给那个驱动去读。这很像浏览器对网页做的 MIME 嗅探只不过嗅探对象变成了栅格或矢量的真实文件。1.11.5 的栅格驱动里GeoTIFF 是主打的因为它自带地理配准信息和 ArcGIS/QGIS 兼容性最好。它的读写稳定性比较高你拿来做瓦片临时落盘或数据交换问题不大。另一个常用的是 HFA即须 .img 格式虽然是某老牌商业软件留下的但 GDAL 依然良好支持。还有 ENVI 的 .hdr 格式很多遥感原始影像都是它。矢量方面ESRI Shapefile 当然排在前面但它的属性字段有 DBF 限制字段名最多 10 字节字段数也受限GeoJSON 驱动适合现在 Web 地图生态中流转数据KML 则是 Google 系的格式很多地方用得到。以“驱动注册”为例你写代码时要先调用GDALAllRegister()否则你只调用了GDALOpen一定会报driver not found。这正是源码包与编译好的二进制不同的地方头文件和.dll或.a都在链接方式由你控制。#include gdal_priv.h #include ogrsf_frmts.h int main() { GDALAllRegister(); // 注册所有内置驱动不调用这步后面什么都打不开 GDALDataset* poDS static_castGDALDataset*( GDALOpen(D:/Work/mosaic/area51.tif, GA_ReadOnly) ); if (poDS nullptr) { printf(Open failed. Check driver registration or file existence.\n); return 1; } printf(Driver: %s\n, poDS-GetDriver()-GetDescription()); printf(Raster size: %dx%d\n, poDS-GetRasterXSize(), poDS-GetRasterYSize()); GDALClose(poDS); return 0; }这段代码里GDALOpen的第二个参数GA_ReadOnly表示只读打开如果你需要写文件再存盘就传GA_Update。一般地图渲染只读就够了乱开GA_Update容易把原始文件搞脏到时候后悔药都没得吃。GetRasterXSize和GetRasterYSize返回的是像素宽高如果你要给界面分配内存读像素先拿这两个值做计算。项目中我用过它打开约十余种格式没见过大的翻车但要注意1.11.5发布较早较新的云优化GeoTIFFCOG虽然也能读性能却不如新版本。因此业务上如果特别依赖 COG建议别在这里折腾直接换更高版本。2.2 栅格与矢量不要把它们放到同一个“概念盒子”里初学 GDAL 的常见误区是把栅格与矢量混在一起理解。其实在 GDAL 1.11.5 里栅格部分叫 GDAL矢量部分叫 OGR两个体系在代码里也有差异但最终都通过GDALDataset统一表达只是它的子接口不同。栅格数据处理你一般要做四件事读栅格块、重采样、写新文件、算统计。1.11.5 的RasterIO是核心函数能把你需要的窗口和波段一次读入内存也能做降采样即通过nBufXSize和nBufYSize控制输出缓冲区尺寸。比如你有原始 20000×20000 的影像只要预览时缩小到 1000×1000 的窗口GDAL 内部会帮你做抽取或平均这比你自己写循环去读像素再缩放要快得多。矢量处理的核心则是 OGR 的图层、要素、字段三层结构。你要遍历一个 Shapefile 里的所有多边形先拿GetLayerCount看层数再拿GetLayer(0)取第一层接着用GetNextFeature()循环取要素取完用GetFieldInt等函数拿属性。凡是涉及空间关系查询如“点在哪个面内”1.11.5 也带了相应接口只是性能远不如空间索引体系完整的新版本。所以你要先判断自己的应用属于哪一类再决定接口方向。我见过有人拿GDALRasterIO去处理属性表越用越别扭那实际上是在拿栅格 API 处理矢量数据属于典型黑匣子用法。正确的做法是栅格归栅格矢量归矢量两者需要交互时再通过转换函数比如GDALRasterizeLayers把矢量转成栅格掩膜或者用GDALVectorTranslate反向操作。2.3 从按文件访问到按目录访问GDAL 的路径与配置参数GDAL 1.11.5 对路径的处理比较朴素它对中文路径、含空格路径虽然大多能正常打开但有时会有编码障碍。1.x 时代GDAL 推荐用 UTF-8 路径如果你在 Windows 下用的是系统默认 GBK 编码字符串某些驱动会直接失败。我看到很多老项目里都预设了GDAL_FILENAME_IS_UTF8这个配置为YES如果你手头代码是自己写的记得保持一致。配置项不止这一个另一个是GDAL_DATA它指向gdal-data目录里面有pcs.csv、gcs.csv等坐标系统定义文件。你装完编译好的二进制后如果用相对路径运行找不到gdal-data就会出大问题——比如坐标转换时提示Unable to find PROJ.4 database。设置环境变量可以用系统级设置也可以在代码里指定#include cstdlib setenv(GDAL_DATA, D:/tools/gdal1115/share/gdal, 1); setenv(GDAL_FILENAME_IS_UTF8, YES, 1);setenv在 Windows 下的 MinGW 环境中也可用只是严格来说它是 POSIX 风格Windows 下最好用_putenv_s两者行为略有差异。我用_putenv_s多一些因为在 MSVC 下它更标准化。注意必须在GDALAllRegister()之前设置否则某些驱动初始化时就会读取错误配置。3. 在 Windows 上用 MinGW 落地把库装进 C/Qt 工程的每一步3.1 为什么这个包选 MinGW 而不是 MSVC主流的 Windows C 开发一般分 MSVC 和 MinGW 两大阵营。GDAL 官方提供的 Windows 二进制大多是 MSVC 编译的而 Qt 从 5.15 开始虽然官方支持 MSVC但很多长期维护的老项目却在用 MinGW——比如基于某个或某开源工具定制的 Qt 套件。GDAL 用 MinGW 编译主要是符合同一套工具链的 ABI 需求。C 没有稳定的 ABIMSVC 的.lib与 MinGW 的.a不能混用。如果你把 MSVC 的 GDAL 库丢给 MinGW 的 Qt 程序去链接最常见的结果是链接失败、符号找不到甚至是运行时崩溃。反过来自己拿 MinGW 源码编译 GDAL 也是一个办法但你要处理依赖库、构建配置等问题比较费神。因此直接用 mingw64 编译好的 GDAL 1.11.5可以少趟很多坑尤其是它连依赖库都一并編好你只需要在工程里指一下路径。工程配置上IDE 里要区分 include 目录和 lib 目录。以 Qt Creator 为例你的.pro文件里应该写明INCLUDEPATH D:/tools/gdal1115/include LIBS -LD:/tools/gdal1115/lib -lgdal-l后面的gdal会自动链上libgdal.dll.a或libgdal.a具体取决于包内提供的是静态库还是导入库。一般 mingw64 编译的 GDAL 是动态库也就是说你会看到gdal.dll与libgdal.dll.a同时存在.dll.a是导入库链接时用运行时需要把gdal.dll放到可执行文件旁边或加进 PATH。3.2 整理依赖你需要把哪些 DLL 带到部署目录很多人在这里会踩坑。编译过了程序也起来了但部署到另一台电脑上就报“找不到 gdal.dll”或“找不到 libgcc_s_seh-1.dll”。前者好理解后者是 MinGW 运行时库需要一并带上。我一般会把用到的 DLL 收拾到同一个目录里包括gdal.dll、libgcc_s_seh-1.dll、libstdc-6.dll、libwinpthread-1.dll这些然后写个deploy.bat将它们拷到一个bin文件夹。Qt 自身的 DLL 就交给windeployqt去处理。打包发布时目标机器不装开发环境这些运行时库不带上就会出现很神秘的状态代码明明没问题应用却打不开。另外一个细节是 PATH。开发机上编译能运行可能是因为你环境变量里已经加了 GDAL 的bin目录而当你要把应用交给别人环境变量没了就容易出问题。比较稳的做法是在主程序main()最开始把 GDAL 的 bin 目录用SetDllDirectory或者QCoreApplication::addLibraryPath加上去如果你用的是 QtQCoreApplication的路径机制和 Windows DLL 搜索路径不完全一致需要小心。实际中我通常选择静态链接 MinGW 运行时库只把gdal.dll作为外部依赖这样发布时文件少很多。想通过静态链接方式需要在编译 GDAL 时就使用-static-libgcc -static-libstdc。不过此前提到这是别人编好的二进制静态与否取决于包内.a文件的具体情况。如果你看到包中只有单个libgdal.dll.a那依然是动态依赖gdal.dll静态编译的说法就不成立。3.3 “开箱即用”之前的环境变量四件套拿到编译好的包不要急着打开 IDE 写代码。我先看目录结构确认里面包含include、bin、lib和share有的包把gdal-data放在share/gdal下。位置不同环境变量指向就不同。然后按顺序设置四个环境变量确认没放错环境变量作用我常用的示例GDAL_DATA指向坐标系定义等数据文件D:/tools/gdal1115/share/gdalGDAL_DRIVER_PATH驱动动态库所在路径如需要D:/tools/gdal1115/lib/gdalpluginsPATH加入 GDAL 的 bin 目录D:/tools/gdal1115/binPROJ_LIB若是新版含 PROJ 才需要1.11.5 一般不要求设置完后先用命令行试一下gdalinfo --version能正常输出版本号就说明库可以被找到。如果提示缺少 DLL回到 3.2 节补运行时库。3.4 编译和链接写一个最简单的栅格打开例子从代码验证到配置再到编译整个过程是一步步来的。以下用命令行方式演示因为很多 IDE 新手容易在图形界面上找错按钮用命令行可以把逻辑展示得更清楚。假设目录结构是D:/work/read_tif/ main.cpp你的main.cpp可以写成#include gdal_priv.h #include cstdio int main() { GDALAllRegister(); const char* path D:/work/read_tif/input.tif; GDALDataset* poDS static_castGDALDataset*(GDALOpen(path, GA_ReadOnly)); if (poDS nullptr) { printf(Failed to open dataset: %s\n, path); return 1; } int width poDS-GetRasterXSize(); int height poDS-GetRasterYSize(); int bands poDS-GetRasterCount(); printf(Size: %d x %d, Bands: %d\n, width, height, bands); double geo[6]; if (poDS-GetGeoTransform(geo) CE_None) { printf(Origin: (%.6f, %.6f)\n, geo[0], geo[3]); } else { printf(No geo transform available.\n); } GDALClose(poDS); return 0; }GetGeoTransform是栅格数据最常调用的函数它返回一个六元素数组存放像元大小和旋转参数用于把行列坐标换算成地理坐标。geo[0]是左上角 x 坐标geo[3]是左上角 y 坐标geo[1]和geo[5]一般是像元宽高。如果返回不是CE_None说明这个文件没有空间参考信息那你只能拿到行列值无法直接做投影转换。命令行编译g -o read_tif main.cpp \ -ID:/tools/gdal1115/include \ -LD:/tools/gdal1115/lib \ -lgdal-I是头文件查找路径-L是库查找路径-l指定库名。MinGW 将gdal解析为libgdal.dll.a或libgdal.a。链接成功后运行之前确认gdal.dll在 PATH 或当前目录下否则会出现“程序无法启动找不到 dll”的情况。这几个命令写在一个build.bat里以后每次改工程都能反复用。4. 常见问题与避坑记录五个最容易翻车的地方4.1 现象undefined reference链接失败我在用 mingw64 版本对接 Qt 工程时最常见的就是链接期报出成串的undefined reference to GDALOpen...。如果你查库文件会发现libgdal.dll.a在目录里摆着-lgdal也写了但就是链接不过。原因一般是库路径没配对或在同一个命令行里把.a文件直接当源文件放在main.cpp前导致链接器处理顺序不对。GNU 链接器对库的依赖顺序相当敏感被依赖的库要放在右边。我当时把-lgdal放到了main.cpp前面结果一堆符号解析不了。解决方式是把-lgdal放到源文件之后再不行就加上-Wl,--start-group -lgdal -Wl,--end-group强制循环解析。这个参数会让链接器多次扫描库能缓解库之间的相互依赖但一般没必要。调整顺序后我这边问题消失。这是最常见也最容易解决的坑。4.2 现象运行时提示“无法定位程序输入点”场景是机器上已经装有另一个 GDAL 版本或者系统 PATH 中存在旧版gdal.dll。程序启动时优先加载了那个不兼容的版本就会出现“无法定位程序输入点”或各种函数地址错误。原因是 Windows DLL 搜索顺序把旧版 GDAL 排在了前面。解决方式是让程序所在目录优先放上正确版本的 DLLWindows 首先搜索应用程序所在目录这比 PATH 优先级高。我一般会在发布目录里放一份和编译时相同的gdal.dll让程序绝对不要“借用”系统里的新版——曾经图省事没放结果换到客户机器就黑匣子一样打不开后来强制自己每次部署前先检查目录里 DLL 的版本。4.3 现象中文路径打开文件总是失败写代码时用D:/数据/影像.tif这种路径在 Windows 下GDALOpen返回nullptr。英文路径则一切正常。原因有两点一是 GDAL 1.11.5 很多内部接口默认按 UTF-8 解释路径如果你用std::string存的是 GBK 编码就会解析不出来二是某个驱动会调 C 标准库函数对非 ASCII 字符支持不够好。解决方式是把所有路径转成 UTF-8 编码再传给 GDAL。Qt 下可以用QString::toUtf8()非 Qt 环境则可以在 Windows 上自己写一个小函数调MultiByteToWideChar转到宽字符再用WideCharToMultiByte转成 UTF-8。这件事我踩过后就在代码里加了一层路径转换封装再也不用玄学去猜为什么打不开。4.4 现象PROJ相关的坐标转换失败使用OGRCoordinateTransformation做投影转换时突然报failed to load PROJ.4或者坐标系解析不出来。原因在于GDAL_DATA没有正确指向gdal-data目录或者 1.11.5 的pcs.csv缺失。有的精简版包会把gdal-data去掉以减小体积但代价是你做不了重投影。解决方式是重新下载完整包确认share/gdal下存在pcs.csv、gcs.csv和gdal_datum.csv等文件。用代码设好GDAL_DATA后可以在应用启动时打印当前环境变量并检查关键文件是否存在避免部署环境差异引起问题。我把这步写进了一个诊断函数客户环境出错时直接看日志就能判断是不是gdal-data缺失。4.5 现象Debug 与 Release 混用后行为怪异在 Qt Creator 里把编译模式切到 Debug结果链接到的是一个 Release 版的gdal.dll表面上能运行但某些内存相关操作崩溃或输出乱码。原因是 GDAL 1.11.5 的动态库本身如果带调试符号就不是同一个 DLL而你链接的导入库对应的是 Release 运行时。这是 C 开发的通用问题——跨配置、跨编译器混用二进制库都会带来 ABI 不兼容。解决方式是不要试图混用明确自己用的是 MinGW 编译的版本就不要去链 MSVC 的导入库反之亦然。另外一个容易被忽略的点是运行时库也要配好MinGW 的libstdc-6.dll和 MSVC 的运行时文件不能乱放。我在一个模拟项目里试过混搭结果调试了两天才发现 Debug 与 Release 目录下两个 DLL 被同时放到了 PATH 里清理后问题解决。5. 拿去就能用的验证方法用 gdalinfo 与自写脚本确认库没问题拿到编译好的 GDAL 1.11.5别急着塞进工程先用它自带的命令行工具做一次“体检”确认这个二进制在你目标机器上是否正常。因为命令行工具依赖的 DLL 和开发时用的库是同一套命令行能跑通C 工程里大概率也能跑通。第一步打开 cmd 或 PowerShell运行gdalinfo --version正常情况下会输出类似GDAL 1.11.5, released 2015/...的版本信息。如果提示“不是内部或外部命令”说明 PATH 没生效或gdalinfo.exe不在bin目录里回到之前的环境变量配置去查。我手上的包通常把gdalinfo.exe放在 GDAL 的bin目录如果你在目录下找到gdalinfo.exe但运行时提示缺 DLL就用Dependencies.exe或lddMinGW 环境自带看它依赖哪些 DLL。第二步拿一个你实际要处理的 GeoTIFF 文件试运行gdalinfo D:/work/read_tif/input.tif观察输出里的Driver、Size、Coordinate System和Corner Coordinates。如果源文件带投影但这里没有显示说明GDAL_DATA配置有问题或者该文件的元数据本来就不完整。比如你会发现Coordinate System is下面空白这时候先检查文件本身有没有.tfw、.prj之类的辅助文件。原始 TIFF 不带prj文件是很正常的因为坐标信息被放在 TIFF 的 GeoTag 里不依赖外置文件。gdalinfo跑通了再用命令行做一次小转换验证写路径也没问题gdal_translate -of GTiff -outsize 50% 50% D:/work/read_tif/input.tif D:/work/read_tif/output_half.tif-outsize 50% 50%表示把宽和高各缩小一半。加了-of GTiff指定输出格式为 GeoTIFF。如果这条命令能成功跑完说明 GDAL 不只是能读写文件也正常。若输出文件生成的尺寸和坐标信息都正确库的读写链路就基本过关。这一步我每次拿到“新”GDAL 包都会做相当于一个两分钟冒烟测试。如果你有多个驱动要验证把文件后缀换成.shp再用ogrinfo测试一下矢量部分。接下来的问题是确认这个 GDAL 1.11.5 是否能和你的 Qt 版本共存。先在空的 Qt 工程里调用GDALVersionInfo(RELEASE_NAME)返回字符串能打印出来再继续写其他代码。我一般会在窗口标题上显示 GDAL 版本号这样运行期一看就知道加载的库到底是不是编译时指定的那个。这个方法很简单但相当实用——它确保你不会被系统里其他 GDAL 干扰。实际开发时我还习惯把gdalinfo的散列值和库文件的修改时间写进一个构建信息文件里。当现场出现怪异问题先比对客户机上这份文件与本地是否一致不一致就直接替换不用浪费时间查代码。因为很多看起来像“代码 bug”的问题最后都会回归到 DLL 版本不一致上。从那以后我每次拿到新的 GDAL 包都会强制走一遍命令行冒烟测试再在程序里显示版本号最后把文件散列值记录到构建日志里。希望这套流程也能帮你少绕几个弯。本文还有配套的精品资源点击获取