Turf.js Wiki

简体中文

English

简体中文

English

Appearance

距离和方位 ​

概述 ​

本页记录 Turf.js 模块，用于计算地理点之间的距离和方位，以及 along、destination 和 midpoint 等相关操作。这些模块在依赖层次结构中形成第 2 层原始操作（参见第 2.3 页），并被高级几何操作广泛使用。

所有距离和方位计算支持两种数学方法：

|| 方法 | 路径类型 | 用例 | 模块 | ||-------------------------|--------------------------|-------------------------------------------|-----------------------------------------------------------------------------------------------------| || 大圆（测地线） | 球面上的最短路径 | 大多数距离/导航计算 | @turf/distance, @turf/bearing, @turf/destination | || 恒向线（等角航线） | 恒定罗盘方位 | 海洋/航空导航，墨卡托地图 | @turf/rhumb-distance, @turf/rhumb-bearing, @turf/rhumb-destination |

复合操作如 @turf/along 和 @turf/midpoint 通过组合距离、方位和目的地计算来构建这些原始操作。

模块依赖结构 ​

距离和方位模块遵循清晰的依赖层次结构：

SVG
100%

恒向线模块（@turf/rhumb-distance、@turf/rhumb-bearing、@turf/rhumb-destination）遵循相同的依赖模式，但实现恒定方位计算。

大圆距离 ​

@turf/distance 模块 ​

distance 函数使用 Haversine 公式计算球面上两点之间的最短距离。这是 Turf.js 中最常用的距离计算。

函数签名：

function distance(
  from: Coord,
  to: Coord,
  options?: { units?: Units }
): number

算法概述：

SVG
100%

Haversine 公式正确处理跨对跖线的坐标差异，适用于所有纬度/经度组合。它使用公式：

a = sin²(Δφ/2) + cos(φ1) * cos(φ2) * sin²(Δλ/2)
c = 2 * atan2(√a, √(1−a))
distance = R * c

其中 φ 是纬度，λ 是经度，R 是地球半径。

大圆方位 ​

@turf/bearing 模块 ​

bearing 函数计算沿大圆路径从一个点到另一个点的罗盘方向。

函数签名：

function bearing(
  start: Coord,
  end: Coord,
  options?: { final?: boolean }
): number

方位计算流程：

SVG
100%

方位以 -180 到 +180 度的范围返回。0° 方位指向北，90° 指向东，180° 或 -180° 指向南，-90° 指向西。

大圆目的地 ​

@turf/destination 模块 ​

destination 函数计算从起点沿大圆路径行进给定距离和方位的终点。

函数签名：

function destination(
  origin: Coord,
  distance: number,
  bearing: number,
  options?: { units?: Units; properties?: Properties }
): Feature<Point>

目的地计算：

SVG
100%

计算使用球面三角学来精确计算地球表面上的目的地。距离被转换为弧度（角距离）用于内部计算。

恒向线距离 ​

@turf/rhumb-distance 模块 ​

rhumbDistance 函数计算沿恒定方位路径的两点之间的距离。与大圆计算不同，恒向线在墨卡托投影上显示为直线。

SVG
100%

核心计算使用 Mercator 投影数学和拉伸因子 q 来处理不同纬度的经度压缩：

|| 变量 | 用途 | 公式 | || --- | --- | --- | || DeltaPhi | 纬度差 | phi2 - phi1 | || DeltaPsi | Mercator 投影因子 | log(tan(phi2/2 + PI/4) / tan(phi1/2 + PI/4)) | || q | 拉伸因子 | DeltaPhi / DeltaPsi 当 DeltaPsi > 10e-12 | || delta | 角距离 | sqrt(DeltaPhi² + q² * DeltaLambda²) |

恒向线方位 ​

@turf/rhumb-bearing 模块 ​

rhumbBearing 函数确定两点之间的恒定罗盘航向。计算通过 final 选项参数处理初始和最终方位。

SVG
100%

