在 Java 中调用 GDAL BuildVRT

Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

在 Java 中调用 GDAL BuildVRT,直接用 org.gdal.gdal.gdal.BuildVRT:先执行 gdal.AllRegister(),再把源栅格路径放进 Vector,把命令行风格的选项放进另一个 Vector 交给 BuildVRTOptions,最后传入目标 .vrt 路径即可得到虚拟马赛克 Dataset。JAR 与原生库必须同一版本,用完务必调用 delete() 释放。截至 2026 年 11 月,官方稳定版为 3.13.3(2026-08-18 发布),Maven 上常见配套为 3.13.0。这样可以把多幅影像拼成按需读取的 VRT,不必立刻写出实体大文件。

VRT 把多幅影像拼成虚拟马赛克的示意

Java 绑定环境怎么配

要解决的问题是:Java 代码能找到 gdalalljni 原生库,且和 gdal.jar 版本完全一致,否则一跑就 UnsatisfiedLinkError。官方只提供源码和容器,Java 绑定需自己构建或找预编译包。

  • Maven 引入(仅 JAR,原生库另配):groupId 为 org.gdal、artifactId 为 gdal,版本建议与本地原生库对齐,目前可见较新的是 3.13.0。以官网和 Maven Central 实际可下版本为准。
  • 原生库来源:从源码 CMake 打开 -DBUILD_JAVA_BINDINGS=ON 产出 gdal.jar + gdalalljni(.so/.dylib/.dll);Windows 也可从 GISInternals 预编译包里取配套 dll;Linux/macOS 还可用 conda-forge 或 Homebrew 提供的库再补 Java 绑定。
  • 路径设置:Linux 设 LD_LIBRARY_PATH,macOS 设 DYLD_LIBRARY_PATH,Windows 把含 gdalalljni.dll 的目录加入 PATH,或统一用 JVM 参数 -Djava.library.path=…。同时建议设好 GDAL_DATA、PROJ_LIB。
  • 架构与线程:JAR、dll/so、JDK 必须同为 64 位;GDAL 需启用多线程支持,因为 Java GC 跑在独立线程。

配好后可用简单命令验证:java -classpath gdal.jar:… 跑一下 gdalinfo 或自写一小段 AllRegister 测试。更完整的 VRT 使用场景可先看本站 GDAL VRT 怎么用:虚拟栅格拼接、按需读取与批处理入口,弄清虚拟文件思路再写 Java。

BuildVRT 的基本调用步骤

目标明确:把一组 GeoTIFF(或其它 GDAL 可读栅格)建成一个 .vrt,后续可按需读、再 gdal_translate 或发布服务。步骤如下。

  1. 调用 gdal.AllRegister(),确保驱动全部加载。
  2. 准备 Vector<String> sources,依次 add 每幅源影像的绝对或相对路径(也可用 Dataset[] 重载)。
  3. 准备 Vector<String> opts,按命令行顺序塞选项和参数字符串(例如先 “-te”,再 xmin、ymin、xmax、ymax 四个字符串);不需要选项就传空 Vector。
  4. 执行 Dataset ds = gdal.BuildVRT(“out.vrt”, sources, new BuildVRTOptions(opts)); 检查返回是否为 null。
  5. 用 ds 做后续读写或直接结束;最后必须 ds.delete(),避免原生资源泄漏。

带进度回调的重载也可用 ProgressCallback。源特别多(数十万级)时,官方从 GDAL 3.9 起更推荐先用 gdaltindex 生成 GTI 兼容 tileindex,再让 BuildVRT 吃这个索引,性能更稳。本站 GDAL合并大影像慢吗?VRT虚拟文件咋建? 里讲过大影像用 VRT 的思路,Java 侧同样适用。

GDAL 官方 gdalbuildvrt 程序说明页界面
GDAL 官方 gdalbuildvrt 程序说明页界面(截图来源:gdal.org)

常用选项与 BuildVRTOptions 写法

BuildVRTOptions 的构造函数吃的就是 CLI 风格字符串列表,顺序和 gdalbuildvrt 命令行一致。不清楚时对照官方文档即可。

