Turf.js booleanDisjoint 空间关系判定完全指南:@turf/boolean-disjoint 原理、用法与源码解析
Turf.js booleanDisjoint 空间关系判定完全指南:@turf/boolean-disjoint 原理、用法与源码解析
导读
@turf/boolean-disjoint 是 Turf.js 模块化地理空间引擎中负责空间关系判定的核心布尔函数之一:当两个 GeoJSON 几何体的交集为空集时返回 true(即两者“不相交”)。本文以 packages/turf-boolean-disjoint/README.md 为骨架,结合该模块的 TypeScript 源码、测试用例 与 43 个 GeoJSON 夹具(fixture),系统讲解函数签名、参数语义、内部算法分派、ignoreSelfIntersections 选项的底层影响以及回归测试用例,帮助你写出可靠的空间查询、碰撞检测与要素过滤逻辑。
一、函数签名与核心语义
booleanDisjoint 判定的是 两个几何体的交集是否为空集(intersection is an empty set)。如果为空,返回 true;只要存在任意一个共同点——无论是内部相交、边界相接还是完全重叠——都返回 false。
从 README.md 与 index.ts 中的 JSDoc 可知完整签名:
| 参数 | 类型 | 说明 |
|---|---|---|
feature1 |
Geometry | Feature<any> |
第一个 GeoJSON 几何对象或要素 |
feature2 |
Geometry | Feature<any> |
第二个 GeoJSON 几何对象或要素 |
options |
Object(可选,默认 {}) |
可选参数对象 |
options.ignoreSelfIntersections |
boolean(可选,默认 true) |
是否忽略输入要素自身的自相交(self-intersection) |
返回值:boolean——交集为空集返回 true,否则返回 false。
基础用法示例
原文档给出的最小可运行示例:
var point = turf.point([2, 2]);
var line = turf.lineString([[1, 1], [1, 2], [1, 3], [1, 4]]);
turf.booleanDisjoint(line, point);
//=true
点 [2, 2] 与竖直线 x = 1 毫无接触,因此判定为不相交,结果为 true。将点坐标换成 [1, 2](落在线上),结果即为 false。
二、安装与引入方式
该模块可从 npm 单独安装,也可以随全量 Turf 包一起使用:
# 方式一:仅安装单模块
$ npm install @turf/boolean-disjoint
# 方式二:安装包含全部模块的 @turf/turf
$ npm install @turf/turf
在 TypeScript / ESM 项目中(该包 "type": "module",见 package.json)可按需导入:
import { booleanDisjoint } from "@turf/boolean-disjoint";
// 或
import booleanDisjoint from "@turf/boolean-disjoint"; // 默认导出
在 Turf 聚合包中,它与其他布尔判定函数一起被统一导出(见 packages/turf/index.ts),因此也可以直接写 turf.booleanDisjoint(...)。运行环境要求 Node.js ≥ 22(见 package.json)。
三、源码级算法解析:几何类型的两级分派
booleanDisjoint 的实现遵循“先降维展平,再按几何类型分派”的思路(见 index.ts):
- Multi 几何展平:入口函数用
@turf/meta的flattenEach分别遍历两个要素。这保证了 MultiPoint、MultiLineString、MultiPolygon 以及 GeometryCollection 等复合几何会被拆解为基本几何逐一参与判定(index.ts)。任意一组子几何“不相交”检查失败,整体即返回false,且遍历会提前终止。 - 基本类型配对分派:展平后的每个子几何只会是 Point / LineString / Polygon 三种基本类型,私有函数
disjoint以switch (geom1.type)+ 内层switch (geom2.type)完成 3×3 的配对分派(index.ts),每个组合都有专门的判定子过程。
各组合的判定方式与所用依赖如下:
| 组合(geom1 × geom2) | 判定算法 | 依赖模块 |
|---|---|---|
| Point × Point | 精确比较坐标是否相等(compareCoords) |
内置 |
| Point × LineString | 点是否落在线段上(isPointOnLine) |
内置 |
| Point × Polygon | 点是否在多边形内(booleanPointInPolygon) |
@turf/boolean-point-in-polygon |
| LineString × LineString | 线段求交 + 共线重叠兜底(isLineOnLine) |
@turf/line-intersect |
| LineString × Polygon | 顶点包含判定 + 线段求交(isLineInPoly) |
boolean-point-in-polygon、line-intersect、@turf/polygon-to-line |
| Polygon × Polygon | 顶点互判 + 边界线段求交(isPolyInPoly) |
同上三个模块 |
两个值得注意的实现细节:
- 共线/重叠线的兜底检测:
lineIntersect只报告“线段真正交叉”的交点,对共线(collinear)部分重叠的线会漏判。因此isLineOnLine在求交结果为空后,还会把两条线的每个顶点拿到对方线上做一次点在线段判定(index.ts),用于捕获完全或部分重叠的情况。 - 多边形仅比较外环:
isPolyInPoly只遍历feature.coordinates<a href="https://link.gitcode.com/i/1588aa294c8a2c54fdbe471fb970c59b" target="_blank">0](外环),并在最后将两个多边形经polygonToLine转成线后求交([index.ts)。因此两个多边形只要有一个顶点落在对方内部,或边界线段相交,就视为“不相交”不成立。
四、ignoreSelfIntersections 选项的底层影响
该选项默认值为 true,其作用是控制 输入要素自身自相交 是否被纳入“共享点”的判定。
从 test.ts 的专项测试可以还原其行为:当一条自相交的 LineString(如 [[1,1],[2,2],[1,2],[2,1]] 形成的“X”形折线)与另一条不与其相交的线做判定时——
ignoreSelfIntersections: true(默认):返回true(判定不相交),自相交造成的“视觉重叠”被忽略;ignoreSelfIntersections: false:返回false(判定相交),因为自相交点也被视为两几何的公共点。
该选项最终被透传给 lineIntersect(见 index.ts),因此它主要影响线-线、线-面、面-面组合的求交结果。在实际业务中,如果输入数据来自数字化过程、可能存在抖动或自相交瑕疵,保持默认值 true 可以避免因几何自身缺陷导致误判;而如果数据已确保合法(valid),可显式传 false 以获得更严格的判定。
五、与 booleanIntersects 的关系
在 Turf 的布尔函数家族中,booleanDisjoint 与 booleanIntersects 是互补关系:二者始终互为反值——booleanDisjoint(a, b) === !booleanIntersects(a, b)。因此空间查询中二者可以互相替代,选择哪一个取决于代码的可读性偏好;但需注意 booleanIntersects 与 booleanContains、booleanWithin 之间在“严格包含/边界相接”等细节语义上并不完全等价,若需要更细粒度判定请查阅对应模块文档。
六、测试体系与回归案例
该模块的测试由 test.ts 驱动,采用 tape + glob 遍历夹具的方式:
- 夹具目录结构:
test/true/与test/false/下按几何类型/几何类型/*.geojson组织,覆盖 Point、LineString、Polygon、MultiPoint、MultiPolygon 之间的两两组合,共 43 个 GeoJSON 夹具; - 双引擎校验:测试同时断言 Turf 自身结果,并在设置了
SHAPELY环境变量时用boolean-shapely(Python Shapely 的绑定)交叉验证结果(test.ts); - 专项选项测试:第二组测试专门覆盖
ignoreSelfIntersections为true/false时的五种组合场景(线-线、线-面、面-面),见 test.ts。
此外,夹具中的 issue-1216.geojson 是历史 issue 的回归样例:两个实际经纬度多边形(一个横跨 46.5135°N~46.5245°N 的窄带,另一个在 46.5171°N~46.5210°N 与其纵向重叠)存在交集,因此被放入 false 目录,确保该边界情形不被误判为 disjoint。
七、性能基准
仓库内置的 bench.ts 基于 Benchmark.js 对每个夹具计时(运行 pnpm --filter @turf/boolean-disjoint bench 可复现)。其注释中记录的近一次基准结果(见 bench.ts)显示:纯坐标比较的 PointDisjointFromPoint 约 1800 万 ops/sec,而涉及线段求交的 LineIsNotDisjointFromLine 约 5 万 ops/sec,量级差异主要由是否触发几何求交算法决定。基准数据因机器而异,这里仅用于说明算法复杂度分布:点-点最快,线-线/线-面最慢,在批量空间过滤场景中可据此安排计算顺序。
八、补充图示:disjoint 语义速览
仓库文档自带的 esri-disjoint.gif 直观展示了 disjoint 关系的 9 种几何组合:Point/Point、Point/MultiPoint、Point/LineString、Point/Polygon、MultiPoint/MultiPoint、MultiPoint/LineString、MultiPoint/Polygon、LineString/Polygon 与 Polygon/Polygon。图中橙色与黑色几何对象彼此完全分离、无任何接触,这正是 booleanDisjoint 返回 true 的直观形态,也是 ESRI/SQL 空间语义中 ST_Disjoint 的对应概念。
九、实战建议
- 批量要素过滤:遍历 FeatureCollection 时,用
booleanDisjoint(feature, queryArea)快速剔除不相交要素,配合空间索引(如 @turf/geojson-rbush)先粗筛 bbox 再精确判定,可获得数量级性能提升; - 碰撞检测:判定线/面是否与缓冲区或其他要素相交时,disjoint 的反值即“存在交点”,语义比直接调用求交函数更清晰;
- 数据质量:来自手绘、扫描或第三方源的数据建议保持
ignoreSelfIntersections: true默认值,避免自相交缺陷导致误报; - 结果验证:业务关键判定可参照 test.ts 的做法,与 Shapely 等成熟引擎交叉验证后再上线。
