Turf.js booleanDisjoint 空间关系判定完全指南:@turf/boolean-disjoint 原理、用法与源码解析

原创2026-09-24 13:11:511,986 阅读
文章标签:数据分析

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):

  1. Multi 几何展平:入口函数用 @turf/meta 的 flattenEach 分别遍历两个要素。这保证了 MultiPoint、MultiLineString、MultiPolygon 以及 GeometryCollection 等复合几何会被拆解为基本几何逐一参与判定(index.ts)。任意一组子几何“不相交”检查失败,整体即返回 false,且遍历会提前终止。
  2. 基本类型配对分派:展平后的每个子几何只会是 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 的对应概念。

esri-disjoint 示意图:展示 Point、MultiPoint、LineString、Polygon 等 9 种几何组合下不相交关系的空间形态

九、实战建议

  • 批量要素过滤:遍历 FeatureCollection 时,用 booleanDisjoint(feature, queryArea) 快速剔除不相交要素,配合空间索引(如 @turf/geojson-rbush)先粗筛 bbox 再精确判定,可获得数量级性能提升;
  • 碰撞检测:判定线/面是否与缓冲区或其他要素相交时,disjoint 的反值即“存在交点”,语义比直接调用求交函数更清晰;
  • 数据质量:来自手绘、扫描或第三方源的数据建议保持 ignoreSelfIntersections: true 默认值,避免自相交缺陷导致误报;
  • 结果验证:业务关键判定可参照 test.ts 的做法,与 Shapely 等成熟引擎交叉验证后再上线。

相关资源

登录后查看全文
turf