常见选项 作用简述 Java Vector 示例片段
-te xmin ymin xmax ymax 裁剪输出范围 opts.add(“-te”); opts.add(xmin); … 四个值
-tr xres yres 指定目标分辨率 opts.add(“-tr”); opts.add(“10”); opts.add(“10”);
-separate 每个输入放独立波段 opts.add(“-separate”);
-r nearest/bilinear/… 重采样方法 opts.add(“-r”); opts.add(“bilinear”);
-allow_projection_difference 允许投影略有差异仍拼接 opts.add(“-allow_projection_difference”);
-strict / -non_strict 警告是否升级为失败 opts.add(“-strict”);
-pixel-function 重叠像素聚合(GDAL 3.12+,如 mean/min) opts.add(“-pixel-function”); opts.add(“mean”);

默认把输入当更大马赛克的瓦片(波段数与输入一致)。异构投影或波段数不匹配时默认会跳过并警告,需要严格失败就加 -strict。完整参数表以 GDAL 官方 gdalbuildvrt 文档 为准。Java 方法签名可查 Java BuildVRT API 文档。

调用时要注意什么、出错怎么办

先保证环境对,再谈业务逻辑。验收标准很简单:生成的 .vrt 能被 gdalinfo 打开,波段数、范围、分辨率符合预期,且用 gdal_translate 抽一小块不报错。

  • 版本强绑定:gdal.jar、gdalalljni、底层 libgdal/PROJ 必须同源同版本,混用必崩。
  • 资源释放:Dataset、部分中间对象都要 delete();大循环里尤其注意。
  • 投影与波段:不一致时先统一(gdalwarp)或明确加 -allow_projection_difference;需要失败则 -strict。
  • 超大源列表:改用 tileindex,避免一次塞几十万路径进 Vector。
  • 分辨率平均模式偶发浮点问题(旧行为):改用 highest/lowest 或显式 -tr。
  • 错误处理:默认警告不阻断;可用自定义 ErrorHandler 或 -strict 让问题立刻暴露。

最常见报错 UnsatisfiedLinkError: no gdalalljni in java.library.path,几乎全是路径或架构不匹配。Windows 可把 dll 拷到 JDK 的 bin 目录试一下;确认 System.loadLibrary(“gdalalljni”) 能找到。其它依赖库(如 PROJ)缺失也会连锁报错,把它们一并放进库路径。

常见问题

为什么一运行就 UnsatisfiedLinkError?

原生库没进 java.library.path 或 PATH,或者 JAR 与 dll/so 版本、架构不一致。先核对 LD_LIBRARY_PATH / PATH / -Djava.library.path,再确认 64 位匹配,必要时重新从同一份源码或 GISInternals 包取出全套文件。

BuildVRTOptions 怎么正确传 -te 这类带参数的选项?

按命令行顺序把字符串塞进 Vector:先加 “-te”,紧接着加四个范围字符串。不要自己拼成一个长字符串,也不要漏参数个数,否则选项解析失败。

源影像投影不完全一样能不能拼?

默认会跳过并警告。需要强制拼就加 -allow_projection_difference;想让警告变失败就加 -strict。更稳妥的做法是先用 gdalwarp 统一到同一 CRS 再 BuildVRT。

生成的 VRT 很大或源特别多,Java 里会卡吗?

VRT 本身只是 XML 描述,通常很快;但源数量到数十万级时,建议改用 gdaltindex 生成 tileindex 再喂给 BuildVRT。内存上记得及时 delete Dataset,避免长时间占用原生句柄。

总结:在 Java 里调用 gdal buildvrt 的关键是「同版本 JAR + 原生库 + AllRegister + BuildVRTOptions 按 CLI 顺序传参 + 用完 delete」。先把环境跑通 gdalinfo,再写业务代码;复杂马赛克先在命令行验证参数,确认无误后再迁到 Java。建议同步阅读本站 VRT 相关教程,把虚拟栅格的读取与批处理思路一起用上,效率会更高。