大地测量工具箱 TYEclipse/dsh-geodesy

dsh-geodesy

面向 DeepSeek Harness（dsh）的大地测量数学工具箱：大圆距离、方位角、目的地推算、DMS 解析、恒向线、路径交点、球面多边形面积、偏航（cross-track）距离、点在多边形内判定、多段航线总里程与球面圆（覆盖范围）——全部是本地、确定性的工具，零运行时依赖。

中文简介：dsh 插件「大地测量工具箱」——大圆距离、方位角、目的地推算、DMS 坐标解析、恒向线（罗盘等角航线）距离、两条大圆路径交点、球面多边形面积、点到路径的偏航距离（cross-track）、点是否在球面多边形内、多段航线总里程与偏航/绕行量、球面圆（覆盖范围），共十一个纯计算工具，零运行时依赖。专治大模型手算球面几何的常见错误（弧度与角度混用、经纬度顺序颠倒、忘记地球半径、把球面多边形当平面算、反算偏航距离时把「最近点」与「垂足」混为一谈、把球面覆盖范围当平面圆算等）。

为什么需要它

大模型算大地测量数学总是翻车：经纬度顺序搞反、地球半径用错、忘了角度转弧度、DMS 换算算错、把球面多边形当平面处理。这个插件把这部分数学从模型脑子里搬出来，交给精确的球面三角学：

- geo_distance —— 两点间大圆距离（haversine），附带初始/最终方位角与 16 方位罗盘方向；结果可用 km、m、mi 或 nmi
- geo_bearing —— 两点间初始与最终大圆方位角，外加两点的大圆中点
- geo_destination —— 正算大地测量问题：给定起点、方位角与距离，算出目的地（附带往返距离校验）
- coord_parse —— 解析并校验坐标字符串（十进制、DMS、后缀、成对形式），转换成十进制度 + 格式化 DMS
- geo_rhumb —— 两点间恒向线（等角航线 / loxodrome）距离与方位角，附带大圆距离作对比
- geo_intersection —— 两条大圆路径（各给起点 + 初始方位角）的交点；报告最近的交点、对跖交点，以及到两个起点的距离
- geo_area —— 用球面角盈（Girard 定理）算球面多边形的面积与周长，始终附带互补区域的面积
- geo_cross_track —— 点偏离大圆路径多远：带符号的偏航距离、到垂足的沿航距离、垂足坐标、垂足是否落在路径两端点之间，以及到线段最近点的距离
- geo_point_in_polygon —— 坐标是否在球面多边形内？同时报告边界两侧（封闭区域与有向边左侧区域）、边界命中情况，以及点所在区域的面积
- geo_path —— 汇总多段航线：每段的长度、航向（方位角 + 罗盘方位）与累计里程，外加航线总里程、两端点间直线距离、绕行量，以及回到起点的距离
- geo_circle — 球冠（「某点半径 r 以内的全部区域」）：面积及其占球面的比例、边界圆的周长、边界是否为大圆、覆盖的经纬度范围框（含极点与反经线情形），以及给定点是否落在其中

所有计算均使用 IUGG 平均地球半径 6371.0088 km（可通过插件 radiusKm 选项配置，例如用于月球或行星计算）。

安装

dsh plugin --profile web add github:TYEclipse/dsh-geodesy

需要 pnpm 在 PATH 中。然后重启该配置档的服务（或执行 dsh restart web）。

用法

向智能体提出涉及地球表面数学的问题，它会自动调用工具：

- 「北京到上海的大圆距离是多少？」
- 「从伦敦看纽约在哪个方向？中点在哪里？」
- 「我在巴黎正东 200 km 处——这是哪里？」
- 「把 37°46′30″N, 122°25′8.4″W 解析成十进制度。」
- 「从 (45°N, 0°) 到 (45°N, 90°) 保持恒定航向航行，要走多远？比大圆航线长多少？」
- 「从 (0, 0) 出发向正东的飞行走廊，与从 (0, 90) 出发向正北的飞行走廊在哪里相交？」
- 「球面上三角形 (0,0)、(0,90)、(90,0) 的面积是多少？」
- 「我从 (0,0) 驶向 (0,10)——在 (1,5) 处偏离航线多远？在哪里回到航线？」
- 「(45, 45) 在球面三角形 (0,0)、(0,90)、(90,0) 内吗？」
- 「这个 0.2° 的框位于反经线上——(0, 0) 在框内吗？」（对跖点陷阱：朴素的角度和判定会说在，实际不在）
- 「伦敦 → 巴黎 → 罗马这条航线有多长？比直飞远多少？」
- 「北京 300 km 以内的全部区域——面积多大？边界在哪里？」

示例

geo_rhumb — (45°N, 0°) → (45°N, 90°)，恒定航向：

{
"valid": true,
"unit": "km",
"distance": 7076.411574,
"kilometers": 7076.411574,
"miles": 4397.078297,
"nauticalMiles": 3820.956573,
"bearing": 90,
"compass": "E",
"greatCircleKm": 6671.704814
}

