dsh-geodesy

Geodesic math toolbox for DeepSeek Harness (dsh): great-circle distances, bearings, destination points, and DMS coordinate parsing — all as local, deterministic tools with zero runtime dependencies.

中文简介：dsh 插件「大地测量工具箱」——大圆距离、方位角、目的地推算与 DMS 坐标解析四个纯计算工具，零运行时依赖。专治大模型手算球面距离/坐标换算的常见错误（弧度与角度混用、忘记地球半径、经纬度顺序颠倒等）。

Why

LLMs reliably fumble geodesic math: they mix up latitude/longitude order, use the wrong Earth radius, forget degrees→radians, and botch DMS conversions. This plugin moves that math out of the model's head and into exact spherical trigonometry:

  • geo_distance — great-circle distance (haversine) between two points, with initial/final bearings and the 16-wind compass direction; results in km, m, mi, or nmi
  • geo_bearing — initial & final great-circle bearings plus the great-circle midpoint of two points
  • geo_destination — the direct geodesic problem: given a start point, bearing and distance, compute the destination (with a round-trip distance check)
  • coord_parse — parse and validate coordinate strings (decimal, DMS, suffixes, pairs) and convert them to decimal degrees + formatted DMS

All math uses the IUGG mean Earth radius 6371.0088 km (configurable via the plugin radiusKm option, e.g. for lunar or planetary calculations).

Install

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

Requires pnpm on your PATH. Then restart the profile's services (or dsh restart web).

Usage

Ask the agent questions that involve Earth-surface math; it will call the tools automatically:

  • "What is the great-circle distance from Beijing to Shanghai?"
  • "Which direction is New York from London, and where is the midpoint?"
  • "I'm 200 km due east of Paris — where am I?"
  • "Parse 37°46′30″N, 122°25′8.4″W into decimal degrees."

Examples

geo_distance — Beijing (39.9042, 116.4074) → Shanghai (31.2304, 121.4737):

{
  "valid": true,
  "unit": "km",
  "distance": 1067.311645,
  "kilometers": 1067.311645,
  "miles": 663.196709,
  "nauticalMiles": 576.302184,
  "initialBearing": 153.072675,
  "finalBearing": 156.029266,
  "compass": "SSE"
}

coord_parse:

{
  "valid": true,
  "input": "37°46′30″N, 122°25′8.4″W",
  "latitude": 37.775,
  "longitude": -122.419,
  "latDms": "37°46′30″N",
  "lonDms": "122°25′8.4″W"
}

Coordinate input formats

coord_parse accepts, deterministically:

Input Meaning
39.9042, 116.4074 decimal pair, lat, lon order
116.4074E, 39.9042N pair with suffixes — order is irrelevant, axes come from suffixes
39°54′15″N 116°23′27″E DMS pair (comma optional when suffixed)
37°46′30″N / 37d46m30sN / 37:46:30N / 37 46 30 N single DMS coordinate
37.775N / -122.419 single decimal (negative = S/W)
37.775, kind: "lat" unsuffixed single value with an explicit axis hint

Invalid input returns valid: false with a reason — never a silent guess.

Tools

Tool Purpose
geo_distance haversine distance, km/m/mi/nmi, initial & final bearing, compass point
geo_bearing initial/final bearings + great-circle midpoint
geo_destination destination point from start + bearing + distance, with round-trip check
coord_parse parse/validate decimal & DMS coordinate strings → decimal degrees + DMS

Configuration

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

Development

pnpm install
pnpm build
pnpm test     # 115 tests, anchored to independently computed closed-form values
pnpm lint

License

MIT © TYEclipse