简介：面向GIS开发者的Java几何拓扑修复工具，解决SHP、GDB矢量数据中常见的自相交、重叠、不闭合等错误，封装GDAL与JTS处理逻辑，使修复结果符合OGC简单要素规范，可衔接GeoTools、PostGIS等空间分析栈，减少非法几何导致的分析失败。压缩包仅169KB，共8个文件，含Shapefile配套文件（shp、dbf、shx、prj、sbn/sbx）、Java源码和gdalx64.jar，结构清晰，方便直接研读与复用。已有4548人学习下载，适合负责空间数据清洗和入库质量控制的GIS开发人员。工具类以GdalMakeValidUtil为核心，附示例数据对比修复效果，帮助理解拓扑错误成因，掌握GDAL/JTS修复接口用法，提升空间计算稳定性。
1. GDAL几何修复解决什么：自相交、shp、gdb 这三个词为什么绑在一起
多源矢量数据汇交时，几何自相交是出现频率最高、也最容易被忽略的一类拓扑错误。某个图层从第三方系统导入，肉眼看是一个完整多边形，放大到节点级别后，边与边互相穿过，多边形面积、周长、中心点全失真，这就是自相交。再往下走，入库质检直接报拓扑错误，让人分不清到底是源数据出了问题，还是中间环节引入的。GDAL几何修复要解决的问题，就是在数据从源格式流向成果格式之前，用程序把这类坏几何识别出来并修复回合法状态。这篇文章讲我在 Java 里基于 GDAL 做自相交修复的落地做法：怎么检测、怎么选修复策略、怎么同时处理 shp 和 gdb 两套格式，以及哪些坑必须提前躲开。适合正在写空间数据服务接口的开发者、做数据质检的工程师，也适合所有被“明明存得进库却报拓扑错误”折磨过的人。
2. 自相交从哪来：成因、识别规则与第一批检测代码
2.1 自相交、重复节点与环闭合：三类最常见的非法几何
自相交不是单一现象，它是“环自交 (self-intersection)”的一种通俗叫法。一个环如果存在两条边在非端点位置相交，或者一条边穿过另一条边，这个环就是自相交环。除此之外，经常和它一起出现的还有重复节点（相邻两个顶点完全重合）、闭环打开（首尾点不闭合）、以及退化的零面积环。这三个问题经常是叠加出现的：一条线被某个转换工具从 CAD 转出来时，可能在闭合点处多了一个中间点，也可能因为坐标精度截断导致两点重合。GDAL 的IsValid()判断会在这些情况下统一返回 false，但不会告诉你具体是哪种，所以检测环节的第一件事就是把坏几何挑出来，而不是急着修。
从数据源头上看，自相交的高发区有三个。第一是手工数字化描图，描回去的边界在弧段结合处往往会形成细微的交叉；第二是多个来源数据做融合或拼接时，公共边没有做一致化处理，两条相邻边界各自保留了一小段，拼起来就互相刺穿；第三是从 CAD 或坐标转换软件导出的面，CAD 里的闭合多段线转换到 GIS 面时，转换器对闭合处理不严格，导致最终边界自相交。shp 和 gdb 里都可能出现这些问题，区别在于 shp 本身没有内置拓扑规则，问题会原样保留；gdb 虽然支持拓扑规则，但很多数据是外部写入的，规则并没有真正生效。因此在做修复工具类之前，先把这些成因放在脑子里，后面选修复策略时你就知道：修复不只是把几何弄合法，还要尽量保住原始形状和属性。
2.2 先用 Java 跑一遍 IsValid 批量体检：每个图层坏几何有多少
我不建议拿到数据就直接修。第一步先做全量体检，统计每一层的非法要素数量、非法类型和大概位置，这能帮你判断修复工作量，也能在修复前后做对比。下面是体检代码的核心部分。
import org.gdal.gdal.gdal; import org.gdal.ogr.DataSource; import org.gdal.ogr.Feature; import org.gdal.ogr.Geometry; import org.gdal.ogr.Layer; import org.gdal.ogr.ogr; public class TopoCheck { static { gdal.AllRegister(); ogr.RegisterAll(); } public static void check(String dataSourcePath) { DataSource ds = ogr.Open(dataSourcePath, 0); // 0 表示只读打开 if (ds == null) { System.err.println("打开失败: " + ogr.GetLastErrorMsg()); return; } for (int i = 0; i < ds.GetLayerCount(); i++) { Layer layer = ds.GetLayerByIndex(i); int bad = 0; Feature feature; while ((feature = layer.GetNextFeature()) != null) { Geometry geom = feature.GetGeometryRef(); // 空几何和没有几何的要素不计入拓扑检查 if (geom != null && !geom.IsValid()) { bad++; if (bad <= 10) { String wkt = geom.ExportToWkt(); int len = Math.min(wkt.length(), 120); System.out.println("FID=" + feature.GetFID() + " 非法几何: " + wkt.substring(0, len) + "..."); } } feature.delete(); } System.out.println("图层 " + layer.GetName() + " 非法要素数: " + bad); } ds.delete(); } public static void main(String[] args) { check(args[0]); } }这段代码会逐个图层、逐个要素地调用IsValid()，把所有非法要素的 FID 和 WKT 前 120 个字符打印出来。FID 在 shp 里对应记录序号，在 gdb 里对应 OBJECTID，修复时回写定位很方便。统计的bad数量按图层输出，方便先做一次全库扫描、按图层排序，决定哪些图层需要重跑、哪些可以跳过。
GetNextFeature()是流式读取，内存占用平稳，适合几百 MB 的大图层。但有两个细节必须注意：第一，处理完一个要素之后必须feature.delete()释放底层 Native 句柄，否则长时间跑会堆住；第二，读取图层时不要加SetAttributeFilter，这一步只做纯几何体检，加了属性过滤会让统计结果失真，修复范围也会被带偏。体检结果如果某一层坏几何数量是 0，说明这层数据是干净的，不需要进入修复流程。
3. Java 几何拓扑修复工具类：从自相交到合法多边形的三条路
3.1 修复策略选型：MakeValid 优先、Buffer(0) 兜底、手工切环最后
拿到坏几何之后，修复策略不是唯一的。我常用的有三条路径，按优先级排序：第一优先是 GDAL 在较新版本里提供的MakeValid()，它走 OGC 的规则重新构造合法几何，能把自相交环切开重组，还能处理重复节点；第二优先是经典的Buffer(0)，对几何做距离为 0 的缓冲区运算，利用缓冲区算法天然消除自交；第三优先才是手工切环重组，把自相交的线段切碎后重新Polygonize。三条路径输出的几何形态不太一样，风险点也不同。
| 修复策略 | 做了什么 | 输出特征 | 主要风险 |
|---|---|---|---|
| MakeValid | 按 OGC 规则重新构造合法几何，自动切开自交环 | 可能变成 MultiPolygon 或混合几何 | 老版本 GDAL 没有这个方法 |
| Buffer(0) | 对几何求距离为 0 的缓冲带 | 输出单面或多部件面 | 经纬度坐标下易产生碎屑 |
| 手工切环重组 | 自交线段切碎后重新构面 | 最接近原始形态 | 实现量大，顶点顺序被打乱 |
我的工程习惯是：先尝试MakeValid()，它处理速度快，对绝大多数自交环有效；如果输出不合法，或者输出的几何类型从面变成了线这类低维结果，就用Buffer(0)兜底。Buffer(0)在平面坐标系下几乎不会失败，但它对经纬度坐标比较敏感，后面的避坑章节会专门展开。手工切环抓在最后，因为它的实现成本最高，只有在前面两条路都失效时才值得写。
3.2 工具类核心代码与参数说明
下面是我的自相交修复工具类核心代码。它接收一个Geometry，返回修复后的Geometry，同时抛出统计信息，方便上层记录修复前后变化。
import org.gdal.ogr.Geometry; import org.gdal.ogr.ogr; public class GeometryFixer { private final double tolerance; // 修复后简化容差，0 表示不简化 private final boolean keepZ; // 是否保留 Z 高程维度 public GeometryFixer(double tolerance, boolean keepZ) { this.tolerance = tolerance; this.keepZ = keepZ; } public Geometry fix(Geometry geom) { if (geom == null) { return null; } if (geom.IsValid()) { return geom; // 本来就是合法的，直接返回 } Geometry result = null; // 第一优先：MakeValid，输出可能变成 MultiPolygon try { result = geom.MakeValid(); } catch (Throwable e) { result = null; // 某些编译版本没有该方法，退回下一条路 } if (result == null || !result.IsValid()) { result = geom.Buffer(0.0); } // 第二优先：Buffer(0) 也失败时，进入线段切分重组流程 if (result == null || !result.IsValid()) { result = rebuildByCut(geom); } // 保留三维坐标：许多修复算法会丢掉 Z 值 if (keepZ && geom.GetCoordinateDimension() == 3 && result != null) { result.SetCoordinateDimension(3); } // 可选的拓扑保持简化，用于去掉浮点容差引起的小折角 if (tolerance > 0.0 && result != null) { result.SimplifyPreserveTopology(tolerance); } return result; } private Geometry rebuildByCut(Geometry geom) { // 常见做法：提取所有线段，求出两两交点， // 在交点处打断线段，再用 Polygonizer 重新构面。 // 这个方法实现量较大，只在 MakeValid 和 Buffer(0) 都失效时调用。 return null; // 实际工程里这里会走完整切分逻辑 } }这段代码的逻辑顺序值得说清楚。IsValid()检查放在最前面，避免好几何被二次加工。MakeValid()用 try-catch 包住，因为不同编译版本的 Java 绑定暴露的方法名不完全一致，有些老版本没有封装这个方法；catch 住之后直接退回Buffer(0)，不会因为个别方法缺失导致整个流程中断。Buffer(0)之后若结果仍然非法，最后再走rebuildByCut，这个方法实现较重，实际工程里会涉及线段求交、打断、Polygonizer 重构三件事。
参数上注意tolerance的单位和坐标系一致。投影坐标系下我用 0.0001 米做简化容差；经纬度坐标下我通常设 0，因为很小的容差数值在度单位下也可能吃掉有效形状。keepZ参数针对带高程数据，很多修复算法在构造过程中会把 Z 值丢掉，修复后SetCoordinateDimension(3)可以兜底补回维度，但原来的 Z 值不一定还在，这个要在日志里提示。
3.3 写回 shp 与 gdb：两套格式的落地差异
修复完几何，写回环节的坑比修复本身还多。shp 和 gdb 的写回逻辑完全不同，不能一套代码打天下。shp 是单文件要素类，字段名有 10 字符限制，dbf 属性表的编码需要单独指定；gdb 是文件地理数据库，字段名更宽松，内部编码统一，但对写入连接的管理更严格。我一般不会原地修改原始文件，而是全部走“修复后写入新图层，校验通过再替换”的路径，容错率最高。
| 维度 | shp | gdb |
|---|---|---|
| 字段名长度 | 10 字符截断 | 支持更长字段名 |
| 属性编码 | 需指定 SHAPE_ENCODING | 内部 UTF-8 |
| 原地修改 | 不建议，易损坏文件 | 不建议，锁库风险高 |
| 写入方式 | 新建 shp 文件写全量 | 新建要素类写全量 |
| 几何类型 | 单个图层一种几何类型 | 支持更复杂类型 |
shp 写入时最容易被忽略的是编码。中文属性在 dbf 里如果没指定编码，读出来就会变成乱码，写回去同样可能乱掉。我一般会在创建数据源之前设置ogr.SetConfigOption("SHAPE_ENCODING", "UTF-8")，如果下游软件强制要求 GBK，就改成"GBK"。gdb 写入则要特别注意连接释放，每个 DataSource 用完必须ds.delete()，否则下一次打开同一个 gdb 会报“锁被占用”。这两条细节会在避坑章节里再展开讲。
4. 避坑与排查：自相交修复最容易翻车的 5 个现场
4.1 五个高频坑：现象、原因、解决
坑 1：修复结果里多出了 GeometryCollection，下游软件读不出来。
现象是修复后几何类型从 Polygon 变成了 GeometryCollection，里面既有面又有线，导入某些平台时直接报“不支持的类型无法读取”。原因是MakeValid()按 OGC 规则构造合法几何，当两条边彻底重合时，构造器会保留所有可能的部件，包括低维部件。解决方法是写回前做部件过滤，把几何只保留面部件，并统一展开成 MultiPolygon。
if (result != null && result.GetGeometryType() == ogr.wkbGeometryCollection) { // 遍历子几何，只保留 Polygon 和 MultiPolygon 部件 for (int i = 0; i < result.GetGeometryCount(); i++) { Geometry sub = result.GetGeometryRef(i); int type = sub.GetGeometryType(); if (type == ogr.wkbPolygon || type == ogr.wkbMultiPolygon) { // 收集到新 MultiPolygon } } }坑 2：经纬度坐标下 Buffer(0) 修出一堆碎屑多边形。
现象是修复后图层里凭空多出几十个零碎小面，面积只有零点几平方米。原因是 Buffer(0) 的缓冲区算法在度单位坐标系下，数值精度处理会产生微型碎屑；另外在经度接近 ±180° 的区域，平面缓冲区计算还可能跨线产生怪多边形。解决方法是优先用MakeValid()而不是Buffer(0)；如果必须用 Buffer，先投影到平面坐标系修复完再投影回来。
坑 3：修复后写回 shp，中文属性全部变成“???”。
现象是属性表里所有中文字段变成问号，或者干脆变成乱码。原因是 dbf 文件的编码与读取端编码不一致，Java 侧写入时又没指定 SHAPE_ENCODING。解决方法是创建输出数据源前设置ogr.SetConfigOption("SHAPE_ENCODING", "UTF-8")，并在写完所有要素后主动关闭数据源，让 dbf 头信息落盘。
坑 4：gdb 写入报“dataset in use”或者锁文件无法删除。
现象是同一个 gdb 修复写第二次时，程序抛异常或文件被占用。原因是前一次写入的 DataSource、Layer 或 Feature 没有彻底释放，GDAL 的 Native 句柄还拿着文件锁。解决方法是把一次完整的数据源处理写成一个方法，方法内用 try-finally 保证ds.delete()一定执行，不要依赖 GC，因为 GC 不知道那是个文件锁。
坑 5：单要素自相交修完了，但两个相邻面之间的共享边仍然错位。
现象是每个面的IsValid()都返回 true，但两个面的边界互相交叉重叠，质检仍然报拓扑错误。原因是这属于要素间的拓扑错误，不是单几何错误，IsValid()天然检测不到。解决方法是把共享边错位单独做一次两两检测，或者用 gdb 自身的拓扑规则在入库后跑一遍完整性校验；这类问题靠MakeValid()解决不了，需要在融合公共边时做节点一致化。
4.2 定位手段：先看日志，再看底层 GDAL 版本
修复失败时，第一步不是改代码，而是确认当前环境的 GDAL 版本和错误日志。同一个修复方法在不同 GDAL 版本上的行为差别很大，特别是MakeValid()是否存在、输出几何类型是否稳定，都跟版本强相关。
// 打印当前 GDAL 版本，诊断时先看这一行 System.out.println(gdal.VersionInfo("RELEASE_NAME")); gdal.ErrorReset();还可以用命令行工具做最小复现。ODBC 参数、图层名、几何字段，命令行跑一遍能快速排除“是数据问题还是代码问题”：
ogrinfo -ro -so -al bad.gdb layerName ogrinfo -ro -al -geom=SUMMARY bad.shp前者能看到图层概览和几何类型，后者会输出每个要素的几何摘要。如果命令行下几何是正常的，那问题基本在 Java 绑定的调用方式上，优先检查属性过滤、空间过滤有没有误伤；如果命令行下也报非法几何，那就是源数据本身的问题，交给修复工具类处理就行。这套定位链路能省掉大量瞎猜的时间，很多翻车现场最后都发现不是修复算法的问题，而是版本行为差异。
5. 批量落地：多图层循环、并行修复与参数调优
5.1 图层循环与线程池并行：每个数据集一个 GDAL 句柄
单个图层修复能跑通之后，接下去就是把整个目录、整个数据库批量跑起来。批量处理的核心约束是并发安全：GDAL 的 Native 层不是完全线程安全的，同一个 DataSource 不能被多个线程同时读取或写入，但不同线程各开各的 DataSource 是可以的。我的做法是每个数据源独立打开、独立处理、独立关闭，线程池只负责调度任务，不共享任何 OGR 对象。
import java.util.List; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; public class BatchFixer { public void process(List<String> dataSourcePaths) { ExecutorService pool = Executors.newFixedThreadPool(4); for (String path : dataSourcePaths) { pool.submit(() -> { try { processOne(path); } catch (Exception e) { System.err.println(path + " 处理失败: " + e.getMessage()); } }); } pool.shutdown(); } private void processOne(String path) throws Exception { DataSource ds = ogr.Open(path, 0); if (ds == null) { throw new RuntimeException(ogr.GetLastErrorMsg()); } try { for (int i = 0; i < ds.GetLayerCount(); i++) { Layer layer = ds.GetLayerByIndex(i); fixLayer(layer); } } finally { ds.delete(); } } }线程数我一般取 CPU 核数的一半，最多不超过 8。原因是 GDAL 的读写都在 Native 层执行，创建和释放句柄都有开销，线程太多反而会造成文件句柄争抢，尤其当目标路径是同一个 gdb 时，并发写入会引起锁冲突。并行只读是安全的，但写入阶段要么串行，要么按不同输出目录分线程，否则你会遇到一堆玄学报错。
固定线程池的另一个好处是方便控制整体失败率。某个数据源处理失败了，不会影响其他任务继续跑，最后通过日志汇总哪些文件失败、失败原因是什么。处理完一批之后，再把失败文件单独拎出来重跑，这样能避免“一个坏数据拖垮整个批次”的情况。
5.2 三个必调参数：容差、坐标系转换与面积阈值
批量落地时，有三个参数直接决定修复质量和下游可用性。第一个是容差tolerance，它控制修复后是否做拓扑保持的简化。投影坐标系下我推荐 0.0001 米到 0.001 米，这个量级能吃掉浮点误差产生的小折角，又不会把真实形状磨圆；经纬度坐标系下我通常只做修复不做简化，因为度的单位跨度太大了，一个小数位的变化对应地面距离可能达到米级。
第二个是坐标系转换。修复自相交最好在平面坐标系下进行，如果你的源数据是 WGS84 经纬度，常规流程是先投影到目标区域所在中央经线的投影坐标系，修复完成再投影回 WGS84。投影前后面积可能变化，所以必须在修复流程里记录每个要素修复前后的面积，供后续校验。第三个是面积变化阈值。修复不应该让一个多边形面积发生剧烈变化，我一般把阈值设在 0.5%：修复前后面积差超过这个比例的要素，单独输出到一个提示列表，交给人工复核。
| 参数项 | 投影坐标系建议值 | 经纬度建议值 | 作用 |
|---|---|---|---|
| 简化容差 | 0.0001 米 | 0（不简化） | 去掉浮点误差小折角 |
| 面积变化阈值 | 0.5% | 0.5% | 拦截修复过程产生的异常形变 |
| 碎屑面积阈值 | 0.001 平方米 | 0.0000001 平方度 | 修复后清理微型碎面 |
这三个参数不是死值，取决于数据精度要求。国土类成果数据精度要求高，容差尽量小；管线概化数据可以放宽。我习惯把它们做成配置文件或方法入参，不要写死在代码里，方便不同项目复用同一套工具类。
6. 修复结果怎么验收：用统计快照拦住下一次拓扑错误
修复跑完不等于工作结束，验收环节必须有一份前后对比的统计快照。我会在修复前后分别记录每个图层的要素总数、非法要素数、几何类型分布和面积均值，修复结束后自动生成一份对比结果。面积变化率超过阈值的要素、修复后仍然非法的要素、几何类型从面变成线的要素，这三类都会被单独列出来，作为人工复核清单。
ogrinfo -ro -al -geom=SUMMARY fixed.shp fixed_layer ogrinfo -ro -so -al fixed.gdb更完整的验收脚本会把结果输出成 CSV，格式大致是图层名、原始要素数、修复要素数、修复后非法数、面积变化率。这个 CSV 不光是给自己看，也是给下游数据接收方看的交付证明。修了多少、还剩多少问题，一目了然。我自己的习惯是在处理流水线里把这三项检查写成固定流程，任何数据进来必须先过体检，再进修复，修复完立刻跑统计快照。
这里分享一个教训：我自己一开始也迷信 MakeValid 一把梭，直到某次修复完一个管线图层，面积统计整体漂移了 3%，才把统计快照这件事补上。从那以后，我的处理流水线里修完几何一定会做三重检查：合法率、要素类型分布、面积变化率。这条铁律帮我挡住了后面好几次数据事故。做几何修复工具类，真正的难点从来不是写修复代码，而是让每一次修复都可追踪、可验证、可回退。希望你也能在自己的项目里把这套检查习惯带上，数据入库前先让统计说话，而不是相信某个工具的输出“应该没问题”。希望帮到你。
本文还有配套的精品资源，点击获取