geo_intersection — 赤道（从 (0,0) 向东）× 子午线（从 (0,90) 向北）：

{
"valid": true,
"lat": 0,
"lon": 90,
"distanceFromStart1Km": 10007.557221,
"distanceFromStart2Km": 0,
"antipodeLat": 0,
"antipodeLon": -90,
"antipodeDistanceFromStart1Km": 10007.557221,
"antipodeDistanceFromStart2Km": 20015.114442
}

geo_area — 八分之一球面三角形 (0,0)、(0,90)、(90,0)：恰好是球面的八分之一：

{
"valid": true,
"vertices": 3,
"areaKm2": 63758235.121609,
"perimeterKm": 30022.671663,
"excessRadians": 1.5707963268,
"complementKm2": 446307645.851263
}

geo_cross_track — 查询点 (1, 5) 相对赤道路径 (0,0) → (0,10)：

{
"valid": true,
"side": "left",
"crossTrackKm": 111.19508,
"distanceToPathKm": 111.19508,
"alongTrackKm": 555.975401,
"footLat": 0,
"footLon": 5,
"withinSegment": true,json
{
"distanceToSegmentKm": 111.19508,
"pathLengthKm": 1111.950802,
"trackBearing": 90,
"bearingToFoot": 180
}

geo_point_in_polygon —— 用 (45, 45) 对八分之一球面三角形 (0,0)、(0,90)、(90,0) 做判断： json { "valid": true, "insideEnclosed": true, "insideLeftRegion": true, "onBoundary": false, "vertices": 3, "areaKm2": 63758235.121609, "complementKm2": 446307645.851263, "regionAreaKm2": 63758235.121609 }

geo_path —— London (51.5074, -0.1278) → Paris (48.8566, 2.3522) → Rome (41.9028, 12.4964)：这条路线比直线长 15 km，绕行约 1%： json { "valid": true, "points": 3,
"legs": [
{ "leg": 1, "fromIndex": 0, "toIndex": 1, "distanceKm": 343.556535, "cumulativeKm": 343.556535, "initialBearing": 148.115617, "compass": "SSE" },
{ "leg": 2, "fromIndex": 1, "toIndex": 2, "distanceKm": 1105.281675, "cumulativeKm": 1448.83821, "initialBearing": 130.58791, "compass": "SE" }
],
"totalKm": 1448.83821,
"straightKm": 1433.783288,
"detourKm": 15.054922,
"detourPercent": 1.05,
"closureKm": 1433.783288,
"closesLoop": false,
"maxLegKm": 1105.281675,
"minLegKm": 343.556535,
"zeroLengthLegs": []
}

geo_circle —— 北京 (39.9042, 116.4074) 周边 300 km 范围，判断 (40.5, 117) 是否在圈内。这个球冠占地球表面积 0.055%，边界圆周长 1884 km，所占矩形跨 5.4° 纬度、7.0° 经度： json { "valid": true, "angularRadiusDeg": 2.697961, "areaKm2": 282691.098586, "surfaceFraction": 0.0005542247, "boundaryKm": 1884.259081, "boundaryIsGreatCircle": false, "minLat": 37.206239, "maxLat": 42.602161, "minLon": 112.889481, "maxLon": 119.925319, "lonSpanDeg": 7.035838, "crossesAntimeridian": false, "coversAllLongitudes": false, "includesNorthPole": false, "includesSouthPole": false, "coversWholeSphere": false, "pointDistanceKm": 83.198018, "containsPoint": true, "pointOnBoundary": false }

geo_distance —— 北京 (39.9042, 116.4074) → 上海 (31.2304, 121.4737)： json { "valid": true, "unit": "km", "distance": 1067.311645, "kilometers": 1067.311645, "miles": 663.196709, "nauticalMiles": 576.302184, "initialBearing": 153.072675, "finalBearing": 156.029266, "compass": "SSE" }

语义说明

- geo_area 的绕向：返回的面积是有向边左侧的区域。顶点按逆时针排列（从球外看）得到多边形本身；顺时针排列得到它的补集。complementKm2 总会给出，所以无论要哪一侧，都只差一个字段。多边形必须是简单多边形（不自交），顶点最多 100 个。
- geo_point_in_polygon 会同时报告边界两侧，因为球面上的边界永远有两侧：
- insideEnclosed —— 就是普通的「点是否在多边形内」。封闭区域取边界把球面分成的两块区域中较小的那块，所以顺时针绕的正方形，内部仍指它围出的区域。
- insideLeftRegion —— 有向边 LEFT 侧的区域，也就是 geo_area 称为 areaKm2 的那块区域。顶点按逆时针排列时，两种判断结果一致；按顺时针排列时，两者相反（note 里会说明）。
- 距边约 6 mm 以内的点（浮点容差）标记为 onBoundary: true，不属于任何一块区域。方法采用带符号的大圆射线交叉绕数法。流行的「对查询点处的角度求和」捷径会把多边形对跖点附近的点判为内部，本方法不会。
- geo_cross_track 的符号约定：查询点位于行进方向 LEFT 侧时 crossTrackKm 为正（右手定则，从球外看）；垂足位于路径起点前方时 alongTrackKm 为正，位于后方时为负。垂足落在段外时，withinSegment: false，distanceToSegmentKm 是到较近端点的距离，不是垂直距离（note 里会说明）。恰好偏离路径 90° 的点没有唯一垂足，按错误上报。
- geo_path：各段都是大圆弧，所以路线总长是各段长度之和，绕行量（detourKm = 总长 − 直线距离）永不为负——只有当每个途经点都落在过起终点的同一条大圆上时，它才为零。detourKm 是两个上报总长之差（各自四舍五入到 6 位小数），所以可以拿这两个数手工核对。两个相同途经点连成的段上报为 0 km，且没有 initialBearing/compass（零长度大圆没有航向——硬编一个 0° 就是悄悄给出错误答案），该段编号列在 zeroLengthLegs 里。最后一个途经点与第一个相同时，closesLoop 为 true，直线距离为 0，不上报 detourPercent。
- geo_circle 描述的是球冠，不是平面圆盘：
- areaKm2 是精确的球冠面积 2πR²(1 − cos d)，surfaceFraction 是它占整个球面的比例；平面近似 πr² 只对小球冠成立（r = 1000 km 时，它比真实面积大 0.21%）。
- 纬度范围是 centre ± d；只有半径恰好为周长的四分之一（d = 90°）时 boundaryIsGreatCircle 才为 true，此时球冠是半球。
- 到达极点的球冠包含该极点：会设置 includesNorthPole/includesSouthPole，coversAllLongitudes 为 true，minLon/maxLon 上报为完整范围（球冠不是矩形）。跨过反子午线的球冠，其范围会回绕：crossesAntimeridian 为 true，minLon 在 maxLon 的东侧（经 ±180° 把它们连起来）；lonSpanDeg 始终是真实的角度宽度。
- 半径达到周长一半或更大时，覆盖整个球面（coversWholeSphere，面积 = 4πR²，boundaryKm = 0）。
- containsPoint/pointOnBoundary 由大圆距离判定，绝不用包围盒——包围盒测试会误判靠近盒角的点。「在边界上」指距圆周约 6 mm 以内；放在那里的点既不算在内也不算在外。注意工具坐标会舍入到 1e-6 度（约 11 cm 弧长），比这个容差更粗，所以别指望舍入后的坐标会被识别为恰好落在边缘上。
- geo_intersection 报告离第一条路径起点最近的交点；当该交点位于路径 1 的反面（从起点 1 看的方位角相差约 180°）时，会有一条 note 说明，此时前方的是对跖交点。
- geo_rhumb 对零长度线返回方位角 0（不存在唯一航向）。

坐标输入格式

coord_parse 确定性地接受：

| 输入 | 含义 |
| 39.9042, 116.4074 | 十进制对，lat, lon 顺序 |
| 116.4074E, 39.9042N | 带后缀的对——顺序无关，轴由后缀决定 |
| 39°54′15″N 116°23′27″E | DMS 对（带后缀时逗号可省略） |
| 37°46′30″N / 37d46m30sN / 37:46:30N / 37 46 30 N | 单个 DMS 坐标 |
| 37.775N / -122.419 | 单个十进制值（负 = 南/西） |
| 37.775, kind: "lat" | 无后缀单值，附带显式轴提示 |

无效输入返回 valid: false 并给出原因——绝不静默猜测。

工具

| 工具 | 用途 |
| geo_distance | haversine 距离，km/m/mi/nmi，初始与最终方位角，罗盘点 |
| geo_bearing | 初始/最终方位角 + 大圆中点 |
| geo_destination | 由起点 + 方位角 + 距离求目标点，带往返校验 |
| coord_parse | 解析/校验十进制与 DMS 坐标字符串 → 十进制度 + DMS |
| geo_rhumb | 等角航线距离 + 方位角（loxodrome），与大圆对比 |
| geo_intersection | 两条大圆路径的交点（+ 对跖交点，距起点的距离） |
| geo_area | 球面多边形面积 + 周长（球面角盈），补集面积 |
| geo_cross_track | 到大圆路径的偏航距离：带符号偏航 + 沿航，垂足，线段距离 |
| geo_point_in_polygon | 球面多边形的内外判定（两侧、边界命中、区域面积） |
| geo_path | 多段路线总计：每段距离/航向/累计，相对直线的绕行 |
| geo_circle | 球冠：面积、边界圆周长、经纬度包围盒（极点与反子午线）、包含判定 |

配置 yaml plugins: dsh-geodesy: radiusKm: 6371.0088 # sphere radius; use 1737.4 for the Moon, 3389.5 for Mars

开发 sh
pnpm install
pnpm build
pnpm test # 223 tests, anchored to independently computed closed-form values (test/oracle/anchors.py)
pnpm lint

许可证

MIT © TYEclipse