方位计算使用 Mercator 空间中坐标差的反正切，通过经度归一化处理对跖线穿越。

恒向线目的地 ​

@turf/rhumb-destination 模块 ​

rhumbDestination 函数计算沿恒向线行进给定起点、距离和方位的终点。

SVG
100%

目的地计算涉及几个关键数学步骤：

  1. 角距离计算：delta = distance / radius
  2. 坐标投影：转换为弧度并应用三角函数
  3. 方位应用：DeltaPhi = delta * cos(theta)，DeltaLambda = delta * sin(theta) / q
  4. 结果归一化：确保经度保持在 -180 到 +180 度范围内

复合操作 ​

@turf/along 模块 ​

along 模块计算 LineString 上指定距离处的点。它组合距离计算与坐标插值以找到精确位置。

函数签名：

function along(
  line: Feature<LineString | MultiLineString> | LineString | MultiLineString,
  distance: number,
  options?: { units?: Units }
): Feature<Point>

Along 算法：

SVG
100%

算法沿线段行走，累积距离直到达到或超过目标距离。当目标在段内时，它使用 bearing 和 destination 来插值精确点。

@turf/midpoint 模块 ​

midpoint 模块计算两点之间的测地线中点。与坐标的简单平均不同，这找到沿大圆路径的真实中点。

函数签名：

function midpoint(
  point1: Coord,
  point2: Coord
): Feature<Point>

中点计算流程：

SVG
100%

这种方法确保中点位于两点之间的大圆路径上，这与坐标的算术平均值不同，除非点位于赤道或共享相同经度。

实现细节 ​

单位转换系统 ​

所有距离相关模块与 @turf/helpers 提供的统一单位系统集成：

|| 单位 | 到米的转换因子 | 常见用途 | || --- | --- | --- | || meters | 1 | 科学、公制 | || kilometers | 1000 | 大多数操作的默认值 | || miles | 1609.344 | 美国测量 | || nauticalmiles | 1852 | 海洋/航空 | || feet | 0.3048 | 英制测量 | || radians | 6371008.8（地球半径） | 角距离 | || degrees | 111319.49（在赤道） | 角度测量 |

@turf/helpers 中的 convertLength() 函数处理转换：

convertLength(distance: number, originalUnit: Units, finalUnit: Units): number

模块特定默认值：

  • @turf/distance：默认输出是 kilometers
  • @turf/destination：默认输入是 kilometers
  • @turf/along：默认输入是 kilometers

坐标系统处理 ​

180 度经线管理 ​

所有恒向线计算实现对 180 度经线（国际日期变更线）的一致处理，以防止坐标系统错误：

SVG
100%

这种归一化出现在所有三个恒向函数中，使用相同的逻辑模式，确保整个库的坐标处理一致。

通用依赖 ​

所有距离和方位模块依赖基础模块进行坐标处理和验证：

@turf/invariant 函数：

  • getCoord(coord)：从 Point 要素、坐标或坐标数组中提取 [longitude, latitude] 数组
  • getCoords(feature)：从 LineString 和其他几何体中提取坐标数组

@turf/helpers 函数：

  • convertLength()：距离的单位转换
  • point()：创建具有可选属性的 GeoJSON Point 要素
  • radiansToLength()：将角距离（弧度）转换为线性距离
  • lengthToRadians()：将线性距离转换为角距离（弧度）
  • degreesToRadians()：三角计算的角度转换
  • radiansToDegrees()：将结果转换回度

这些基础函数确保所有距离/方位模块的输入验证和坐标处理一致。

错误处理和边界情况 ​

数值稳定性 ​

恒向线实现包括几个数值稳定性措施：

SVG
100%

这些稳定性措施处理：

  • 东西向航线：当 DeltaPsi 接近零时（病态计算）
  • 极地穿越：当纬度超过 ±90 度时
  • 对跖线穿越：国际日期变更线的经度归一化

Copyright © 2026 LZUGIS